Nyne.ai API Login
Person APIs

Person Research API

Generate a comprehensive person intelligence dossier combining enrichment data, social analysis, article mentions, and AI-powered insights in a single call. Requires at least one direct identifier (email, phone, or social_media_url), or a name together with a company or city. Deep research can take several minutes; the POST returns a request_id that you can poll about every 5 seconds, or you can supply a callback_url.

POST https://api.nyne.ai/person/deep-research API key

Manual credentials take precedence over your account key.

Overview

Deep Research runs an autonomous research pass on a person and returns a structured dossier for due diligence, recruiting, sales preparation, and analyst workflows.

Best for

  • Preparing for high-value meetings
  • Creating sourced person dossiers
  • Summarizing professional background and public context

Returns

  • Structured research findings
  • Profile and source context
  • Relevant public signals

Parameters

email string optional
Email identifier. Validated for format.
phone string optional
Phone identifier. Separators are stripped; 7-15 digits with an optional leading +.
social_media_url string | array optional
A profile URL from a supported social media site, or an array of up to 3 profile URLs.
0 / 3
name string optional
Full name. Requires company or city when used without a direct identifier.
company string optional
Employer; pairs with name for name-based search.
city string optional
City; pairs with name. Truncated to 100 chars.
probability_score boolean optional
Include match-probability scoring in the dossier.
e.g. false
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
Deep Research - Charged when the research request is accepted
Heads up
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": {
      "enrichment": {
        "displayname": "Jane Doe",
        "headline": "VP of Product at Acme",
        "organizations": [
          {
            "name": "Acme",
            "title": "VP of Product",
            "is_current": true
          }
        ]
      },
      "articles": {
        "count": 3,
        "articles": [
          {
            "title": "Jane Doe on AI in Product",
            "url": "https://example.com/article"
          }
        ]
      },
      "dossier": {
        "identity_snapshot": {
          "name": "Jane Doe",
          "role": "VP of Product",
          "company": "Acme"
        },
        "career_dna": {
          "trajectory": "Product Manager → VP of Product",
          "superpower": "user empathy"
        },
        "psychographic_profile": {
          "archetypes": [
            "Builder",
            "Connector"
          ],
          "values": [
            "innovation",
            "craft"
          ]
        },
        "key_relationships": [
          {
            "name": "John Smith",
            "handle": "@johnsmith",
            "nature": "former colleague"
          }
        ]
      }
    },
    "completed_on": "2026-01-15T10:45:00Z"
  },
  "timestamp": "2026-01-01T00:00:00"
}