Documentation

Authentication

Send an API key as a bearer token. Keys are created in the dashboard and shown once — only a hash is stored, so a lost key is replaced rather than recovered.

A key can never do more than the person who created it. Its scopes are intersected with that member's current permissions on every request, so removing someone from an organization removes their keys' power at the same moment.

Credits

Credits are the only meter. A verification costs half a credit; a search, find or company lookup costs one; asking how many addresses exist at a domain is free.

Nothing is charged for an answer we did not produce. A search that returns no results, a finder that finds nothing, and a verification that could not be completed are all free. Every movement appears in the ledger with the operation that caused it and the balance it produced.

Errors

One shape, always. Switch on code — it comes from a closed catalogue. Message text is written for people and may change between releases.

The behaviour to get right

Two things mean the mailbox was never tested:

• A 503 with code ENGINE_CAPACITY — no sending capacity was available, so the work was not done.
• A result with retryable: true, usually status: "unknown" — the receiving server blocked the probe, greylisted it, or DNS failed.

Both are questions, not answers. Writing either into your database as undeliverable will silently remove real customers from your list, and because neither is charged, retrying costs nothing. Honour retryAfterSeconds and ask again.

Idempotency

Endpoints that move money or launch a bulk job require an Idempotency-Key header. Reuse the same key for every retry of one intent — a fresh key per attempt defeats the point. The same key with a different body returns IDEMPOTENCY_KEY_CONFLICT rather than silently replaying the first response.

Pagination

Lists are cursor-paginated. Pass the nextCursor from a response as cursor on the next request; a null cursor means the end. Offsets are deliberately not offered — results arrive continuously from background crawls and bulk jobs, so an offset silently repeats and drops rows while a user reads.

Citations

Every discovered address carries a sources array. Each entry has the page it appeared on, when it was first extracted, when it was last confirmed, and whether it is stillOnPage. That last field is the one worth surfacing in your own product — an address published two years ago and since removed is not the same as one confirmed today.

Rate limits

Per key and per route, with verification tighter than search because each call spends real sending capacity. Limits come back in standard draft-7 rate limit headers, and a 429 carries Retry-After.

For agents

/llms.txt is a single plain-text brief describing the product, its guarantees and its pricing — enough to answer questions about VerifyInbox without crawling thirty pages.