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

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

Type of entity: 'person', 'business', or 'organization'

country

string

Country code or name for better matching

birthDate

string

Date of birth in ISO format (YYYY-MM-DD)

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", "eu_csl"],
    "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}

Get detailed information about a specific screening.

Path Parameters

id

string (required)

The screening ID

Example Request

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

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",
    "entityName": "Viktor Sokolov",
    "lastRiskScore": 85,
    "lastRiskLevel": "high",
    "riskThreshold": 50,
    "isActive": true,
    "createdAt": "2024-01-15T10:35:00Z"
  }
}

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"

DELETE

/monitors/{id}

Remove an entity from continuous monitoring.

Path Parameters

id

string (required)

The monitor ID

Example Request

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

Response

{
  "success": true,
  "data": {
    "id": "mon_xyz789",
    "removed": true
  }
}

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

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
`TIER_LIMIT_EXCEEDED`	403	Monthly quota exceeded
`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	UN
`au_dfat`	DFAT Consolidated List	AU

Ready to integrate?

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