Skip to main content
POST
cURL

Authorizations

x-api-key
string
header
required

Your application's API key, from Developers -> API keys in the Business Console. The primary key has full access. A named key can be scoped: none, read or write per resource, limited to some workflows or to approved sessions, to a list of IP addresses, and to an expiry date. 401 means the key is wrong, revoked or expired; 403 means no key was sent, the key has no access to this resource or action, or the request came from an address outside its IP list; 404 on a session route means the session is outside the key's workflows or statuses. A key without media access receives image, video and PDF URLs as null, and a key without sessions write receives session links and tokens as null. See https://docs.didit.me/console/api-keys.

Body

multipart/form-data
front_image
file
required

Front side of the identity document. Allowed extensions: tiff, jpg, jpeg, png, webp, pdf. Maximum upload size: 10 MB (larger files are rejected with 400). PDFs are rendered to an image before OCR; encrypted PDFs require front_image_password. Images are automatically compressed to ~0.5 MB and EXIF orientation is applied. Upload the full, uncropped capture with all four corners of the document visible.

front_image_password
string
write-only

Password to decrypt front_image when it is an encrypted PDF. Sending an encrypted PDF without (or with a wrong) password returns 400.

back_image
file

Back side of the document — send it whenever the document has one (many ID cards carry the MRZ or a barcode on the back; omitting it simply leaves the MRZ and back-side fields empty in the response — this endpoint does not raise a missing-MRZ warning). Same format and size limits as front_image. When omitted, back_image and back-side fields are null in the response.

back_image_password
string
write-only

Password to decrypt back_image when it is an encrypted PDF.

perform_document_liveness
boolean
default:true

Screens both images for presentation fraud: screen replays (SCREEN_CAPTURE_DETECTED), printed copies (PRINTED_COPY_DETECTED), and portrait manipulation (PORTRAIT_MANIPULATION_DETECTED). Any of these auto-declines. Enabled by default; set to false to skip fraud screening and reduce latency. When enabled and the provider returns no usable score, the response is In Review with a DOCUMENT_LIVENESS_NOT_COMPUTED warning rather than Approved.

Example:

true

minimum_age
integer | null

Accepted and validated (1–120) but currently not applied by this endpoint — it never produces a MINIMUM_AGE_NOT_MET warning from this field. Enforce age rules from the returned date_of_birth/age, or use a verification-session workflow with age restrictions.

Required range: 1 <= x <= 120
expiration_date_not_detected_action
enum<string>
default:NO_ACTION

What to do when no expiration date can be read (EXPIRATION_DATE_NOT_DETECTED). Default NO_ACTION because many identity documents print no expiry date. Note: a detected and past expiry date always declines (DOCUMENT_EXPIRED), regardless of this option.

Available options:
NO_ACTION,
DECLINE
invalid_mrz_action
enum<string>
default:DECLINE

What to do when the extracted MRZ fails check-digit validation (MRZ_VALIDATION_FAILED). A missing MRZ raises no warning on this endpoint. Only relevant for documents that carry an MRZ. REVIEW is not supported on this endpoint and returns 400.

Available options:
NO_ACTION,
DECLINE
inconsistent_data_action
enum<string>
default:DECLINE

What to do when extracted data is internally inconsistent: DATA_INCONSISTENT, MRZ_AND_DATA_EXTRACTED_FROM_OCR_NOT_SAME (visual zone disagrees with the MRZ), or DOCUMENT_NAME_DIFFERENT_FROM_OTHER_APPROVED_DOCUMENTS.

Available options:
NO_ACTION,
DECLINE
critical_field_occlusion_action
enum<string>
default:DECLINE

What to do when a critical printed field was physically covered on the capture (CRITICAL_FIELD_OCCLUSION_DETECTED) - an identity number, a name, the date of birth, or the expiry date. Declines by default, like this endpoint's other document-integrity risks: covering the numbers a report is reconciled against is what a redacted document looks like. The value read for a covered field is dropped from the extraction either way, so the matching *_NOT_DETECTED warning usually accompanies it. REVIEW is not supported on this endpoint and returns 400.

Available options:
NO_ACTION,
DECLINE
document_or_personal_number_format_mismatch_action
enum<string>
default:NO_ACTION

What to do when a number does not match the format its issuing authority uses for that document type (DOCUMENT_NUMBER_FORMAT_MISMATCH, PERSONAL_NUMBER_FORMAT_MISMATCH). Default NO_ACTION, which reports the warning without changing the status. REVIEW is not supported on this endpoint and returns 400.

Available options:
NO_ACTION,
DECLINE
preferred_characters
enum<string>
default:latin

Preferred script for name/address fields on documents that print both Latin and non-Latin text (Arabic, Cyrillic, CJK, …). latin returns transliterated/Latin values; non_latin prefers the native script.

Available options:
latin,
non_latin
save_api_request
boolean
default:true

When true (default), persists the call as an API-type session — visible in the Business Console, retrievable via GET /v3/session/{sessionId}/decision/ using the returned request_id, announced through a status.updated webhook, and with document images returned as media URLs. When false, nothing is stored, request_id is a transient UUID, and images are returned inline as base64 JPEG strings.

Example:

true

vendor_data
string

Optional opaque string (your internal user id, email, UUID…) stored on the persisted session and echoed back in the response. Use it to correlate API calls with your own records and to filter sessions later.

Example:

"user-123"

metadata
object

Optional JSON object stored with the session (when save_api_request=true) and echoed back in the response. In multipart requests, send it as a JSON-encoded string field (e.g. metadata={"flow":"onboarding"}) — it is parsed into an object.

Example:

Response

Document processed. id_verification.status is Approved, Declined, or In Review; every detected issue is itemized in id_verification.warnings. In Review is returned when a requested document-liveness check produced no usable result (DOCUMENT_LIVENESS_NOT_COMPUTED). A problematic document still returns 200 with status: "Declined" — inspect the body, not just the HTTP code. When save_api_request=true, request_id is the persisted session id and image fields are short-lived media URLs; with save_api_request=false they are inline base64 JPEG strings.

request_id
string<uuid>

Persisted session id when save_api_request=true (usable with GET /v3/session/{sessionId}/decision/); otherwise a transient correlation UUID.

id_verification
object
vendor_data
string | null

Echo of the vendor_data you sent, or null.

metadata
object | null

Echo of the metadata object you sent, or null.

created_at
string<date-time>

ISO 8601 timestamp (UTC) of when the response was generated.

Last modified on November 1, 2026