Developer API

One contract from request to evidence.

Create an asynchronous screening, poll the resource, and consume a structured result with explicit coverage and limitations.

OpenAPI 3.1 Create API key

Quickstart

Create your first screening

Send a bearer API key and a unique idempotency key. The create call returns immediately with a queued resource.

cURL

POST

curl https://adversesearch.com/api/v1/screenings \
  -H "Authorization: Bearer $ADVERSESEARCH_API_KEY" \
  -H "Idempotency-Key: case-4821-attempt-1" \
  -H "Content-Type: application/json" \
  -d @subject.json

Request shape

Use only the identifiers you are allowed to process.

firstName and lastName are required. Every other subject field is optional. Phone numbers use E.164 format and country uses an ISO 3166-1 alpha-2 code.

subject.jsonJSON

{
  "subject": {
    "firstName": "Alex",
    "middleName": "Morgan",
    "lastName": "Example",
    "dateOfBirth": "1987-04-12",
    "country": "US",
    "city": "New York"
  },
  "referenceId": "case_4821",
  "searchDepth": "standard"
}

Asynchronous lifecycle

Poll a stable resource.

queued

The request and quota reservation were accepted.

searching

Available sources are being discovered and reviewed.

completed

The response includes an outcome, coverage, and any verified findings.

Use the URL in the Location response header. Poll every two to five seconds and stop on completed, incomplete, failed, or cancelled.

Decision-safe outcomes

Do not turn uncertainty into a clean result.

potential_match

At least one source-backed event passed the identity and relevance gates.

no_verified_matches

No event passed those gates within the completed search scope. This is not proof of absence.

inconclusive

Relevant information was found, but identity evidence was not strong enough.

search_incomplete

No supported result could be returned and coverage was materially limited. Never treat this as a no-match result.

Always inspect coverage.complete. A supported finding keeps its outcome even when another part of the planned search could not be completed.

Errors and retries

Retry with intent.

Every request error has a stable code and request ID. A terminal screening can also include a stable failureCode. Treat it as a diagnostic signal, not permission to retry automatically. Reuse the same idempotency key only with the exact same body. A different body with the same key returns 409.

Keep API keys on the server.

Never place a live key in browser code, mobile bundles, URLs, or logs.