Our screening API never returns a match score. Here are the three responses it does return

POST /api/v1/search with an X-API-Key header and a JSON body containing entity_name. It answers 202 with a search_id — never with a result, because one check runs across the whole source register. Poll GET /api/v1/search/{search_id} until status is completed, then read the per-source fields. Each of those fields is a short finding whose first line is a Status: Sanctioned, Potential PEP match, Potential watchlist match or No relevant listing found. There is no numeric score in the response and no threshold in the request. What you design instead is a review policy: which statuses enter your review queue, and who signs the disposition.

curl -X POST https://screenveritai.com/api/v1/search \
  -H "X-API-Key: svai_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
        "entity_name": "Example Trading Ltd",
        "entity_type": "company",
        "search_type": "sanctions_check",
        "language": "en"
      }'

Read that table once and the design is plain: the name is the query. Everything else is metadata you will be glad to have in your own audit trail. There is one trap in that generosity: unknown JSON keys are ignored rather than rejected, so a misspelled field name fails silently. Validate the payload on your side.

The answer is immediate and content-free:

{
  "search_id": "3f7c2a51-9b4e-4c8a-8d21-6f0e4b7a55d3",
  "status": "processing",
  "message": "Search queued successfully. Poll the GET endpoint for results.",
  "estimated_time_seconds": 15
}

estimated_time_seconds is a fixed hint derived from the search type — 15 for sanctions_check, 20 for adverse_media, 30 for full_search, 1,800 for deep_research_report. It is a scheduling hint, not a measurement and not a service level. Use it to size your first sleep, not your timeout.

curl https://screenveritai.com/api/v1/search/3f7c2a51-9b4e-4c8a-8d21-6f0e4b7a55d3 \
  -H "X-API-Key: svai_your_key_here"

The whole client rule is one line: poll until status == "completed" or status.startswith("error_"). All five documented failure statuses begin with error_. A prefix test also catches any new failure status that follows the same naming; a hard-coded list of the five would not. Polling counts against your rate limit, so start at the ETA and back off.

Trimmed to the fields that carry meaning; the real body repeats the same shape for every jurisdiction. The field names and status words in the three responses are the API's own. The names, references, dates and URLs are invented examples.

{
  "id": "3f7c2a51-9b4e-4c8a-8d21-6f0e4b7a55d3",
  "entity_name": "Example Person 01",
  "entity_type": "person",
  "status": "completed",
  "search_type": "sanctions_check",
  "ofac_sanctions": "## OFAC Sanctions Findings\n\n**Status:** *No relevant listing found*\n\n**Details:**\n- No relevant listing was found in this source for the searched entity.\n\n**Source:** *OFAC Sanctions*",
  "eu_sanctions": "## EU Sanctions Findings\n\n**Status:** *No relevant listing found*\n\n...",
  "uk_sanctions": "...", "un_sanctions": "...",
  "criminal_watchlists": null,
  "pep": null,
  "sanctions_sources": [
    { "source_id": "ofac_sanctions", "title": "OFAC Sanctions", "authority": "Office of Foreign Assets Control", "details": "...", "hit_count": 0 },
    { "source_id": "eu_sanctions", "title": "EU Sanctions", "authority": "", "details": "...", "hit_count": 0 }
  ],
  "created_at": "2026-09-04T09:12:41.882431+00:00",
  "completed_at": "2026-09-04T09:12:57.114902+00:00"
}

There is one field per main jurisdiction — ofac_sanctions, eu_sanctions, uk_sanctions, un_sanctions, pl_sanctions, fr_sanctions, canada_sanctions, australia_sanctions, switzerland_sanctions, south_africa_sanctions and new_zealand_sanctions — and each one is a short Markdown finding written for a person to read. A source that was screened and found nothing still returns a field, and that distinction carries weight. Absence of a field means the source was not part of that run; a no-hit finding means it was.

sanctions_sources is the machine-readable twin of those strings, and the one you should branch on: one object per screened source with a hit_count on each, covering the 11 main jurisdictions and the additional registers behind them. sum(hit_count) is your alarm; the 11 strings are for the human. additional_sanctions_sources carries the same objects for the non-jurisdiction registers only, and exists for older clients. criminal_watchlists and pep come back null when nothing matched — those two domains report findings and nothing else, so a null is the no-hit case and any non-empty string is something to read. completed_at, paired with created_at, is what you store as the evidence timestamp.

Store this. Do not label it. "No relevant listing found in the checked sources on 4 September 2026" is a defensible sentence; "clear" is a claim about the world that a name lookup cannot support.

{
  "entity_name": "Example Trading Ltd",
  "status": "completed",
  "search_type": "sanctions_check",
  "ofac_sanctions": "## OFAC Sanctions Findings\n\n**Status:** *Sanctioned*\n\n**Details:**\n- **Matched entity:** EXAMPLE TRADING LTD\n- **Identification:** 51234; EXAMPLE TRADING LIMITED; EXAMPLE TRD\n- **Justification:** Acting for or on behalf of a designated entity.\n- **Measures:** SDGT\n- **Dates:** 2026-08-26\n- **Authority:** Office of Foreign Assets Control\n- **Evidence URL:** https://sanctionssearch.ofac.treas.gov/Details.aspx?id=99999\n\n**Source:** *Office of Foreign Assets Control*",
  "sanctions_sources": [
    { "source_id": "ofac_sanctions", "title": "OFAC Sanctions", "authority": "Office of Foreign Assets Control", "details": "...", "hit_count": 1 }
  ]
}

Unescape that string and you get a short structured finding. Every line in it is an instruction:

An exact hit on a sanctions list is not a decision you take alone. It is a freeze-and-escalate event under your own procedure, and the evidence URL plus the identification reference are what your report to the competent authority will be built from.

This is the response that consumes your week: the name matches, the identity does not resolve.

{
  "entity_name": "A. Example",
  "status": "completed",
  "search_type": "sanctions_check",
  "ofac_sanctions": "## OFAC Sanctions Findings\n\n**Status:** *No relevant listing found*\n\n...",
  "pep": "## PEP Findings\n\n**Status:** *Potential PEP match*\n\n**Details:**\n- **Matched entity:** A. Example\n- **Identification:** Andrzej Example; 1971; pl\n- **Datasets:** Poland Public Officials Register\n\n**Source:** *Poland Public Officials Register*",
  "criminal_watchlists": null
}

Read the status words literally. A sanctions finding says Sanctioned — an assertion about a register. PEP and criminal-watchlist findings say Potential PEP match and Potential watchlist match — an assertion about a resemblance. That word "potential" is the API telling you, in the only vocabulary it has, that this is a candidate and not a conclusion.

What you have here is an initial for a given name, a birth year rather than a date, and a country. What you do not have is a person. The next step is not a threshold; it is three cheap identity checks: whether the customer's recorded date of birth contradicts 1971, whether the register entry's role fits the customer's profile, and whether the dataset publishes an identifier your KYC file also holds. Two contradictions close it as a false positive. One agreement and one gap keep it open.

The retrieval layer does compute similarity internally. It is not returned, and that is deliberate: a number without the reasoning behind it is a decision you cannot defend and a control you cannot calibrate. Print a score and every review meeting turns into an argument about the score.

There is exactly one numeric threshold in the pipeline, and it runs the other way. Full Search adds a review stage over the candidates, and a candidate is removed only when the review is at least 0.95 confident it is a false positive and can write the reason. Everything below that bar stays in front of you, reason attached.

So the threshold you choose is a policy, not a parameter. The queues and targets below are our recommendation, not a rule from any regulator; set your own:

A screening result is not an audit artefact until a human has written what it means. Store one disposition row per candidate, not per search:

The rationale field is the whole point. An examiner does not ask what your tool scored; they ask why this candidate was closed, and a stored sentence answers that three years later when the analyst has left.

An intentional re-screen uses a fresh Idempotency-Key and creates a new search_id with its own billing and dated result. If the request times out, retry with the same key and payload to recover that search instead of starting another paid run. A changed payload under an existing key is a conflict. Key your scheduling queue on (subject_id, list_version) so a subject is re-screened once per data change rather than once per cron tick.

GET /api/v1/coverage gives you the version signal:

{
  "status": "ok",
  "checkedAt": "2026-09-04T09:20:03.418662+00:00",
  "domains": {
    "sanctions": { "domain": "sanctions", "expected_tables": 51, "available_tables": 51, "tables": ["…"], "latest_updated_at": "2026-09-04T04:11:52+00:00" },
    "criminal_watchlists": { "domain": "criminal_watchlists", "available_tables": 16, "tables": ["…"], "latest_updated_at": "2026-09-03T22:40:07+00:00" },
    "pep": { "domain": "pep", "available_tables": 2, "tables": ["…"], "latest_updated_at": "2026-09-01T03:15:44+00:00" }
  }
}

Counts and timestamps above are illustrative — call the endpoint for the live ones. The field that matters is latest_updated_at, and it is per domain because sanctions, criminal watchlists and PEP refresh on different cadences. When latest_updated_at for a domain moves past the timestamp of a stored snapshot, that snapshot is stale by definition. At €0.39 per check with search_type: sanctions_check, a 2,000-name book re-screened after a list movement costs €780. That is the number to put next to the cost of explaining a missed designation, not next to the cost of doing nothing.

There is no official client library in any language, no webhooks and no callbacks. Polling is the only delivery mechanism and 202 is the only success response to a POST, so a working integration is one POST, one polling loop and one row of storage. There is no verdict field either. The response hands you a status per source, and the match/review/clear rollup is yours to compute and yours to own. There is no score, no threshold parameter and no "confidence" key. Errors arrive as a flat envelope, {"error": …, "message": …, "status_code": …}: 401 for a missing or invalid key, 403 for a key lacking search:write or search:read, and 429 with Retry-After when you outrun your tier.

None of that is a gap to apologise for. A short integration is one your successor can still read. What you should insist on — from ScreenVeritAI or from anyone else — is what the three responses above name: the list, the reference, the measures, the date and the authority's own URL. The human who signs the disposition needs something to decide with.

Screening supports compliance review and due diligence documentation. The disposition remains yours.