The response

What comes back from a match request, field by field, and how to read a score.

An example response

A real answer to one query against the sanctions collection with limit=1:

{
  "collection": "sanctions",
  "algorithm": "standard",
  "threshold": 0.75,
  "limit": 1,
  "filters": {
    "topics": [],
    "include_dataset": [],
    "exclude_dataset": []
  },
  "responses": {
    "q1": {
      "status": 200,
      "query": {
        "schema": "Person",
        "name": [
          "Igor Putin"
        ],
        "birthDate": [
          "1953-03-30"
        ],
        "nationality": [
          "ru"
        ],
        "imo": []
      },
      "total": 1502,
      "results": [
        {
          "id": 379735083,
          "caption": "ПУТІН ІГОР ОЛЕКСАНДРОВИЧ",
          "schema": "Person",
          "score": 1,
          "match": true,
          "features": [
            {
              "feature": "name_match",
              "explanation": "'IGOR'≈'IGOR' exact 1.00 · 'PUTIN'≈'PUTIN' exact 1.00 · 'ALEKSANDROVICH' not in query",
              "score": 0.9,
              "weight": 1,
              "matched_name": "PUTIN IGOR ALEKSANDROVICH"
            },
            {
              "feature": "dob_match",
              "explanation": "query 1953-03-30 · record 1953-03-30 · match",
              "score": 0.1,
              "weight": 0.25
            },
            {
              "feature": "country_match",
              "explanation": "query RU · record RU · match",
              "score": 0.05,
              "weight": 0.1
            }
          ],
          "source": "Ukraine NSDC",
          "datasets": [
            "Ukraine NSDC"
          ],
          "topics": [
            "sanction"
          ],
          "list_type": "SANCTION",
          "programme": "UA NSDC",
          "birth_date": "1953-03-30",
          "nationality": "RU",
          "imo": null,
          "aliases": [
            "PUTIN IHOR OLEKSANDROVYCH",
            "PUTIN IGOR ALEKSANDROVICH",
            "ПУТИН ИГОРЬ АЛЕКСАНДРОВИЧ",
            "ПУТІН ІГОР ОЛЕКСАНДРОВИЧ"
          ],
          "merged_entity": "bbfc9049-d481-4d74-9062-3c98fd501194",
          "first_seen": "2026-09-24T11:21:48.933154+00:00",
          "last_seen": "2026-09-24T11:21:48.933154+00:00",
          "url": "/estate/record.html?id=379735083"
        }
      ]
    }
  },
  "checked_at": "2026-10-04T01:32:58.153Z"
}

Anatomy of a response

Field	Contents
`collection`	The collection searched.
`algorithm`, `threshold`, `limit`	The scoring method, threshold and result limit that applied.
`filters`	The topics and register filters that applied.
`responses`	One entry per query, under the key you gave it.
`responses.<key>.status`	`200` when the query ran; `400` when it could not (then `error` says why, for example a query with no name and no IMO number).
`responses.<key>.total`	How many candidate records were scored for this query.
`responses.<key>.results`	The best-scoring records, highest first, up to `limit`.
`responses.<key>.query`	The query as the service read it.
`checked_at`	When the check ran, in UTC. Keep it with your screening record.

The parsed query

query shows what the matcher actually used: the schema, and the names, birth dates, countries and IMO numbers it read, after property aliases were resolved. If a value you sent is missing here, it was under a property the matcher does not read. Compare it with your input when a result looks wrong.

Result fields

id: The record ID: one entry in one register. Use it with /api/entity/<id> and store it with your decision.
caption: The record's primary name as the publisher wrote it.
schema: Entity type: Person, Company, Organization, Vessel, Airplane or LegalEntity when the type is not known.
score: From 0 to 1: how closely the record resembles your query, after every feature is applied.
match: True when score is at or above the threshold of the request.
features: The explanation: one entry per feature that applied, with feature, score (its effect), weight, a readable explanation, and for names the matched_name that aligned best.
datasets: The register the record comes from, by its full name. Use these names in include_dataset and exclude_dataset.
source: The register's short list name as stored on the record.
topics: Risk tags for the record, for example sanction or role.pep.
list_type: The kind of list: SANCTION, PEP, DEBARMENT, TAX_WARRANT, INSOLVENCY.
programme: The programme or legal basis the publisher gives for the listing, where there is one.
birth_date, nationality, imo, aliases: The record's own values, for side-by-side review with your query.
merged_entity: The merged entity ID when this party has been linked across registers; fetch /api/entity/<merged_entity> for the combined view.
first_seen, last_seen: When we first collected the record, and when it was last loaded from its source.
url: The record's page on this site.

A score is resemblance, not risk. A score of 1 means the record looks like your query; it does not say the party is the same, or how serious the listing is. Read topics, programme and the record itself, and confirm against the publisher's official list before acting.

Results in detail

Match results are deliberately short. For the full record, every listing and the other registers that name the same party, call the entities API with the result id, or open the record page from url.

Lineage: where each value came from

Every result names its register. For value-by-value history (which source published each name or date, and when it was first and last seen), use statements.csv in the bulk files. There is no statements endpoint in the API yet.

Reducing false alerts

Look in the right place. Screen against the collection your obligations require, and use topics and register filters to leave out lists you do not need.
Send more detail. A birth date, nationality or IMO number separates namesakes; without them, everyone with the same name scores alike.
Set the threshold deliberately. Raise it to cut noise on common names, and keep the explanations with every decision. See Tuning.

Last updated 2026-10-03