OpenSanctions integration

Overview

OpenSanctions is a global database of PEPs (politically exposed persons), sanctioned entities, vessels, and crime watchlists, aggregated from 200+ official sources. The Automize connector covers Match (KYC screening), Search, Reconcile, Entity lookup, Statements, and dataset metadata via the Pro API.

• Regions: Hosted at api.opensanctions.org. Self-hosted available – point the connector at your instance. The dataset itself is updated daily; the Pro API is on the same daily refresh cadence.
• Plans: Free CC-BY data download (bulk). Pro API is a paid tier with rate-limited HTTP access. Enterprise tier offers a private instance + SLA + change-data-capture feeds.

Setting up the connection

Auth type: Bearer Token.

1. Sign up at opensanctions.org and provision a Pro API key from your account dashboard.
2. Paste it as the API token. Connector sends Authorization: ApiKey <key> on every request.
3. Hit Healthz right after pasting – returns the API build SHA + dataset version. Confirms the key is live.

Find your credentials at https://www.opensanctions.org/api/.

Rate limits

Pro API quota is per-month requests (varies by plan). Burst limit ~100 req/sec. Match endpoint is the heaviest – each query may scan multiple datasets. Connector throttles + retries on 429.

Data model

OpenSanctions data graph:

    Dataset             named source list (us_ofac_sdn, eu_fsf, ...)
      └─ Entities       Person | Company | Organization | Vessel |
                        Address | Crypto Wallet | Aircraft
           ├─ Properties (name, alias, birthDate, country, ...)
           ├─ Statements (the source-attributed claims that built
           │              this entity – exportable for audit trails)
           └─ Topics     PEP, sanction, role.pep, crime, debarment

Each entity has a stable id (e.g. ofac-12345, ru-cei-abc). Cross-
dataset deduplication links the same real-world entity across
multiple source lists – match against entity.id once, see the
aggregate.

Algorithms (configurable per Match call):

    name-based        fuzzy name matching only
    name-qualified    name + country + birth-year/founded-year
    regression-v1     ML-trained scorer combining many signals

Score thresholds (industry rules of thumb):

    >= 0.85   strong match – auto-block / EDD
    0.70-0.85 likely match – review queue
    0.50-0.70 weak signal  – manual review optional
    < 0.50    typically false positive

Available operations

10 operations available. Click any row to jump to its detail.

Operations

List Matching Algorithms

List supported matcher algorithms and their scoring profiles

No input parameters.

Tips

• GET /algorithms – lists Match algorithms available on your plan (name-based, name-qualified, regression-v1, …).
• Each algorithm exposes its tuneable parameters; pass them as algorithm_params on Match to override defaults.

Get Dataset

Get a dataset's metadata (counts, sources, schema)

Tips

• GET /datasets/{dataset_name} – full dataset metadata: publisher, jurisdiction, source URL, refresh cadence, entity count by schema.
• Publisher field is important for compliance attribution – record it in your screening audit log.

Get Entity

Fetch a single entity (person/organization/vessel/etc.) by id

Tips

• Returns the full entity record including aliases, source datasets, and supporting statements. entity_id is from a Match or Search response.
• datasets[] tells you WHY this entity is on the list (UK HMT, US OFAC, EU FSF, etc.) – material for any audit log.

Get Statements

Statement-level history for an entity (audit trail)

No input parameters.

Tips

• Underlying CSV of source statements that built the entity. Useful for explainability when an auditor asks 'why is this person on the list?'

Healthcheck

Service health probe

No input parameters.

Tips

• Liveness + dataset-freshness check. Returns build SHA, last_export_at, dataset_version, available scopes.
• Use as a credential health probe before kicking off batch screening – confirms the API is up + data is current.

List Datasets

List datasets / sanctions lists available

No input parameters.

Tips

• Catalog of all source lists. Filter active=true; published date in 'updated_at' tells you when each list was last refreshed.

Match Entities

Batch-match candidate entities against the index – primary screening endpoint

Tips

• The primary KYC operation. POST body: queries.{key}.schema (Person|Company|Organization|Vessel) + properties (name, birthDate, country, ...).
• Returns ranked matches with score in [0,1]. >= 0.7 is a strong match; 0.5-0.7 is review-required; < 0.5 typically false positive.
• Pass algorithm=name-based for fuzzy name matching, or algorithm=name-qualified for stricter (name + country + birth year).

Reconcile (OpenRefine)

OpenRefine-compatible reconciliation manifest endpoint

Tips

• OpenRefine-compatible reconciliation API. Drop the endpoint URL straight into OpenRefine; works for bulk batch matching from spreadsheets.

Reconcile Queries

OpenRefine reconciliation queries – POST a batch of name lookups

Tips

• Batch variant of Reconcile. Submit a queries dict ({key: {query, type, properties}, ...}) and get back matches per key.
• Faster than looping single Reconcile calls – one HTTP round-trip, server-side parallel matching.

Search

Free-text search over the chosen dataset

Tips

• GET-style full-text search. Use for ad-hoc lookups; Match is the right tool for compliance screening.
• limit caps results; default 10. dataset= filters to a specific list (e.g. 'us_ofac_sdn').

FAQ

Score threshold – what should I use?

>= 0.7 auto-block / require enhanced due diligence. 0.5-0.7 manual review. < 0.5 ignore. Tune empirically – your false-positive tolerance depends on the regulator (FATF jurisdictions are stricter than non-FATF).

How fresh is the data?

Most lists refresh daily (OFAC, UK HMT, EU FSF). Some PEP lists refresh weekly. Healthz returns dataset_version + last_export_at – fold these into your screening audit log.

Self-host vs Pro API – when do I switch?

Self-host when you need: (a) deterministic latency (no shared queue); (b) air-gapped deployment for sensitive jurisdictions; (c) > 1M screens/month (Pro API gets expensive). Self-hosting needs ~16 GB RAM and the daily CSV import pipeline.

Match a company by registration number?

Pass properties.registrationNumber and properties.jurisdiction. Match weights registration ID heavily – a hit on registration number alone is typically score=0.95+.

Related connectors

• Trulioo
• Smile-identity
• Sumsub
• Shufti-pro
• Veriff