Building a monitoring workflow

How to keep screening results current as the lists change, using our API or delta files, without drowning reviewers in routine updates.

Screening checks a party once. Monitoring checks it again whenever the lists change, and raises an alert only when something new matters. We do not run a monitoring service for customers: this guide shows how to build one on our API or bulk files.

To be provided: Whether we plan to offer a hosted monitoring or alerting service, and when. Nothing on this page should be read as such an offer.

Screening and monitoring

Monitoring repeats three steps: notice that the data changed, re-screen the parties it could affect, and compare the new results with the decisions you already made. The hard part is the third step: a good monitoring system raises an alert for a new listing, not for every routine data update.

Building your alert state

Design the alert model first

Start from your obligations: which lists, which programmes and which jurisdictions matter to you. Then keep one stored decision per pair of your party and our record, keyed by our record id (and the merged_entity when there is one), so the next run can tell new matches from known ones.

Two decisions per alert

Resolution: is this record the same party as yours? Confirmed, not a match, or open. A name or birth-date change on our side can reopen it.
Relevance: does the listing matter to you? Decided from topics, list_type, programme and the register. A new programme or a new register for a known party can make a cleared match relevant.

What to store for each match

Field	Why
Your party ID	Joins the alert to your customer record.
Record `id`	The register entry that matched. Use it to re-check the record.
`merged_entity` and its `referents`	The party across registers, and the records it was built from.
`score` and `features`	Why it matched, for audit and for spotting score drift.
Resolution	Your decision: confirmed, not a match, or open.
Relevance	Whether the listing matters under your obligations.
`datasets`	Which registers listed the party at decision time.
`topics` and `programme`	What kind of listing it was, and under which programme.
Collection `version`	From `/api/catalog`: the build you screened against.
`checked_at`	When the check ran.

Re-alerting depends on your obligations

A Canadian institution bound by the Special Economic Measures Act and the Justice for Victims of Corrupt Foreign Officials Act cares first about Canadian listings; one with US exposure also cares about OFAC. Record the registers and programmes in scope for each business line, and re-alert only when a change touches them. Register names come from datasets; filter with include_dataset.

When to alert again on a known party

Resolution may have changed: the record's names, birth date or nationality changed, or the score moved by more than your tolerance.
Relevance may have changed: new topics, a new programme, or a new register in datasets or in the merged entity.
Both: the party was delisted (the record no longer answers) or a new record for it appeared.

Checking a stored record is a single GET /api/entity/<id>?nested=false.

Merges and splits

When we link records of the same party, they gain a common merged entity ID; when we unlink them, it changes. Both can make an old alert look new. To cope:

Key decisions by record ID, not only by merged ID.
When a new result shares a merged ID with a record you already cleared, show the earlier decision to the reviewer.
When a stored record answers 308, follow it to the merged entity and carry your decision over after review.
Expect the score to move when records are linked: a merged view may carry more names and dates.
Re-check stored record IDs periodically; see Keeping your stored IDs current.

How the data changes

Three sources of change

The publisher: a register adds, amends or removes entries.
Our processing: we improve how a register is read (types, dates, countries, programmes), which changes records without any change at the source.
Linking: records are linked to, or unlinked from, a merged entity.

The noise problem

Only the first kind is usually news. The second and third can touch many records at once. Compare the values that matter to your decisions (names, birth date, nationality, topics, programme, register), not the whole record, before you raise an alert.

Choosing an approach

	Re-screening with the API	Applying delta files
Set-up	Re-send your parties to `/api/match` on a schedule.	Load the bulk files once, then apply `delta.json` after each build.
Engineering	Small: a scheduled job and a table of decisions.	Larger: a local copy of the data, delta processing and your own matching.
Scope filtering	Collection, `topics` and register filters on every request.	Filter the files or the deltas yourself.
Catching changes in relevance	Every re-screen sees current topics and programmes.	Compare old and new versions of changed entities.
Delay	As often as you schedule it, after each build.	After each build, once deltas are published.
Prerequisite	Licensed API use.	A bulk data licence.

To be provided: Guidance on the portfolio size at which delta-based monitoring becomes preferable to API re-screening.

Monitoring with the API

Scheduled re-screening

Poll /api/catalog and note each collection's version.
When the version changes, re-send your parties to /api/match/<collection> in batches of 20, with the same filters and threshold as before.
Compare each result with your stored decisions, using the rules above.
Queue new or changed matches for review and store the new checked_at and version.

curl "https://api.crownintelligence.net/api/catalog"

import requests

BASE = "https://api.crownintelligence.net"
catalog = requests.get(f"{BASE}/api/catalog", timeout=30).json()
versions = {c["name"]: c["version"] for c in catalog["collections"]}
print(versions)  # store these; re-screen when a version changes

Less noise through scope

Send the same topics, include_dataset and exclude_dataset on every run, so a change to a register you do not use never reaches review. To list records first seen recently in a collection, use /api/search/<collection>?sort=first_seen with a filter.

Re-screening only what changed

Between full re-screens, add changed_since to the match request. Candidates are then limited to records first collected on or after that date or time, or whose published content changed in a bulk build since then. A party that matches nothing new comes back with no results, so every result is a new or changed record to compare with your decisions. Use the time of your previous run, with the same collection, filters and threshold.

curl -X POST "https://api.crownintelligence.net/api/match/sanctions?changed_since=2026-09-20" \
  -H "Content-Type: application/json" \
  -d '{"queries":{"c-1042":{"schema":"Person","properties":{"name":["Vladimir Putin"],"birthDate":["1952-10-07"]}}}}'

Format. An ISO 8601 date or time, for example 2026-10-01 or 2026-10-01T12:00:00Z. A date alone means midnight UTC. Any other value returns HTTP 400 with an explanation. The value applied is echoed back in filters.changed_since.
Also on search. /api/search?changed_since= lists new and changed records with the usual filters.
Removals are not reported. A record taken off its register simply stops matching. To learn about removals, read the DEL lines of delta files or re-screen in full.
Keep full re-screens. Changes are counted from the bulk builds, and up to 20,000 changed records are taken into account per request (records first collected since the date are always included). After a long gap, or a build that changed more records than that, re-screen in full.

Monitoring with delta files

Processing workflow

Each collection's build index, /downloads/collections/<collection>/index.json, lists the files of the current build with their checksums. From the second build on, delta.json lists what changed since the previous build, one operation per line: ADD (new record), MOD (changed record) and DEL (removed record). Apply them in order to your copy, then re-screen the parties that could match the added and changed records. See Delta files.

Less noise through comparison

For each MOD, compare the old and new versions of the values your decisions depend on, and ignore the rest.

Re-screen in full from time to time

Deltas follow our data, not your book: a change to your customer's details, or a missed build, is not in them. Re-screen everything periodically, and whenever you change thresholds or filters.

Help

Questions about building a monitoring workflow: [email protected] or Get support.

Last updated 2026-10-03