Partner API v1 · Draft, not yet live

Cases and evidence packs

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 case ties a set of match results to a reviewer's decisions, and produces an evidence pack that shows what was searched, when, against which registers, and what was decided. The pack holds references and digests, never the name or date of birth of the person screened.

Opening a case

The required scope is cases:write. A case starts from a match_request_id and a customer_ref. Include query_refs to limit it to some queries of the request; by default it holds every query. The optional reference is your own case number.

curl https://api.crownintelligence.net/v1/cases \
  -H "X-Api-Key: $CI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: case-7731-open" \
  -d '{"match_request_id": "mr_01J9Z3K4M6AB",
       "customer_ref": "cust-0042",
       "reference": "CASE-7731",
       "query_refs": ["case-7731:party-1"]}'

Recording decisions

A reviewer records one of three decisions against a query_ref and record_id: true_match, false_positive or unresolved. Decisions are append-only. A later decision for the same pair sets superseded_by on the earlier row, so the history is kept.

Notes are for the reviewer's reasoning only. Do not write a name or a date of birth in a note. The service checks this by policy, not by schema.

curl https://api.crownintelligence.net/v1/cases/$CASE_ID/dispositions \
  -H "X-Api-Key: $CI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: disp-7731-1" \
  -d '{"query_ref": "case-7731:party-1",
       "record_id": "crown-88213",
       "disposition": "false_positive",
       "note": "Different year of birth and no shared identifiers."}'

The evidence pack

Read the pack with GET /v1/cases/{id}/evidence. Send Accept: application/json for JSON, or Accept: application/pdf for a PDF with the same content.

curl -o evidence.json https://api.crownintelligence.net/v1/cases/$CASE_ID/evidence \
  -H "X-Api-Key: $CI_API_KEY" \
  -H "Accept: application/json"

curl -o evidence.pdf https://api.crownintelligence.net/v1/cases/$CASE_ID/evidence \
  -H "X-Api-Key: $CI_API_KEY" \
  -H "Accept: application/pdf"

The JSON has this shape, shown here with placeholder values:

{
  "case_id": "case_01J9Z8...",
  "generated_at": "2026-10-13T15:10:00Z",
  "manifest_sha256": "<64 hex characters>",
  "notice": {"en": "...", "fr": "..."},
  "billing_ref": {"source_service": "partner-api", "order_id": "ord_2026_1041", "type": "ORDER"},
  "match_requests": [
    {
      "query_ref": "case-7731:party-1",
      "query_digest": "hmac-sha256:<hex>",
      "status": "hit",
      "searched_at": "2026-10-13T14:02:11Z",
      "registers_searched": [{"list_id": "...", "loaded_at": "...", "licence": "PERMITTED"}],
      "matches": [{"record_id": "crown-88213", "band": "STRONG", "score": 0.94, "features": []}],
      "dispositions": [{"record_id": "crown-88213", "disposition": "false_positive"}]
    }
  ]
}
  • query_digest is a keyed HMAC-SHA256 of the normalised name, date of birth and country codes, under a key unique to your account. It lets a reviewer see that a stored query is the same query you later hold, without the name being kept. A route that checks a subject against the digest is not in v1.
  • manifest_sha256 is a hash over the whole pack. Keep the value you receive, so a later copy can be checked against it.
  • notice is the bilingual statement that accompanies the pack.

To tie a query to a person, join the pack to your own records by query_ref. Crown Intelligence cannot do this join for you, because it does not hold the names.

Putting it together

// Opening a case, recording the reviewer's decision, then pulling the pack.
const headers = { "X-Api-Key": process.env.CI_API_KEY, "Content-Type": "application/json" };
const base = "https://api.crownintelligence.net/v1";

const c = await (await fetch(base + "/cases", {
  method: "POST", headers: { ...headers, "Idempotency-Key": "case-7731-open" },
  body: JSON.stringify({ match_request_id: "mr_01J9Z3K4M6AB", customer_ref: "cust-0042", reference: "CASE-7731" })
})).json();

await fetch(base + "/cases/" + c.id + "/dispositions", {
  method: "POST", headers: { ...headers, "Idempotency-Key": "disp-7731-1" },
  body: JSON.stringify({ query_ref: "case-7731:party-1", record_id: "crown-88213",
                         disposition: "false_positive", note: "Different year of birth." })
});

const pack = await (await fetch(base + "/cases/" + c.id + "/evidence", {
  headers: { "X-Api-Key": process.env.CI_API_KEY, "Accept": "application/json" }
})).json();
// Store pack.manifest_sha256 with the pack. Join the pack to your own records by query_ref.

Open points

  • A route that checks a subject against a digest, with the subject data sent once and not stored, is proposed but not in v1.
  • Retention periods for matches, digests, usage rows and evidence packs are for the owner to set.

Example identifiers are illustrative. The pack's contents follow section 10 of the draft contract.