REST API v1

API Reference

Integrate sanctions screening into your applications. Screen entities, set up continuous monitoring, and receive alerts via webhooks.

Quick Start

Get started with the SanctScan API in minutes

1. Get your API key

Create an API key in your organization settings at Settings → API Keys

2. Make your first request

curl -X POST https://sanctscan.app/api/v1/screen \
-H "Content-Type: application/json" \
-H "x-api-key: your_api_key" \
-d '{"name": "John Smith"}'

Authentication

All API requests require authentication using an API key. Include your API key in the x-api-key header.

curl -H "x-api-key: your_api_key" https://sanctscan.app/api/v1/screenings

Keep your API key secure

Never expose your API key in client-side code or public repositories. Use environment variables to store your key.

Base URL

https://sanctscan.app/api/v1

A machine-readable spec is available at /openapi.json (OpenAPI 3.1).

Endpoints

POST

/screen

Screen an entity against all sanctions lists. Returns risk score, matched lists, and detailed match information.

Request Body

name

string (required)

The name of the entity to screen

entityType

string

One of: 'person', 'business', 'organization', 'aircraft', 'vessel'. 'business' is treated as an alias of 'organization'. Any other value returns VALIDATION_ERROR.

country

string

2-letter ISO 3166-1 alpha-2 country code (e.g. 'DE'). Other formats return VALIDATION_ERROR.

birthDate

string

Date of birth as YYYY-MM-DD. Other formats return VALIDATION_ERROR.

groupByCluster

boolean

Collapse rows for the same party across sources into one match carrying every source it is listed on, in a `listings` array. Defaults to false, so existing integrations keep one result per source row.

Optional Headers

Idempotency-Key

string (max 255 chars)

Safely retry requests without double-billing or duplicate screening records. Replays of the same key within 24 hours return the original response with an 'Idempotency-Replayed: true' header.

Example Request

curl -X POST https://sanctscan.app/api/v1/screen \
-H "Content-Type: application/json" \
-H "x-api-key: your_api_key" \
-d '{
  "name": "Viktor Sokolov",
  "entityType": "person",
  "country": "RU"
}'

Response

{
"success": true,
"data": {
  "screeningId": "scr_abc123",
  "entityId": "us_ofac:12345",
  "entityName": "Viktor Sokolov",
  "riskScore": 85,
  "riskLevel": "high",
  "confidence": 92,
  "matchedSources": ["us_ofac"],
  "matchDetails": [
    {
      "dataset": "us_ofac",
      "datasetLabel": "OFAC SDN",
      "matchScore": 92,
      "entity": {
        "id": "us_ofac:12345",
        "name": "Viktor SOKOLOV",
        "entityType": "person",
        "country": "Russia",
        "programs": ["RUSSIA-EO14024"],
        "listingDate": "2022-03-15"
      }
    }
  ],
  "isMonitored": false
}
}

GET

/screenings

List all screenings for your organization with filtering and pagination.

Query Parameters

page

number

Page number (default: 1)

pageSize

number

Results per page (default: 20, max: 100)

riskLevel

string

Filter by risk level: 'low', 'medium', or 'high'

dateFrom

string

Filter screenings from this date (ISO format)

dateTo

string

Filter screenings up to this date (ISO format)

search

string

Search by entity name

Example Request

curl "https://sanctscan.app/api/v1/screenings?riskLevel=high&pageSize=10" \
-H "x-api-key: your_api_key"

Response

{
"success": true,
"data": [
  {
    "id": "scr_abc123",
    "entityId": "us_ofac:12345",
    "entityName": "Viktor Sokolov",
    "query": "Viktor Sokolov",
    "riskScore": 85,
    "riskLevel": "high",
    "matchedSources": ["us_ofac", "eu_csl"],
    "isMonitored": true,
    "timestamp": "2024-01-15T10:30:00Z"
  }
],
"meta": {
  "pagination": {
    "page": 1,
    "pageSize": 10,
    "total": 42,
    "totalPages": 5
  }
}
}

GET

/screenings/:id

Fetch a single screening with full match details.

Example Request

curl https://sanctscan.app/api/v1/screenings/scr_abc123 \
-H "x-api-key: your_api_key"

Response

{
"success": true,
"data": {
  "id": "scr_abc123",
  "entityId": "us_ofac:12345",
  "entityName": "Viktor Sokolov",
  "query": "Viktor Sokolov",
  "riskScore": 85,
  "riskLevel": "high",
  "confidence": 92,
  "matchedSources": ["us_ofac"],
  "matchDetails": [ /* same shape as POST /screen */ ],
  "usedSources": ["us_ofac", "eu_csl", "uk_csl", "un_csl", "us_csl"],
  "isMonitored": true,
  "country": "RU",
  "birthDate": null,
  "timestamp": "2024-01-15T10:30:00Z"
}
}

POST

/monitors

Add an entity to continuous monitoring. You'll receive webhook notifications when the entity's sanctions status changes. Each search is monitored once: if a screening with the same name and filters (ignoring case and spacing) is already monitored, this returns 409 CONFLICT, and new screenings of that search come back with isMonitored: true.

Request Body

screeningId

string (required)

The ID of a previous screening to monitor

riskThreshold

number

Alert threshold for risk score changes (default: 55)

Example Request

curl -X POST https://sanctscan.app/api/v1/monitors \
-H "Content-Type: application/json" \
-H "x-api-key: your_api_key" \
-d '{
  "screeningId": "scr_abc123",
  "riskThreshold": 50
}'

Response

{
"success": true,
"data": {
  "id": "mon_xyz789",
  "screeningId": "scr_abc123",
  "isActive": true,
  "isNew": true
}
}

GET

/monitors

List all monitored entities for your organization.

Query Parameters

page

number

Page number (default: 1)

pageSize

number

Results per page (default: 20, max: 100)

Example Request

curl https://sanctscan.app/api/v1/monitors \
-H "x-api-key: your_api_key"

Webhooks

Configure webhooks in your organization settings to receive real-time notifications when monitored entities have status changes.

Webhook Payload

When an alert is created or resolved, we send a POST request to your webhook URL.

{
"event": "alert.created",
"timestamp": "2024-01-15T14:30:00Z",
"organization": {
  "id": "org_abc123",
  "slug": "acme-corp",
  "name": "Acme Corporation"
},
"alert": {
  "id": "alt_def456",
  "monitorId": "mon_xyz789",
  "entityId": "entity-1448-1705329000000",
  "entityName": "Viktor Sokolov",
  "oldRiskScore": 45,
  "newRiskScore": 85,
  "oldRiskLevel": "medium",
  "newRiskLevel": "high",
  "oldSources": [],
  "newSources": ["us_ofac"],
  "timestamp": "2024-01-15T14:30:00Z",
  "resolvedAt": null
}
}

Every request carries X-SanctScan-Event, X-SanctScan-Delivery (stable across retries, use it to drop duplicates) and X-SanctScan-Signature: sha256= followed by the hex HMAC-SHA256 of the raw body, keyed with your webhook secret. Test sends add X-SanctScan-Test: true.

A delivery that does not get a 2xx response within 10 seconds is retried after 1 minute, 5 minutes, 15 minutes, 1 hour and 4 hours. A webhook that fails 10 times in a row is paused.

Webhook Events

alert.created

When a rescreen changes a monitored entity's risk level, crosses its threshold, or finds it on a new list

alert.resolved

When an alert is resolved by a user

Rate Limits & Request IDs

Each API key may make up to 60 requests per minute. Every response includes rate-limit headers and a unique request ID. Quote the request ID when contacting support.

X-Request-Id: req_V1StGXR8_Z5jdHi6
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1784755720

Exceeding the limit returns 429 RATE_LIMITED with a Retry-After header (seconds).

Error Codes

All errors follow a consistent format with a code and message.

{
"success": false,
"error": {
  "code": "VALIDATION_ERROR",
  "message": "Name is required"
}
}

Code	Status	Description
`UNAUTHORIZED`	401	Missing x-api-key header
`INVALID_API_KEY`	401	Invalid, revoked or expired API key
`FORBIDDEN`	403	The key's owner is no longer a member of its organization
`BAD_REQUEST`	400	The request body is not valid JSON
`VALIDATION_ERROR`	400	Invalid request parameters; the message names the field
`NOT_FOUND`	404	Resource not found
`CONFLICT`	409	This search is already being monitored
`TIER_LIMIT_EXCEEDED`	403	Monthly quota exceeded
`RATE_LIMITED`	429	Rate limit exceeded. Respect the Retry-After header.
`FEATURE_NOT_AVAILABLE`	403	API access requires the Starter tier or above
`INTERNAL_ERROR`	500	Server error

Supported Sanctions Lists

We screen against the following major sanctions lists, updated daily.

Source ID	Name	Region
`us_ofac`	OFAC SDN List	US
`us_csl`	US Consolidated Screening List	US
`eu_csl`	EU Consolidated Sanctions List	EU
`uk_csl`	UK Sanctions List	UK
`un_csl`	UN Consolidated Sanctions List	Global
`au_dfat`	DFAT Consolidated List	AU
`ch_seco`	Swiss SECO Sanctions List	CH
`ca_gac`	Canada Global Affairs (GAC) Autonomous Sanctions	CA
`jp_mof`	Japan Ministry of Finance Sanctions	JP

Ready to integrate?

Create a free account and get your API key in minutes.