Partner API v1 · Draft, not yet live

Monitoring

Draft — not yet live. This describes the proposed v1 partner contract (version 1.0.0-rc.1). No endpoint on this page is deployed, and no API key can be issued yet.

A monitor watches public list entries, records and collections for changes. It never holds the name, date of birth or country of a person you screen, so re-screening your own people is done in your own system.

Why a monitor does not hold a person

Crown Intelligence never stores a screened person's record. A monitor that watched a person would have to keep that person's name, date of birth and country, so that a new list entry could be compared with them. That is the record the rule forbids. This version therefore monitors public targets only, and the link to your own person stays in your system.

Creating a monitor

The required scope is monitors:manage. The body has a customer_ref (your opaque reference), up to 50 targets and the changes to report in notify_on. The schema is closed.

  • entity: an entity ID, such as crown-e- followed by a UUID. You learn it from a match result.
  • record: a record ID, crown- followed by a number. Each match includes its record_id.
  • collection: a collection name, such as sanctions or peps.
curl https://api.crownintelligence.net/v1/monitors \
  -H "X-Api-Key: $CI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: mon-setup-0001" \
  -d '{"customer_ref": "cust-0042",
       "targets": [{"type": "entity", "id": "crown-e-6f0c2d1e-8a7b-4c39-9d21-5e4b7a10c3f8"}],
       "notify_on": ["listed", "delisted", "amended", "merged"]}'

A body that carries a name, a date of birth, a country or an identity number is refused with 400 personal_data_not_accepted. The shape of the error is shown below; the message text is illustrative.

{"type":"https://api.crownintelligence.net/problems/personal_data_not_accepted",
 "title":"Personal data is not accepted","status":400,"code":"personal_data_not_accepted",
 "detail":"A monitor stores a customer reference and public targets only.",
 "messages":{"en":"A monitor stores a customer reference and public targets only.",
   "fr":"Un suivi ne conserve qu'une référence client et des cibles publiques."},
 "request_id":"req_01J9Z7..."}

monitor.hit events then arrive at your webhook when a watched target is listed, delisted, amended or merged. See webhooks.

Re-screening your own people

When an event arrives, you re-screen the people you hold yourself. Two calls do this. GET /v1/search with changed_since returns only what changed since your last run, which also keeps unit use down. POST /v1/match then screens each subject with the details you hold.

curl "https://api.crownintelligence.net/v1/search?changed_since=2026-10-12T00:00:00Z&collection=sanctions&limit=50" \
  -H "X-Api-Key: $CI_API_KEY"
// Runs in YOUR system when a monitor.hit or list.updated event arrives.
// Your subject data never goes to Crown Intelligence except as the query of a match request.
async function rescreenSubjects(subjects, changedSince) {
  // 1. Ask what changed, scoped to the collections you watch.
  const url = "https://api.crownintelligence.net/v1/search?changed_since=" +
    encodeURIComponent(changedSince) + "&collection=sanctions&limit=50";
  const changed = await (await fetch(url, { headers: { "X-Api-Key": process.env.CI_API_KEY } })).json();

  // 2. Re-screen only your own subjects, with your own copy of their details.
  for (const subject of subjects) {
    const body = { queries: [{ query_ref: subject.ref, entity_type: "Person",
                              name: subject.name, dob: subject.dob, country: subject.country }] };
    const res = await fetch("https://api.crownintelligence.net/v1/match", {
      method: "POST",
      headers: { "X-Api-Key": process.env.CI_API_KEY, "Content-Type": "application/json",
                 "Idempotency-Key": "rescreen-" + subject.ref + "-" + changedSince },
      body: JSON.stringify(body)
    });
    // 3. Handle each status as on the matching page: only no_hit_searched is a negative.
  }
  return changed;
}

Crown Intelligence sees only the query for each match. It keeps a keyed digest of that query and not the name.

Open points

  • Watching a public entry tells Crown Intelligence that you are interested in it. It does not reveal your subject to anyone. Partner terms should state this.
  • A partner that keeps its subjects in a store that calls Crown Intelligence has the same obligations on that store as Crown Intelligence has for its own. Partner terms should say so.
  • Monitors that hold named subjects would need a change to the decision that forbids them, a separate store and a retention rule. None of that is in v1.

This design follows option A in section 9 of the draft contract. Owner sign-off is open.