Request

This page explains how to build a request to POST /v1/screen, the main endpoint for screening one subject. Batch sends that same subject inside subjects. Wallet sends one wallet value and has no options.

Endpoints

All requests must contain the following base URL:

Base URLhttps://api.sanctionslookup.com

All endpoints share a rate limit of 5 requests per second.

Method	Endpoint	Description
POST	`/v1/screen`	One person, company, vessel, or aircraft.
POST	`/v1/screen/batch`	Up to 50 subjects in one call.
POST	`/v1/screen/wallet`	One crypto wallet address.

Headers

Every request to all three endpoints must include Authorization and Content-Type.

Header	Value	Description
Authorizationrequired	`Bearer YOUR_API_KEY`	API authentication
Content-Typerequired	`application/json`	Request format

See the Authentication page for setup and trial access.

Body

The body has two objects: subject, which describes who or what you screen, and options, which controls how the screening runs. Only subject.name is required.

POSThttps://api.sanctionslookup.com/v1/screen

Authorization: Bearer YOUR_API_KEY

Content-Type: application/json

{

"subject": {

"name": "Kim Jong Un",

+ "subject_ref": "client_123", // Your internal id

+ "type": "INDIVIDUAL"

+ "options": {

+ "sources": ["ofac_sdn", "ofac_cons", "un_cons"] // Omit to screen every list

+ }

}

Replace YOUR_API_KEY with your key. New accounts get 100 free screenings. Get an API key →

What we suggest for production. subject_ref comes back in the response, so you can match results to your records. sources fixes the lists you screen, so your coverage only changes when you change it.

Added on top of Minimal

subject ·required

The fields below live inside subject. Validation pointers start at /subject, for example /subject/name.

Field	Description
namestringrequired	Subject name to screen.
subject_refstringoptional	Your internal identifier per subject. Returned in the response only when sent.
typestringoptional*	Subject type. INDIVIDUAL, ENTITY, VESSEL, AIRCRAFT, or CRYPTO. Omit it to search every party type. The response includes `subject_type` only when this field was sent.
identifiersarray of objectsoptional	Exact values. Each item is `{ "value": string }`. Examples are on the subject pages.
detailsobjectoptional	Extra fields for the chosen `type`. See the subject page for that type.

*Required when details is present.

options ·optional

Controls match filtering, which lists are searched, and response size. Omit sources to screen every list. Batch uses the same object.

Field	Default	Description
sourcesarray of stringsoptional	all lists	Lists to screen. Omit the field to screen every list. When present, only those lists are searched. Ids are in lists. The response `metadata.sources` uses the same ids, in that order. An unknown id or an empty array is rejected.
min_scoreintegeroptional	80	Minimum score threshold (0–100). Start with the default and increase it only for a specific reason.
max_resultsintegeroptional	10	Max matches returned for each subject (1–100). Start with the default and increase it only for a specific reason.
dob_penaltybooleanoptional	true	Default `true`: when `details.date_of_birth` is sent and the listed year conflicts by more than one year, the score is lowered. A matching year still raises it. Set `false` to leave a conflicting year out of the score. If no date of birth is sent, this field has no effect.

*If omitted, default values are applied automatically.

lists ·optional

Values for options.sources. The response metadata.sources uses these ids in this order.

id	list name
ofac_sdn	OFAC SDN List
ofac_cons	OFAC Consolidated Sanctions List
un_cons	UN Security Council Consolidated List
uk_sanc	UK Sanctions List
eu_cons	EU Consolidated Financial Sanctions List
ca_cons	Consolidated Canadian Autonomous Sanctions List
au_cons	DFAT Consolidated List
ch_cons	Swiss Sanctions List (SECO)

Identifiers

identifiers is optional on a subject. On a batch, the same field lives on each subjects[] entry. Validation pointers are /subject/identifiers and /subjects/0/identifiers.

Identifiers are exact values used to identify a subject. Provide one or more identifiers as an array of objects in the format { "value": "string" }. Examples include LEI (5493001KJTIIGC8Y1R12), tax ID (EE123456789), passport number (P1234567), DUNS (123456789), and VAT (EE12345678).

Attributes

Attributes are descriptive values that provide additional context about a subject, such as date of birth or country code. To use attributes, you must set the type, as attributes are type-specific. Including attributes helps improve match precision and reduce false positives.

See each subject type's attributes on its own page: Individual, Entity, Vessel, and Aircraft.

Updated on October 22, 2026