API docs · Screen Terminal

Screening API

Quick start

curl -s https://screen.unbackoffice.com/v1/screen \
  -H "X-API-Key: $SCREEN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Vladimir Putin", "dob": "1952-10-07", "country": "RU"}'

Auth

Send your key in the X-API-Key header on every request. Keep it on your server. Never put it in a browser or mobile app. Base URL: https://screen.unbackoffice.com.

A key can call POST /v1/screen and POST /v1/screen/batch. Nothing else.

Request · `POST /v1/screen`

JSON body:

Field	Type	Required	Notes
`name`	string	yes	Full name to screen, in any script. (min 2, max 200)
`dob`	string	no	Date of birth — YYYY-MM-DD preferred; DD/MM/YYYY, '7 Oct 1952', YYYY-MM and YYYY are also accepted (max 32)
`country`	string	no	ISO-3166 alpha-2 (max 56)
`aliases`	array of string	no	extra name forms to screen (max items 8)

Send the name as written. Names in other scripts (Chinese, Arabic, Cyrillic, Korean and more) are converted to their standard Latin spellings and screened in both forms.

Response

{
  "result_band": "strong",
  "match_count": 1,
  "sanctions_band": "strong",
  "pep_band": "strong",
  "watchlist_band": "none",
  "matches": [
    {
      "person_id": "…",
      "name": "Vladimir Vladimirovich Putin",
      "country": "RU",
      "date_of_birth": "1952-10-07",
      "match_score": 1.0,
      "match_band": "strong",
      "risk_types": ["sanction", "pep"],
      "pep_classification": "sanctioned",
      "matched_on": ["name", "country", "dob"]
    }
  ],
  "dob_check": {"input": "1952-10-07", "status": "ok", "read_as": "1952-10-07", "note": null},
  "screened_at": "2026-10-08T09:30:00Z",
  "data_as_of": "2026-10-08T04:00:00Z"
}

Trimmed. Real responses carry more detail per match: the source, the explanation and the evidence.

Bands

strong: high-confidence match. Review it as a hit.
possible: partial match. Send it to an analyst.
weak: lower similarity, or a conflicting detail such as date of birth. Review per your policy.
none: no match.

Key fields

result_band: the highest band of any match, of any type.
sanctions_band, pep_band, watchlist_band: the highest band per risk type. Route on these, not on result_band. A sanctions hit can rank below a stronger PEP namesake.
by_type: per type (sanction, pep, rca, watchlist, debarment, soe, other) the band, count and top match.
matches[]: best first. Each has match_score (0 to 1), match_band, risk_types, pep_classification, matched_on and an explanation.
dob_check: how your date of birth was read. An unreadable date is ignored, never counted as a mismatch.
name_resolution: for names in other scripts, the script found and the Latin spellings used.
screened_at and data_as_of: when the screen ran and how fresh the lists were.

Sanctions are strict liability. Review every sanctions hit, at any band. Never clear one on date of birth alone.

Batch · `POST /v1/screen/batch`

Up to 50 names per call. Each item takes the same fields as /v1/screen.

curl -s https://screen.unbackoffice.com/v1/screen/batch \
  -H "X-API-Key: $SCREEN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"queries": [{"name": "Vladimir Putin", "country": "RU"}, {"name": "Jane Example"}]}'

Returns count, with_matches, with_sanctions_matches, with_pep_matches and results[], one result per name, in order.

Errors

Status	Meaning
`401`	Missing or invalid key, or the key was revoked.
`402`	Not enough screens left on this key. The body says how to get more (below).
`403`	This key can't call that endpoint.
`422`	Invalid request, for example a one-letter name or more than 50 names in a batch.
`429`	Too many requests per minute, for this key or from this IP. Wait and retry.
`503`	Temporarily unavailable. Retry shortly.

Errors come back as JSON with a detail field.

Quota

A free key has 100 screens. They don't expire or reset.
One screen is one name. A batch of 20 names uses 20 screens.
A batch is all or nothing: if the key can't cover every name, nothing is screened or charged.
Invalid requests (422) are not charged.
Get another 100-screen key for each new colleague who signs in through your referral link.
For more, pick a tier and message us on WhatsApp.

When a key runs out, you get 402:

{
  "detail": {
    "error": "quota_exhausted",
    "message": "This key has no screens left. Refer a colleague to get a new 100-screen key, or message us on WhatsApp to upgrade.",
    "screens_remaining": 0,
    "screens_needed": 1,
    "referral_url": "https://screen.unbackoffice.com/?ref=yourcode",
    "upgrade_url": "https://wa.me/…",
    "tiers_url": "https://screen.unbackoffice.com/tiers"
  }
}

Machine-readable spec: /openapi.json