Sanctions Screening API
Integrate sanctions screening into your applications. Screen entities, set up continuous monitoring, and receive alerts via webhooks.
The SanctScan API screens a person, organization, vessel or aircraft against 9 official sanctions lists in one REST call and returns each match with its list, match score and the overall risk level. Monitors re-run the same search after every daily list import, and a signed webhook tells your system when the result changes. Requests authenticate with an x-api-key header and are limited to 60 per minute per key. API access starts on the Starter plan. The machine-readable spec is at /openapi.json.
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/screeningsKeep 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/v1A machine-readable spec is available at /openapi.json (OpenAPI 3.1).
Endpoints
/screenRequest Body
nameThe name of the entity to screen
entityTypeOne of: 'person', 'business', 'organization', 'aircraft', 'vessel'. 'business' is treated as an alias of 'organization'. Any other value returns VALIDATION_ERROR.
country2-letter ISO 3166-1 alpha-2 country code (e.g. 'DE'). Other formats return VALIDATION_ERROR.
birthDateDate of birth as YYYY-MM-DD. Other formats return VALIDATION_ERROR.
groupByClusterCollapse 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.
referenceYour own note for this screening, such as a customer ID, case number or address. It is stored with the screening and returned on every read, and it is never used for matching. Put only the name in `name`: extra words there lower the match score.
Optional Headers
Idempotency-KeySafely 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",
"entityName": "Viktor Sokolov",
"riskScore": 85,
"riskLevel": "high",
"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,
"reference": "CRM-1042"
}
}/screeningsQuery Parameters
pagePage number (default: 1)
pageSizeResults per page (default: 20, max: 100)
riskLevelFilter by risk level: 'low', 'medium', or 'high'
dateFromFilter screenings from this date (ISO format)
dateToFilter screenings up to this date (ISO format)
searchSearch 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",
"entityName": "Viktor Sokolov",
"query": "Viktor Sokolov",
"riskScore": 85,
"riskLevel": "high",
"matchedSources": ["us_ofac", "eu_csl"],
"isMonitored": true,
"reference": "CRM-1042",
"timestamp": "2024-01-15T10:30:00Z"
}
],
"meta": {
"pagination": {
"page": 1,
"pageSize": 10,
"total": 42,
"totalPages": 5
}
}
}/screenings/:idExample Request
curl https://sanctscan.app/api/v1/screenings/scr_abc123 \
-H "x-api-key: your_api_key"Response
{
"success": true,
"data": {
"id": "scr_abc123",
"entityName": "Viktor Sokolov",
"query": "Viktor Sokolov",
"riskScore": 85,
"riskLevel": "high",
"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,
"reference": "CRM-1042",
"timestamp": "2024-01-15T10:30:00Z"
}
}/monitorsRequest Body
screeningIdThe ID of a previous screening to monitor
riskThresholdAlert 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
}
}/monitorsQuery Parameters
pagePage number (default: 1)
pageSizeResults 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.
{
"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",
"entityName": "Viktor Sokolov",
"reference": "CRM-1042",
"oldRiskScore": 45,
"newRiskScore": 85,
"oldRiskLevel": "medium",
"newRiskLevel": "high",
"oldSources": [],
"newSources": ["us_ofac"],
"timestamp": "2024-01-15T14:30:00Z",
"resolvedAt": null,
"outcome": null
}
}alert.reference is the reference saved with the monitored screening, such as your customer or case ID, or null when it has none.
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.outcome is false_positive or confirmed_match; it is null on alert.created. The analyst's note stays in SanctScan.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: 1784755720Exceeding 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 Specially Designated Nationals and Blocked Persons List | US |
us_csl | US Consolidated Screening List | US |
eu_csl | EU Consolidated Financial Sanctions List | EU |
uk_csl | UK Sanctions List | UK |
un_csl | UN Security Council Consolidated List | Global |
au_dfat | Australia DFAT Consolidated List | AU |
ch_seco | Swiss SECO Consolidated Sanctions List | CH |
ca_gac | Consolidated Canadian Autonomous Sanctions List | CA |
jp_mof | Japan Ministry of Finance Economic Sanctions List | JP |