# OSINT Deep Search > Run an agentic OSINT investigation on a person. Disabled by default - access on request. - **Endpoint:** `POST https://api.nyne.ai/person/osint` - **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/osint?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. - **Access:** Access required - this endpoint is disabled by default on every account. Request access: mailto:support@nyne.ai?subject=OSINT%20API%20access%20request - **HTML version:** https://api.nyne.ai/documentation/person/osint Runs an autonomous OSINT investigation across public sources and reconciles everything it finds into a single person report: identity, aliases, usernames, emails, phones, social accounts (including when an account was created and last seen active, where that is known), employment and education history, locations, websites, public content, public records, corporate roles, adverse findings, breach exposure, images, and wallets. Sections with no findings are omitted. Requires at least one direct identifier (`email`, `phone`, `social_media_url`, `username`, or `domain`), *or* a `name` together with a `company` or `city`. `mode` selects how hard the agent works the search (`shallow`, `medium` by default, or `deep`) and therefore what it costs; the retired `depth` parameter is rejected with `400` rather than silently downgraded. A search keeps running server-side for up to 30 minutes, so poll about every 10 seconds or supply a `callback_url`. **This endpoint is disabled by default for every account** - see Access below before you integrate it. ## Access OSINT Deep Search is off by default on every account, so there is nothing to test until it is switched on for yours: submits return `403 PRODUCT_NOT_AVAILABLE` and the playground below stays disabled. Request access and we will enable it for your workspace, then the same API key you already use starts working here. Request access: mailto:support@nyne.ai?subject=OSINT%20API%20access%20request ## 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 LinkedIn, Twitter/X, Instagram, or Facebook profile URL, or an array of up to 3 such URLs (one per platform). Other hosts are rejected with `400`. | "https://linkedin.com/in/janedoe" | | `username` | string | no | A handle to pivot from, resolved across platforms. | "janedoe" | | `domain` | string | no | A domain tied to the subject, e.g. a personal site or an employer domain. | "janedoe.dev" | | `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" | | `mode` | string | no | Search effort tier, and what the request costs: `shallow`, `medium` (default), or `deep`. Case-insensitive; any other value returns `400`. See Credit usage for the per-tier price. | "medium" | | `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/osint?request_id=" \ -H "X-API-Key: YOUR_API_KEY" \ -H "X-API-Secret: YOUR_API_SECRET" ``` ## Credit usage | Item | Credits | Condition | | --- | --- | --- | | OSINT Deep Search (medium) | 100 | Default mode - charged once, when a report with data is delivered | | Shallow mode | 50 | Charged instead of the default when mode is shallow | | Deep mode | 150 | Charged instead of the default when mode is deep | ## Responses | Code | Meaning | | --- | --- | | `200` | Status poll result - returns the current request status, plus the report or error once terminal | | `202` | Request queued - poll the status endpoint (or wait for the callback) with the returned request_id | | `400` | INVALID_PARAMETERS - malformed JSON, no usable identifier, an unsupported social URL, an invalid mode, or the retired depth parameter | | `401` | Missing or invalid API credentials | | `402` | insufficient_credits - not enough credits for the requested mode | | `403` | PRODUCT_NOT_AVAILABLE - OSINT is not enabled for this account (request access), or ACCESS_DENIED when the request_id belongs to another API key | | `404` | NOT_FOUND - no matching request for this request_id | | `429` | RATE_LIMIT_EXCEEDED | | `500` | INTERNAL_ERROR - request failed unexpectedly | | `502` | UPSTREAM_UNAVAILABLE - the OSINT service could not start or track the search | | `503` | SERVICE_UNAVAILABLE - the endpoint is temporarily unavailable | ## Example request ### cURL ```bash curl -X POST https://api.nyne.ai/person/osint \ -H "X-API-Key: YOUR_API_KEY" \ -H "X-API-Secret: YOUR_API_SECRET" \ -H "Content-Type: application/json" \ -d '{ "email": "jane.doe@acme.com", "social_media_url": "https://linkedin.com/in/janedoe", "mode": "medium" }' ``` ### Python ```python import requests resp = requests.post( "https://api.nyne.ai/person/osint", headers={ "X-API-Key": "YOUR_API_KEY", "X-API-Secret": "YOUR_API_SECRET", }, json={ "email": "jane.doe@acme.com", "social_media_url": "https://linkedin.com/in/janedoe", "mode": "medium", }, ) data = resp.json() print(data) ``` ### Node ```javascript const resp = await fetch("https://api.nyne.ai/person/osint", { method: "POST", headers: { "X-API-Key": "YOUR_API_KEY", "X-API-Secret": "YOUR_API_SECRET", "Content-Type": "application/json", }, body: JSON.stringify({ email: "jane.doe@acme.com", social_media_url: "https://linkedin.com/in/janedoe", mode: "medium", }), }); 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([ "email" => "jane.doe@acme.com", "social_media_url" => "https://linkedin.com/in/janedoe", "mode" => "medium", ]), ]); $data = json_decode(curl_exec($ch), true); print_r($data); ``` ## Initial 202 response ```json { "request_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4_1717000000_4271", "status": "processing", "message": "OSINT deep search request submitted. Use GET with request_id to check status.", "created_on": "2026-01-15T10:45:02" } ``` ## Completed poll response ```json { "request_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4_1717000000_4271", "status": "completed", "completed": true, "created_on": "2026-01-15T10:45:02", "completed_on": "2026-01-15T10:52:31", "result": { "identity": { "name": "Jane Doe", "kind": "person", "labels": [ "product leadership" ], "confidence": 0.92, "identifiers": [ { "value": "jane.doe@acme.com", "confidence": 0.95, "best": true } ] }, "aliases": [ { "value": "Jane A. Doe", "kind": "legal", "confidence": 0.71 } ], "usernames": [ { "value": "janedoe", "platform": "github", "url": "https://github.com/janedoe", "confidence": 0.88 } ], "emails": [ { "value": "jane.doe@acme.com", "kind": "work", "verified": true, "confidence": 0.95 } ], "phones": [ { "value": "+15551234567", "kind": "mobile", "verified": false, "confidence": 0.62 } ], "social_profiles": [ { "platform": "linkedin", "url": "https://linkedin.com/in/janedoe", "username": "janedoe", "display_name": "Jane Doe", "follower_count": 4200, "confidence": 0.93, "first_seen": "2026-01-15T10:47:10Z", "last_seen": "2026-01-15T10:47:10Z", "usage": { "created_at": "2011-03-08T00:00:00Z", "last_seen_at": "2026-01-10T00:00:00Z" }, "registered": true, "verified": false, "platform_variables": { "headline": "VP of Product at Acme" } } ], "employment_history": [ { "company": "Acme", "title": "VP of Product", "start_date": "2023-04", "current": true, "confidence": 0.9 } ], "education_history": [ { "institution": "State University", "degree": "BSc", "field": "Computer Science", "confidence": 0.7 } ], "locations": [ { "city": "Austin", "region": "TX", "country": "US", "current": true, "confidence": 0.81 } ], "websites": [ { "url": "https://janedoe.dev", "title": "Jane Doe", "domain": "janedoe.dev", "confidence": 0.76 } ], "public_content": [ { "title": "Jane Doe on shipping AI products", "url": "https://example.com/interview", "description": "Interview covering product strategy at Acme.", "published_at": "2025-11-02T00:00:00Z", "confidence": 0.65 } ], "breaches": [ { "breach_name": "ExampleForum", "date": "2019-05-01", "exposed_fields": [ "email", "password_hash" ], "confidence": 0.8 } ], "confidence": 0.88 } } ``` --- All documentation pages are available as Markdown by appending `.md` to their URL. Index: https://api.nyne.ai/llms.txt