Documentation · Screening API

Integration checklist

What to decide, build and test before Crown Intelligence screening goes live in your system: the collection, the field mapping, the match threshold, how possible matches are reviewed and logged, how records stay current, and how the integration handles limits and errors.

The screening API needs no key today and answers anonymous requests. The checks below use the endpoints in the Screening API guide and the API reference. Automated or systematic screening, and use in a business process, need a commercial licence under our terms of use. Confirm that before you connect a live system.

Choose a collection

Each collection is a separate match path. Pick the one that matches the lists your obligations cover. A register is not a collection on its own; to narrow a search to one register, use include_dataset.

• Choose the collection for each process, and write the choice down with the reason and the owner.
• Store the collection name in configuration, so changing it does not need a code release.
• Confirm the collection's version from /api/catalog at each run (see Re-screen and monitor).

Map customer fields to the match request

A match request sends up to 20 named queries in one body, each with a schema and properties. Use your own customer or counterparty ID as the query key, so every response maps back to your record.

• Map each customer field to one row above, and drop empty fields rather than sending empty strings.
• Send every name you hold for a party, up to five, including transliterations.
• Send the birth date at the precision you hold, and never guess the day or month.
• Test a query with no name, IMO or MMSI. The API returns status 400 for that query only (see Test with known names).

A starting point that maps a customer record, sends a batch with retries, and prints the top result for each party.

import os, time, json, requests

BASE = os.environ.get("CROWN_API_BASE", "https://api.crownintelligence.net")
session = requests.Session()
session.headers["User-Agent"] = "my-screening-tool/1.0 ([email protected])"


def to_query(customer):
    """Map one customer record to a match query (see the field table above)."""
    props = {"name": customer["names"][:5]}
    if customer.get("birth_date"):
        props["birthDate"] = [customer["birth_date"]]        # YYYY, YYYY-MM or YYYY-MM-DD
    if customer.get("nationality"):
        props["nationality"] = [customer["nationality"]]     # ISO 3166-1 alpha-2, e.g. "ca"
    if customer.get("imo"):
        props["imoNumber"] = [customer["imo"]]               # seven digits
    return {"schema": customer["schema"], "properties": props}


def match(collection, queries, limit=5, threshold=0.75, changed_since=None, retries=3):
    """POST /api/match with retries for 429 (honour Retry-After) and 5xx (back off)."""
    params = {"limit": limit, "threshold": threshold}
    if changed_since:
        params["changed_since"] = changed_since
    for attempt in range(retries + 1):
        r = session.post(f"{BASE}/api/match/{collection}", params=params,
                         json={"queries": queries}, timeout=60)
        if r.status_code == 429 and attempt < retries:
            time.sleep(int(r.headers.get("Retry-After", "5")))
            continue
        if r.status_code >= 500 and attempt < retries:
            time.sleep(2 ** attempt)
            continue
        r.raise_for_status()
        return r.json()


customers = {
    "C-1001": {"schema": "Person", "names": ["Igor Putin", "Игорь Путин"], "birth_date": "1953-03-30", "nationality": "ru"},
    "C-1002": {"schema": "Vessel", "names": ["Selam"], "imo": "9418286"},
    "C-1003": {"schema": "Person", "names": ["Zz Crown Checklist Testperson"], "birth_date": "1980", "nationality": "ca"},
}
queries = {cid: to_query(c) for cid, c in customers.items()}
out = match("default", queries, limit=3, threshold=0.75)

for cid, answer in out["responses"].items():
    print(cid, answer["status"], "candidates:", answer["total"])
    for hit in answer["results"][:1]:
        print("   top:", hit["caption"], hit["score"], "match" if hit["match"] else "no match", hit["datasets"][:1])
print("checked_at:", out["checked_at"], "| collection:", out["collection"], "| threshold:", out["threshold"])

Set the threshold and read the match flag

Each result has a score from 0 to 1 and a match flag, which is true when the score is at or above threshold. The default threshold is 0.75 and the default limit is 5 results per query (up to 50). Results below the threshold still come back with match set to false, so reviewers can see near misses.

• Record the threshold, the algorithm and the limit in your screening policy, and have compliance approve them.
• Use algorithm=standard (the default; best means the same). name-only scores on the name alone: birth date, country, IMO number and type are reported as features but do not change the score. GET /api/algorithms lists the features and constants.
• Test the threshold with known names before go-live (see Test with known names). Do not change it without a new approval and a note of the date.
• Treat a score as resemblance, not identity. Confirm every match against the publisher's official list before acting on it.

Handle possible matches

A result with match set to true is a possible match, not a finding. Route it to a review queue, and keep a decision for each one.

• Show the reviewer the caption, score, features, datasets, topics and programme for each possible match.
• Open the full record with GET /api/entity/<id> for its listings, dates and source link (where the record gives one). The sample in Re-screen and monitor shows the call.
• Record the decision as one of: confirmed match, not a match, or open. Record the reviewer, the date and the reason.
• Check the publisher's official list before acting on a confirmed match.
• Apply your own escalation rules to confirmed matches. Escalation is a matter for your policy, not for the API.
• Keep the record id and the merged_entity (where one is given). A merged entity can group records from several registers.

Log what was checked

We do not store query bodies, so your system must keep its own record of every check, including checks with no match. Store the response as received, and add the fields below.

• Log checks that returned no match, as well as possible matches.
• Keep logs in UTC, and keep them for as long as your record-keeping policy requires.
• Make the log readable by an auditor without the application: one row per check, with the decision linked.

Re-screen and monitor

Lists change. A party cleared last month can match after a new listing. Re-screen on a schedule, and when a collection is rebuilt.

• Poll /api/catalog on a schedule and store each collection's version. When it changes, re-screen the parties in that collection.
• For a routine alert run, add changed_since to the match request. It returns only records added or changed on or after that date or time. “Added” means first collected; “changed” means an export build saw the published record change.
• Run a full re-screen on a longer cycle, without changed_since, so that nothing is missed if a run fails.
• If you hold the bulk files, use the per-collection delta.json (one JSON object per line, with an op and the changed entity, which carries its last_change) and deltas.json (added, modified and removed counts for each build). Handle every op value you find, and re-screen when you meet one you do not expect.
• Alert reviewers only on a new listing or a change that touches their obligations. The routine updates should not reach them. See Building a monitoring workflow.

import os, json, requests

BASE = os.environ.get("CROWN_API_BASE", "https://api.crownintelligence.net")

# Versions now, to compare with the versions stored at the last run
catalog = requests.get(f"{BASE}/api/catalog", timeout=30).json()
versions = {c["name"]: c["version"] for c in catalog["collections"]}
last_run = {"sanctions": "20261004022212-jhp"}  # the version stored at the last run
changed = [name for name, v in versions.items() if last_run.get(name) not in (None, v)]
print("collections rebuilt since the last run:", changed)

# Only records added or changed since the last run (ISO 8601 date or time)
body = {"queries": {"C-1001": {"schema": "Person", "properties": {"name": ["Igor Putin"], "birthDate": ["1953"]}}}}
r = requests.post(f"{BASE}/api/match/sanctions", params={"limit": 10, "changed_since": "2026-10-01"},
                  json=body, timeout=60)
r.raise_for_status()
answer = r.json()["responses"]["C-1001"]
print("changed since 2026-10-01:", answer["total"], "candidates;", r.json()["filters"]["changed_since"])

# Entity lookup for the review screen
ent = requests.get(f"{BASE}/api/entity/379781867", timeout=30).json()
print(ent["id"], ent["name"], ent["register"], ent["list_type"], ent["listings"][0]["register"])

Rate limits, retries and volume

The data service has a per-address request limit that the operator can switch on. It is off today, and no figure is published. The terms reserve the right to apply limits or volume caps to automated use, so agree your volumes with us before you send a large batch.

• Do not send credentials. The API has no keys today and ignores them. Keep any future key in a secret store, not in code.
• Send up to 20 queries in one match request, rather than one request per party.
• Set a request timeout. The samples in this section use 60 seconds.
• When a response is 429 Too Many Requests, wait for the number of seconds given in Retry-After, then retry. When the limit is on, each response also carries X-RateLimit-Limit and X-RateLimit-Remaining.
• On a 5xx response, retry with an increasing delay, and stop after a few tries.
• Do not retry a 400 or 404. Those mean the request needs to change. Log them and fix the mapping.
• Limit the number of parallel requests in your system, and send a User-Agent that names your tool and a contact address.

Test with known names

Test the integration against names with known listings before go-live, and keep the test set in version control. Include:

• Listed names, with the listing confirmed on the publisher's list, in each collection you rely on.
• Spelling variants, reversed name order, initials, and transliterations.
• Birth dates at year, month and day precision, and a party with no birth date.
• Names that should not match, and a vessel with an IMO number, if you screen vessels.
• A query with no name, IMO or MMSI. Expect status 400 for that query, with the error name, imoNumber or mmsi required. The other queries in the request still return.
• An unknown collection, which returns 404 with the list of valid collections.

One check we ran for this page: the query Igor Putin, birth year 1953 and nationality ru, against the sanctions collection with a threshold of 0.8 returned the sanctions listing at score 1 with match set to true. Results depend on the build in use, so record the collection version with each test run and repeat the tests after each rebuild.

Go-live checks

• A commercial licence is in place for automated or systematic screening.
• The base address is set in configuration, and the integration uses no credentials.
• Collections, field mappings, thresholds and the limit are approved and written down.
• Possible matches reach the review queue, and each decision and its reviewer are recorded.
• The log holds every check with the collection version and checked_at, and an auditor can read it.
• Re-screening runs on schedule, and a rebuilt collection triggers a re-screen.
• Retries work for 429 and 5xx, and 400 errors are logged and reported.
• Known-name tests pass on the production build, and the results are saved.
• Someone owns the integration and knows where to send questions: [email protected].

Samples

The samples below are starting points, so run them in a test environment before you rely on them. Set CROWN_API_BASE to change the base address; the default is the public service.

Node.js: match request

const BASE = process.env.CROWN_API_BASE ?? "https://api.crownintelligence.net";
const queries = {
  vessel: { schema: "Vessel", properties: { name: ["Selam"], imoNumber: ["9418286"] } },
  person: { schema: "Person", properties: { name: ["Igor Putin"], birthDate: ["1953-03-30"], nationality: ["ru"] } },
};
const params = new URLSearchParams({ limit: "3", threshold: "0.75" });
const res = await fetch(`${BASE}/api/match/maritime?${params}`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ queries }),
});
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const data = await res.json();
for (const [key, answer] of Object.entries(data.responses)) {
  const top = answer.results[0];
  console.log(key, answer.status, answer.total, top ? [top.caption, top.score, top.match] : "no hits");
}

curl: collection versions and one match

# Versions of each collection, to see when a list was rebuilt
curl -s "$CROWN_API_BASE/api/catalog" | python3 -c 'import json,sys; [print(c["name"], c["version"]) for c in json.load(sys.stdin)["collections"]]'

# One party against the sanctions collection
curl -s -X POST "$CROWN_API_BASE/api/match/sanctions?limit=3&threshold=0.8&topics=sanction" \
  -H "Content-Type: application/json" \
  -d '{"queries":{"q1":{"schema":"Person","properties":{"name":["Igor Putin"],"birthDate":["1953"],"nationality":["ru"]}}}}'

Last updated 2026-10-10