secuveriAPI docs
OpenAPIMarkdown

Screen one person against sanctions and PEP lists

POST/v1/aml/screen

Uses the same lists and scoring as the AML workflow step. Send Idempotency-Key to reuse a saved response and billing ID on retries, scoped to organization and environment. Encrypted responses are replayable for 24 hours from the first attempt; expired keys return 410 and cannot charge again. Without the header, every request is independent. At most 120 calls per minute per organization, including replays. Raw subject input is not stored.

Send your API key in the x-api-key header.

Headers

  • Idempotency-Keystring8–200 chars

    A unique identifier for this intended screening. Reuse on retries; printable non-space ASCII. Changed request details conflict. Generate a new key only for a new intended screening.

Request bodyapplication/jsonrequired

  • namestring2–200 chars
  • namesarray of string0–5 items

    Further spellings: aliases, maiden name.

  • date_of_birthstring

    YYYY-MM-DD.

  • nationalitystringpattern ^[A-Za-z]{3}$

    ISO alpha-3.

  • document_numberstring5–64 chars
  • include_pepsbooleandefault true
  • referencestring≤ 128 chars

    Your id; echoed back and included in the encrypted saved response when Idempotency-Key is used.

Responses

  • 200The screening.
    • screening_idstring
    • statestring

      One ofCLEARPOSSIBLE_MATCH

    • hitsarray of object
      Show 8 child properties
      • liststring

        One ofsecoeuunofacukpep

      • entry_idstring
      • kindstring
      • matched_namestring
      • scorenumber
      • breakdownobject
      • programsarray of string
      • listed_onstring | null
    • listsarray of object

      The list versions used.

    • include_pepsboolean
    • screened_atstringdate-time
    • referencestring
    • signed_resultstring

      The same answer as an ES256 JWS (typ aml_screening).

  • 400Invalid input.
  • 401Missing, unknown or expired API key.
  • 402The balance does not cover the screening.
  • 403The key lacks the scope this call needs, or its IP allowlist refuses the caller.
  • 409The same key is in progress (idempotency_in_progress, Retry-After: 1), conflicts with different request details, or its reservation was refunded.
  • 410The saved-response window expired; this key cannot create another charge.
  • 429More than 120 screenings in a minute.
  • 503A source list or matching capacity/worker is unavailable. Capacity errors return Retry-After: 1. Retry with the same Idempotency-Key; no charge is started for rejected matching work.
curl -X POST https://api-verify.secuveri.com/v1/aml/screen \
  -H "x-api-key: $SECUVERI_API_KEY" \
  -H "content-type: application/json" \
  -H "Idempotency-Key: signup-1042-retry-safe" \
  -d '{
  "name": "Jane Doe",
  "names": [
    "string"
  ],
  "date_of_birth": "1990-04-12"
}'
Response · 200
{
  "screening_id": "<screening id>",
  "state": "CLEAR",
  "hits": [
    {
      "list": "seco",
      "entry_id": "<entry id>",
      "kind": "<kind>",
      "matched_name": "Jane Doe",
      "score": 0.92,
      "breakdown": {},
      "programs": [
        "string"
      ],
      "listed_on": "<listed on>"
    }
  ],
  "lists": [
    {}
  ],
  "include_peps": true,
  "screened_at": "2026-10-23T09:12:44.120Z",
  "reference": "customer-1042",
  "signed_result": "eyJhbGciOiJFUzI1NiIsImtpZCI6Ii4uLiJ9.…"
}