API Reference

Programmatically screen names against global sanctions lists with explainable results and evidence. Use your API key in the Authorization header. See Authentication for key management and server-only secrets.

Quickstart Authentication

Overview

Base URL

https://your-domain.com

Version

Content-Type

application/json

Required headers

Authorization: Bearer <YOUR_API_KEY>
Content-Type: application/json
Idempotency-Key: <uuid>          # recommended for POST for safe retries

Idempotency: Send a unique Idempotency-Key on POST requests. We will coalesce exact duplicates within a window and return the same result.

POST /api/v1/screen

Screen one or more names. Returns potential matches with confidence, human-readable reasons, and structured evidence (aliases, identifiers, addresses, source links).

Request body

POST /api/v1/screen
{
  "names": string[],                 // required unless "policyQuery" is used
  "entityTypes": string[] | null,    // optional: ["individual","entity","vessel","aircraft","wallet"]
  "sources": string[] | null,        // optional subset of source keys (see list below). default: all enabled
  "policyQuery": {                   // optional policy-only filter; if provided with empty "names", zero units consumed
    "countries": string[] | null,    // e.g. ["US","EU","UK","CH","CA","AU"]
    "programCodes": string[] | null, // e.g. ["SDGT","SDN","UKR","BELARUS"]
    "keywords": string[] | null      // free-text program/list keywords
  },
  "options": {                       // optional knobs (sensible defaults)
    "maxMatchesPerName": number,     // default 10
    "threshold": number,             // 0..1; default calibrated internal
    "returnRaw": boolean             // include full raw source entry in each match.evidence.raw
  }
}

Supported `entityTypes`

individual
entity
vessel
aircraft
wallet (for blockchain screening, if enabled)

Response

200 OK
{
  "results": [
    {
      "input": "Ali Hassan",
      "isSanctioned": true | false,
      "matches": [
        {
          "source": "EU Sanctions list",
          "sourceKey": "eu",
          "dataset": "EU (FSF)",
          "entityType": "individual",
          "matchedName": "Ali Hassan",
          "matchScore": 0.93,        // 0..1 (1.00 = exact)
          "level": "🟢 Very high confidence",
          "reason": "Exact name match + DOB match + alias overlap",
          "detailsList": [
            { "label": "Date of birth", "value": "1971-05-20" },
            { "label": "Citizenship", "value": "IR" }
          ],
          "evidence": {
            "primaryName": "Ali Hassan",
            "aliases": ["Hassan Ali", "Ali al-Hassan"],
            "identifiers": { "Passport": ["IR12345"] },
            "addresses": ["Tehran, Iran"],
            "nationality": "IR",
            "programs": ["EU-IR"],
            "dates": {
              "Date of birth": "1971-05-20",
              "Date listed": "2012-11-10"
            },
            "sourceUrls": ["https://.../eu_sanctions/entry/123"]
          },
          "raw": { /* optional, if options.returnRaw=true */ }
        }
      ]
    }
  ],
  "policyMatches": [
    /* if policyQuery provided without names */
  ],
  "scannedSources": ["ofac_sdn","eu","uk","un","ch","au","ca"],
  "unavailableSources": [],
  "meta": { "tookMs": 124, "tenantId": "org_abc", "planKey": "pro" }
}

Examples

cURL Node (fetch)Python (requests)

curl -X POST https://your-domain.com/api/v1/screen \
  -H "Authorization: Bearer $MATCHAUDIT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "names": ["Vladimir Putin"], "entityTypes": ["individual"] }'

export async function screen(names) {
  const res = await fetch("https://your-domain.com/api/v1/screen", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.MATCHAUDIT_API_KEY}`,
      "Content-Type": "application/json",
      "Idempotency-Key": crypto.randomUUID()
    },
    body: JSON.stringify({ names, entityTypes: ["individual"] })
  });
  if (!res.ok) throw new Error(`Screen failed: ${res.status}`);
  return res.json();
}

import os, uuid, requests
resp = requests.post(
  "https://your-domain.com/api/v1/screen",
  headers={
    "Authorization": f"Bearer {os.getenv('MATCHAUDIT_API_KEY')}",
    "Content-Type": "application/json",
    "Idempotency-Key": str(uuid.uuid4())
  },
  json={"names": ["Vladimir Putin"], "entityTypes": ["individual"]},
  timeout=30
)
print(resp.json())

Field glossary

Field	Type	Description
results[].matches[].matchScore	number (0..1)	Normalized similarity score; 1.00 is exact.
results[].matches[].level	string	Calibrated confidence band (emoji + label).
results[].matches[].reason	string	Human-readable justification for the hit.
results[].matches[].detailsList	array	Flattened key facts shown in the UI (DOB, citizenship, etc.).
results[].matches[].evidence	object	Structured evidence (aliases, identifiers, programs, dates, URLs).
scannedSources	string[]	Which datasets were actually scanned for this request.
unavailableSources	string[]	Datasets temporarily unavailable during the request.
meta.tookMs	number	Processing time in milliseconds.

Source keys

Key	Label / Dataset
ofac_sdn	US OFAC – SDN
ofac_non_sdn	US OFAC – Non-SDN
us_consolidated	US Treasury – Consolidated
uk	UK OFSI / UK Sanctions List
eu	EU (FSF)
un	UN Consolidated
ch	Switzerland (SECO)
au	Australia (DFAT)
ca	Canada (GAC)
bis_entity	US BIS – Entity List
bis_dpl	US BIS – Denied Persons
bis_uvl	US BIS – Unverified List
ddtc_itar	US State/DDTC – ITAR Debarred

Pass any subset in sources. If omitted, we scan all enabled datasets for your tenant/plan.

Limits & rate-limiting

Per-request names (Free)

Per-request names (Pro)

200

RPS

Plan-based (burst-friendly)

On 429 rate_limited or 503 unavailable, retry with exponential backoff.
Use Idempotency-Key on POSTs to make retries safe.

GET /api/v1/usage/summary

Returns current-month usage for a tenant (organization). Requires a server-only bearer secret (API_AUTH_SECRET). Do not call from browsers.

Query parameters

Param	Type	Required	Description
tenantId	string (uuid)	Yes	Tenant/organization ID to fetch usage for.
planKey	string	Yes	Your plan key (e.g., free, pro, business, hv).

Request

GET /api/v1/usage/summary?tenantId=<uuid>&planKey=pro
Authorization: Bearer <API_AUTH_SECRET>

Response

200 OK
{
  "planKey": "pro",
  "included": 3000,
  "used": 123,
  "remaining": 2877,
  "periodStartIso": "2025-10-01T00:00:00.000Z",
  "periodEndIso":   "2025-11-01T00:00:00.000Z"
}

Errors

400 bad_request

Body must be valid JSON

400 no_names

Provide at least one name (unless policy-only)

400 too_many_names

Exceeded per-request cap for your plan

401 unauthorized

Invalid/missing API key

403 forbidden

Key not allowed for endpoint/tenant

429 rate_limited

Too many requests/second; retry with backoff

429 limit_exceeded

Monthly allowance reached (tenant-wide)

500 engine_failed

Screening engine not available

503 unavailable

Temporary outage; retry with backoff

Tip: Keep API keys out of browser code. If you must call from the client, proxy via your server and enforce per-tenant quotas.

API Reference

Quickstart Authentication

Overview

Base URL

https://your-domain.com

Version

Content-Type

application/json

Required headers

Authorization: Bearer <YOUR_API_KEY>
Content-Type: application/json
Idempotency-Key: <uuid>          # recommended for POST for safe retries

Idempotency: Send a unique Idempotency-Key on POST requests. We will coalesce exact duplicates within a window and return the same result.

POST /api/v1/screen

Screen one or more names. Returns potential matches with confidence, human-readable reasons, and structured evidence (aliases, identifiers, addresses, source links).

Request body

POST /api/v1/screen
{
  "names": string[],                 // required unless "policyQuery" is used
  "entityTypes": string[] | null,    // optional: ["individual","entity","vessel","aircraft","wallet"]
  "sources": string[] | null,        // optional subset of source keys (see list below). default: all enabled
  "policyQuery": {                   // optional policy-only filter; if provided with empty "names", zero units consumed
    "countries": string[] | null,    // e.g. ["US","EU","UK","CH","CA","AU"]
    "programCodes": string[] | null, // e.g. ["SDGT","SDN","UKR","BELARUS"]
    "keywords": string[] | null      // free-text program/list keywords
  },
  "options": {                       // optional knobs (sensible defaults)
    "maxMatchesPerName": number,     // default 10
    "threshold": number,             // 0..1; default calibrated internal
    "returnRaw": boolean             // include full raw source entry in each match.evidence.raw
  }
}

Supported `entityTypes`

individual
entity
vessel
aircraft
wallet (for blockchain screening, if enabled)

Response

200 OK
{
  "results": [
    {
      "input": "Ali Hassan",
      "isSanctioned": true | false,
      "matches": [
        {
          "source": "EU Sanctions list",
          "sourceKey": "eu",
          "dataset": "EU (FSF)",
          "entityType": "individual",
          "matchedName": "Ali Hassan",
          "matchScore": 0.93,        // 0..1 (1.00 = exact)
          "level": "🟢 Very high confidence",
          "reason": "Exact name match + DOB match + alias overlap",
          "detailsList": [
            { "label": "Date of birth", "value": "1971-05-20" },
            { "label": "Citizenship", "value": "IR" }
          ],
          "evidence": {
            "primaryName": "Ali Hassan",
            "aliases": ["Hassan Ali", "Ali al-Hassan"],
            "identifiers": { "Passport": ["IR12345"] },
            "addresses": ["Tehran, Iran"],
            "nationality": "IR",
            "programs": ["EU-IR"],
            "dates": {
              "Date of birth": "1971-05-20",
              "Date listed": "2012-11-10"
            },
            "sourceUrls": ["https://.../eu_sanctions/entry/123"]
          },
          "raw": { /* optional, if options.returnRaw=true */ }
        }
      ]
    }
  ],
  "policyMatches": [
    /* if policyQuery provided without names */
  ],
  "scannedSources": ["ofac_sdn","eu","uk","un","ch","au","ca"],
  "unavailableSources": [],
  "meta": { "tookMs": 124, "tenantId": "org_abc", "planKey": "pro" }
}

Examples

cURL Node (fetch)Python (requests)

curl -X POST https://your-domain.com/api/v1/screen \
  -H "Authorization: Bearer $MATCHAUDIT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "names": ["Vladimir Putin"], "entityTypes": ["individual"] }'

export async function screen(names) {
  const res = await fetch("https://your-domain.com/api/v1/screen", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.MATCHAUDIT_API_KEY}`,
      "Content-Type": "application/json",
      "Idempotency-Key": crypto.randomUUID()
    },
    body: JSON.stringify({ names, entityTypes: ["individual"] })
  });
  if (!res.ok) throw new Error(`Screen failed: ${res.status}`);
  return res.json();
}

import os, uuid, requests
resp = requests.post(
  "https://your-domain.com/api/v1/screen",
  headers={
    "Authorization": f"Bearer {os.getenv('MATCHAUDIT_API_KEY')}",
    "Content-Type": "application/json",
    "Idempotency-Key": str(uuid.uuid4())
  },
  json={"names": ["Vladimir Putin"], "entityTypes": ["individual"]},
  timeout=30
)
print(resp.json())

Field glossary

Field	Type	Description
results[].matches[].matchScore	number (0..1)	Normalized similarity score; 1.00 is exact.
results[].matches[].level	string	Calibrated confidence band (emoji + label).
results[].matches[].reason	string	Human-readable justification for the hit.
results[].matches[].detailsList	array	Flattened key facts shown in the UI (DOB, citizenship, etc.).
results[].matches[].evidence	object	Structured evidence (aliases, identifiers, programs, dates, URLs).
scannedSources	string[]	Which datasets were actually scanned for this request.
unavailableSources	string[]	Datasets temporarily unavailable during the request.
meta.tookMs	number	Processing time in milliseconds.

Source keys

Key	Label / Dataset
ofac_sdn	US OFAC – SDN
ofac_non_sdn	US OFAC – Non-SDN
us_consolidated	US Treasury – Consolidated
uk	UK OFSI / UK Sanctions List
eu	EU (FSF)
un	UN Consolidated
ch	Switzerland (SECO)
au	Australia (DFAT)
ca	Canada (GAC)
bis_entity	US BIS – Entity List
bis_dpl	US BIS – Denied Persons
bis_uvl	US BIS – Unverified List
ddtc_itar	US State/DDTC – ITAR Debarred

Pass any subset in sources. If omitted, we scan all enabled datasets for your tenant/plan.

Limits & rate-limiting

Per-request names (Free)

Per-request names (Pro)

200

RPS

Plan-based (burst-friendly)

On 429 rate_limited or 503 unavailable, retry with exponential backoff.
Use Idempotency-Key on POSTs to make retries safe.

GET /api/v1/usage/summary

Returns current-month usage for a tenant (organization). Requires a server-only bearer secret (API_AUTH_SECRET). Do not call from browsers.

Query parameters

Param	Type	Required	Description
tenantId	string (uuid)	Yes	Tenant/organization ID to fetch usage for.
planKey	string	Yes	Your plan key (e.g., free, pro, business, hv).

Request

GET /api/v1/usage/summary?tenantId=<uuid>&planKey=pro
Authorization: Bearer <API_AUTH_SECRET>

Response

200 OK
{
  "planKey": "pro",
  "included": 3000,
  "used": 123,
  "remaining": 2877,
  "periodStartIso": "2025-10-01T00:00:00.000Z",
  "periodEndIso":   "2025-11-01T00:00:00.000Z"
}

Errors

400 bad_request

Body must be valid JSON

400 no_names

Provide at least one name (unless policy-only)

400 too_many_names

Exceeded per-request cap for your plan

401 unauthorized

Invalid/missing API key

403 forbidden

Key not allowed for endpoint/tenant

429 rate_limited

Too many requests/second; retry with backoff

429 limit_exceeded

Monthly allowance reached (tenant-wide)

500 engine_failed

Screening engine not available

503 unavailable

Temporary outage; retry with backoff

Tip: Keep API keys out of browser code. If you must call from the client, proxy via your server and enforce per-tenant quotas.

API Reference

Overview

Required headers

POST /api/v1/screen

Request body

Supported entityTypes

Response

Examples

Field glossary

Source keys

Limits & rate-limiting

GET /api/v1/usage/summary

Query parameters

Request

Response

Errors

API Reference

Overview

Required headers

POST /api/v1/screen

Request body

Supported entityTypes

Response

Examples

Field glossary

Source keys

Limits & rate-limiting

GET /api/v1/usage/summary

Query parameters

Request

Response

Errors

Supported `entityTypes`

Supported `entityTypes`