IDV Integrator Customer API (1.4.0)

Returns the static field descriptors for the Customer model — name, type, label, and whether each field is integrator-writable / searchable. There are no per-tenant custom fields, so this is a fixed list.

Exact-match search over an allow-list of PII fields. Sent as a POST body so PII stays out of URLs/logs. The body must be a non-empty object whose keys are a subset of the searchable fields; any other key → 400 invalid_search_field. Returns up to 200 results; next_cursor is always null (search is not paginated). Anonymized Customers have their PII erased (all searchable fields are null), so they never match a PII search. Their customer_id is also replaced at erasure, so only the new id returned by the anonymize call reaches the erased record. null filter values are rejected (a null match would enumerate erased fields).

Keyset-paginated list ordered by (created_at desc, customer_id desc). Pass the returned next_cursor back as cursor to fetch the next page; a null next_cursor means the last page.

Supply-on-create — the migration primitive for re-creating an existing customer (e.g. under a legacy {national_id}_{uuid} scheme) with its historical external_id preserved. external_id must match ^[a-zA-Z\d._-]{1,64}$ and be unique per tenant.

Updates any subset of the writable identity fields. Unknown keys are rejected. Each of these is a workflow-managed field, so if a verification run is active for this Customer the write returns 409 WORKFLOW_RUN_ACTIVE (fail-open on a guard outage). An anonymized Customer is terminal: the write is rejected with 409 CUSTOMER_ANONYMIZED.

Right-to-erasure: wipes the Customer's PII and cascades to every child Digital Identity (flips each to the terminal anonymized decision and clears raw biometric blob refs), then best-effort removes the person from the 1:N face-dedup watchlists. Never a row delete, so assignment history survives. Subject to the fail-closed active-run guard, like every other anonymize. Not idempotent by path id. Erasure replaces the Customer's customer_id with a freshly generated opaque UUID, so repeating the call with the original id returns 404 not_found — that does not mean the erasure failed. The new id is in the customer_id of the first response; retry with that value if you need a confirmed repeat.

Which hands the Customer has a usable palm enrolment for, derived from the primary Digital Identity's palm rows. A hand is reported only while its stored biometric reference still exists, so erased palms never appear and an anonymized Customer reports an empty list.

Non-destructive erasure of one Digital Identity: flips it to the terminal anonymized decision, wipes its PII/biometric blob refs, and removes it from the watchlists. If it is the Customer's only identity the erasure cascades to the parent Customer (cascaded_to_customer: true). Refused (409 ANONYMIZE_PRIMARY_DI_BLOCKED, carrying customer_id in details) when it is the primary identity of a Customer that has other identities — anonymize the Customer instead. Idempotent on an already-anonymized identity, except after a cascade: cascading replaces the parent Customer's customer_id, so repeating the call on the original {customerId} returns 404. Use POST /v1/identities/{identityId}/anonymize for a retry-safe repeat. Subject to the fail-closed active-run guard.

Manually overrides the identity's decision (marks it as a manual decision) and re-syncs the parent Customer's denormalized decision. Guarded unconditionally by the fail-closed active-run guard: forcing a decision while a workflow run is live is exactly the race the guard prevents. An anonymized identity is terminal — the transition is rejected with 409 IDENTITY_ANONYMIZED. Returns an empty object on success.

Returns the extracted onboarding data (name, date of birth, document number, place of birth, …) and the S3 keys of the captured images for a single Digital Identity, addressed by its own id — no customer id needed, so it also serves in-progress identities that were never promoted to a Customer (customer_id is then null). Fetch each image via GET /v1/identities/{identityId}/images/{slot} (slot = the property name in images). On an anonymized identity the erased fields and image keys are null.

Streams one captured image of the identity. The identity lookup in the caller's own tenant database is the tenancy proof, so every slot is servable by id — including in-progress identities the deprecated key-addressed GET /v1/customers/images/{key} cannot reach without a known key. All stored keys now share the {orgId}/verifications/… org-first layout, worker-written references included. 404 when the identity does not exist, the slot holds no image, the image was erased by anonymization, or the stored object is no longer present in storage. Sends ETag and honours If-None-Match (304); responses are privately cacheable for 24 hours.

Deprecated 1.2.3-compat alias of GET /v1/identities/{identityId} — identical response body; new integrations should use the flat route.

Deprecated 1.2.3-compat alias — use the slot-addressed GET /v1/identities/{identityId}/images/{slot}, which also serves the workflow-storage keys this route rejects. Streams one captured image by the S3 key taken from the images object of the identity-data endpoint. Only keys under the caller's own {orgId}/verifications/… prefix are served — foreign, malformed, or internal workflow-storage keys yield 404. Sends ETag and honours If-None-Match (304); responses are privately cacheable for 24 hours.

Flat variant of POST /v1/customers/{customerId}/identities/{identityId}/anonymize that resolves the Customer FROM the identity, so it can reach customer-less identities (a standalone reject, an unresolved-duplicate cell) that the nested route structurally cannot address. Same scope resolution; cascades to the parent Customer when the identity is its only one. The active-run guard keys on the Customer, so it applies only to customer-bound identities — a customer-less identity is instead refused while still pending (409 IDENTITY_WORKFLOW_IN_PROGRESS) and never returns 503.

Every Assignment held by this Customer, newest first. Unpaginated — the full result set is returned. An unknown customerId is a 404, not an empty list.

Every Assignment recorded for one external_identifier, across all Customers, newest first. Unpaginated — the full result set is returned.

Links an integrator-side artifact to a Customer, optionally pinning it to one of that Customer's Digital Identities. The Assignment is always created active; assignment_id and assigned_at are server-owned. A Customer may hold only one open (active or suspended) Assignment per external_identifier. Creating a second one returns 409 conflict — close the existing one with POST /v1/assignments/transfer first.

The Assignment field list with per-field flags, mirroring GET /v1/customers/schema. Only remote_reference and custom_fields are writable by integrators.

Closes the open Assignment that from_customer_id holds for this external_identifier — status becomes unassigned and unassigned_at is stamped — and, when to_customer_id is supplied, opens a fresh active Assignment on that Customer with a new assignment_id. Both halves commit together. This is the only way an Assignment reaches the unassigned state. Omit to_customer_id, or send it as null, to unassign without opening anything. In that case digital_identity_id, remote_reference and custom_fields must be absent. Sending digital_identity_id or remote_reference — even as null — returns 400 invalid_body; custom_fields: null is rejected earlier still, by schema validation, with 400 VALIDATION_ERROR. The opened Assignment does not inherit remote_reference or custom_fields from the closed one; supply them here if the destination needs them.

Only remote_reference and custom_fields are writable; every other field is fixed for the life of the Assignment. Closed (unassigned) Assignments stay patchable, so a late reference correction is possible. Only the keys present in the body are written.

Removes the Assignment row outright. This is a hard delete, not a state change — the record is gone and does not appear in any later listing. To close an Assignment while keeping its history, use POST /v1/assignments/transfer without a to_customer_id.

Moves an active Assignment to suspended. Not idempotent — calling it on an Assignment that is not active, including one already suspended, returns 409 conflict.

Moves a suspended Assignment back to active. Not idempotent — calling it on an Assignment that is not suspended, including one already active, returns 409 conflict.

Unauthenticated liveness check, served outside the versioned lane — no bearer token, no tenant context. It answers from the process alone and does not reach the database, so a 200 means the service is running, not that it can serve tenant requests.