canonical: https://jentic.com/apis/opensanctions.org/opensanctions # OpenSanctions API Jentic publishes the only available OpenAPI specification for OpenSanctions API, keeping it validated and agent-ready. OpenSanctions aggregates global sanctions lists, politically exposed persons (PEP) registers, and related risk datasets, and exposes them as searchable and matchable entity records. The API supports text search, structured entity matching, statement-level access, and catalog browsing, making it useful for KYC, compliance screening, and investigative research. ## For AI agents Search and match persons and companies against sanctions, PEP, and related risk lists via the OpenSanctions API. ## Scope Does not handle identity document verification, biometrics, or adverse media monitoring - use for sanctions, PEP, and entity-graph lookups only. ## Capabilities - Run free-text search against a chosen OpenSanctions dataset - Submit a structured entity (name, country, birthDate) for fuzzy matching against a dataset - Retrieve a full entity record by ID, including aliases and source statements - List entities adjacent to a given entity (relationships, ownership) - Query the underlying statements that back an entity - Browse the dataset catalog and supported matching algorithms ## Use cases ### KYC sanctions screening A regulated business screens new customers against OpenSanctions during onboarding by submitting a structured record (name, date of birth, country) to the match endpoint. The API returns scored candidate entities so the compliance team can adjudicate high-confidence hits without scraping individual sanction lists. Example prompt: POST to /match/{dataset} with the customer's name, country, and birthDate against dataset='default' and inspect candidates with score above 0.7. ### Investigative entity exploration Investigative journalists and analysts pull a starting entity by ID, then walk the adjacency graph via /entities/{entityId}/adjacent to discover related companies, beneficiaries, and PEP relationships. The statements endpoint exposes the underlying source records, supporting rigorous citation in published work. Example prompt: GET /entities/{entityId} for the target, then GET /entities/{entityId}/adjacent and follow the highest-confidence directorship edges. ### Vendor risk batch screening A procurement team runs its full vendor list through OpenSanctions on a recurring schedule by querying /search/{dataset} for each vendor name and flagging any non-empty hits. Recurring screening covers the case where a previously clean vendor later appears on a new list. Example prompt: Iterate the vendor list, GET /search/{dataset}?q=vendor_name, and write any non-empty result into the risk register for human review. ### Agent-driven sanctions screening through Jentic An onboarding agent calls OpenSanctions via Jentic to screen new accounts before activation, using the match endpoint for structured fields and falling back to text search for ambiguous inputs. Jentic isolates the API key so the agent can run thousands of screenings without ever holding the secret directly. Example prompt: Search Jentic for 'match a person against sanctions', load /match/{dataset}, and execute it for the new customer record at dataset='default'. ## Key endpoints | Method | Path | Description | | --- | --- | --- | | GET | /search/{dataset} | Run text search against a dataset | | POST | /match/{dataset} | Run structured entity match against a dataset | | GET | /entities/{entityId} | Retrieve an entity record by ID | | GET | /entities/{entityId}/adjacent | List entities adjacent to a given entity | | GET | /statements | Query underlying statements | | GET | /catalog | Browse datasets in the catalog | | GET | /algorithms | List supported matching algorithms | ## Key resources - **Search** — Free-text search across a chosen dataset - **Match** — Structured entity matching with scored candidates - **Entities** — Retrieve entity records and walk adjacency graph - **Statements** — Source-level statements backing each entity - **Catalog and algorithms** — Browse datasets and matching algorithms ## Why Jentic - **Setup:** Wiring the OpenSanctions API by hand means sending your key in the Authorization header, choosing the right dataset path segment, and shaping match and search requests for sanctions, PEP, and entity-graph lookups. Through Jentic you install once, import the OpenSanctions API from the API Directory, store the key once, and your agent calls it. - **Permission scoping:** OpenSanctions puts the entity id in the URL path (/entities/{entityId}), so a rule can pin your agent to one entity: it can read that entity and its adjacent records and nothing else. You choose the operations it may call, so broader match or search operations are not included unless you add them. - **Credential handling:** Your OpenSanctions API key is stored once, encrypted, by your own Jentic One instance and injected into the Authorization header at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'match a person against sanctions' or 'search OpenSanctions for a company', and Jentic returns the matching match or search operation with its dataset path parameter and request schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **ComplyAdvantage API** — Commercial sanctions and AML screening with managed risk scoring - **Refinitiv World-Check API** — Enterprise watchlist data with deep PEP and adverse media coverage - **Onfido API** — Identity verification and document checks alongside sanctions screening ## FAQ ### Why is there no official OpenAPI spec for OpenSanctions API? OpenSanctions did not previously publish an OpenAPI specification in this exact shape. Jentic generates and maintains this spec so that AI agents and developers can call OpenSanctions API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer. ### What authentication does the OpenSanctions API use? OpenSanctions uses an API key passed in the Authorization header. Through Jentic the key is held in the encrypted vault and injected at request time so the agent never sees the raw value, even when running batch screenings. ### Can I match structured customer records, not just names? Yes. POST /match/{dataset} accepts a structured query with fields like name, country, and birthDate, and returns scored candidate entities. This is more accurate than free-text /search for KYC use, where extra signals reduce false positives. ### What are the rate limits for the OpenSanctions API? OpenSanctions applies tier-based rate limits and dataset entitlements that are not encoded in the OpenAPI spec; the API key carries the entitlement. Check your account dashboard before scheduling high-volume batch screenings. ### How do I screen a customer through Jentic? Run pip install jentic, search 'match a person against sanctions', load /match/{dataset}, and execute it with the structured customer fields. Jentic injects the Authorization header and returns the candidate list with match scores. ### Which datasets are available? Browse /catalog to see datasets such as the default consolidated list, regional sanctions, and PEP collections. Pass the chosen dataset slug in the {dataset} path parameter on the search and match endpoints. ### Can I limit what my agent is allowed to do with the OpenSanctions API? Yes. Jentic One is self-hosted, so your own rules decide which OpenSanctions operations and credentials the agent may use. Because the entity id sits in the URL path at GET /entities/{entityId}, you can pin the agent to a single entity so it only reads that record and its adjacent entities and nothing else. Broader operations like POST /match/{dataset} or GET /search/{dataset} stay off unless you explicitly add them.