### Python Quickstart: Match a Person Source: https://www.opensanctions.org/docs/api/quickstart Use this snippet to perform your first entity matching request against the OpenSanctions API. Ensure you have the 'requests' library installed and your OPENSANCTIONS_API_KEY environment variable set. ```python # dependencies = ["requests"] # # Run with: uv run quickstart.py import os import requests BASE_URL = "https://api.opensanctions.org" API_ENDPOINT = "match" DATASET = "default" API_KEY = os.environ.get("OPENSANCTIONS_API_KEY") session = requests.Session() session.headers["Authorization"] = f"ApiKey {API_KEY}" query = { "schema": "Person", "properties": { "firstName": ["Aleksandr"], "lastName": ["Zacharov"], "birthDate": ["1965"], }, } response = session.post( f"{BASE_URL}/{API_ENDPOINT}/{DATASET}", json={"queries": {"q": query}}, ) response.raise_for_status() results = response.json()["responses"]["q"]["results"] for r in results: print(f"\n{r['caption']}, ID: {r['id']}, Match score: {r['score']}") print('Available information:\n ', ', '.join(list(r.keys()))) if 'properties' in r.keys(): print('Available properties:\n ', ', '.join(list(r['properties'].keys()))) if 'topics' in r['properties']: print('Risk topics:\n ', ', '.join(list(r['properties']['topics']))) ``` -------------------------------- ### Basic API Request Example Source: https://www.opensanctions.org/docs/api/quickstart This example demonstrates a basic query to the OpenSanctions API. Ensure you have the correct API endpoint and parameters for your search. ```python from opensanctions import Api api = Api() results = api.search_entities(name="Aleksandr Zacharov") for result in results: print(result.caption) print(result.schema) print(result.id) ``` -------------------------------- ### Authorization Header Example Source: https://www.opensanctions.org/docs/bulk/delivery-service Example of how to format the Authorization header for authenticating with the data delivery service. This token is provided during customer onboarding. ```http Authorization: Token [yoursecret] ``` -------------------------------- ### API Request with Best Algorithm Source: https://www.opensanctions.org/docs/api/tuning Example of how to specify the 'best' algorithm in an API request to get ranked results. ```http GET /api/3/search?q=john+doe&algorithm=best ``` -------------------------------- ### Query-by-Example with FollowTheMoney Schema Source: https://www.opensanctions.org/docs/api/request Construct a query using the FollowTheMoney (FtM) format to describe an entity for screening. This example defines a 'Person' with specific properties. ```python ... query = { "schema": "Person", "properties": { "firstName": ["Arkadii"], "fatherName": ["Romanovich"], "lastName": ["Rotenberg", "Ротенберг"], "birthDate": ["1951"], "nationality": ["Russia"], }, } ... ``` -------------------------------- ### Python Requests Example Source: https://www.opensanctions.org/docs/api/authentication This Python code snippet demonstrates how to set up a requests session with the `Authorization` header for API authentication. ```APIDOC ## Python Requests Example ### Description This example shows how to use the Python `requests` library to authenticate API calls by setting the `Authorization` header, typically read from an environment variable. ### Code ```python import os import requests API_URL = "https://api.opensanctions.org" API_KEY = os.environ.get("OPENSANCTIONS_API_KEY") session = requests.Session() session.headers['Authorization'] = f"ApiKey {API_KEY}" # Example: Run a match query query = {"schema": "Person", "properties": {"name": ["Vladimir Putin"]}} request = {"queries": {"query": query}} response = session.post(f"{API_URL}/match/default", json=request) response.raise_for_status() results = response.json().get("responses").get("query").get("results") # Example: Fetch an entity response = session.get(f"{API_URL}/entities/Q7747") response.raise_for_status() entity_data = response.json() ``` ``` -------------------------------- ### OpenSanctions /match API Request Example Source: https://www.opensanctions.org/docs/api/request This example demonstrates how to use the Python requests library to query the OpenSanctions /match API. It shows how to set up authentication, define query parameters for filtering results (topics, include_dataset, algorithm, threshold), and structure the request body with entity details for both a person and a company. ```APIDOC ## OpenSanctions /match API Request ### Description This endpoint uses a query-by-example approach to find matching entities in the OpenSanctions database. You provide a detailed description of an entity, and the API returns ranked candidates. ### Method `POST` ### Endpoint `/match/{dataset}` ### Parameters #### Query Parameters - **topics** (array of strings) - Optional - Only consider entities that have at least one of these topics. - **include_dataset** (array of strings) - Optional - Only consider entities that are in at least one of these datasets. - **algorithm** (string) - Optional - The matching algorithm to use. Defaults to `best`. - **threshold** (float) - Optional - A score threshold for matching. Higher values may yield fewer results. #### Request Body - **queries** (object) - Required - Contains the entity descriptions for matching. - **q** (object) - Required - The entity description. - **schema** (string) - Required - The Follow The Money (FtM) schema of the entity (e.g., `Person`, `Company`). - **properties** (object) - Required - A dictionary of entity properties to match against. - *Keys are property names (e.g., `firstName`, `lastName`, `name`, `birthDate`, `jurisdiction`).* - *Values are arrays of strings representing possible values for the property.* ### Request Example ```python import os import requests API_KEY = os.environ.get("OPENSANCTIONS_API_KEY") BASE_URL = "https://api.opensanctions.org" API_ENDPOINT = "match" DATASET = "default" # the dataset to look for matches in PARAMS = { "topics": [ "sanction", "sanction.linked", "debarment", ], "include_dataset": [ "us_ofac_sdn", "us_ofac_cons", ], "algorithm": "logic-v2", "threshold": 0.8, } PERSON_QUERY = { "schema": "Person", "properties": { "firstName": ["Arkadii"], "fatherName": ["Romanovich"], "lastName": ["Rotenberg", "Ротенберг"], "birthDate": ["1951"], }, } COMPANY_QUERY = { "schema": "Company", "properties": { "name": ["Stroygazmontazh"], "jurisdiction": ["Russia"], }, } session = requests.Session() session.headers["Authorization"] = f"ApiKey {API_KEY}" person_response = session.post( f"{BASE_URL}/{API_ENDPOINT}/{DATASET}", json={"queries": {"q": PERSON_QUERY}}, params=PARAMS, ) company_response = session.post( f"{BASE_URL}/{API_ENDPOINT}/{DATASET}", json={"queries": {"q": COMPANY_QUERY}}, params=PARAMS, ) ``` ### Response #### Success Response (200) - The response will be a JSON object containing a list of matching entities, ranked by relevance. The exact structure is detailed in the `/docs/api/response/` documentation. ``` -------------------------------- ### Entity Status Examples Source: https://www.opensanctions.org/reference Examples of entity statuses, including active, inactive, and dissolved states with their respective dates. ```text Active / Inactive ``` ```text Dissolved (last known activity October 2024) ``` ```text Liquidated on 12 November 2022 ``` -------------------------------- ### Basic Field Query Example Source: https://www.opensanctions.org/docs/api/search Demonstrates how to combine multiple field queries to search for entities. Use this to narrow down search results by specific criteria. ```text name_parts:vladimir properties.lastName:Putin phones:+4915223433333 ``` -------------------------------- ### Interval Start Date Property Source: https://www.opensanctions.org/reference Represents the start date of an interval. This is a 'date' type. ```json { "startDate": "date" } ``` -------------------------------- ### Entity Schema Example Source: https://www.opensanctions.org/reference An example of the JSON schema used to represent entities within the OpenSanctions dataset. This schema defines the structure and types of data associated with each entity. ```json { "entity": { "type": "thing", "name": "Thing", "weakAlias": { "children": [ [ "$", "td", null, { "children": [ [ "$", "code", null, { "children": [ [ "$", "span", null, { "className": "text-muted", "children": [ "Thing", ":" ] } ], [ "$", "wbr", null, {} ], "weakAlias" ] } ], [ "$", "td", null, { "children": [ [ "$", "code", null, { "children": "name" } ], " ", "(", [ "$", "code", null, { "children": 384 } ], ")" ] } ], [ "$", "td", null, { "children": [ [ "$", "div", null, { "className": "mb-1", "children": [ [ "$", "strong", null, { "children": "Weak alias" } ] ] } ], [ "$", "div", null, { "className": "Reference-module-scss-module___fmbFhG__propDescription", "children": [ [ "$", "article", null, { "children": [ [ "$", "p", null, { "children": "A relatively broad or generic alias that should not be used for matching in screening systems." } ] ] } ] ] } ] ] } ] ] } ] ] } } } ``` -------------------------------- ### First Matching API Request Source: https://www.opensanctions.org/docs/api/quickstart This example shows how to make a basic POST request to the /match endpoint to find potential matches for a person based on provided properties. ```APIDOC ## POST /match/{dataset} ### Description Uses query-by-example to find ranked candidates from the database based on a detailed entity description. ### Method POST ### Endpoint `/match/{dataset}` ### Parameters #### Path Parameters - **dataset** (string) - Required - The dataset to search within (e.g., `default`). #### Query Parameters None #### Request Body - **queries** (object) - Required - An object containing the queries to be executed. - **q** (object) - Required - The query object. - **schema** (string) - Required - The schema type of the entity (e.g., `Person`, `Organization`). - **properties** (object) - Required - An object containing the properties of the entity to match against. - **firstName** (array of strings) - Optional - First name(s) of the person. - **lastName** (array of strings) - Optional - Last name(s) of the person. - **birthDate** (array of strings) - Optional - Birth date(s) of the person (YYYY, YYYY-MM, or YYYY-MM-DD). ### Request Example ```json { "queries": { "q": { "schema": "Person", "properties": { "firstName": ["Aleksandr"], "lastName": ["Zacharov"], "birthDate": ["1965"] } } } } ``` ### Response #### Success Response (200) - **responses** (object) - Contains the results for each query. - **q** (object) - The response for the query named 'q'. - **results** (array) - A list of matching entities, ranked by score. - **caption** (string) - A human-readable name for the entity. - **id** (string) - The unique identifier for the entity. - **score** (number) - The match score for this candidate. - **properties** (object) - Contains various properties of the matched entity. - **topics** (array of strings) - Risk topics associated with the entity. #### Response Example ```json { "responses": { "q": { "results": [ { "caption": "Aleksandr Zacharov", "id": "6015118b3111111111111111", "score": 0.95, "properties": { "firstName": ["Aleksandr"], "lastName": ["Zacharov"], "birthDate": ["1965-01-01"], "nationality": ["Russian"], "topics": ["russia-direct-investment", "oligarch"] } } ] } } } ``` ``` -------------------------------- ### Interval Properties: startDate Source: https://www.opensanctions.org/reference Defines the start date of an interval. This property is of type 'date' and has a length of 32. ```json { "startDate": "Interval:startDate" } ``` -------------------------------- ### Date Property: startDate Source: https://www.opensanctions.org/reference Represents the start date for an interval, such as the issue date of a document or the beginning of a sanctioned status. The type is 'date' with a length of 32. ```json [\"$\",\"tr\",\"startDate\",{\"children\":[{\"$\":\"td\",null,{\"children\":[false,[\"$\",\"code\",null,{\"children\":[{\"$\":\"span\",null,{\"className\":\"text-muted\",\"children\":[\"Interval\",\":\"]}},{\"$\":\"wbr\",null,{}},\"startDate\"]}]}]},{\"$\":\"td\",null,{\"children\":[[\"$\",\"code\",null,{\"children\":[{\"$\":\"a\",null,{\"href\":\"https://followthemoney.tech/explorer/types/date/\",\"children\":\"date\"}}]}]},\" \",\"(\",[\"$\",\"code\",null,{\"children\":32}]),\" )\"]}},{\"$\":\"td\",null,{\"children\":[[\"$\",\"div\",null,{\"className\":\"mb-1\",\"children\":[{\"$\":\"strong\",null,{\"children\":\"Start date\"}}]}]},[[\"$\",\"div\",null,{\"className\":\"Reference-module-scss-module __fmbFhG __propDescription\",\"children\":[{\"$\":\"article\",null,{\"children\":[{\"$\":\"p\",null,{\"children\":\"The date of issue of a document, or on which a relationship, sanctioned status, occupation, etc. started\"}}]}]},\"$undefined\"],null,null]}}]}]} ``` -------------------------------- ### Example Data Structure Source: https://www.opensanctions.org/reference Illustrates a nested data structure with various data types including strings, numbers, booleans, and nested arrays. This is a common pattern for representing complex entities. ```json ["$","tr",null,{"children":[["$","td",null,{"children":[["$","code",null,{"children":[["$","span",null,{"className":"text-muted","children":["Interval",": "]}]],["$","wbr",null,{}],"endDate"]}]],null]},{"children":[["$","code",null,{"children":["$","a",null,{"href":"https://followthemoney.tech/explorer/types/date/","children":"date"}]}]]," ","(",["$","code",null,{"children":32}],")"}]},{"children":[["$","div",null,{"className":"mb-1","children":["$","strong",null,{"children":"End date"}]}],[[ "$","div",null,{"className":"Reference-module-scss-module___fmbFhG___propDescription","children":["$","article",null,{"children":["$","p",null,{"children":["The date of expiry of a document, or on which a relationship, sanctioned status, occupation, etc."]}]}]}]}]}]}] ``` -------------------------------- ### Thing: topics property Source: https://www.opensanctions.org/reference Defines the 'topics' property for a 'Thing' entity, used for controlled tags to qualify entities and associate them with risk categories. It includes examples of common topics like 'sanction', 'debarment', and 'role.pep'. ```json { "children": [ ["$", "td", null, {"children": [false, ["$", "code", null, {"children": [["$", "span", null, {"className": "text-muted", "children": ["Thing", ":"]}]], ["$", "wbr", null, {}], "topics"]}]], null] ], ["$", "td", null, {"children": [["$", "code", null, {"children": "topic"}]], " (", ["$", "code", null, {"children": 64}] , ")"] ], ["$", "td", null, {"children": [["$", "div", null, {"className": "mb-1", "children": ["$", "strong", null, {"children": "Topics"}]}]], [[$"div", null, {"className": "Reference-module-scss-module__fmbFhG__propDescription", "children": ["$", "article", null, {"children": ["$", "p", null, {"children": "Controlled tags used to qualify the entity and associate it with a risk category"}]}]}]], "$undefined"], null, [["$", "div", null, {"childr"]] ] } ``` -------------------------------- ### Enrich OpenRefine Tables with Reconciliation API Data Extension Source: https://www.opensanctions.org/changelog This example demonstrates how to use the Reconciliation API's Data Extension protocol to add new columns to OpenRefine tables. Ensure your OpenRefine setup is compatible with this protocol. ```json ["$","p",null,{"children":["Reconciliation API's Data Extension protocol for the first time, allowing users to enrich OpenRefine tables with new columns using the API.\"}\\],[\"$\",\"p\",null,{\"children\":\"See more: https://github.com/opensanctions/yente/releases/tag/v4.2.0\"}\\ ]]}" ] ``` -------------------------------- ### On-Premise Deployment Reference Source: https://www.opensanctions.org/docs/bulk/delivery-service Link to yente documentation for running the service on-premise. This section provides further details for self-hosted deployments. ```link https://yente.followthemoney.tech/delivery/ ``` -------------------------------- ### OpenSanctions API Match Request Example Source: https://www.opensanctions.org/docs/api/request Demonstrates how to make a /match API request using Python's requests library. Includes setting up authentication, defining query parameters, and structuring person and company queries. ```python import os import requests API_KEY = os.environ.get("OPENSANCTIONS_API_KEY") BASE_URL = "https://api.opensanctions.org" API_ENDPOINT = "match" DATASET = "default" # the dataset to look for matches in PARAMS = { "topics": [ "sanction", "sanction.linked", "debarment", ], "include_dataset": [ "us_ofac_sdn", "us_ofac_cons", ], "algorithm": "logic-v2", # the current default via `best`; you may want to pin it "threshold": 0.8, # higher than the default (0.7); may lead to fewer results } PERSON_QUERY = { "schema": "Person", # the FtM schema "properties": { "firstName": ["Arkadii"], "fatherName": ["Romanovich"], "lastName": ["Rotenberg", "Ротенберг"], "birthDate": ["1951"], }, } COMPANY_QUERY = { "schema": "Company", # the FtM schema "properties": { "name": ["Stroygazmontazh"], "jurisdiction": ["Russia"], }, } session = requests.Session() session.headers["Authorization"] = f"ApiKey {API_KEY}" person_response = session.post( f"{BASE_URL}/{API_ENDPOINT}/{DATASET}", json={"queries": {"q": PERSON_QUERY}}, params=PARAMS, ) company_response = session.post( f"{BASE_URL}/{API_ENDPOINT}/{DATASET}", json={"queries": {"q": COMPANY_QUERY}}, params=PARAMS, ) ``` -------------------------------- ### Person Schema Example Source: https://www.opensanctions.org/docs/api/response This snippet shows an example of a 'Person' entity returned by the API, including various identifying and descriptive properties. ```APIDOC ## Person Schema ### Description Represents an individual entity within the OpenSanctions dataset. ### Response Example (200 OK) ```json { "id": "NK-aU5ybkbRFJucf8YMwsJvDw", "caption": "Alexander Vyacheslavovich ZAKHAROV", "schema": "Person", "properties": { "address": [ "272 Pushkinskaya Street, Apt 41, Izhevsk, 426008", "IZHEVSK, 426008" ], "addressEntity": [ "addr-a300b5bf407e387d2cf1f1a2f74b8178edde276e" ], "alias": [ "Zakharov Oleksandr Viacheslavovych", "Aleksandr Vyacheslavovich ZAKHAROV", "ЗАХАРОВ Александр Вячеславович", "Alexander Vyacheslavovich Zakharov", "Zacharov Aleksandr Vjačeslavovič", "Александр Вячеславович ЗАХАРОВ", "Aleksandr Vjačeslavovič ZACHAROV" ], "birthCountry": [ "ru" ], "birthDate": [ "1965-09-21" ], "birthPlace": [ "Izhevsk, Russia", "Russia", "Ijevsk, République oudmourte : RUSSIE", "Izhevsk, Russian Federation", "Ijevsk, République oudmourte, URSS (aujourd'hui Fédération de Russie)", "Izhevsk", "Izhevsk, RUSSIAN FEDERATION" ], "citizenship": [ "ru" ], "country": [ "ru" ], "createdAt": [ "2025-02-13" ], "fatherName": [ "Vjačeslavovič", "Vyacheslavovich", "ВЯЧЕСЛАВОВИЧ", "Вячеславович" ], "firstName": [ "Aleksandr Vyacheslavovich", "Aleksandr", "Александр", "Alexander Vyacheslavovich", "Alexander" ], "gender": [ "male" ], "innCode": [ "183111242406" ], "lastName": [ "Zakharov", "Zacharov", "ZAKHAROV", "Захаров" ], "middleName": [ "Vjačeslavovič", "Vyacheslavovich", "Вячеславович" ], "modifiedAt": [ "2025-03-04" ], "name": [ "Захаров Александр Вячеславович", "ZAKHAROV, Aleksandr Vyacheslavovich", "Aleksandr Vyacheslavovich ZAKHAROV", "Александр Вячеславович Захаров", "Alexander ZAKHAROV", "Aleksandr Vjačeslavovič Zacharov", "Zakharov Aleksandr Vyacheslavovich", "Alexander Vyacheslavovich ZAKHAROV", "Aleksandr Vyacheslavovich Zakharov", "Захаров Олександр В'ячеславович", "Zakharov Aleksandr" ], "nationality": [ "ru" ], "notes": [ "183111242406 (fiscalcode-National Fiscal Code) (Tax Identification Number)", "Alexander Zakharov is a majority stakeholder of LLC CST (also known as Zala Aero), which is engaged in the development, production and operation of aerial target complexes and unmanned aerial vehicles (UAVs). LLC CST manufactures UAVs KUB and Lancet-1, used by the Russian military in its war of aggression against Ukraine. LLC CST is listed by the Union. JCS Kalashnikov Concern, an entity listed by the Union, has a significant shareholding in LLC CST. Alexander Zakharov is also the chief designer of Aeroscan, owned until at least October 2023 by his son. Aeroscan is also engaged, along with LLC CST, in the development and production of UAVs used by the Russian military in Ukraine. Alexander Zakharov accompanied President Vladimir Putin and Minister of Defence Sergei Shoigu when they visited the Aeroscan production site for Lancet UAVs in September 2023 and February 2024, respectively. Therefore, Alexander Zakharov is supporting actions and policies which undermine or threaten the territorial integrity, sovereignty and independence of Ukraine, or stability or security in Ukraine." ] } } ``` ``` -------------------------------- ### Example API Request Source: https://www.opensanctions.org/docs/api/request This Python snippet demonstrates how to construct a request to the OpenSanctions API using the "/match" endpoint. It shows how to define entity attributes for a query-by-example search. ```python from opensanctions import Api api = Api() # Example: Find entities matching a person results = api.match( "person", name="Jens Albrecht", birth_date="1970-01-01", nationality="de" ) # Print the results for result in results: print(result) ``` -------------------------------- ### Entity Response Example (JSON) Source: https://www.opensanctions.org/docs/api/entities This is an example of the JSON response structure for an entity, showing nested ownership and sanction details, datasets, and referents. ```json { "id": "NK-aU5ybkbRFJucf8YMwsJvDw", "schema": "Person", "properties": { "name": ["Alexander Vyacheslavovich ZAKHAROV"], "birthDate": ["1965-09-21"], "country": ["ru"], "position": ["Owner of LLC CST"], "ownershipOwner": [ { "id": "ru-770bdf5f22537fa2a94176f53fa87fe28ecf94fa", "schema": "Ownership", "properties": { "owner": ["NK-aU5ybkbRFJucf8YMwsJvDw"], "percentage": ["50"], "asset": [ { "id": "NK-abdzbEBkqyT29GyREbiURZ", "schema": "Company", "properties": { "name": ["LLC CST"], "country": ["ru"] } } ] } } ], "sanctions": [ { "id": "ofac-927f7a4547f68cd05570180fed763dd2d5d8eca7", "schema": "Sanction", "properties": { "authority": ["Office of Foreign Assets Control"], "program": ["RUSSIA-EO14024"], "country": ["us"], "entity": ["NK-aU5ybkbRFJucf8YMwsJvDw"] } } ] }, "datasets": ["gb_fcdo_sanctions", "us_ofac_sdn", "eu_fsf", "ua_nsdc_sanctions"], "referents": ["ofac-45937", "gb-fcdo-rus2051", "eu-fsf-eu-12789-10"], "target": true, "first_seen": "2023-11-02T16:38:16", "last_seen": "2026-03-23T12:10:26" } ``` -------------------------------- ### Your First Request Source: https://www.opensanctions.org/docs/api/quickstart This example demonstrates how to search for a person using the OpenSanctions API. It sets up the API endpoint, defines a query for a specific person (Aleksandr Zacharov, born in 1965), sends a POST request, and then processes and prints the results. ```APIDOC ## POST /match/ ### Description This endpoint is used to search for entities (people, organizations, etc.) within the OpenSanctions dataset based on provided criteria. ### Method POST ### Endpoint `/match/default` ### Parameters #### Query Parameters - **queries** (object) - Required - A JSON object containing the search queries. - **q** (object) - Required - The main query object. - **schema** (string) - Required - The type of entity to search for (e.g., "Person", "Organization"). - **properties** (object) - Required - An object defining the properties to filter by. - **firstName** (array) - Optional - An array of first names to match. - **lastName** (array) - Optional - An array of last names to match. - **birthDate** (array) - Optional - An array of birth dates to match. ### Request Example ```json { "queries": { "q": { "schema": "Person", "properties": { "firstName": ["Aleksandr"], "lastName": ["Zacharov"], "birthDate": ["1965"] } } } } ``` ### Response #### Success Response (200) - **responses** (object) - Contains the results for each query. - **q** (object) - Results for the primary query. - **results** (array) - A list of matching entities. - **caption** (string) - A human-readable caption for the entity. - **id** (string) - The unique identifier of the entity. - **score** (number) - The match score for the entity. - **properties** (object) - Additional properties of the entity. - **topics** (array) - A list of risk topics associated with the entity. #### Response Example ```json { "responses": { "q": { "results": [ { "caption": "Aleksandr Zacharov", "id": "6021186881818112", "score": 0.95, "properties": { "firstName": ["Aleksandr"], "lastName": ["Zacharov"], "birthDate": ["1965-01-01"], "topics": ["sanctions", "pep"] } } ] } } } ``` ```