Person APIs

Personal Interests

Resolves a person and returns an inferred interest graph (topics, affinities, psychographic signals). At least one of email, phone, social_media_url, or name is required. Name-only lookups can match the wrong person - adding company and/or a LinkedIn URL improves disambiguation. Only sections with detected signals are included in the response (possible sections: core_profile, location_intelligence, cultural_dna, psychographics, interest_graph, brand_affinities, professional_ecosystem, social_graph_clusters); empty sections are omitted, and every insight carries a supporting_accounts array naming the accounts that justify it. The request is queued and completes asynchronously - supply a callback_url or poll the status endpoint with the returned request_id.

POST https://api.nyne.ai/person/interests API key

API Key API Secret

Manual credentials take precedence over your account key.

Overview

Infer a person’s interests and affinities.

Parameters

email string optional

Email identifier. Validated for format.

phone string optional

Phone identifier.

social_media_url string optional

Profile URL;

name string optional

Full name. At least one identifier (email/phone/url/name) is required.

company string optional

Current company or workplace - disambiguates a name-based lookup.

callback_url string optional

If set, the completed result is POSTed here when the job finishes. Must be a valid HTTP(S) URL on an allowed host when a callback allow-list is configured.

Retrieving the result

This endpoint is asynchronous. A successful submit returns a request_id while the job runs in the background. Poll the same path with a GET request - same authentication headers - passing the request_id as a query parameter:

Loading your API credentials...

Each poll returns the job's current status; once it is completed the payload carries the result shown under Responses. Polling an unknown or expired request_id returns 404 request_not_found.

Status	Meaning
queued · processing · pending	The job is still running - keep polling.
completed	The job finished; the payload carries the result and completed: true.
failed	Terminal - the job could not complete; the error field explains why.

Poll every few seconds at first, backing off for long-running jobs. Polling is free - status checks never burn credits.

Prefer push delivery?

Supply the optional callback_url parameter and the completed payload is POSTed to your endpoint when the job finishes - no polling required. Delivery is retried up to 5 times with exponential backoff (1s, 5s, 15s, 1m, 5m) and a 30-second timeout per attempt; respond with a 2xx status to acknowledge receipt.

Credit usage

Credits are charged based on the matched configuration. The listed cost is the per-result unit price.

Feature	Credits	Notes
Interest Analysis	5	Charged on a completed analysis
No match	0	Empty results never burn credits

Heads up

A positive credit balance is required before each request. Empty results do not burn credits.

Responses

200 Status poll result - returns the current request status and result/error fields when available

202 Request queued - poll the status endpoint (or wait for the callback) with the returned request_id

400 Malformed JSON, missing required parameters, or an invalid field

401 Missing or invalid API credentials

402 insufficient_credits - not enough credits to complete the request

403 subscription_required or ip_not_allowed

404 request_not_found - no matching request is available for this API key

429 rate_limit_exceeded

503 service_unavailable - the API is temporarily unavailable

A successful response wraps the payload in the { success, data, timestamp } envelope (also shown live in the panel on the right):

{
  "success": true,
  "data": {
    "request_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4_1717000000_4271",
    "status": "completed",
    "completed": true,
    "result": {
      "core_profile": {
        "archetypes": [
          "Tech Leader",
          "Thought Leader"
        ],
        "supporting_accounts": [
          "@techcrunch",
          "@ycombinator"
        ]
      },
      "interest_graph": {
        "technology": {
          "interests": [
            {
              "topic": "Machine Learning",
              "supporting_accounts": [
                "@exampleai"
              ]
            }
          ]
        },
        "sports_and_fitness": {
          "interests": [
            {
              "activity": "Running",
              "supporting_accounts": [
                "@strava"
              ]
            }
          ]
        }
      },
      "brand_affinities": [
        {
          "category": "Cloud Platforms",
          "brands": [
            "AWS",
            "Google Cloud"
          ]
        }
      ],
      "professional_ecosystem": {
        "industry_focus": [
          "SaaS",
          "Developer Tools"
        ],
        "supporting_accounts": [
          "@github",
          "@stripe"
        ]
      },
      "following_count": 2847
    },
    "completed_on": "2026-01-15T10:31:00Z"
  },
  "timestamp": "2026-01-01T00:00:00"
}