Skip to main content
All of these are signed GET requests. Their fields are described in Data models.

​
The decision

Returns the verification: status, reason, duplicate_check, your external_id and external_metadata, and erasure. This is what the webhook told you, and the place to confirm it. The webhook also carries the document object described below, without the images.

​
Finding a verification by your ID

When you have only your own external_id, for example to check whether a user already has a verification, list the workspace’s verifications:
Each item is the verification as GET /v1/verifications/{id} returns it (shortened above), newest first.
  • external_id: exact, case-sensitive match.
  • status: one or more statuses, comma-separated, such as status=approved,declined. A verification waiting for an ID document is filtered as started and listed as documents_required.
  • limit: 1 to 100; 20 by default.
  • cursor: the next_cursor of the previous page, sent with the same filters. next_cursor is null on the last page.
The query string is signed too, with its parameters sorted by name and a comma written as %2C; see API authentication. Learn about outcomes from webhooks rather than by listing again and again; see Rate limiting.

​
The document

On KYC and age verification by ID document workspaces, and on a facial age estimation that fell back to a document. A KYC workspace gets eleven fields:
An age workspace gets type, issuing_country and four fields. The other seven keys are absent, not null:
A US driving licence also carries the state that issued it, on any workspace:
How to read it:
  • null means the field was not read, or is not printed on that document. A passport has no address, many cards print no place of birth, and the German identity card prints no sex.
  • type is an open enum (passport, id, driver_license, residence_permit, other): handle values you do not know. other is a readable document that is not an identity card, passport, driving licence or residence permit, such as a health insurance card. id is the same value the upload endpoint takes.
  • issuing_subdivision is the state or province that issued the document, as a bare code (FL, CA, PR; up to three uppercase letters or digits), or null. Today it is filled for US driving licences and ID cards. It is null when issuing_country is, it is on every workspace, and it is kept after erasure.
  • issuing_country and nationality are ISO 3166-1 alpha-2 (XK for Kosovo). nationality is published only when the document itself states it. They differ on a residence permit and can differ on any document.
  • gender is F, M or X. X means the document states that the sex is unspecified. On a Mexican voter card or driving licence created before 20 August 2026 17:00 UTC, gender is null.
  • date_of_birth, issue_date and expiry_date are YYYY-MM-DD. A document that prints only the month or year of expiry reports the last day of that period. A birth or issue date printed partially is null, never rounded. A permanent document (for example PERMANENTE or INDEFINIDA) reads as a null expiry_date.
  • place_of_birth is the printed text, not normalised.
  • address is the printed text as read: trimmed, null when empty, not parsed and not normalised. It may contain line breaks. KYC workspaces only.
  • Text fields are trimmed; an empty one is null.

​
The age estimate

On Facial age estimation workspaces:
passed answers whether the person is at or above the workspace’s minimum age. The estimate itself is not returned as an age.

​
The images

Returns the image bytes. Use the urls from the document result; they are API URLs, so the request must be signed like any other. The server SDKs stream the download for you.

​
When data is gone

Images and personal data are kept for a limited time and can be erased on request; see Data retention and erasure. After that:
  • erasure on the verification is set and says when and why;
  • document fields are null and image urls are null;
  • downloading an image answers 404 MEDIA_NOT_FOUND.
The status, the reason and the dates stay.