# Sanctions Screening (`sanctions.screen`)

Screen a person, company or vessel name against the US Consolidated Screening List (Treasury, Commerce and State lists) and get clear, possible match or match, with list, programs and country for every hit.

Docs: https://primaryapi.com/docs/api-reference/sanctions/screen

- Endpoint: `POST https://api.primaryapi.com/v1/run/sanctions.screen`
- Category: Compliance & Records · Platform: `sanctions` · Kind: validation · Status: live
- Price: 1 credit per call. Every call costs the same, including calls that were retried automatically.
- Billing unit: per successful call
- Reliability: routed to a healthy upstream and retried automatically when an attempt fails; live 30-day status: `GET https://api.primaryapi.com/v1/status/apis?sku=sanctions.screen`
- Execution: synchronous (answers 202 only if it outlives the wait window)

## Input

| Field | Type | Required | Default | Constraints | Description |
|---|---|---|---|---|---|
| `name` | string | yes |  | max 150 chars | Name of the person, company or vessel to screen, 2-150 characters with at least one Latin letter. |
| `country` | string | no |  | pattern: ^[A-Za-z]{2}$ | Optional ISO 3166-1 alpha-2 country code, e.g. "RU": ranks matches from that country first and never removes a match. |
| `type` | enum | no |  | one of: person, entity, vessel | Only records of this type (records without a type always stay in). Omit to screen every record type. |

Unknown fields are rejected with `400 invalid_input`. The routing controls `preferLatencyUnderMs` and `maxCredits` may be sent in the same JSON body.

## Output

When `output.found` is `true`, `output.data` has this shape:

| Field | Type | Description |
|---|---|---|
| `screened` | boolean |  |
| `outcome` | enum | match = at least one strong match |
| `nameSearched` | string |  |
| `countrySearched` | string \| null |  |
| `typeSearched` | enum \| null |  |
| `hitCount` | integer | Records scoring at or above the possible-match threshold |
| `strongMatchCount` | integer |  |
| `possibleMatchCount` | integer |  |
| `listsWithHits` | string[] | List codes with at least one hit |
| `topMatchName` | string \| null |  |
| `topMatchList` | string \| null |  |
| `topMatchPrograms` | string[] |  |
| `listsChecked` | integer | Source lists in the screened copy (12 for the full US Consolidated Screening List) |
| `recordsChecked` | integer |  |
| `listUpdated` | string \| null | When the screened list copy was published (ISO-8601) |
| `listIsStale` | boolean | The list copy is older than 3 days (a stale copy never reports "clear") |
| `coverage` | enum | us_csl = all US Consolidated Screening List sources; treasury_only = OFAC SDN + non-SDN only (fallback) |
| `matches` | object[] | Top 10 hits, strong first, then country matches, then score |
| `matches[].matchStrength` | enum | strong = score >= 0.93; possible = 0.80-0.93 |
| `matches[].matchedName` | string | The listed name or alias that matched best |
| `matches[].matchedOn` | enum |  |
| `matches[].score` | number | Name similarity 0-1 (token Jaro-Winkler, our matcher) |
| `matches[].countryMatch` | boolean | The record lists the requested country |
| `matches[].name` | string | Primary listed name |
| `matches[].recordType` | string \| null | Individual, Entity, Vessel, Aircraft or null (some lists carry no type) |
| `matches[].listCode` | string | Source list code, e.g. SDN, EL, DPL, NON-SDN |
| `matches[].listName` | string |  |
| `matches[].agency` | string \| null | Publishing agency, e.g. "Treasury Department" |
| `matches[].programs` | string[] | Sanctions programs, e.g. ["CUBA"] |
| `matches[].countries` | string[] | ISO-2 codes on the Consolidated Screening List; country names on the OFAC files |
| `matches[].addresses` | string[] |  |
| `matches[].datesOfBirth` | string[] |  |
| `matches[].aliases` | string[] | Up to 20 listed aliases |
| `matches[].listedSince` | string \| null |  |
| `matches[].listUrl` | string \| null | Official source list page |

When the thing you asked about does not exist (or a search matches nothing) the call still succeeds: `output.found` is `false`, `output.data` is `null` and `output.reason` says why (`not_found`, `private`, `no_results`, …). Misses are free unless the notes below say misses are billed.

## Example request

```bash
curl -sS -X POST "https://api.primaryapi.com/v1/run/sanctions.screen" \
  -H "Authorization: Bearer $PRIMARYAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Banco Nacional de Cuba"}'
```

## Example response

_Values are placeholders that follow the output schema; `credits` is what this call would cost at the usual price._

```json
{
  "output": {
    "found": true,
    "data": {
      "screened": true,
      "outcome": "match",
      "nameSearched": "Banco Nacional de Cuba",
      "countrySearched": null,
      "typeSearched": null,
      "hitCount": 1,
      "strongMatchCount": 1,
      "possibleMatchCount": 0,
      "listsWithHits": [
        "SDN"
      ],
      "topMatchName": "BANCO NACIONAL DE CUBA",
      "topMatchList": "SDN",
      "topMatchPrograms": [
        "CUBA"
      ],
      "listsChecked": 12,
      "recordsChecked": 26186,
      "listUpdated": "2026-10-30T22:15:00.000Z",
      "listIsStale": false,
      "coverage": "us_csl",
      "matches": [
        {
          "matchStrength": "strong",
          "matchedName": "BANCO NACIONAL DE CUBA",
          "matchedOn": "name",
          "score": 1,
          "countryMatch": false,
          "name": "BANCO NACIONAL DE CUBA",
          "recordType": "Entity",
          "listCode": "SDN",
          "listName": "Specially Designated Nationals",
          "agency": "Treasury Department",
          "programs": [
            "CUBA"
          ],
          "countries": [
            "CH",
            "ES",
            "JP",
            "PA"
          ],
          "addresses": [
            "Zweierstrasse 35, Zurich, CH-8022, CH",
            "Avenida de Concha Espina 8, Madrid, E-28036, ES",
            "Dai-Ichi Bldg. 6th Floor, 10-2 Nihombashi, 2-chome, Chuo-ku, Tokyo, 103, JP",
            "Federico Boyd Avenue & 51 Street, Panama City, PA"
          ],
          "datesOfBirth": [],
          "aliases": [
            "BNC",
            "NATIONAL BANK OF CUBA"
          ],
          "listedSince": null,
          "listUrl": "https://sanctionslist.ofac.treas.gov/Home/SdnList"
        }
      ]
    }
  },
  "provider": "PrimaryAPI",
  "credits": 1,
  "items": 1,
  "requestId": "req_01JBXK6Y2N9V8T4R3Q2P1M0A7Z"
}
```

## Pricing and reliability

- Usual price: 1 credit per call
- Price ceiling: the usual price, even when a call is retried. A quote’s `maxCredits` is the most a given call can cost; the `maxCredits` routing control caps it per call
- Live 30-day status, success rate, uptime and latency: `GET https://api.primaryapi.com/v1/status/apis?sku=sanctions.screen`

## Errors to handle

`invalid_input`, `unauthorized`, `insufficient_balance`, `key_limit_reached`, `trial_cap_reached`, `forbidden`, `not_found`, `idempotency_conflict`, `rate_limited`, `all_sources_failed`, `service_unavailable`, `timeout`. See https://primaryapi.com/docs/errors.

## Notes

Fuzzy name matching in process against list copies refreshed every 6 hours: score >= 0.93 is a strong match, 0.80-0.93 a possible match (our thresholds); legal forms (Inc, LLC, PJSC…) and word order are ignored, the country only ranks. Every answer carries listUpdated and recordsChecked; a copy older than 3 days never answers "clear" (the call fails over instead). A clear screening is a billable answer. No UN/UK/EU lists yet.

## Legal

Screening aid only: a possible or strong match needs analyst review against the official agency lists before acting, and a "clear" result is not a compliance determination. US sanctions apply strict liability and also cover entities 50% or more owned by listed persons, which no list contains. Names of natural persons are processed: send only what the screening needs.

