> ## Documentation Index
> Fetch the complete documentation index at: https://docs.compliapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Batch screening

> Screen up to 50 subjects of mixed types in one request

Screens up to **50 subjects** in one call — crypto addresses, emails, websites, government IDs, countries and names, mixed freely. Each item is screened exactly as its own endpoint would screen it, and its result has that endpoint's shape. Use it to re-screen a customer base on a schedule, to check every counterparty on an invoice run, or to screen everything known about one customer at once.

**items** `object[]` *required*

1–50 subjects. Each item:

| Field | Description |
| - | - |
| `type` | `crypto`, `email`, `website`, `government_id`, `country`, `name`, `vessel` or `aircraft` — the same checks as [`/screen/crypto`](https://docs.compliapi.com/api/screen/crypto), [`/screen/email`](https://docs.compliapi.com/api/screen/email), [`/screen/website`](https://docs.compliapi.com/api/screen/website), [`/screen/id`](https://docs.compliapi.com/api/screen/id), [`/screen/country`](https://docs.compliapi.com/api/screen/country), [`/screen/name`](https://docs.compliapi.com/api/screen/name), [`/screen/vessel`](https://docs.compliapi.com/api/screen/vessel) and [`/screen/aircraft`](https://docs.compliapi.com/api/screen/aircraft) |
| `value` | The value to screen |
| `ref` | Optional. Your own reference for the subject (a customer or invoice id, up to 200 characters), returned with its result (and inside it) and recorded on its audit rows |
| `lists` | Optional. List slugs for this item, overriding the batch-level `lists` |
| `party_type`, `birth_date`, `country`, `id_number`, `threshold` | Optional, `name` items only — the same options as [`/screen/name`](https://docs.compliapi.com/api/screen/name)'s `type`, `birth_date`, `country`, `id_number` and `threshold` |

**lists** `string`

Comma-separated [list slugs](https://docs.compliapi.com/api/screen/lists.md) for every item (default: all enabled lists).

```bash Example request theme={null}
curl -X POST https://api.compliapi.com/api/v1/screen/batch \
  -H "Authorization: Bearer $COMPLIAPI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {"type": "name", "value": "Jane Example", "birth_date": "1980", "ref": "cust-1042"},
      {"type": "email", "value": "jane@example.com", "ref": "cust-1042"},
      {"type": "crypto", "value": "0x098B716B8Aaf21512996dC57EB0615e2383E2f96", "ref": "wallet-77"}
    ]
  }'
```

## Response

`results` holds one entry per item, in request order, with its `index`, your `ref`, `type`, `value` and a `status`:

* `ok` — `result` is exactly what the item's own endpoint returns: the [screening envelope](https://docs.compliapi.com/api/screen.md), or for `name` items the scored [`/screen/name` envelope](https://docs.compliapi.com/api/screen/name).
* `error` — the item's input was rejected (an unknown list slug, a malformed birth date, an unknown country…); `error` says why, and the item is **not** metered.

Top-level `screened` and `errors` count the two, and `flagged` / `sanctioned` are true when any screened item is.

```json Example response theme={null}
{
  "screened": 3,
  "errors": 0,
  "flagged": true,
  "sanctioned": true,
  "results": [
    {
      "index": 0, "ref": "cust-1042", "type": "name", "value": "Jane Example", "status": "ok",
      "result": { "value": "Jane Example", "flagged": false, "sanctioned": false, "lists_checked": ["ofac", "ofac_consolidated"], "threshold": 85, "excluded": 0, "matches": [] },
      "error": null
    },
    {
      "index": 1, "ref": "cust-1042", "type": "email", "value": "jane@example.com", "status": "ok",
      "result": { "value": "jane@example.com", "flagged": false, "sanctioned": false, "lists_checked": ["ofac", "ofac_consolidated"], "matches": [] },
      "error": null
    },
    {
      "index": 2, "ref": "wallet-77", "type": "crypto", "value": "0x098B716B8Aaf21512996dC57EB0615e2383E2f96", "status": "ok",
      "result": {
        "value": "0x098B716B8Aaf21512996dC57EB0615e2383E2f96", "flagged": true, "sanctioned": true, "lists_checked": ["ofac", "ofac_consolidated"],
        "matches": [{ "list": "ofac", "list_name": "US OFAC SDN", "list_type": "sanctions", "match": "exact", "value": "0x098B716B8Aaf21512996dC57EB0615e2383E2f96", "source_url": "https://sanctionssearch.ofac.treas.gov/Details.aspx?id=27307", "metadata": { "symbol": "ETH", "name": "Ethereum", "sdn_name": "LAZARUS GROUP" } }]
      },
      "error": null
    }
  ]
}
```

## Quota and billing

Each screened item is **one request** against your monthly quota; rejected items cost nothing. Before screening, the batch is checked against the requests remaining in your period: if they cannot cover every item, the whole batch is refused with `429` (`code: "QUOTA_EXCEEDED"`, the detail saying how many it needed and how many remain) and nothing is screened or charged — send a smaller batch or [upgrade](https://app.compliapi.com/dashboard/plans). Every screened item is written to your organization's audit trail like a single call.

Batch screening requires an [API token](https://docs.compliapi.com/authentication.md); it is not available with [x402 pay-per-request](https://docs.compliapi.com/payments.md), and PEP screening, VPN detection and geolocation are not batchable.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.