# Screen a person or company (POST /v1/screen)

> POST /v1/screen: Screen a person or company. border.bot API reference (Compliance).

Source: https://border.bot/docs/api/screen-party

> Documentation index: https://border.bot/llms.txt. Every page is Markdown at its URL + `.md`.

`POST https://api.border.bot/v1/screen`

Requires an API key (`Authorization: Bearer bb_live_…`).

Check a name (and a company) against denied-party lists: the US Consolidated Screening List (the SDN list, the Entity List, the Denied Persons List and the other export-screening lists of Commerce, State and the Treasury). Names and aliases match exactly or fuzzily (from 0.7); each check is kept as your evidence. Free, up to 60 a minute per workspace. A match is a lead to review, not a verdict.

API key scope: `compliance`.

## Request body (JSON)

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | yes | The person’s or company’s name, as you have it. |
| `company` | string | no | A company to screen too (a buyer and their employer, say). |
| `country` | string | no | The party’s country (ISO-2): matches with an address, nationality or flag there are flagged `countryMatch`. |
| `type` | "individual" \| "entity" | no | Only parties of this type. Vessels, aircraft and parties of unknown type are always screened. |
| `reference` | string | no | Your reference (an order or customer id), kept with the check as evidence. |

## Responses

- `200`: The matches, best first, and the lists screened. (`ScreenResponse`)
- `400`: Invalid input (`invalid_input`). (`Error`)
- `401`: Missing, invalid, revoked or expired API key (`unauthorized`). (`Error`)
- `403`: The API key doesn’t have the `compliance` scope (`forbidden`, `details.reason: "missing_scope"`). (`Error`)
- `429`: Rate limited (`rate_limited`). Retry after `Retry-After` seconds; `RateLimit` says which limit was hit (`r=0`, `t` seconds until its window ends) and `RateLimit-Policy` its quota. (`Error`)
- `500`: Unexpected error (`internal`). (`Error`)

## Example

```bash
curl -X POST 'https://api.border.bot/v1/screen' \
  -H 'Authorization: Bearer bb_live_...' \
  -H 'Content-Type: application/json' \
  -d '{"name":"<string>"}'
```