---
title: "Screen up to 50 names in one call"
method: POST
path: "/sanctions/screen"
tags: ["Sanctions"]
---

# Screen up to 50 names in one call

`POST /sanctions/screen`

## Request

- Base URL: `https://api.prometiam.com/functions/v1/risk-api`
- URL: `https://api.prometiam.com/functions/v1/risk-api/sanctions/screen`
- Auth: HTTP bearer

Batch form of `GET /sanctions/screen`. Send `items` (name plus optional dob, entity_type, country) or the shorthand `names`. Shared options `threshold`, `list`, `active_only`, `group` and `limit` (hits per name, default 10) apply to every item. Requires the sanctions scope: batch calls do not draw on the free trial allowance. Every item costs what the same single call costs (3 credits for a screened name) against the plan's per-minute, daily and monthly limits; a batch that does not fit is refused up front with 429 `batch_exceeds_quota` and `max_items_now`. Supports an optional `Idempotency-Key` header (see the parameter) for safe replay of the whole batch.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `items` SanctionsScreenItem[]
    - `name` string, required
    - `dob` string, date: Optional date of birth disambiguator (YYYY-MM-DD).
    - `entity_type` 'person' | 'company' | 'vessel' | 'aircraft' | 'unknown'
    - `country` string: Optional country/nationality filter.
  - `names` string[]: Shorthand for items without disambiguators.
  - `threshold` integer
  - `list` string: Comma-separated source lists, e.g. OFAC,EU
  - `active_only` boolean
  - `group` 'entity'
  - `limit` integer: Hits per name.

## Response `200`

Results in request order

- object
  - `data` SanctionsScreenBatchResult[]: One result per item, in request order.
    - `index` integer: Position of the item in the request array.
    - `input` object: The item as sent.
    - `error` string, nullable: Set when status is error or timeout.
    - `status` 'match' | 'clear' | 'error' | 'timeout': `clear` means no hit at or above the threshold on the active lists; it is not a certification.
    - `hits` SanctionsHit[]: Hits for this name, in the same shape as `GET /sanctions/screen` (grouped rows when `group=entity`).
      - `id` integer: Sanctions entity id. Use with GET /sanctions/entity/{id}.
      - `entity_name` string: Name as published by the source list.
      - `entity_type` 'person' | 'company' | 'vessel' | 'aircraft' | 'unknown': Values are literal. 'any'/'entity' are NOT stored values.
      - `aliases` string[], nullable
      - `country` string: Country as published. Often null.
      - `nationality` string
      - `date_of_birth` string, date, nullable
      - `date_of_birth_raw` string, nullable: Unparsed DOB string as published (may be a range or partial).
      - `date_of_incorporation` string, date, nullable
      - `identification_numbers` object, nullable: Passport / tax / registry numbers keyed by type.
      - `source_list` string: e.g. OFAC, EU, UN, or a US export-control list.
      - `program` string
      - `program_detail` string, nullable
      - `listing_date` string, date, nullable
      - `delisting_date` string, date, nullable
      - `is_active` boolean: False once delisted.
      - `notice_url` string, nullable: Link to the publishing authority's notice.
      - `match_score` integer: Fuzzy match confidence, 0-100.
      - `matched_name` string: The specific string that matched - the entity name or one alias.
      - `matched_on` 'name' | 'alias': Which field produced matched_name.
    - `hit_count` integer
    - `distinct_entities` integer
    - `best_match_score` integer, nullable
  - `meta` object
    - `items` integer
    - `errors` integer
    - `query_ms` integer
    - `note` string
    - `rate_limit` object
    - `matches` integer
    - `clear` integer
    - `threshold` string
    - `grouping` string

## Other responses

- `400`: Malformed body, empty items, more than the per-call maximum, or a malformed `Idempotency-Key` (`validation_error`).
- `403`: Scope not in the plan (`upgrade_required`). Batch calls do not draw on the free trial allowance.
- `409`: `idempotency_key_in_progress`: a request with this `Idempotency-Key` is still running. `Retry-After` says how long to wait.
- `422`: `idempotency_key_reuse`: this `Idempotency-Key` was already used with a different request body.
- `429`: `batch_exceeds_quota`: the batch has more items than the tightest active limit allows (credits or requests); `max_items_now` says how many fit.

---

[API](https://skmtc.dev/prometiam/apis/prometiam-risk-intelligence-api.md) · [All operations](https://skmtc.dev/prometiam/apis/prometiam-risk-intelligence-api/llms.txt) · [OpenAPI document](https://skmtc.dev/prometiam/apis/prometiam-risk-intelligence-api/revisions/3ee0626d5a45?raw)