Screen | border.bot API docs

Screen a person or company against denied-party and sanctions lists with the border.bot API, with each possible match, the list that names it and why it matched, kept as evidence.

Screen checks a name, and a company if you give one, against denied-party lists: the US Consolidated Screening List, with OFAC's SDN list, the Entity List, the Denied Persons List and the other export-screening lists of Commerce, State and the Treasury. The Screen page explains how it works.

Endpoints#

Endpoint	What it does
`POST /v1/screen`	Screen one party
`GET /v1/screen/checks`	Your past checks, kept as evidence

Screen a party#

curl -X POST https://api.border.bot/v1/screen \
  -H "Authorization: Bearer $BORDERBOT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "name": "Northwind Maritime Holdings",
    "country": "AQ",
    "reference": "order-1042"
  }'

const response = await fetch('https://api.border.bot/v1/screen', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.BORDERBOT_TOKEN}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({
    "name": "Northwind Maritime Holdings",
    "country": "AQ",
    "reference": "order-1042"
  }),
});
const data = await response.json();

import os, uuid

import requests

response = requests.post(
    "https://api.border.bot/v1/screen",
    headers={"Authorization": f"Bearer {os.environ['BORDERBOT_TOKEN']}", "Idempotency-Key": str(uuid.uuid4())},
    json={
        "name": "Northwind Maritime Holdings",
        "country": "AQ",
        "reference": "order-1042",
    },
)
data = response.json()

<?php
$ch = curl_init('https://api.border.bot/v1/screen');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('BORDERBOT_TOKEN'),
        'Content-Type: application/json',
        'Idempotency-Key: ' . bin2hex(random_bytes(16)),
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'name' => 'Northwind Maritime Holdings',
        'country' => 'AQ',
        'reference' => 'order-1042',
    ]),
]);
$data = json_decode(curl_exec($ch), true);

name is required. company screens an employer or trading name too, country flags matches with an address there, type keeps only individual or entity parties, and reference is kept with the check.

What comes back#

Each possible match has its score (0 to 1; matches start at 0.7, and 1 is an exact match of a name or alias), the name that matched, the list that names the party (SDN, Entity List…), its kind and issuer, whether the country matched, and the listed party itself: its names, type, programmes, addresses, identifiers and source. A match is a lead to review, not a verdict.

JSON

{
  "data": {
    "matches": [
      {
        "score": 0.833,
        "matchedName": "Northwind Maritime Holdings",
        "query": "name",
        "list": "SDN",
        "listKind": "sanctions",
        "issuer": "US Treasury (OFAC)",
        "dataset": "US:parties",
        "countryMatch": true,
        "party": {
          "name": "Northwind Maritime Holdings",
          "altNames": [
            "NW Maritime"
          ],
          "type": "entity",
          "programs": [
            "EXAMPLE"
          ],
          "addresses": [
            {
              "address": "Port Example, AQ",
              "country": "AQ"
            }
          ],
          "sourceRef": "9001",
          "startDate": null,
          "endDate": null,
          "remarks": null,
          "sourceUrl": null,
          "identifiers": [],
          "countries": [],
          "birthDates": []
        }
      }
    ],
    "matchCount": 1,
    "searched": [
      {
        "dataset": "US:parties",
        "seq": 18
      }
    ],
    "screenedAt": "2026-10-20T09:30:00.000Z",
    "checkId": "01a15ac1-27d8-7ddf-b0bb-6c3fbe8bf828"
  },
  "credits": {
    "charged": 1,
    "remaining": 96,
    "usageId": "usg_01m5dc29tdkdmpffnd43jmg1w5"
  },
  "replayed": false
}

Costs and limits#

A check costs the screening price in credits (GET /v1/pricing), refunded if it fails. Up to 60 checks a minute per workspace. See credits and retries.

Also from#

MCP: screen_party (see MCP).
Free tool: denied-party screening, no account needed.