# Deep Research > Run an in-depth autonomous research pass on a person. - **Endpoint:** `POST https://api.nyne.ai/person/deep-research` - **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/deep-research?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/deep-research 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`. ## 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 | | --- | --- | --- | --- | --- | | `email` | string | no | Email identifier. Validated for format. | "jane.doe@acme.com" | | `phone` | string | no | Phone identifier. Separators are stripped; 7-15 digits with an optional leading `+`. | "+1-555-123-4567" | | `social_media_url` | string \| array | no | A profile URL from a supported social media site, or an array of up to 3 profile URLs. | "https://linkedin.com/in/janedoe" | | `name` | string | no | Full name. Requires `company` or `city` when used without a direct identifier. | "Jane Doe" | | `company` | string | no | Employer; pairs with `name` for name-based search. | "Acme" | | `city` | string | no | City; pairs with `name`. Truncated to 100 chars. | "Austin" | | `probability_score` | boolean | no | Include match-probability scoring in the dossier. | false | | `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/deep-research?request_id=" \ -H "X-API-Key: YOUR_API_KEY" \ -H "X-API-Secret: YOUR_API_SECRET" ``` ## Credit usage | Item | Credits | Condition | | --- | --- | --- | | Deep Research | - | Charged when the research request is accepted | ## Responses | Code | Meaning | | --- | --- | | `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 | ## Example request ### cURL ```bash curl -X POST https://api.nyne.ai/person/deep-research \ -H "X-API-Key: YOUR_API_KEY" \ -H "X-API-Secret: YOUR_API_SECRET" \ -H "Content-Type: application/json" \ -d '{ "name": "Jane Doe", "company": "Acme", "social_media_url": "https://linkedin.com/in/janedoe" }' ``` ### Python ```python import requests resp = requests.post( "https://api.nyne.ai/person/deep-research", headers={ "X-API-Key": "YOUR_API_KEY", "X-API-Secret": "YOUR_API_SECRET", }, json={ "name": "Jane Doe", "company": "Acme", "social_media_url": "https://linkedin.com/in/janedoe", }, ) data = resp.json() print(data) ``` ### Node ```javascript const resp = await fetch("https://api.nyne.ai/person/deep-research", { method: "POST", headers: { "X-API-Key": "YOUR_API_KEY", "X-API-Secret": "YOUR_API_SECRET", "Content-Type": "application/json", }, body: JSON.stringify({ name: "Jane Doe", company: "Acme", social_media_url: "https://linkedin.com/in/janedoe", }), }); 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([ "name" => "Jane Doe", "company" => "Acme", "social_media_url" => "https://linkedin.com/in/janedoe", ]), ]); $data = json_decode(curl_exec($ch), true); print_r($data); ``` ## Example response ```json { "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" } ``` --- All documentation pages are available as Markdown by appending `.md` to their URL. Index: https://api.nyne.ai/llms.txt