Skip to content
AdverseMe

Developer API

Screening as an API call.

Five endpoints, one header. Create a screening against 110+ sources, poll it, pull the PDF and check your balance from any language that can make an HTTPS request.

Get started See pricing

Last updated .

The AdverseMe API is a small REST surface. Send an X-API-Key header, POST a name to /screen, poll GET /screening/{id} until the status is completed, then GET the PDF. 1 credit per screening, every read and every PDF free. Keys are created in the app and identify the account whose credits are used.

Auth
X-API-Key header
Base URL
adverseme.com/api/public-api
Cost
1 credit per POST /screen
Reads and PDFs
Free

Authentication

One header

Create a key in the app under API keys. The key identifies your account; screenings created with it appear in the app and use your credits.

X-API-Key: YOUR_API_KEY

Keys are stored hashed. Keep them out of client-side code and public repositories; delete and re-create a key if it leaks. Base URL: https://adverseme.com/api/public-api.

Endpoints

Five calls

POST/screen

Create a screening. Costs 1 credit, charged only after the body validates.

Request body

{
  "name": "Jane Example",
  "entity_type": "person",
  "country": "AE",
  "date_of_birth": "1980-01-31",
  "nationality": "AE",
  "aliases": ["J. Example"],
  "address": "Dubai",
  "linkedin_url": "https://www.linkedin.com/in/example",
  "known_employer": "Example Holdings",
  "company_number": "01234567"
}

Response

{
  "screening_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued",
  "message": "Screening queued. Poll GET /screening/{id} until status is \"completed\"."
}
  • name is required.
  • entity_type is person or company. Synonyms such as individual, organisation, org and business are accepted and mapped; anything else is a 400 that names the valid values. Omitted means person.
  • Every other field is optional and only stored when present. Extra identifiers such as date_of_birth, nationality, aliases and company_number sharpen identity matching and form part of the result's evidence signature.
  • The screening is queued and run asynchronously. Poll GET /screening/{id}.

GET/screening/{id}

Fetch one screening you own.

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Jane Example",
  "entity_type": "person",
  "country": "AE",
  "status": "completed",
  "risk_level": "medium",
  "risk_score": 41,
  "results": { "key_findings": [], "sanctions": [], "adverse_media": [], "sources_metadata": { "total": 117, "with_results": 31, "sources": [] }, "lane_status": {} },
  "sources": [],
  "created_at": "2026-09-01T10:30:00Z",
  "updated_at": "2026-09-01T10:34:12Z"
}
  • status moves from queued to processing to completed, failed or cancelled.
  • results is the full result object the app renders: findings, sanctions, adverse media with dropped items, associated-party screening, sources_metadata with a per-source outcome, and lane_status.
  • risk_score and risk_level are null until the council has scored; a completed screening the council could not score is returned unscored rather than with a fake number.

GET/screening/{id}/pdf

Download the PDF report. Free.

Response

Content-Type: application/pdf
Content-Disposition: inline; filename="adverseme-<id>.pdf"

(binary)
  • Only for status completed; otherwise a 400 with the current status.
  • The first request renders and stores the file; later requests return the stored copy.
  • 503 if the rendering service is unavailable. Retry later; nothing is charged.

GET/screenings

List your screenings, newest first.

Response

{
  "items": [
    { "id": "...", "name": "Jane Example", "entity_type": "person", "country": "AE", "status": "completed", "risk_level": "medium", "risk_score": 41, "source": "api", "created_at": "...", "updated_at": "..." }
  ],
  "total": 142,
  "page": 1,
  "limit": 20
}
  • Query parameters: page (default 1) and limit (default 20, maximum 100).
  • Each item carries the summary fields and source, which is api for screenings created here.

GET/credits

Current balance and plan for the key's account.

Response

{ "credits_remaining": 287, "plan": "professional" }
  • Plans: Starter 50 screenings, Professional 300 screenings, Enterprise 1500 screenings a month. See pricing.

Code samples

curl and JavaScript

curl

# Create a screening (1 credit)
curl -X POST "https://adverseme.com/api/public-api/screen" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Jane Example", "entity_type": "person", "country": "AE"}'

# Poll the result
curl "https://adverseme.com/api/public-api/screening/SCREENING_ID" \
  -H "X-API-Key: YOUR_API_KEY"

# Download the PDF once status is "completed"
curl -o report.pdf "https://adverseme.com/api/public-api/screening/SCREENING_ID/pdf" \
  -H "X-API-Key: YOUR_API_KEY"

# List screenings and check credits
curl "https://adverseme.com/api/public-api/screenings?page=1&limit=20" -H "X-API-Key: YOUR_API_KEY"
curl "https://adverseme.com/api/public-api/credits" -H "X-API-Key: YOUR_API_KEY"

JavaScript (Node 18+)

const BASE = "https://adverseme.com/api/public-api";
const headers = { "X-API-Key": process.env.ADVERSEME_API_KEY, "Content-Type": "application/json" };

// 1. Create
const created = await fetch(`${BASE}/screen`, {
  method: "POST",
  headers,
  body: JSON.stringify({ name: "Jane Example", entity_type: "person", country: "AE" }),
}).then((r) => r.json());
// { screening_id, status: "queued", message }

// 2. Poll until terminal
let result;
do {
  await new Promise((r) => setTimeout(r, 5000));
  result = await fetch(`${BASE}/screening/${created.screening_id}`, { headers }).then((r) => r.json());
} while (!["completed", "failed", "cancelled"].includes(result.status));

// 3. PDF (free)
const pdf = await fetch(`${BASE}/screening/${created.screening_id}/pdf`, { headers });
const bytes = Buffer.from(await pdf.arrayBuffer());

Errors and credits

What can go wrong, and what it costs

CodeMeaningWhat to do
400Bad requestEmpty or invalid JSON, missing name, or an entity_type that is not person or company. The error text says which.
401UnauthorizedThe X-API-Key header is missing or does not match an active key.
402Payment requiredNot enough credits for a new screening. Nothing was created; top up or change plan.
404Not foundThe screening id does not exist or belongs to another account, or the path is not one of the five endpoints.
500Server errorRetry later; the error body carries a message for support.
503PDF unavailableThe renderer is not reachable right now. Retry the PDF request later.

Every error is JSON of the form { "error": "field 'name' is required" }.

Credits. POST /screen costs 1 credit, deducted after validation so a rejected request is never charged. GET /screening, GET /screenings, GET /credits and the PDF are free.

Asynchronous by design. A screening queries 110+ sources and runs the AI council, so /screen returns at once with an id and you poll. The app shows the same screening with live progress.

Same result as the app. The results object is the one the app renders, including the per-source outcomes and dropped matches described under Engine Trace, and the PDF is the same file described under Reports.

Related

Keep reading

Create a key and make the first call.

Keys are issued in the app on every plan. One credit per screening, PDFs free.

Choose a plan See a sample report