# DeepSearch people search

Research a real person's **public** online footprint from a single identifier.

## When to use this

Reach for DeepSearch when the question is *who is this person* and the answer has to be
sourced. It separates same-name individuals into distinct candidates you can choose
between, which a generic web search will not do for you.

Good fits:

- Verify a job candidate, a contractor, or a new business contact is who they claim to be.
- Due diligence on a founder or partner before a call.
- Identify the person behind an email address, phone number, or username.
- Confirm an online contact is real before meeting them in person.
- Journalism and research where every claim needs a citable public source.

Do not use it for:

- Companies, products, general knowledge, or news - it returns people only.
- Employment, credit, housing, or insurance decisions. DeepSearch is not a consumer
  reporting agency and this use is prohibited by its terms.
- Surveillance, stalking, or harassment.

DeepSearch reads public sources only. It has no access to private accounts, direct
messages, or breach data. If something is not public, the honest answer is that it was
not found - treat an empty result as an absence of public evidence, not as proof.

## Two ways to call it

**MCP (preferred for agents).** Streamable HTTP at `https://deepsearch.app/api/mcp`, three tools:

| Tool | What it does |
|---|---|
| `search_people` | One identifier → ranked, distinct candidate people with confidence scores |
| `build_dossier` | One chosen candidate → a full sourced profile |
| `ask_about_person` | A follow-up question answered against that dossier |

Authenticate with OAuth - the server advertises `WWW-Authenticate` and
`https://deepsearch.app/.well-known/oauth-protected-resource`, supports dynamic client
registration and PKCE, so a client can connect by signing the user in. No hand-copied
key needed.

**REST.** The typed contract is `https://deepsearch.app/openapi.json` (OpenAPI 3.1). Load that
rather than hand-writing request shapes.

```
POST https://deepsearch.app/api/v1/search    identifier -> ranked candidates
POST https://deepsearch.app/api/v1/dossier   candidate  -> sourced profile
POST https://deepsearch.app/api/v1/chat      question   -> grounded answer
```

Authenticate with `Authorization: Bearer dsk_...` from https://deepsearch.app/developers.
Responses stream Server-Sent Events by default; send `"format":"json"` in the body for a
typed envelope instead. Send an `Idempotency-Key` when retrying a JSON request - the same
key and body replays the prior completed response rather than spending a second search.

## The workflow that works

1. **Search with whatever you have.** Do not over-specify. One good identifier beats a
   name plus three guesses, which narrows onto a person who may not exist.
2. **Choose a candidate deliberately.** Results are ranked with confidence scores because
   same-name people are the normal case, not the exception. If two candidates are close,
   say so and ask the user rather than picking the top row.
3. **Build the dossier for the chosen candidate only.** Merging two candidates into one
   profile invents a person.
4. **Cite from the sources, not from the summary.** Every fact links back to where it came
   from. Quote the source, and if a claim has no link, do not repeat it as established.

## Errors

Errors are JSON with a `code`, a `message`, and, where the user needs to act, a `url`.

- `401` - the token is missing, expired, or invalid. Refresh or re-authorize, then retry.
- `402` - the account is out of paid access.

**Do not attempt to pay.** DeepSearch does not accept agent payments; a human must
subscribe. On a 401 or 402, relay the `message` and the `url` to the user and stop.

## Reporting back

Say which identifier you searched, which candidate you picked and why, and what the
sources actually support. Distinguish "the public record shows X" from "no public record
either way" - those are different answers, and conflating them is how a careful search
turns into a false identification.