API partenaire v1 · Version préliminaire, pas encore en service

Dossiers et dossiers de preuves

Version préliminaire, pas encore en service. Cette page décrit le contrat v1 proposé pour les partenaires (version 1.0.0-rc.1). Aucun point d’accès décrit ici n’est déployé, et aucune clé d’API ne peut encore être émise.

Un dossier relie un ensemble de résultats de correspondance aux décisions d'un réviseur et produit un dossier de preuves qui indique ce qui a été recherché, à quel moment, dans quels registres et ce qui a été décidé. Le dossier ne contient que des références et des empreintes numériques, jamais le nom ni la date de naissance de la personne vérifiée.

Ouverture d’un dossier

La portée requise est cases:write. Un dossier est créé à partir de match_request_id et de customer_ref. Ajoutez query_refs pour le limiter à certaines requêtes de la demande; par défaut, il contient toutes les requêtes. Le champ facultatif reference correspond à votre propre numéro de dossier.

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"]}'

Consignation des décisions

Un réviseur consigne l’une des trois décisions à l’égard d’un query_ref et d’un record_id : true_match, false_positive ou unresolved. Les décisions sont ajoutées en fin d’historique, sans modification. Une décision ultérieure pour la même paire définit superseded_by sur la ligne précédente, de sorte que l’historique est conservé.

Les notes servent uniquement à consigner le raisonnement du réviseur. N’y inscrivez ni nom ni date de naissance. Le service applique cette règle par politique, et non par schéma.

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."}'

Le dossier de preuves

Consultez le dossier de preuves avec GET /v1/cases/{id}/evidence. Envoyez Accept: application/json pour obtenir du JSON, ou Accept: application/pdf pour obtenir un PDF au contenu identique.

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"

Le JSON a la structure suivante, présentée ici avec des valeurs fictives :

{
  "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 est un HMAC-SHA256 à clé calculé sur le nom normalisé, la date de naissance et les codes de pays, au moyen d’une clé propre à votre compte. Il permet à un réviseur de constater qu’une requête conservée est bien celle que vous détenez par la suite, sans que le nom soit conservé. Un chemin permettant de comparer un sujet à l’empreinte ne fait pas partie de la v1.
  • manifest_sha256 est une empreinte calculée sur l’ensemble du dossier de preuves. Conservez la valeur reçue afin de pouvoir y comparer une copie ultérieure.
  • notice est la déclaration bilingue qui accompagne le dossier de preuves.

Pour relier une requête à une personne, associez le dossier de preuves à vos propres fiches au moyen de query_ref. Crown Intelligence ne peut pas effectuer cette association pour vous, car elle ne détient pas les noms.

Mise en pratique

// 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.

Points en suspens

  • Un chemin permettant de comparer un sujet à une empreinte, les données du sujet étant transmises une seule fois et non conservées, est proposé, mais ne fait pas partie de la v1.
  • Il revient au propriétaire de fixer les durées de conservation des correspondances, des empreintes, des lignes d’utilisation et des dossiers de preuves.

Les identifiants des exemples sont fournis à titre indicatif. Le contenu du dossier de preuves suit la section 10 de l’ébauche du contrat.