API reference

People search

Find people by name, phone, email, or username.

POST/api/v1/search

Scope: search
Formats: JSON · SSE
Sandbox: Free fixtures

curl https://deepsearch.app/api/v1/search \  -H "Authorization: Bearer $DEEPSEARCH_API_KEY" \  -H "Content-Type: application/json" \  -d '{        "query": "Ada Lovelace",        "type": "name",        "format": "json"      }'

Example request

Authorization

Authorizationheaderrequired

Send Bearer $DEEPSEARCH_API_KEY with the search scope. The free sandbox uses the published test key.

Authentication guide

Body parameters

querystringrequired

The name, phone number, email address, or username to look up.

typeenum

How to interpret the query.

namephoneemailusername

Default: name

platformsstring | string[]

For a username search, narrow discovery to supported focus platforms (e.g. instagram, x, linkedin). Ignored for other types.

formatenum

sse streams Server-Sent Events as results arrive; json collects every event and returns one object.

ssejson

Default: sse

sandboxboolean

Return deterministic, unmetered fixtures for CI, demos, and parser development.

Default: false

Response

JSON responses preserve the operation result and include request metadata, usage, and collected events. SSE delivers progress and result events as they arrive.

Streaming & formats

{  "object": "search_result",  "request_id": "req_01HZY8M7YQ2C7W9F4X9J7Z1H3A",  "metadata": {    "api_version": "v1",    "operation": "search",    "request_id": "req_01HZY8M7YQ2C7W9F4X9J7Z1H3A",    "generated_at": "2026-06-19T12:00:00.000Z"  },  "usage": {    "metered": true,    "percentageCharged": 2,    "remainingPercent": 98,    "resetAt": "2026-07-01T00:00:00.000Z",    "source": "included",    "credits": 1,    "allowanceSource": "weekly"  },  "hits": [    {      "id": "ada-lovelace",      "name": "Ada Lovelace",      "headline": "Mathematician · London",      "initials": "AL",      "confidence": 82,      "location": "London, United Kingdom",      "tags": [        "3 social profiles",        "London"      ]    }  ],  "events": [    {      "type": "status",      "label": "Scanning public sources"    },    {      "type": "hit",      "hit": {        "id": "ada-lovelace",        "name": "Ada Lovelace",        "headline": "Mathematician · London",        "initials": "AL",        "confidence": 82,        "location": "London, United Kingdom",        "tags": [          "3 social profiles",          "London"        ]      }    },    {      "type": "done"    }  ]}

Example responseapplication/json

Sources & coverage

Submit an identifier and stream back ranked candidate matches (PersonHit objects) drawn from public sources. Each candidate carries a confidence score and descriptive tags so you can disambiguate before requesting a full dossier.

Usage & caching

Standard search is Medium usage. Cached results and idempotent replays use no usage.

Usage & rate limits

Examples illustrate the contract. Test request runs the selected deployment; sandbox fixtures are unmetered.