---
title: "The matching API"
summary: "Learn how to use the `/match` endpoint to make a screening call, scope your query, and interpret responses."
url: "https://www.opensanctions.org/docs/api/matching/"
date_updated: "2026-08-04"
---

The `/match` endpoint uses query-by-example: you describe an entity in as much detail as you can, and the API returns ranked candidates from the database.
You can experiment with the `/match` endpoint via the [advanced screening search](/advancedsearch/).

To get started:

* Follow the **[quickstart tutorial](/docs/api/quickstart/)** to make your first screening call and interpret the response, including how to get an API key and [authenticate requests](/docs/api/authentication/).
* Read about **[composing a request](/docs/api/request/)**: scoping the query and structuring the queried entity.
* Understand **[the response](/docs/api/response/)**: the parsed `query` and each `results` field explained.
* Learn about using [the `/entities` endpoint](/docs/api/entities) for fetching the full details of an entity.

## On-premise deployment

[Commercial license customers](/licensing/) can also use an [on-premise deployment](/docs/on-premise/) to perform the same process within their own infrastructure.

{% linkcard title="Read more" %}
[Configuring OpenSanctions Data (`yente`)](https://yente.followthemoney.tech/delivery/)
{% /linkcard %}

## Using the matching API to build a screening process {% #screening %}

Screening checks are a different challenge to normal text searches: your query is supposed to describe a person or company in some detail to allow the OpenSanctions API to check if that entity (or a similar one) is flagged.

OpenSanctions' API server is a powerful way to query and access the entities in our database. This guide will show you how to use the `/match` endpoint to get more precise screening results using *query-by-example* to do multi-attribute lookups.

### Step 1: Speak the language

Let's say, for example, that you have a customers dataset that specifies the name, birth date, nationality and perhaps a national ID number for each person you want to check.

The first step would then be to implement a piece of code that formats each of these entries to conform with the [entity format](/docs/entities/) used by OpenSanctions, assigning each of the columns in your source data to one of the fields specified in the [data dictionary](/reference/). (This, of course, works not just for [people](/reference/#schema.Person), but also [companies](/reference/#schema.Company), [vessels](/reference/#schema.Vessel), even [crypto wallets](/reference/#schema.CryptoWallet)).

Here's an example entity in JSON format:

```json
{
    "schema": "Person",
    "properties": {
        "firstName": ["Arkadii"],
        "fatherName": ["Romanovich"],
        "lastName": ["Rotenberg", "Ротенберг"],
        "birthDate": ["1951"],
        "nationality": ["Russia"],
    }
}
```

A few things to note:

* The `schema` defines the type of entities to match this example against. Of course, the schema could also be `Company`, or `Vessel`, etc.
* You can specify multiple property values — for example, different variations of the name, or different addresses and identification numbers.
* The API internally uses standardised formats for [country codes](https://followthemoney.tech/explorer/types/country/), [dates](https://followthemoney.tech/explorer/types/date/), [phone numbers](https://followthemoney.tech/explorer/types/phone/), etc., but you can just supply a country name and the API will attempt to identify the correct country code (in this case: `ru`) for the entity.

Generating this JSON form of your records should be a simple exercise. Do not worry too much about details like whether a country name should live in the `country` or `jurisdiction` properties: the matching happens by data type (in this case: [country](https://followthemoney.tech/explorer/types/country/)), not precise field name.

### Step 2: Choose where to look

OpenSanctions combines watchlists from hundreds of different data sources — some are sanctions lists, others databases of national politicians, even entities involved in crime. For this introduction, we'll query the whole database by using the `default` [collection](/docs/glossary/#collection) endpoint. This will produce results across all available data categories. In order to reduce false alarm rates, you will need to [apply specific query filters](/docs/api/request/#scoping) later.

What data sources and collections will be queried is determined by the URL of the matching endpoint used in your integration, e.g. `https://api.opensanctions.org/match/default`.

### Step 3: The code

See the [quickstart tutorial](/docs/api/quickstart/#your-first-request) for an example request.

Note that when running this for your own data, you'll need to add a data source, and a place to store the highest-scoring matches for analyst review.

### Understanding the results

The results returned by the `/match` API contain basic information about each candidate or matching entity. For sanctioned entities, take note of the `programId` property: it describes the [sanctions program](/docs/programs/) under which the designation was made.

If you want to retrieve additional details regarding an entity you can use the `/entities/<id>` endpoint to retrieve a [nested representation](/docs/nested-entities/) that includes details about family and business relationships, and detailed sanctions designations. Each sanction-designated entity (`Person`, `Company`, `Vessel`, etc.) can be tied to several `Sanction` objects. A `Sanction` object describes details about the sanctions imposed by an authority against an entity: the start and end dates, the name and country of the authority, and the `programId`, which can be expanded into [additional details on the relevant policy regime](/docs/programs/).

Of course, you can also view the OpenSanctions entity page (`https://opensanctions.org/entities/<id>`) for each result to see their documented connections to other items.

{% linkcard title="Read more" %}
[The response](/docs/api/response/)
{% /linkcard %}

### Reducing false alerts

If one of your queries returns a result, this is not immediately cause for alarm: the database for politically exposed persons in particular contains many individuals with common names, and matches will be fairly frequent. Instead, you should invest time to fine-tune the configuration of the matching system, and eventually also set up a process for human review.

The following strategies can be used to reduce error rates in results returned from the API:

* **[Define good query filters](/docs/api/request/#scoping)** to avoid screening against data sources or risk factors that are irrelevant to your use case.
* **[Tune the matching algorithm](/docs/api/tuning/)** to define alerting thresholds relevant to your use case. A sanctions screening system may need to be more aggressive in matching names than a PEP screening process. Your specific data profile might benefit from up- or down-ranking one of the matching features we use.
* Provide **as much detail in your queries** as possible. Explore the [data dictionary](/reference/) to see the properties might be used as ways to quickly discard a match before it triggers an alarm.