Login / Register
← All Features

API & MCP Integration

Programmatic access to sanctions screening.
The same matching pipeline that powers the platform — available via REST API and Model Context Protocol.

Early access. API endpoints and protocols subject to change.

REST API

Screen names, retrieve entity intelligence, and explore relationship networks

An API (Application Programming Interface) allows your existing software to communicate with 123sanctions directly — no manual login, no copy-paste, no human in the loop. Your systems send a request, receive structured results, and process them automatically.

The API exposes the full screening pipeline as a set of JSON endpoints. Every request runs the same multi-layer scoring engine, the same ML models, and the same nightly-updated sanctions index as the web interface. No separate data, no reduced functionality.

API access is included in every 123sanctions account. Create an API key in your account settings and start integrating immediately.

7Endpoints
JSONRequest & Response
<250msAvg. Screening Response
AES-256Encryption at Rest

Authentication & Rate Limiting

API key authentication with sliding-window rate control

Every request (except health checks) requires an API key in the X-API-Key header. Keys are hashed with SHA-256 before storage — the raw key is never persisted. Each key has a configurable rate limit enforced via an atomic Redis sliding window.

Authentication Details
HeaderDescription
X-API-KeyYour API key (required for all endpoints except /health)
Content-Typeapplication/json (required for POST requests)

Rate limit headers are included in every response:

HeaderDescription
X-RateLimit-LimitMaximum requests per minute
X-RateLimit-RemainingRemaining requests in the current window
Retry-AfterSeconds to wait (only on 429 responses)

Screening Endpoint

POST /api/v1/screen

Submit a name and receive matching sanctions entities ranked by score. Optional parameters for entity type, date of birth, nationality, and score threshold refine results. The response includes up to 10 matches with entity IDs, source information, and sanctions status.

Request Parameters
FieldTypeRequiredDescription
namestringYesName to screen (max 200 characters)
entity_typestringNoPERSON, ORGANIZATION, COMPANY, VESSEL, AIRCRAFT, SECURITY
date_of_birthstringNoISO 8601 date (YYYY-MM-DD)
nationalitystringNoISO 3166-1 alpha-2 country code
thresholdintegerNoMinimum score 0–100 (default: 80)
Example Request
POST /api/v1/screen Content-Type: application/json X-API-Key: sk_live_... { "name": "Vladimir Putin", "entity_type": "PERSON", "date_of_birth": "1952-10-07", "nationality": "RU", "threshold": 80 }
Example Response
{ "request_id": "req_a1b2c3d4e5f6", "hits": [ { "entity_id": 12345, "canonical_name": "Vladimir Vladimirovich Putin", "score": 97, "entity_type": "PERSON", "sources": ["EU_CONSOLIDATED", "OFAC_SDN", "UK_FCDO"], "listing_count": 5, "is_sanctioned": true, "is_pep": true } ], "total_hits": 1, "screening_time_ms": 187 }

Batch Screening

POST /api/v1/screen/batch

Screen up to 50 names in a single request. The same matching pipeline runs for each name, but entity metadata is fetched in a single batch query for efficiency. Each name counts as one request against your monthly limit.

Request Format
POST /api/v1/screen/batch Content-Type: application/json X-API-Key: sk_live_... { "names": [ {"name": "Person A", "entity_type": "PERSON"}, {"name": "Person B", "date_of_birth": "1990-01-01"}, {"name": "Company X", "entity_type": "COMPANY"} ], "threshold": 80 }

Each entry supports the same parameters as the single screening endpoint. The global threshold applies to all entries unless overridden per entry.

Response Format
{ "request_id": "req_b4c5d6e7f8g9", "results": [ {"name_index": 0, "hits": [...], "total_hits": 3}, {"name_index": 1, "hits": [], "total_hits": 0}, {"name_index": 2, "hits": [...], "total_hits": 1} ], "total_names": 3, "screening_time_ms": 420 }

Entity & Network Endpoints

Detailed entity intelligence and relationship networks

After a screening hit, retrieve the full entity profile — aliases, listings across all sources, biographical data — and explore the entity's relationship network: shared addresses, identity documents, corporate links, and family connections.

Available Endpoints

GET /api/v1/entities/{entity_id}

Returns the full entity profile: canonical name, type, sanctions/PEP status, all aliases and name variants, active listings with source and programme, date of birth, nationalities, and connection count.

GET /api/v1/entities/{entity_id}/network

Returns paginated entity connections with type filtering. Connection types include shared_address, shared_identifier, corporate_officer, corporate_owner, family_member, explicit_associate, and more. Each connection includes a confidence score and evidence.

GET /api/v1/sources

Lists all active sanctions sources with last import timestamp, entity count, and listing count. Cached for 5 minutes.

GET /api/v1/usage

Returns API usage statistics for your key: total requests, average response time, per-endpoint breakdown, and last-24h volume.

GET /api/v1/health

Public health check. No authentication required.

Network Response Example
{ "entity_id": 12345, "canonical_name": "Vladimir Vladimirovich Putin", "connections_count": 127, "connections": [ { "connected_entity_id": 54321, "connected_entity_name": "Associated Entity", "connection_type": "explicit_associate", "confidence": 95, "connected_is_sanctioned": true } ], "pagination": { "limit": 100, "offset": 0, "total": 127, "has_more": true } }

Error Handling & Data Minimisation

Consistent error format. No unnecessary data exposure.

All errors return a JSON object with a single error field. HTTP status codes follow standard semantics: 400 for invalid input, 401 for missing or invalid API key, 403 for PEP-gated access, 404 for unknown entities, 429 for rate limiting, and 503 for temporary unavailability.

The screening endpoint never echoes input data in responses. PEP-only entities in network results are redacted for API keys without PEP access — entity IDs and names are replaced with placeholders to prevent indirect identification. Usage logging records endpoint names and response times only, never request or response bodies.

HTTP Status Codes
CodeMeaning
200Success
400Invalid request parameters
401Missing or invalid API key
403PEP-only entity without PEP access
404Entity not found
429Rate limit exceeded
503Service temporarily unavailable

MCP Server

Sanctions screening as a tool for AI agents

The Model Context Protocol (MCP) is an open standard that lets AI assistants interact with external tools and data sources. Instead of switching between applications, an AI assistant can screen a name, retrieve an entity profile, or explore a relationship network directly — as naturally as asking a question.

The 123sanctions MCP server exposes the full screening and entity intelligence API as MCP tools. AI agents in compliance workflows can screen names, retrieve entity profiles, and explore relationship networks — without custom integration code.

Available MCP Tools
  • screen_name — Screen a name against all active sanctions lists. Returns scored matches with entity type, source, and sanctions status.
  • get_entity — Retrieve the full profile of a sanctioned entity: aliases, listings, biographical data, and connection count.
  • get_entity_network — Explore an entity's relationships: corporate links, shared addresses, family connections, and co-listing patterns.
  • list_sources — List all active sanctions sources with metadata and last update timestamps.
Use Cases
  • KYC Copilot: An AI assistant screens customer names during onboarding, retrieves entity details for flagged results, and drafts compliance reports — all through MCP tool calls.
  • Transaction Monitoring: AI agents in payment processing workflows screen counterparty names in real time and escalate hits with full entity context.
  • Due Diligence Automation: AI-powered research tools explore entity networks, identify sanctioned associates, and compile relationship maps for compliance officers.
  • Regulatory Reporting: AI assistants generate sanctions exposure reports by querying entity data and connection graphs across jurisdictions.
How It Works

The MCP server runs as a lightweight process that connects to the 123sanctions API. AI agents discover available tools via the MCP protocol handshake, then invoke them with structured parameters. The server handles authentication, rate limiting, and response formatting transparently.

// Example: AI agent screens a name via MCP { "tool": "screen_name", "arguments": { "name": "Vladimir Putin", "entity_type": "PERSON" } } // MCP server returns structured result { "hits": [ { "canonical_name": "Vladimir Vladimirovich Putin", "score": 97, "sources": ["EU_CONSOLIDATED", "US_OFAC_SDN", "UK_FCDO", "CH_SECO", "AU_DFAT", "CA_SEMA"], "is_sanctioned": true } ] }

To connect, create an API key in your account settings under "MCP & API" and add the server URL to your MCP client configuration. Works with Claude Desktop, Cursor, and any MCP-compatible AI tool.

API Access

Every account includes API and MCP access. Create keys in your account settings.

Create and manage API keys directly in your account settings under “MCP & API”.

The free plan includes 1 API key, 10 requests per minute, and 500 requests per month — enough to explore the API and build a proof of concept. Higher limits are available on paid plans.

ERP Integration

Custom connector for your enterprise software — built for you

ERP (Enterprise Resource Planning) systems are the backbone of most organisations — managing customers, suppliers, transactions, and master data. Sanctions screening is most effective when it runs where the data lives: inside your ERP, your CRM, your payment system, or your onboarding workflow.

At 123sanctions, ERP integration is not a separate product. We build it for you.

We build a custom integration tailored to your specific software environment — whether it is an enterprise resource planning system, a customer management platform, an accounting suite, or any other business application. This is not a generic plugin. It is a purpose-built connector designed for your data model, your workflows, and your compliance requirements.

We develop these integrations within our engineering capacity on a first-come, first-served basis.

How It Works
  • You describe your setup: Which system, which version, where sanctions screening should trigger (new customer creation, payment approval, periodic batch review, etc.).
  • We build the connector: A purpose-built integration that uses the 123sanctions API to screen data from your system in real time or on a schedule. Results flow back into your existing workflow.
  • You review and deploy: The integration runs in your environment, under your control. We provide documentation and support for the setup.

No minimum contract. No setup fees. The screening itself uses your account's API quota.

Integrate Sanctions Screening Into Your Stack.

Screen names, retrieve entity intelligence, and explore relationship networks — programmatically.

Login / Register