---
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/export-screening`
- URL: `https://api.stratumapis.com/v1/export-screening/bulk`
- Auth: API key in header `X-Stratum-Key`

Each name can be a plain string, or an object with its own `country`, `type`, `minScore` and `reference`.
Top-level `type` and `minScore` are defaults for names that don't set their own; `country` goes on each name.
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
        - `country` string: Two-letter ISO 3166 code
        - `type` 'person' | 'entity' | 'any'
        - `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
    - `result` 'no_match' | 'possible_match', required
    - `count` integer, required: Number of possible matches at or above minScore
    - `matches` union[], required: Best first, from any of the lists screened
      - union
        - ExportMatch
          - `list` 'us_el' | 'us_dpl' | 'us_dtc' | 'us_uvl' | 'us_isn' | 'us_meu', required: `us_el` US Entity List, `us_dpl` Denied Persons List, `us_uvl` Unverified List, `us_meu` Military End User List (all BIS); `us_dtc` ITAR Debarred List, `us_isn` Nonproliferation Sanctions (both State Department)
          - `listLabel` string, required
          - `name` string, required: Name on the list
          - `aliases` string[]
          - `score` number, required: How closely the name matches (1.0 = exact). A possible match is something to review
          - `matchedAlias` string: The listed alias that matched
          - `addresses` object[]
            - `text` string: Street address and postal code
            - `city` string
            - `country` string: ISO 3166 code
          - `countries` string[]: ISO codes of every listed address
          - `countryMatch` 'match' | 'mismatch' | 'not_listed': Present when you sent a country. `not_listed` means the listing gives no address country.
          - `listedOn` string, date: When the party was listed
          - `endsOn` string, date: When a time-limited order ends (mainly Denied Persons orders)
          - `federalRegister` string: The Federal Register notice
          - `licenceRequirement` string: As the list states it
          - `licencePolicy` string: As the list states it, e.g. "Presumption of denial"
          - `programmes` string[]: Nonproliferation Sanctions programmes
          - `listingId` string: The Consolidated Screening List's id for the record
          - `sourceUrl` string, uri: The list's page at its publisher
          - `moreInfoUrl` string, uri
        - SanctionsMatch: The same fields as a match from the Sanctions Screening API, plus `listLabel`
          - `list` 'ofsi' | 'un' | 'eu' | 'ofac', required: `ofsi` is the UK Sanctions List (FCDO)
          - `listLabel` string, required
          - `name` string, required
          - `aliases` string[]
          - `type` 'person' | 'entity', required
          - `score` number, required
          - `matchedAlias` string
          - `dateOfBirth` string
          - `nationality` string
          - `sanctionRegime` string
          - `designationDate` string
          - `listingId` string
          - `sourceUrl` string, uri
    - `screenedWith` object, required: The inputs this screen used
      - `type` 'person' | 'entity' | 'any'
      - `minScore` number
      - `country` string
    - `listsScreened` ListScreened[], required: Each list this check covered, with both dates. Keep this with your record of the check.
      - `list` string, required: A list slug: ofsi, un, eu, ofac, or one of the export list slugs
      - `name` string, required
      - `listUpdated` string, date, nullable, required: When the publisher last changed the list. For the sanctions lists, their daily refresh date. `null` when the publisher's date was not in the file we read (never our own date in its place).
      - `weCheckedOn` string, date, required: When we last fetched the list
    - `listsNotScreened` ListNotScreened[], required: Any of the ten lists this check could not cover, and why. Empty when all ten were covered.
      - `list` string
      - `name` string
      - `why` string
    - `notice` string, required: The screening-record notice, for your record
  - `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_country`, `invalid_reference`, `unsupported_field`, `invalid_json`, `missing_names`, `too_many_names`, `per_name_field`. In `/bulk` the message names the item, for example `names[3].country ...`. A country we can't read is always refused, never silently ignored. `dateOfBirth`, `nationality` and `pepAndAdverseMedia` belong to the Sanctions Screening API and are refused here (`unsupported_field`).
- `401`: Missing, invalid or revoked API key (`missing_key`, `invalid_key`, `revoked_key`)
- `403`: The key belongs to a different Stratum API (`wrong_api`; a Sanctions Screening key does not work here), the account has no Export Controls Screening plan (`no_plan`), or the call came through RapidAPI, where this API is not listed (`not_on_rapidapi`)
- `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 export-control lists are not available right now (`export_lists_unavailable`), or the service timed out. Nothing was screened or charged: a screen is never answered from the sanctions lists alone. Treat the name as not yet screened and retry with backoff; do not treat it as clear.

---

[API](https://skmtc.dev/stratumapis/apis/export-controls-screening-api.md) · [All operations](https://skmtc.dev/stratumapis/apis/export-controls-screening-api/llms.txt) · [OpenAPI document](https://skmtc.dev/stratumapis/apis/export-controls-screening-api/revisions/19984f668877?raw)