Back to Documentation

API Reference

Complete reference for all SanctionSnap API endpoints

Base URL

https://sanctionsnap.com/api

All API endpoints are prefixed with /api

Authentication

All API requests require authentication using your API key in the request header:

X-API-Key: your_api_key_here

You can manage your API keys from the dashboard.

Health Check

Simple health status endpoint

GET
/health

Basic health check endpoint that returns API status.

Response

{
  "status": "ok"
}

System Status

Check API status and data source information

GET
/status

Returns comprehensive API status and information about data sources including last update times and record counts.

Response

{
  "status": "healthy",
  "redis_connected": true,
  "sources": {
    "ofac": {
      "refreshed_at": "2024-01-15T10:30:00Z",
      "record_count": 12543
    },
    "eu": {
      "refreshed_at": "2024-01-15T09:15:00Z", 
      "record_count": 8921
    }
  }
}

Search

Search for sanctions matches by name

POST
/search

Search for a name across all sanctions lists with fuzzy matching and similarity scoring.

Request Body

{
  "name": "Vladimir Putin",
  "sources": ["ofac", "eu"],        // Optional: filter by sources
  "countries": ["Russia"],          // Optional: filter by countries  
  "entity_types": ["individual"]    // Optional: filter by entity type
}

Response

[
  {
    "id": 12345,
    "source": "ofac",
    "uid": "12345",
    "name": "PUTIN, Vladimir Vladimirovich",
    "aliases": ["Vladimir Putin", "Vladimir Vladimirovich Putin"],
    "listed_on": "2014-03-20",
    "similarity_score": 0.95,
    "entity_type": "individual",
    "country": "Russia",
    "program": "RUSSIA-EO13661",
    "title": "President of the Russian Federation",
    "details": "DOB: 07 Oct 1952; POB: Leningrad, Russia",
    "date_of_birth": "1952-10-07",
    "place_of_birth": "Leningrad, Russia",
    "nationality": "Russian",
    "designation_date": "2014-03-20",
    "name_similarity": 0.95,
    "alias_similarity": null,
    "matched_via_alias": false
  }
]

Advanced Search

Search with filters for country, entity type, and program

POST
/search/advanced

Advanced search with comprehensive filtering capabilities.

Request Body

{
  "query": "Smith",           // Optional: name to search for
  "country": "Iran",          // Optional: filter by country
  "entity_type": "individual", // Optional: individual, entity, vessel
  "program": "IRAN",          // Optional: sanctions program
  "source": "ofac",           // Optional: specific source
  "limit": 10                 // Optional: max results (default: 10)
}

Response

Same format as basic search with additional metadata and filtering applied.

Batch Screening

Screen multiple records at once

POST
/screen

Screen multiple names in a single request with match detection.

Request Body

{
  "records": [
    {
      "name": "John Smith",
      "id": "customer_001"    // Optional: your internal ID
    },
    {
      "name": "Jane Doe",
      "id": "customer_002"
    }
  ],
  "sources": ["ofac", "eu"],        // Optional: filter by sources
  "countries": ["US", "EU"],        // Optional: filter by countries
  "entity_types": ["individual"]    // Optional: filter by entity type
}

Response

[
  {
    "input_name": "John Smith",
    "input_id": "customer_001",
    "is_match": false,
    "matches": []
  },
  {
    "input_name": "Jane Doe", 
    "input_id": "customer_002",
    "is_match": true,
    "matches": [
      {
        "id": 67890,
        "source": "eu",
        "name": "DOE, Jane",
        "similarity_score": 0.87,
        // ... other entity fields
      }
    ]
  }
]

Entity Details

Get detailed information about a specific entity

GET
/entity/{id}

Retrieve detailed information about a specific sanctioned entity.

Path Parameters

idEntity ID from search results

Response

{
  "id": 12345,
  "source": "ofac",
  "uid": "12345",
  "name": "PUTIN, Vladimir Vladimirovich",
  "aliases": ["Vladimir Putin", "Vladimir Vladimirovich Putin"],
  "listed_on": "2014-03-20",
  "entity_type": "individual",
  "country": "Russia",
  "program": "RUSSIA-EO13661",
  "title": "President of the Russian Federation",
  "details": "DOB: 07 Oct 1952; POB: Leningrad, Russia",
  "source_data": {...},
  "addresses": ["Kremlin, Moscow, Russia"]
}

Usage Statistics

Check your API usage and limits

GET
/usage

Get your current API usage statistics and limits.

Response

{
  "current_usage": 125,
  "limit": 5000,
  "tier": "starter",
  "remaining": 4875
}

Data Sources

Get information about available data sources

GET
/sources

Get detailed information about all available sanctions data sources.

Response

{
  "sources": [
    {
      "code": "ofac",
      "name": "OFAC SDN List",
      "jurisdiction": "United States",
      "record_count": 12543,
      "last_updated": "2024-01-15T10:30:00Z",
      "url": "https://ofac.treasury.gov/..."
    },
    {
      "code": "eu", 
      "name": "EU Consolidated List",
      "jurisdiction": "European Union",
      "record_count": 8921,
      "last_updated": "2024-01-15T09:15:00Z",
      "url": "https://ec.europa.eu/..."
    }
  ],
  "total_records": 45231
}

User Management Endpoints

These endpoints require user authentication (sign-in) rather than API key authentication.

User Profile

Get current user profile information

GET
/user/profile

Get the current user's profile information including tier and account details.

Response

{
  "id": 123,
  "clerk_id": "user_123abc",
  "email": "user@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "tier": "pro",
  "created_at": "2024-01-15T10:30:00Z",
  "is_active": "true"
}

User API Keys

Manage API keys for the current user

GET
/user/api-keys

Get all API keys for the current user.

Response

[
  {
    "key": "sk_abc123...",
    "name": "Production API",
    "tier": "pro",
    "created_at": "2024-01-15T10:30:00Z",
    "is_active": "true"
  }
]
POST
/user/api-keys

Create a new API key for the current user.

Request Body

{
  "name": "My App API Key"  // Optional: custom name
}
DELETE
/user/api-keys/{api_key}

Deactivate an API key belonging to the current user.

User Usage Statistics

Get comprehensive usage statistics for the current user

GET
/user/usage

Get detailed usage statistics across all API keys for the current user.

Response

{
  "current_usage": 1250,
  "limit": 10000,
  "tier": "pro",
  "remaining": 8750,
  "api_keys_count": 3
}

HTTP Status Codes

200
Success
Request completed successfully
400
Bad Request
Invalid request parameters
401
Unauthorized
Invalid or missing API key
429
Rate Limited
Rate limit exceeded
500
Server Error
Internal server error

Rate Limits

Request Limits

Per minute
60 requests
Monthly quota
Based on plan

Plan Limits

Free
250 calls/month
Test
250 calls/month
Starter
2,500 calls/month
Pro
10,000 calls/month
Scale
Unlimited

Rate Limit Headers

All responses include rate limit information:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1640995200