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", "us_ofac_50"],
  "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"
      }
    },
    {
      "dataset": "us_ofac_50",
      "datasetLabel": "OFAC 50% Rule",
      "matchScore": 88,
      "entity": {
        "id": "us_ofac_50:391200EXAMPLE00025",
        "name": "Example Subsidiary GmbH",
        "entityType": "organization",
        "country": "DE",
        "reason": "Blocked under the OFAC 50 Percent Rule (derived, not individually listed)",
        "derivation": {
          "rule": "ofac_50_percent",
          "ownerEntityId": "us_ofac:12345",
          "ownerName": "Example Sanctioned Owner",
          "chain": [
            { "lei": "391200EXAMPLE00025", "name": "Example Subsidiary GmbH" }
          ],
          "asOf": "2026-07-21"
        }
      }
    }
  ],
  "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, including derived-match provenance.

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.

Request Body

screeningId

string (required)

The ID of a previous screening to monitor

riskThreshold

number

Alert threshold for risk score changes (default: 30)

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 a monitored entity's risk status changes, we'll 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": "us_ofac:12345",
  "entityName": "Viktor Sokolov",
  "oldRiskScore": 45,
  "newRiskScore": 85,
  "oldRiskLevel": "medium",
  "newRiskLevel": "high",
  "oldLists": [],
  "newLists": ["OFAC SDN"],
  "timestamp": "2024-01-15T14:30:00Z"
}
}

Webhook Events

alert.created

When a monitored entity's risk status increases

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
`INVALID_API_KEY`	401	Invalid or missing API key
`VALIDATION_ERROR`	400	Invalid request parameters
`NOT_FOUND`	404	Resource not found
`CONFLICT`	409	Entity 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
`us_ofac_50`	OFAC 50% Rule (derived from GLEIF ownership data; matches include a full ownership-chain derivation)	US

Ready to integrate?

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