API de socios v1 · Borrador, aún no disponible

Coincidencias: POST /v1/match

Borrador: aún no disponible. Esta página describe el contrato propuesto de la v1 para socios (versión 1.0.0-rc.1). Ningún punto de acceso de esta página está desplegado y todavía no se puede emitir ninguna clave de API.

Envíe hasta 100 consultas en una sola solicitud. Cada consulta devuelve su propio estado, la hora en que se buscó, los registros contra los que se verificó y las coincidencias que estén en la banda mínima o por encima de ella.

Cómo realizar una solicitud

El alcance requerido es match:read. Cada llamada se cobra con una unidad de consulta por cada consulta del lote. Envíe un Idempotency-Key en cada verificación para que un reintento devuelva la respuesta almacenada en lugar de generar un segundo cobro.

curl

curl https://api.crownintelligence.net/v1/match \
  -H "X-Api-Key: $CI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: screen-2026-10-13-0001" \
  -d '{
    "queries": [
      {"query_ref": "case-7731:party-1", "entity_type": "Person",
       "name": "Aleksandr Petrov", "dob": "1971-05-02", "country": ["RU"]},
      {"query_ref": "case-7731:vessel-1", "entity_type": "Vessel",
       "name": "Sea Lark", "identifiers": {"imo": "9176187"}}
    ],
    "options": {"min_band": "POSSIBLE", "limit": 5, "collections": ["default", "sanctions"]}
  }'

Node

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": "screen-2026-10-13-0001"   // reuse on retry, never on a new screening
  },
  body: JSON.stringify({
    queries: [
      { query_ref: "case-7731:party-1", entity_type: "Person",
        name: "Aleksandr Petrov", dob: "1971-05-02", country: ["RU"] }
    ],
    options: { min_band: "POSSIBLE", limit: 5 }
  })
});
if (!res.ok) throw new Error("HTTP " + res.status + " " + (await res.text()));
const { match_request_id, queries } = await res.json();

Campos de la consulta

El esquema es cerrado. Cualquier otro campo se rechaza con 400 invalid_request. Un lote de más de 100 consultas devuelve 413 batch_too_large.

Opciones

• min_band: STRONG, POSSIBLE o WEAK. El valor predeterminado es POSSIBLE. Consulte las bandas en la descripción general.
• collections: de uno a cinco valores entre default, sanctions, peps, crime y maritime.
• limit: coincidencias por consulta, de 1 a 25. El valor predeterminado es 5.
• include_features: indica si cada coincidencia enumera las características que modificaron su puntuación. El valor predeterminado es true.
• algorithm: standard o name-only, según la lista de la página de algoritmos.

Estados

Cada consulta tiene exactamente un estado. Lea primero los estados en la descripción general: solo no_hit_searched significa que no se encontró ninguna coincidencia, y una consulta nunca queda libre de coincidencias mientras tenga el estado not_searched o error.

Algunos identificadores se aceptan ahora, pero no se buscan hasta que se cargue su registro: lei y wallet_address. Una consulta que solo tiene estos identificadores y ningún nombre devuelve not_searched, y la respuesta los enumera en identifiers_not_searched. Un nombre buscado en registros que no cubren su entity_type devuelve not_searched con el motivo no_register_for_entity_type.

Respuesta

La respuesta enumera un resultado por consulta, en el orden en que se enviaron, y un match_request_id. Use ese ID para abrir un caso y para localizar la solicitud en sus registros de actividad.

{
  "match_request_id": "mrq_01J9Z3K4M6",
  "queries": [
    {
      "query_ref": "case-7731:party-1",
      "status": "hit",
      "searched_at": "2026-10-13T14:02:11Z",
      "registers_searched": [
        {"list_id": "crown-list-0412", "register_name": "EU Consolidated Financial Sanctions",
         "publisher": "European Union", "list_date": "2026-10-09", "loaded_at": "2026-10-12T22:40:00Z",
         "licence": "PERMITTED"}
      ],
      "matches": [
        {"record_id": "crown-88213", "list_id": "crown-list-0412", "band": "STRONG", "score": 0.94,
         "schema": "Person", "caption": "Aleksandr Petrov", "matched_name": "Aleksandr Petrov",
         "features": [
           {"field": "dob", "effect": "+0.10", "rule": "birth date match",
            "explanation": {"en": "Birth date matches.", "fr": "La date de naissance correspond."}}
         ],
         "record_url": "https://crownintelligence.net/records/crown-88213"}
      ]
    },
    {
      "query_ref": "case-7731:wallet-1",
      "status": "not_searched",
      "searched_at": "2026-10-13T14:02:11Z",
      "not_searched_reason": "identifier_not_covered",
      "identifiers_not_searched": ["wallet_address"],
      "registers_searched": [],
      "matches": []
    }
  ]
}

Cada coincidencia incluye record_id, list_id, band, score (0 a 1), schema, caption, matched_name, features y record_url. Cada característica explica un cambio en la puntuación, con field, effect, rule y un explanation bilingüe. La lista de reglas puede crecer sin que cambie la versión, por lo que no la codifique de forma fija.

Cada entrada de registers_searched indica list_id, register_name, publisher, list_date (la fecha propia del editor, o null), loaded_at (cuándo Crown Intelligence cargó por última vez el registro) y licence. Evalúe la actualidad de los datos según loaded_at.

Cómo manejar cada estado

El patrón siguiente envía cada estado a una ruta distinta. Ningún resultado llega a una conclusión «sin coincidencias» salvo no_hit_searched.

// Only no_hit_searched can ever be a negative. Everything else needs a person or a retry.
function outcome(q) {
  switch (q.status) {
    case "hit":
      return { action: "review", matches: q.matches };
    case "no_hit_searched":
      return { action: "no match", registers: q.registers_searched.map(r => r.register_name), searchedAt: q.searched_at };
    case "not_searched":
      return { action: "not checked", reason: q.not_searched_reason };   // never clear
    case "error":
      return { action: "retry", code: q.error.code };                    // never clear
    default:
      throw new Error("unknown status: " + q.status);
  }
}

Confirme siempre una coincidencia con la publicación oficial antes de actuar con base en ella. Una coincidencia es una señal para revisión, no una conclusión.

Qué se almacena

Los cuerpos de las solicitudes no se registran. Crown Intelligence conserva, por consulta, un resumen con clave del nombre normalizado, la fecha de nacimiento y los códigos de país, bajo una clave exclusiva de su cuenta. El nombre y la fecha de nacimiento no se almacenan. Conserve en su propio sistema el vínculo entre su sujeto y query_ref. Los plazos de conservación son un tema pendiente del responsable.

Los ejemplos usan nombres, referencias e ID de registro ilustrativos.