API & MCP Integration

API

Screen names, retrieve entity intelligence, and explore relationship networks

An API lets your software talk to 123sanctions without a human in the middle. Your systems send a JSON request, get structured results back, and act on them.

The full screening pipeline is exposed as JSON endpoints. The scoring engine, the ML models, and the nightly-updated index are identical to what the web interface uses. Same data, same scores, same sources.

API access ships with every account. Manage keys under “MCP & API” in account settings. The free plan covers 1 key, 10 requests per minute and 500 per month — enough for evaluation and a proof of concept. Paid plans raise the limits.

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

Header	Description
`X-API-Key`	Your API key (required for all endpoints except `/health`)
`Content-Type`	`application/json` (required for POST requests)

Rate limit headers are included in every response:

Header	Description
`X-RateLimit-Limit`	Maximum requests per minute
`X-RateLimit-Remaining`	Remaining requests in the current window
`Retry-After`	Seconds 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

Field	Type	Required	Description
`name`	string	Yes	Name to screen (max 200 characters)
`entity_type`	string	No	PERSON, ORGANIZATION, COMPANY, VESSEL, AIRCRAFT, SECURITY
`date_of_birth`	string	No	ISO 8601 date (YYYY-MM-DD)
`nationality`	string	No	ISO 3166-1 alpha-2 country code
`threshold`	integer	No	Minimum 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": 94331, "canonical_name": "Vladimir Vladimirovich Putin", "score": 100, "entity_type": "PERSON", "source_categories": ["pep", "sanctions"], "sources": ["AU_DFAT", "CA_SEMA", "CH_SECO", "CIA_WORLD_LEADERS", "EU_CONSOLIDATED", "UK_FCDO", "US_OFAC_SDN", "WIKIDATA_PEP"], "listing_count": 8, "is_sanctioned": true, "is_pep": true } ], "total_hits": 1, "screening_time_ms": 42 }

Batch Screening

POST /api/v1/screen/batch

Screen up to 50 names per request. Each name runs through the full pipeline; entity metadata is loaded in one batch query. 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 hit, fetch the full profile — aliases, listings, biographical data — and walk the relationship network: shared addresses, shared identifiers, corporate links, 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

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

MCP Server

Sanctions screening as a tool for AI agents

The Model Context Protocol (MCP) is an open standard for AI assistants to call external tools. With it, an assistant can screen a name, pull up an entity profile, or walk a relationship network from inside the chat — no app-switching.

The 123sanctions MCP server exposes the screening and entity-intelligence API as MCP tools. Compliance copilots, KYC assistants and due-diligence agents can call them directly — no 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": 100, "sources": ["AU_DFAT", "CA_SEMA", "CH_SECO", "CIA_WORLD_LEADERS", "EU_CONSOLIDATED", "UK_FCDO", "US_OFAC_SDN", "WIKIDATA_PEP"], "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.

ERP Integration

Custom connector for your enterprise software — built for you

ERP, CRM, payment and onboarding systems hold the customer, supplier and transaction data that screening needs to look at. Screening works best when it runs where that data already lives — inside the system, not as a separate tool people have to remember to open.

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

We build the connector for whichever system you run — ERP, CRM, accounting, custom in-house tooling. It is written against your data model and your existing workflow, not a one-size plugin.

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