Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.1.0
info:
title: OpenSanctions API
description: "\n## Introduction\n\nThe [OpenSanctions](https://www.opensanctions.org) API allows users\
\ to search and query\nthe OpenSanctions [entity graph](https://www.opensanctions.org/docs/entities/).\
\ The API\ncan be used to search people, companies and [other types of entities](https://www.opensanctions.org/reference/#schema).\n\
In particular, it can be used to check the presence of a specific entity on [sanctions\nlists](https://www.opensanctions.org/datasets/sanctions/)\
\ or in the broader\n[OpenSanctions dataset](https://www.opensanctions.org/datasets/).\n\nSee also:\n\
* [Example code in Python, JS, and more](https://github.com/opensanctions/api-examples#folders-and-files)\n\
* [OpenSanctions API product page](https://www.opensanctions.org/docs/api/)\n* [Account and usage\
\ information](https://www.opensanctions.org/service/account/)\n* [API frequently asked questions](https://www.opensanctions.org/docs/api/faq/)\n\
\n### Which endpoint should I use?\n\nThe API supports a variety of methods to access and query OpenSanctions\
\ data:\n\n* **Entity matching ([/match](#tag/Matching/operation/match_match__dataset__post))**. Use\
\ this\n endpoint if you have a set of people or companies you wish to check against\n sanctions\
\ or PEPs lists. This API supports fuzzy name matching and using additional\n criteria (e.g. nationality,\
\ birth dates, tax identifiers, or addresses) to [score\n entity matches](https://www.opensanctions.org/matcher/)\
\ and avoid false positives.\n\n [Read the tutorial](https://www.opensanctions.org/docs/api/matching/)\
\ for an introduction in how to use the matching API. You will also want to familiarise yourself with\
\ the [entity data model](https://www.opensanctions.org/docs/entities/) used by the system and the\
\ [data dictionary](https://www.opensanctions.org/reference/) entity\n types and properties.\n\n\
* **Text-based search ([/search](#tag/Matching/operation/search_search__dataset__get))**\n is a useful\
\ tool for providing a user-facing search interface, including faceted\n navigation. The search uses\
\ [industry standard string syntax](https://www.opensanctions.org/docs/api/search/)\n which can be\
\ used to perform field-specific searches, wildcard and fuzzy searches. The\n scores and ranking\
\ are generated by the search index and express search relevance, not\n match quality.\n\n* **Entity\
\ fetching ([/entities](#tag/Data-access/operation/fetch_entity_entities__entity_id__get))**.\n Retrieve\
\ the full details about an entity in the database. The full record will include\n adjacent entities,\
\ such as company owners and subsidiaries, family members and associates\n for PEPs, and detailed\
\ records for addresses and identification documents linked to\n entities. This endpoint can be used\
\ to perform incremental traversal of the OpenSanctions\n graph.\n\n Read about the [entity data\
\ model](https://www.opensanctions.org/docs/entities/) and\n consult the [data dictionary](https://www.opensanctions.org/reference/)\
\ to see all entity\n types and their respective properties.\n\n* **Statement-based data access ([/statements](#tag/Data-access/operation/statements_statements_get))**\n\
\ allows browsing OpenSanctions data in its most granular form. This can be useful to see\n what\
\ source dataset a particular assertion (e.g. the birth date of a person) is sourced\n from. Read\
\ about the [statement data model](https://www.opensanctions.org/docs/statements/).\n\n* **OpenRefine\
\ Reconciliation API ([/reconcile](#tag/Reconciliation))**. A specialised API\n that lets OpenSanctions\
\ data be used by the [OpenRefine](https://openrefine.org/) data\n cleaning tool. Read [the tutorial](https://www.opensanctions.org/articles/2022-01-10-openrefine-reconciliation/)\n\
\ to understand how this can be used as an investigative tool.\n\n## Authorization and API keys\n\
\nTo use the OpenSanctions API, you need an API key. Please visit the [API product page](https://www.opensanctions.org/api/)\
\ or [contact us](https://www.opensanctions.org/contact/) to learn more. OpenSanctions will issue\
\ free API keys to users in academia, non-profit organizations and those working in for-profit journalism.\n\
\n* [Using API authentication](https://www.opensanctions.org/docs/api/authentication/)\n\n## Dataset\
\ scopes\n\nThe API provides a sophisticated mechanism for selecting the scope of the data\nthat sould\
\ be queried by a particular request - for example, you can run a name\nagainst all sanctions lists,\
\ but not the datasets listing PEPs.\n\nDatasets can be of two types: source datasets - e.g. `us_ofac_sdn`\
\ (the US main\nsanctions list) contain only entities from one source. These source datasets are\n\
grouped into collections - e.g. [`sanctions`](https://www.opensanctions.org/datasets/sanctions/),\n\
which contains entities from all sanctions lists contained in the database, or\n[`peps`](https://www.opensanctions.org/datasets/peps/),\
\ which covers all politically\nexposed persons sourced from various origins. If you are unsure which\
\ dataset you\nwant to screen against, use [`default`](https://www.opensanctions.org/datasets/default/)\
\ (the full\nOpenSanctions dataset).\n\nThese dataset scopes can be applied to searches and mapping\
\ requests by selecting\nthe desired scope in the URL path of the query: `/search/sanctions` will\
\ search\nall sanctioned entities, while `/search/us_ofac_sdn` limits the search to only\nthose entities\
\ listed on the US list.\n\nPlease note that each indivdual entity (e.g. a sanctioned person) can\
\ be linked to\nmultiple datasets because it has been [de-duplicated](https://www.opensanctions.org/docs/identifiers/).\n\
\n* See also: [List of datasets in OpenSanctions](https://www.opensanctions.org/datasets/)"
termsOfService: https://www.opensanctions.org/docs/terms
contact:
name: OpenSanctions
url: https://www.opensanctions.org/
email: info@opensanctions.org
version: yente 5.5.0
x-logo:
url: https://assets.opensanctions.org/images/ura/logo_text_spaced.svg
externalDocs:
description: Home page
url: https://www.opensanctions.org
paths:
/match/{dataset}:
post:
tags:
- Matching
summary: Query by example matcher
description: "Match entities based on a complex set of criteria, like name, date of birth\nand nationality\
\ of a person. This works by submitting a batch of entities, each\nformatted like those returned\
\ by the API.\n\nTutorials:\n* [Using the matching API](https://www.opensanctions.org/docs/api/matching/)\n\
* [Configuring the scoring system](https://www.opensanctions.org/docs/api/scoring/)\n\nFor example,\
\ the following would be valid query examples:\n\n```json\n\"queries\": {\n \"entity1\": {\n\
\ \"schema\": \"Person\",\n \"properties\": {\n \"name\": [\"John Doe\"\
],\n \"birthDate\": [\"1975-04-21\"],\n \"nationality\": [\"us\"]\n \
\ }\n },\n \"entity2\": {\n \"schema\": \"Company\",\n \"properties\":\
\ {\n \"name\": [\"Brilliant Amazing Limited\"],\n \"jurisdiction\": [\"\
hk\"],\n \"registrationNumber\": [\"84BA99810\"]\n }\n }\n}\n```\nThe values\
\ for `entity1`, `entity2` can be chosen freely to correlate results\non the client side when\
\ the request is returned. The responses will be given\nfor each submitted example like this:\n\
\n```json\n\"responses\": {\n \"entity1\": {\n \"query\": {},\n \"results\":\
\ [...]\n },\n \"entity2\": {\n \"query\": {},\n \"results\": [...]\n }\n\
}\n```\n\nThe precision of the results will be dependent on the amount of detail submitted\nwith\
\ each example. The following properties are most helpful for particular types:\n\n* **Person**:\
\ ``name``, ``birthDate``, ``nationality``, ``idNumber``, ``address``\n* **Organization**: ``name``,\
\ ``country``, ``registrationNumber``, ``address``\n* **Company**: ``name``, ``jurisdiction``,\
\ ``registrationNumber``, ``address``,\n ``incorporationDate``"
operationId: match_match__dataset__post
parameters:
- name: dataset
in: path
required: true
schema:
type: string
description: Data source or collection name to scope the query to.
examples:
- default
title: Dataset
description: Data source or collection name to scope the query to.
- name: limit
in: query
required: false
schema:
type: integer
maximum: 500
title: Number of results to return
default: 5
- name: threshold
in: query
required: false
schema:
type: number
title: Score threshold for results to be considered matches
default: 0.7
- name: cutoff
in: query
required: false
schema:
type: number
title: Deprecated, use `threshold` instead. Lower bound of score for results to be returned
at all
deprecated: true
default: 0.7
deprecated: true
- name: algorithm
in: query
required: false
schema:
type: string
title: 'Scoring algorithm to use, currently "best" is defined as logic-v2, options: logic-v2,
ofac, name-based, name-qualified, logic-v1, regression-v1'
default: best
- name: include_dataset
in: query
required: false
schema:
type: array
items:
type: string
title: Only include the given datasets in results
default: []
- name: exclude_schema
in: query
required: false
schema:
type: array
items:
type: string
title: Remove the given types of entities from results
default: []
- name: exclude_dataset
in: query
required: false
schema:
type: array
items:
type: string
title: Remove the given datasets from results
default: []
- name: topics
in: query
required: false
schema:
type: array
items:
type: string
title: Only return results that match any of the given topics
default: []
- name: changed_since
in: query
required: false
schema:
anyOf:
- type: string
pattern: ^\d{4}-\d{2}-\d{2}(T\d{2}(:\d{2}(:\d{2})?)?)?$
- type: 'null'
title: Match against entities that were updated since the given date
- name: exclude_entity_ids
in: query
required: false
schema:
type: array
items:
type: string
maxItems: 50
title: A list of entities IDs to exclude from matching
description: The entity IDs supplied here do not have to be canonical. Supplying any of the
referents of a merged entity will exclude that entity. This parameter may be useful for example
to exclude false-positive matches that have been decided upon by a human.
default: []
description: The entity IDs supplied here do not have to be canonical. Supplying any of the referents
of a merged entity will exclude that entity. This parameter may be useful for example to exclude
false-positive matches that have been decided upon by a human.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/EntityMatchQuery'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/EntityMatchResponse'
'400':
description: Invalid query
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/search/{dataset}:
get:
tags:
- Matching
summary: Simple entity search
description: 'Search endpoint for matching entities based on a simple piece of text, e.g.
a name. This can be used to implement a simple, user-facing search. For proper
entity matching, the multi-property matching API should be used instead.
Search queries can include field-specific fitlers, wildcards and fuzzy searches.
See also: [search API documentation](https://www.opensanctions.org/docs/api/search/).'
operationId: search_search__dataset__get
parameters:
- name: dataset
in: path
required: true
schema:
type: string
description: Data source or collection name to scope the query to.
examples:
- default
title: Dataset
description: Data source or collection name to scope the query to.
- name: q
in: query
required: false
schema:
type: string
title: Query text
default: ''
- name: schema
in: query
required: false
schema:
type: string
title: Types of entities that can match the search
default: Thing
- name: include_dataset
in: query
required: false
schema:
type: array
items:
type: string
title: Restrict the search scope to datasets (that are in the given scope) to search entities
within.
description: Limit the results to entities that are part of at least one of the given datasets.
default: []
description: Limit the results to entities that are part of at least one of the given datasets.
- name: exclude_dataset
in: query
required: false
schema:
type: array
items:
type: string
title: Remove specific datasets (that are in the given scope) from the search scope.
default: []
- name: exclude_schema
in: query
required: false
schema:
type: array
items:
type: string
title: Remove the given types of entities from results
default: []
- name: changed_since
in: query
required: false
schema:
anyOf:
- type: string
pattern: ^\d{4}-\d{2}-\d{2}(T\d{2}(:\d{2}(:\d{2})?)?)?$
- type: 'null'
title: Search entities that were updated since the given date
- name: countries
in: query
required: false
schema:
type: array
items:
type: string
title: Filter by country codes
default: []
- name: topics
in: query
required: false
schema:
type: array
items:
type: string
title: Filter by entity topics (e.g. sanction, role.pep)
default: []
- name: datasets
in: query
required: false
schema:
type: array
items:
type: string
title: Filter by dataset names, for faceting use (respects operator choice).
default: []
- name: filter
in: query
required: false
schema:
type: array
items:
type: string
title: Filter by entity properties (e.g. programId, birthDate)
description: Use the syntax `field:value` to filter on a specific field. Properties are indexed
as fields named `properties.birthDate:1985`.
default: []
description: Use the syntax `field:value` to filter on a specific field. Properties are indexed
as fields named `properties.birthDate:1985`.
- name: limit
in: query
required: false
schema:
type: integer
maximum: 500
title: Number of results to return
default: 10
- name: offset
in: query
required: false
schema:
type: integer
maximum: 9499
title: Start at result with given offset
default: 0
- name: sort
in: query
required: false
schema:
type: array
items:
type: string
title: Sorting criteria
default: []
- name: target
in: query
required: false
schema:
anyOf:
- type: boolean
- type: 'null'
title: Include only targeted entities
description: Please specify a list of topics of concern, instead.
deprecated: true
description: Please specify a list of topics of concern, instead.
deprecated: true
- name: fuzzy
in: query
required: false
schema:
type: boolean
title: Allow fuzzy query syntax
default: false
- name: simple
in: query
required: false
schema:
type: boolean
title: Use simple syntax for user-facing query boxes
default: false
- name: facets
in: query
required: false
schema:
type: array
items:
$ref: '#/components/schemas/Facet'
title: Facet counts to include in response.
default:
- countries
- topics
- datasets
- name: filter_op
in: query
required: false
schema:
$ref: '#/components/schemas/Operator'
title: Define behaviour of multiple filters on one field
description: Logic to use when combining multiple filters on the same field (topics, countries,
datasets). Please specify AND for new integrations (to override a legacy default) and when
building a faceted user interface.
default: OR
description: Logic to use when combining multiple filters on the same field (topics, countries,
datasets). Please specify AND for new integrations (to override a legacy default) and when building
a faceted user interface.
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/SearchResponse'
'400':
description: Invalid query
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/entities/{entity_id}:
get:
tags:
- Data access
summary: Fetch Entity
description: 'Retrieve a single entity by its ID. The entity will be returned in
full, with data from all datasets and with nested entities (adjacent
passport, sanction and associated entities) included. If the entity ID
has been merged into a different canonical entity, an HTTP redirect will
be triggered.
Intro: [entity data model](https://www.opensanctions.org/docs/entities/).'
operationId: fetch_entity_entities__entity_id__get
parameters:
- name: entity_id
in: path
required: true
schema:
type: string
description: ID of the entity to retrieve
examples:
- Q7747
title: Entity Id
description: ID of the entity to retrieve
- name: nested
in: query
required: false
schema:
type: boolean
title: Include adjacent entities (e.g. addresses, family) in response
default: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/EntityResponse'
'308':
description: The entity was merged into another ID
'404':
description: Entity not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/entities/{entity_id}/adjacent:
get:
tags:
- Data access
summary: Fetch Adjacent Entities*
description: '***Beta:** This endpoint is released for wider testing and is not yet recommended
for production use. We welcome feedback. Its interface may change without announcement.
Retrieve entities adjacent to a given entity e.g. passports, sanctions, associates.
This endpoint offers the same information as adjacent entities nested in
[`/entities/{entity_id}`](#tag/Data-access/operation/fetch_entity_entities__entity_id__get),
but offers pagination for cases where the number of results is potentially very large.'
operationId: Fetch_Adjacent_Entities__entities__entity_id__adjacent_get
parameters:
- name: entity_id
in: path
required: true
schema:
type: string
description: ID of the entity whose graph context was requested
examples:
- Q7747
title: Entity Id
description: ID of the entity whose graph context was requested
- name: sort
in: query
required: false
schema:
type: array
items:
type: string
title: Sorting criteria
default: []
- name: limit
in: query
required: false
schema:
type: integer
maximum: 500
title: Number of results per property to return
default: 10
- name: offset
in: query
required: false
schema:
type: integer
maximum: 9499
title: Start at result with given offset
default: 0
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/EntityAdjacentResponse'
'308':
description: The entity was merged into another ID
'404':
description: Entity not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/entities/{entity_id}/adjacent/{property_name}:
get:
tags:
- Data access
summary: Fetch Adjacent By Property*
description: '***Beta:** This endpoint is released for wider testing and is not yet recommended
for production use. We welcome feedback. Its interface may change without announcement.
Retrieve entities adjacent to a given entity for a specific property.
This endpoint offers the same information as adjacent entities nested in
[`/entities/{entity_id}`](#tag/Data-access/operation/fetch_entity_entities__entity_id__get),
but offers pagination for cases where the number of results is potentially very large.'
operationId: Fetch_Adjacent_by_Property__entities__entity_id__adjacent__property_name__get
parameters:
- name: entity_id
in: path
required: true
schema:
type: string
description: ID of the entity hose graph context was requested
examples:
- Q7747
title: Entity Id
description: ID of the entity hose graph context was requested
- name: property_name
in: path
required: true
schema:
type: string
description: Name of the property to fetch adjacent entities for
examples:
- address
- ownershipOwner
title: Property Name
description: Name of the property to fetch adjacent entities for
- name: sort
in: query
required: false
schema:
type: array
items:
type: string
title: Sorting criteria
default: []
- name: limit
in: query
required: false
schema:
type: integer
maximum: 500
title: Number of results per property to return
default: 10
- name: offset
in: query
required: false
schema:
type: integer
maximum: 9499
title: Start at result with given offset
default: 0
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/AdjacentResultsResponse'
'308':
description: The entity was merged into another ID
'404':
description: Entity or property not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/reconcile/{dataset}:
get:
tags:
- Reconciliation
summary: Reconciliation manifest
description: 'Reconciliation API, emulates Google Refine API. This endpoint can be used
to bulk match entities against the system using an end-user application like
[OpenRefine](https://openrefine.org). The reconciliation API uses the same
search and matching functions as the matching API and will also produce
scores that reflect additional properties like country or date of birth, if
specified.
Tutorial: [Using OpenRefine to match entities in a spreadsheet](https://www.opensanctions.org/articles/2022-01-10-openrefine-reconciliation/).'
operationId: reconcile_reconcile__dataset__get
parameters:
- name: dataset
in: path
required: true
schema:
type: string
description: Data source or collection name to scope the query to.
examples:
- default
title: Dataset
description: Data source or collection name to scope the query to.
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/FreebaseManifest'
'400':
description: Invalid query
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/healthz:
get:
tags:
- System information
summary: Health check
description: 'No-op basic health check. This is used by cluster management systems like
Kubernetes to verify the service is responsive.'
operationId: healthz_healthz_get
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/StatusResponse'
'500':
description: Service is not ready
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/readyz:
get:
tags:
- System information
summary: Search index readiness check
description: 'Search index health check. This is used to know if the service has completed
its index building.'
operationId: readyz_readyz_get
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/StatusResponse'
'503':
description: Index is not ready
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/catalog:
get:
tags:
- Data access
summary: Data catalog
description: 'Return the service manifest, which includes a list of all indexed datasets.
The manifest is the configuration file of the yente service. It specifies what
data sources are included, and how often they should be loaded.'
operationId: catalog_catalog_get
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/DataCatalogModel'
'304':
description: The catalog has not changed.
/algorithms:
get:
tags:
- System information
summary: Algorithms
description: 'Return a list of the supported matching/scoring algorithms used by the matching
endpoint.
See also the [scoring documentation](https://www.opensanctions.org/docs/api/scoring/).'
operationId: algorithms_algorithms_get
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/AlgorithmResponse'
/updatez:
post:
tags:
- System information
summary: Force an index update
description: 'Force the index to be re-generated. Works only if the update token is provided
(serves as an API key, and can be set in the container environment).'
operationId: force_update_updatez_post
parameters:
- name: token
in: query
required: false
schema:
type: string
title: Update token for authentication
default: ''
- name: sync
in: query
required: false
schema:
type: boolean
title: Wait until indexing is complete
default: false
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/StatusResponse'
'403':
description: Authorization error.
content:
application/json:
schema:
$ref: '#/component
# --- truncated at 32 KB (63 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/opensanctions/refs/heads/main/openapi/opensanctions-api-openapi.yml