# Discovery > Discover people from the open web with natural-language queries and match conditions. - **Endpoint:** `POST https://api.nyne.ai/person/discovery` - **Group:** Person APIs (https://api.nyne.ai/documentation/person.md) - **Auth:** `X-API-Key` + `X-API-Secret` headers - **Mode:** Asynchronous - submit returns a `request_id` (normally with `202 Accepted`); poll `GET /person/discovery?request_id=` with the same auth headers until the endpoint reports a terminal response. Where supported, a `callback_url` can notify you when queued work finishes; follow this endpoint's retrieval notes. - **HTML version:** https://api.nyne.ai/documentation/person/discovery 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`. ## Authentication All `/person/*` and `/company/*` endpoints authenticate with an API key and secret sent as HTTP headers on every request: `X-API-Key` and `X-API-Secret`. Create keys from your Nyne.ai dashboard and keep the secret server-side. Rate limits: 100 requests/minute, 1,000 requests/hour. Full guide: https://api.nyne.ai/documentation/authentication.md ## Parameters | Name | Type | Required | Description | Example | | --- | --- | --- | --- | --- | | `query` | string | **yes** | Natural-language query describing the people to find. Max 2000 characters. | "AI researchers specializing in NLP at top US universities" | | `requirements` | array | no | Match conditions, each with `name` and `description` (max 20). Each is evaluated independently per candidate with evidence-based reasoning. | [{ "name": "published_papers", "description": "Has published research papers in NLP" }] | | `extract` | array | no | Enrichment fields to extract per matched person, each with `name` and `description` (max 10). | [{ "name": "email", "description": "Professional email address" }] | | `limit` | integer | no | Maximum results to return. Range 5-100, default 10. | 10 | | `quality` | string | no | Quality tier - `basic` (fastest) · `standard` (default) · `premium` (most thorough). | "standard" | | `exclude` | array | no | Entities to exclude from results, each with `name` and `url` (max 100). | [{ "name": "Jane Doe", "url": "janedoe.com" }] | | `metadata` | object | no | Pass-through metadata returned with the results. Values must be string, number, or boolean. | { "campaign": "outreach-q1" } | | `callback_url` | string | no | 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. | "https://hooks.example.com/result" | ## Polling for the result A newly queued submit normally returns `202 Accepted` with a `request_id`. Poll the same path until `status` is `completed` (results stay available afterwards). Where supported, pass a `callback_url` on the submit to receive a webhook when queued work finishes; keep the documented GET as a recovery and retrieval path: ```bash curl "https://api.nyne.ai/person/discovery?request_id=" \ -H "X-API-Key: YOUR_API_KEY" \ -H "X-API-Secret: YOUR_API_SECRET" ``` ## Credit usage | Item | Credits | Condition | | --- | --- | --- | | Discovery Request | 10 | Fixed per request, regardless of the number of results returned | ## Responses | Code | Meaning | | --- | --- | | `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 | ## Example request ### cURL ```bash curl -X POST https://api.nyne.ai/person/discovery \ -H "X-API-Key: YOUR_API_KEY" \ -H "X-API-Secret: YOUR_API_SECRET" \ -H "Content-Type: application/json" \ -d '{ "query": "AI researchers specializing in NLP at top US universities", "requirements": [ { "name": "published_papers", "description": "Has published research papers in NLP" } ], "extract": [ { "name": "email", "description": "Professional email address" } ], "limit": 10, "quality": "standard" }' ``` ### Python ```python import requests resp = requests.post( "https://api.nyne.ai/person/discovery", headers={ "X-API-Key": "YOUR_API_KEY", "X-API-Secret": "YOUR_API_SECRET", }, json={ "query": "AI researchers specializing in NLP at top US universities", "requirements": [ { "name": "published_papers", "description": "Has published research papers in NLP", }, ], "extract": [ { "name": "email", "description": "Professional email address", }, ], "limit": 10, "quality": "standard", }, ) data = resp.json() print(data) ``` ### Node ```javascript const resp = await fetch("https://api.nyne.ai/person/discovery", { method: "POST", headers: { "X-API-Key": "YOUR_API_KEY", "X-API-Secret": "YOUR_API_SECRET", "Content-Type": "application/json", }, body: JSON.stringify({ query: "AI researchers specializing in NLP at top US universities", requirements: [ { name: "published_papers", description: "Has published research papers in NLP", }, ], extract: [ { name: "email", description: "Professional email address", }, ], limit: 10, quality: "standard", }), }); const data = await resp.json(); console.log(data); ``` ### PHP ```php true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "X-API-Key: YOUR_API_KEY", "X-API-Secret: YOUR_API_SECRET", "Content-Type: application/json", ], CURLOPT_POSTFIELDS => json_encode([ "query" => "AI researchers specializing in NLP at top US universities", "requirements" => [ [ "name" => "published_papers", "description" => "Has published research papers in NLP", ], ], "extract" => [ [ "name" => "email", "description" => "Professional email address", ], ], "limit" => 10, "quality" => "standard", ]), ]); $data = json_decode(curl_exec($ch), true); print_r($data); ``` ## Example response ```json { "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": "jane@stanford.edu" }, "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" } ``` --- All documentation pages are available as Markdown by appending `.md` to their URL. Index: https://api.nyne.ai/llms.txt