POST /screen/entity/batch

Screens a list of names in a single call: up to 200 names, settled with one x402 payment for the whole batch. Each item runs through the same engine as GET /screen/entity — the four designation lists in full, aliases included, every hit sourced to the list that published it.

One settlement for N names fits the job it exists for: onboarding a supplier book, clearing a payout list, re-screening a customer base after a lists update.

The batch is settled as one x402 payment for the whole call and priced per name by the gateway (the first name is roughly the price of the single call, then each additional name adds to the total) — see the live /catalog for the authoritative price.

x402 golden rule: the agent pays for the answer to its question. A well-formed batch is a successful answer → 200, even when some of its items are malformed (each flagged at its position) or matched (each with its own verdict). The 4xx range is reserved for requests the service cannot answer — missing or malformed body, empty list, batch over the cap. Those are never charged.

Scope and limits

Same as the single call: designation lists only, no cross-list reconciliation, no PEP screening, no adverse media, no risk score, and a no_hit is a dated statement rather than a clearance certificate. See GET /screen/entity.

Request

POST with a JSON body. Set Content-Type: application/json.

POST /screen/entity/batch
Content-Type: application/json

{
  "items": [
    { "name": "Europäisch-Iranische Handelsbank" },
    { "name": "Compagnie de Saint-Gobain" },
    { "name": "Kim Jong Un", "kind": "person", "birth_year": 1984 }
  ]
}

Each item takes a name (2 to 200 characters) plus the same optional per-item filters as the single endpoint — kind, country, birth_year.

include_weak is a batch-level flag on purpose. It states what you count as a signal — a caller policy — not a property of one name. Weak matches are returned in hits[] either way.

200 response — UnifiedResponse

{
  "data": {
    "count": 4,
    "summary": { "hit": 1, "weak_hit": 1, "no_hit": 1, "error": 1 },
    "results": [ ... ],
    "lists_screened": [
      { "list": "EU-FSF", "entities": 6017 },
      { "list": "OFAC-CONS", "entities": 481 },
      { "list": "OFAC-SDN", "entities": 19157 },
      { "list": "UN", "entities": 1011 }
    ],
    "limits": "Screening covers the designation lists and snapshot date reported above. …"
  },
  "provenance": {
    "source": "ofac-sdn+ofac-consolidated+eu-fsf+un-sc",
    "fetched_at": "2026-07-30T06:56:09Z",
    "freshness": { "kind": "snapshot", "as_of": "2026-07-28T00:00:00Z" }
  }
}

lists_screened, limits and provenance are stated once for the batch: every item was screened against the same snapshot in the same call.

A successful item

Same shape as the single call’s data, minus the batch-level fields, plus its index: query, verdict, verdict_basis, hits, total_matches, truncated. The 50-hit cap applies per item.

{
  "index": 0,
  "query": {
    "name": "Europäisch-Iranische Handelsbank",
    "normalized": "europaisch iranische handelsbank"
  },
  "verdict": "hit",
  "verdict_basis": ["exact", "exact_alias"],
  "hits": [
    {
      "id": "OFAC-SDN:25684",
      "list_source": "OFAC-SDN",
      "kind": "entity",
      "matched_name": "EUROPAISCH-IRANISCHE HANDELSBANK AG",
      "match_type": "exact",
      "programs": ["IFSR", "IRAN", "NPWMD"],
      "listed_on": "2018-11-05"
    },
    {
      "id": "EU:EU.13742.32",
      "list_source": "EU-FSF",
      "kind": "entity",
      "matched_name": "Europäisch-Iranische Handelsbank",
      "match_type": "exact_alias",
      "programs": ["IRN"],
      "listed_on": "2025-09-29"
    }
  ],
  "total_matches": 2,
  "truncated": false
}

A malformed item

Flagged at its position, without failing the batch. The codes are the single endpoint’s.

{
  "index": 3,
  "error": "parameter 'name' must be between 2 and 200 characters once whitespace is collapsed",
  "code": "INVALID_INPUT"
}

Full example

The body

{
  "items": [
    { "name": "Europäisch-Iranische Handelsbank" },
    { "name": "Compagnie de Saint-Gobain" },
    { "name": "Melli Bank Investment Holding" },
    { "name": "A" }
  ]
}

returns count: 4 and summary: { "hit": 1, "weak_hit": 1, "no_hit": 1, "error": 1 } — the bank a hit on two lists, Saint-Gobain a no_hit, the Melli holding a weak_hit on two partial_tokens matches, and the one-character name an INVALID_INPUT at index 3.

Sending the same body with "include_weak": true moves the third item from weak_hit to hit, and the summary to { "hit": 2, "weak_hit": 0, "no_hit": 1, "error": 1 } — with identical hits[].

Errors

{ "error": "batch too large: at most 200 names are allowed per request", "code": "BATCH_TOO_LARGE" }

See also

• GET /screen/entity — the single call, with the full field reference and the match-type semantics.
• POST /screen/address/batch — the same batch shape for crypto addresses.
• For agents — discovery surfaces, the live /catalog and how settlement works.