The matching API

Screen people, companies, organizations and vessels against our collections, with a score and an explanation for every result.

The matching API compares parties you know (customers, suppliers, counterparties, vessels) with every record in a collection and returns the closest, with a score and an explanation. To get started:

Quick start: a first request in cURL, Python or Node.
The request: collections, filters, schema and properties.
The response: scores, explanations and result fields.
The entities API: the full record behind a result.

Building a screening process on the matching API

Screening is not text search. A name alone matches many people; the matcher weighs the name together with birth date, nationality or country, IMO number and entity type, so the party you mean rises and namesakes fall back.

Step 1: describe your parties in our terms

Map your own columns to a query: the full name (and any other names) to name, date of birth to birthDate, nationality, residence or country of registration to nationality or country as two-letter codes, and IMO number to imoNumber. Choose the schema from your customer type.

{
  "schema": "Person",
  "properties": {
    "name": ["Maria Example", "Maria Ejemplo"],
    "birthDate": ["1971-05"],
    "nationality": ["ve", "es"]
  }
}

Every property is a list, so send all the names and nationalities you hold. Convert country names to ISO codes before you send them; the matcher compares codes only.

Step 2: choose where to look

Start with default, which holds every list we publish. If your obligations are narrower, use sanctions, peps, crime or maritime, or keep default and filter with topics and include_dataset. See Scoping.

Step 3: send batches

Send up to 20 parties per request, each under your own key, and store the checked_at time, the scores and the explanations with your records. The quick start has working code.

Understanding the results

Each result is one register's record. topics and list_type say what kind of list it is, programme names the programme or legal basis, and datasets names the register. Fetch the record from the entities API for every listing and every other register that names the same party, or open its page from url.

Reducing false alerts

Send birth dates, nationalities and IMO numbers whenever you hold them.
Screen only the lists you need, using the collection and filters.
Set the threshold for your risk appetite and review everything above it; see Tuning.
Record why each alert was cleared, so the same record does not need fresh review next time.

Reconciliation for OpenRefine

The same matcher is available as a reconciliation service: add https://api.crownintelligence.net/api/reconcile/default (or any collection) in OpenRefine to match a spreadsheet column, with up to 20 queries per batch. See the reference.

Running the matcher yourself

To be provided: Whether we offer an on-premise or self-hosted deployment of the matching service, and on what terms.

Last updated 2026-10-03