Nyne.ai API Login
Person APIs

People Discovery API

Find people from the open web using a natural-language query. The API evaluates each candidate against your requirements, extracts the extract fields you request, and ranks the matches. Every evaluation is backed by source citations with confidence levels (high/medium/low) and excerpt quotes. Jobs progress through pending → searching → completed (or failed) and typically take 1-3 minutes; poll about every 5 seconds or supply a callback_url.

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

Manual credentials take precedence over your account key.

Try it needs this required parameter:

Overview

The People Discovery API finds people from the open web using natural-language criteria and match requirements, supporting broader prospecting and research workflows.

Best for

  • Open-web people discovery
  • Finding prospects by nuanced criteria
  • Building research-backed candidate lists

Returns

  • Discovered person profiles
  • Match evidence and requirements
  • Pagination or job status data

Parameters

query string required
Natural-language query describing the people to find. Max 2000 characters.
requirements array optional
Match conditions, each with name and description (max 20). Each is evaluated independently per candidate with evidence-based reasoning.
0 / 20
extract array optional
Enrichment fields to extract per matched person, each with name and description (max 10).
0 / 10
limit integer optional
Maximum results to return. Range 5-100, default 10.
quality string optional
Quality tier - basic (fastest) · standard (default) · premium (most thorough).
exclude array optional
Entities to exclude from results, each with name and url (max 100).
0 / 100
metadata object optional
Pass-through metadata returned with the results. Values must be string, number, or boolean.
number and true/false values are sent as numbers and booleans
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 Request 10 Fixed per request, regardless of the number of results returned
Heads up
Empty results do not burn credits.

Responses

202 Discovery request accepted and queued for processing
400 INVALID_PARAMETERS / MISSING_PARAMETER
401 AUTHENTICATION_FAILED - invalid or missing API credentials
402 INSUFFICIENT_CREDITS - requires 10 credits
403 NO_ACTIVE_SUBSCRIPTION / PRODUCT_NOT_AVAILABLE / ACCESS_DENIED
404 NOT_FOUND - unknown request_id (on status poll)
429 RATE_LIMIT_EXCEEDED
500 QUEUE_ERROR - the request could not be queued

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": {
      "entity_type": "people",
      "query": "AI researchers specializing in NLP at top US universities",
      "results_count": 1,
      "results": [
        {
          "name": "Dr. Jane Smith",
          "url": "janesmith.ai",
          "description": "NLP researcher at Stanford University specializing in large language models",
          "match_status": "matched",
          "evaluations": {
            "published_papers": {
              "value": "yes",
              "matched": true
            }
          },
          "extractions": {
            "email": "[email protected]"
          },
          "sources": [
            {
              "field": "published_papers",
              "reasoning": "Found multiple publications in top NLP venues including ACL and EMNLP",
              "confidence": "high",
              "citations": [
                {
                  "title": "Stanford NLP Lab - Publications",
                  "url": "https://nlp.stanford.edu/pubs",
                  "excerpts": [
                    "Dr. Smith has published over 30 papers in computational linguistics…"
                  ]
                }
              ]
            }
          ]
        }
      ],
      "metrics": {
        "candidates_evaluated": 50,
        "candidates_matched": 10
      }
    },
    "completed_on": "2026-01-15T10:35:00Z"
  },
  "timestamp": "2026-01-01T00:00:00"
}