---
title: "Screen up to 100 names in one request (one check per name)"
method: POST
path: "/bulk"
---

# Screen up to 100 names in one request (one check per name)

`POST /bulk`

## Request

- Base URL: `https://api.stratumapis.com/v1/sanctions`
- URL: `https://api.stratumapis.com/v1/sanctions/bulk`
- Auth: API key in header `X-Stratum-Key`

Each name can be a plain string, or an object with its own `type`,
`dateOfBirth`, `nationality` and `reference`, so an organisation and the
people responsible for it can go in one request. Top-level `type` and
`minScore` are defaults for names that don't set their own. If the
request would take you past your monthly limit it is refused whole
(429), with how many checks remain. A request answers within about
20 seconds: if names are left when time runs out, the response has
`incomplete: true` and lists them in `notScreened`; send those again.
Only screened names are charged.

## Request body

- object
  - `names` union[], required
    - union
      - string
      - BulkName
        - `name` string, required
        - `type` 'person' | 'entity' | 'any'
        - `dateOfBirth` string: YYYY-MM-DD or YYYY
        - `nationality` string: Two-letter ISO 3166 code
        - `reference` string
        - `minScore` number
  - `type` 'person' | 'entity' | 'any'
  - `minScore` number

## Response `200`

One screening result per name, in request order, each with its own `checkId`

- object
  - `count` integer, required: Names screened in this response
  - `results` ScreeningResult[], required
    - `checkId` string, required: Unique id for this screen. Keep it with your record; we keep no copy of the result.
    - `screenedAt` string, date-time, required: When the screen ran (UTC)
    - `reference` string: Your reference
    - `query` string, required: The name as screened
    - `count` integer, required: Number of possible matches at or above minScore
    - `matches` Match[], required
      - `list` 'ofsi' | 'un' | 'eu' | 'ofac', required: Which list the listing comes from. `ofsi` is the UK Sanctions List (FCDO); the slug predates OFSI's list closing in January 2026 and is kept for compatibility.
      - `name` string, required: Primary name on the list
      - `aliases` string[]
      - `type` 'person' | 'entity', required
      - `score` number, required: How closely the name matches (1.0 = exact), adjusted when you sent a date of birth or nationality: a same-day date of birth adds 0.05, a date of birth in a different year subtracts 0.15, a different nationality subtracts 0.05. A possible match is something to review, not a confirmed match.
      - `nameScore` number: Name similarity alone, before the adjustment. Present when you sent a date of birth or nationality.
      - `matchedAlias` string: The listed alias that matched
      - `dateOfBirth` string: Every date of birth the list publishes, as written there, separated by "; "
      - `dateOfBirthMatch` 'match' | 'partial' | 'mismatch' | 'not_listed': Present for person matches when you sent a date of birth. `match`: a listed date is the same day. `partial`: same year only (the list gives only a year or a range, or a different day). `mismatch`: every listed date is in another year. `not_listed`: the list gives none.
      - `nationality` string: Every nationality the list publishes
      - `nationalityMatch` 'match' | 'mismatch' | 'not_listed': Present for person matches when you sent a nationality
      - `sanctionRegime` string: e.g. "The Russia (Sanctions) (EU Exit) Regulations 2019", "CUBA"
      - `designationDate` string: As written by the list
      - `listingId` string: The list's own identifier for the listing
      - `sourceUrl` string, uri: Where to check the listing on the publisher's site
    - `screenedWith` object, required: The inputs this screen used
      - `type` 'person' | 'entity' | 'any'
      - `minScore` number
      - `dateOfBirth` string
      - `nationality` string
    - `listsScreened` string[], required: Each list screened, with the date it was last updated. Keep this with your record of the check.
    - `screenProvenance` string, required: One sentence naming the lists screened, suitable for an audit record
    - `listsSnapshotAt` string, date-time: When our copy of the lists was built from the publishers' files
  - `incomplete` boolean: Present and true when time ran out before every name was screened
  - `notScreened` object[]: The names not screened yet (with their position in the request); send them again
    - `index` integer
    - `name` string
  - `message` string

## Other responses

- `400`: Invalid input. `code` says which: `missing_name`, `invalid_name`, `invalid_type`, `invalid_date_of_birth`, `invalid_nationality`, `invalid_reference`, `invalid_json`, `missing_names`, `too_many_names`, `per_name_field`. In `/bulk` the message names the item, for example `names[3].dateOfBirth ...`. A date of birth or nationality we can't read is always refused, never silently ignored.
- `401`: Missing, invalid or revoked API key (`missing_key`, `invalid_key`, `revoked_key`)
- `403`: The key belongs to a different Stratum API (`wrong_api`), or it is an account key and the account has no plan for this API (`no_plan`)
- `429`: This month's limit is reached (`monthly_limit_reached`, at twice your plan's allowance) or the free trial's allowance is used (`trial_limit_reached`). Nothing was screened or counted. Treat the names as not screened. Screening resumes on the 1st of next month, on upgrading, or when we raise your limit.
- `500`: The screen did not complete. Treat the name as not yet screened and retry with backoff; do not treat it as clear.
- `503`: The service is temporarily unavailable or timed out. Treat the name as not yet screened and retry with backoff; do not treat it as clear.

---

[API](https://skmtc.dev/stratumapis/apis/uk-sanctions-screening-api.md) · [All operations](https://skmtc.dev/stratumapis/apis/uk-sanctions-screening-api/llms.txt) · [OpenAPI document](https://skmtc.dev/stratumapis/apis/uk-sanctions-screening-api/revisions/10ee3a7ee047?raw)