REST API v1

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.

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.

reference
string (max 200 chars)

Your 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-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",
    "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"
  }
}
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",
      "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
    }
  }
}
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",
    "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"
  }
}
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",
    "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.created
When a rescreen changes a monitored entity's risk level, crosses its threshold, or finds it on a new list
alert.resolved
When a user resolves an alert. 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: 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"
  }
}
CodeStatusDescription
UNAUTHORIZED401Missing x-api-key header
INVALID_API_KEY401Invalid, revoked or expired API key
FORBIDDEN403The key's owner is no longer a member of its organization
BAD_REQUEST400The request body is not valid JSON
VALIDATION_ERROR400Invalid request parameters; the message names the field
NOT_FOUND404Resource not found
CONFLICT409This search is already being monitored
TIER_LIMIT_EXCEEDED403Monthly quota exceeded
RATE_LIMITED429Rate limit exceeded. Respect the Retry-After header.
FEATURE_NOT_AVAILABLE403API access requires the Starter tier or above
INTERNAL_ERROR500Server error

Supported Sanctions Lists

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

Source IDNameRegion
us_ofacOFAC Specially Designated Nationals and Blocked Persons List
US
us_cslUS Consolidated Screening List
US
eu_cslEU Consolidated Financial Sanctions List
EU
uk_cslUK Sanctions List
UK
un_cslUN Security Council Consolidated List
Global
au_dfatAustralia DFAT Consolidated List
AU
ch_secoSwiss SECO Consolidated Sanctions List
CH
ca_gacConsolidated Canadian Autonomous Sanctions List
CA
jp_mofJapan Ministry of Finance Economic Sanctions List
JP

Ready to integrate?

API access starts on the Starter plan. Upgrade from any account and create a key in settings.

We use cookies to measure site traffic. Accept or decline non-essential cookies.