Nyne.ai API Login
Person APIs

Person Discovery API

Keyword-based people discovery - finds and enriches people matching a keyword query, optionally narrowed by location. Returns names, bios, social profiles, photos, and contact data. keywords is required (3-500 chars); max_results defaults to 50 and is clamped to 1-100. The request is queued and returns a request_id; poll the status endpoint or supply a callback_url.

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

Manual credentials take precedence over your account key.

Try it needs this required parameter:

Overview

Discover helps resolve likely people when you have partial details rather than a clean identifier, making it useful for identity discovery and investigative workflows.

Best for

  • Finding someone from incomplete clues
  • Resolving partial person records
  • Starting enrichment from sparse input

Returns

  • Candidate profiles
  • Match context
  • Identifiers for follow-up enrichment

Parameters

keywords string required
Search keywords. Required, 3-500 characters. Deduplicates to the same job for identical keyword sets.
location string optional
Optional location filter.
max_results integer optional
Max profiles to return. Default 50, clamped to 1-100.
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
Discovery - Charged as profiles are discovered
Enrichment - Additional - only charged when contact details are actually found
No results 0 Empty results never burn credits
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": [
      {
        "displayname": "Jane Doe",
        "bio": "Growth marketing lead in fintech, focused on B2B SaaS.",
        "location": "New York, NY",
        "altemails": [
          "[email protected]"
        ],
        "fullphone": [
          "+1-555-123-4567"
        ],
        "social_profiles": {
          "linkedin": {
            "url": "https://linkedin.com/in/janedoe",
            "photo_url": "https://cdn.example.com/photo.jpg"
          }
        },
        "company": "Acme",
        "work_history": [
          {
            "title": "Growth Marketing Lead",
            "company": "Acme",
            "start_date": "2023-04"
          }
        ]
      }
    ],
    "completed_on": "2026-01-15T10:35:00Z"
  },
  "timestamp": "2026-01-01T00:00:00"
}