---
title: "Query by example matcher"
method: POST
path: "/match/{dataset}"
tags: ["Matching"]
---

# Query by example matcher

`POST /match/{dataset}`

Match entities based on a complex set of criteria, like name, date of birth
and nationality of a person. This works by submitting a batch of entities, each
formatted like those returned by the API.

Tutorials:
* [Using the matching API](https://www.opensanctions.org/docs/api/matching/)
* [Configuring the scoring system](https://www.opensanctions.org/docs/api/scoring/)

For example, the following would be valid query examples:

```json
"queries": {
    "entity1": {
        "schema": "Person",
        "properties": {
            "name": ["John Doe"],
            "birthDate": ["1975-04-21"],
            "nationality": ["us"]
        }
    },
    "entity2": {
        "schema": "Company",
        "properties": {
            "name": ["Brilliant Amazing Limited"],
            "jurisdiction": ["hk"],
            "registrationNumber": ["84BA99810"]
        }
    }
}
```
The values for `entity1`, `entity2` can be chosen freely to correlate results
on the client side when the request is returned. The responses will be given
for each submitted example like this:

```json
"responses": {
    "entity1": {
        "query": {},
        "results": [...]
    },
    "entity2": {
        "query": {},
        "results": [...]
    }
}
```

The precision of the results will be dependent on the amount of detail submitted
with each example. The following properties are most helpful for particular types:

* **Person**: ``name``, ``birthDate``, ``nationality``, ``idNumber``, ``address``
* **Organization**: ``name``, ``country``, ``registrationNumber``, ``address``
* **Company**: ``name``, ``jurisdiction``, ``registrationNumber``, ``address``,
  ``incorporationDate``

## Path parameters

- `dataset` string, required — Data source or collection name to scope the query to.

## Query parameters

- `limit` integer
- `threshold` number
- `cutoff` number
- `algorithm` string
- `include_dataset` string[]
- `exclude_schema` string[]
- `exclude_dataset` string[]
- `topics` string[]
- `changed_since` string, nullable
- `exclude_entity_ids` string[] — 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.

## Request body

- EntityMatchQuery
  - `weights` object
  - `config` object — Algorithm-specific configuration parameters.
  - `queries` object, required

## Response `200`

Successful Response

- EntityMatchResponse
  - `responses` object, required
  - `limit` integer, required

## Other responses

- `400` — Invalid query
- `422` — Validation Error
- `500` — Server error

---

[API](https://skmtc.net/opensanctions/apis/opensanctions-api.md) · [All operations](https://skmtc.net/opensanctions/apis/opensanctions-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/opensanctions/opensanctions-api/versions/8261f1aa0d2c/schema)