Skip to main content
POST

​
Overview

Checks a name against the US Treasury’s list of Specially Designated Nationals and returns the entries that match. Each match has a score, the name that matched and the entry as the list publishes it. There are two routes, one for each kind of name: A company name never matches an individual’s entry, and the reverse. Both routes take the same request and return the same response; only tool differs (company_sanctions or person_sanctions). Results return in the response, with no polling.
A screening aid, not a legal determination. No match means no entry on the lists named scored at or above the minimum; it does not mean the party is clear.

​
Authentication

Requires x402 payment in the payment-signature header.

​
Request Body

​
string
required
The name to check, 2 to 200 characters, free text. Word order, accents and punctuation do not matter. A name of one word needs at least 3 letters.
​
number
The lowest score of a match to return, 0.5 to 1 (default 0.85). See What a score means.
​
integer
The most matches to return, highest score first (1 to 25, default 10). total counts every match at or above min_score, which may be more than limit.

​
What a score means

A score runs from 0.5 to 1 and says how closely the words of your name match the words of an entry’s name or of one of its other names (its aliases).
  • 1: the same words, in any order.
  • Below 1: a spelling variant, a missing or extra word, a missing middle name, or an initial in place of a name.
A higher score is a closer match, not a finding. Read matched_name and the entry’s remarks (dates of birth, places, identity numbers where the list gives them) before you act on a match. min_score sets the lowest score returned. Lower it to catch more spelling variants, at the cost of more matches that are not the party you mean. Raise it to 1 to see only the same words.

​
Response (200)

Top-level envelope: success (boolean) and data (object). All fields below are nested under data.
​
string
Durable job ID for audit and lookup
​
string
The receipt for the payment
​
string
Job status: completed
​
string
company_sanctions or person_sanctions
​
integer
How many entries scored at or above min_score. matches holds at most limit of them.
​
object[]
The matching entries, highest score first. Empty when nothing scored at or above min_score.
​
number
0.5 to 1, as described above
​
string
The name that scored: the entry’s own name or one of its other names, as the list writes it
​
object
The entry as the list publishes it: number, name (a person is written SURNAME, Given names), programs (the sanctions programs it is listed under), title, remarks, other_names (each with kind: aka, fka or nka, and name) and addresses (each with street, city and country)
​
object[]
Every list that was checked
​
string
The name of the list, for example US Treasury list of Specially Designated Nationals
​
string
The date and time of the list file the answer was read from (ISO 8601). Read it with every answer: a result is only as current as its as_of.
See Pricing for the price of a call.

​
No match

No match is a completed, charged result with total 0 and an empty matches. It means no entry on the lists named in lists scored at or above min_score. It does not mean the party is clear.

​
When the list is out of date

If a list has never been loaded, or its newest file is older than 72 hours, the call answers 503 with list_out_of_date and does not return a result from it. The response names the lists that are out of date. Try again later. When the check runs before payment, nothing is charged. When it is found after payment, the call is recorded as failed, the response carries its request_id and receipt_id, and a failed call is not charged.

​
Errors

  • 400 invalid_request: name is missing, too short, too long or has no letter or digit, or min_score or limit is out of range. Refused before payment.
  • 503 list_out_of_date: a list is out of date, as above.
  • 500 internal_error: the call failed. It is recorded as failed and is not charged.