Document Verification
Document Verification API Documentation
Document Verification API - Detailed Documentation
The Document Verification API enables the submission and verification of identification documents through a multi-step journey or a single-step process. It also includes optional checks for age verification and disability assessment.
API Playground:
You can try the openJourney endpoint here.
Endpoints Overview
- Document Verification with Journey Build-Up:
- Open a verification journey.
- Upload document images (front, back, selfie).
- Initiate document verification.
- Single-Step Verification:
- Upload all images in a single request.
- Get instant verification results.
- Age and Disability Check:
- Verify user eligibility based on age or disability percentage.
- Error Handling & Codes:
- Standardized error messages for seamless integration.
Authentication
To access the Address Verification API, authentication is required. A Bearer Token must be included in every request.
- Tokens are valid for 60 minutes and must be refreshed after expiration.
- Refer to the Authentication for detailed steps on obtaining a token.
- Include the token in the
Authorization
header as follows:
Authorization: Bearer YOUR_ACCESS_TOKEN
API Base URL
1. Document Verification with Journey Build-Up
Description
This section covers the multi-step approach, where you first open a journey, then upload documents in steps, and finally call the verification endpoint(s).
1.1 Open Journey
Endpoint
POST /openJourney
Description
Starts a new verification journey where the customer can submit documents in steps.
Required Headers
Header | Value |
---|---|
Content-Type | application/json |
Authorization | Bearer yourAccessToken |
Request Body Parameters
Response Structure
Response Structure
Response Structure
Parameter | Type | Required | Description |
---|---|---|---|
journeyId | string | Yes | Unique identifier for the verification journey. |
passThroughData | object | No | Optional metadata to be carried through the journey. |
Example Response
1.2 Add Image
Endpoint
POST /addImage
Description
After opening a journey, you can upload an image representing the front/back of an ID or a selfie.
Adds an image (front, back, or selfie) to the ongoing journey. Images can be submitted as base64-encoded strings or as file uploads.
Request Body Parameters
Request Body Parameters
Request Body Parameters
Parameter | Type | Required | Description |
---|---|---|---|
journeyId | String | Yes | Unique identifier for the verification journey. |
imageName | String | Yes | Name of the uploaded image file. |
imageSide | String | Yes | Specifies which side of the document (front, back, selfie). |
storeOnly | Boolean | No | If true, stores the image without classification. |
imageData | String | Yes | Base64-encoded image or multipart file. |
passThroughData | Object | No | Custom metadata (e.g., user ID). |
Example Request
Example Request with Multiple Images
1.3 Verify
Endpoint
POST /verify
Description
Once you’ve uploaded all relevant images, you can call this endpoint to verify them.
Initiates the verification of all images submitted in this journey. Returns a detailed verification result (see response structure below).
Required Headers
Header | Value |
---|---|
Content-Type | application/json |
Authorization | Bearer yourAccessToken |
Request Body Parameters
Request Body Parameters
Request Body Parameters
Parameter | Type | Required | Description |
---|---|---|---|
journeyId | String | Yes | Unique identifier for the verification journey. |
Response Structure
Response Structure
Response Structure
Parameter | Type | Description |
---|---|---|
journeyId | String | Unique identifier for the verification journey. |
status | String | Status of the verification process (e.g., verificationComplete ). |
identitySubject | Object | Contains extracted identity details from the document. |
identitySubject.type | String | Type of identity subject (e.g., "person" ). |
identitySubject.fullName | String | Full name as extracted from the document. |
identitySubject.nameStructure | Object | Breakdown of the name details. |
identitySubject.nameStructure.firstName | String | First name of the individual. |
identitySubject.nameStructure.lastName | String | Last name of the individual. |
identitySubject.nameStructure.nativeFullName | String | Native full name of the individual. |
identitySubject.gender | String | Gender (M , F , or X ). |
identitySubject.nationality | String | Nationality code (ISO 3166, e.g., "DE" ). |
identitySubject.dob | String | Date of birth (YYYY/MM/DD ). |
identitySubject.addressSingleLine | String | Extracted address in single-line format. |
identitySubject.email | String | Extracted email (if available). |
identitySubject.mobileNumber | String | Extracted mobile number (if available). |
authoritativeData | Object | Contains verified details from the identity document. |
authoritativeData.identityDocument | Object | Identity document details. |
authoritativeData.identityDocument.type | String | Type of document (passport , IDCard , etc.). |
authoritativeData.identityDocument.idNumber | String | Document ID number. |
authoritativeData.identityDocument.issuingCountry | String | Country that issued the document. |
authoritativeData.identityDocument.expeditor | String | Issuing authority (e.g., "BH Neunkirchen" ). |
authoritativeData.identityDocument.expirationDate | String | Expiry date of the document (YYYY/MM/DD ). |
authoritativeData.identityDocument.verificationChannel | String | How verification was performed (optical , manual , etc.). |
proofOfWork | Object | Contains metadata related to proof of verification. |
proofOfWork.type | String | Type of proof (e.g., "image" ). |
proofOfWork.titleOfProof | String | Title describing the proof (e.g., "IDFront" ). |
proofOfWork.timestampOfProof | String | Timestamp when the proof was collected (YYYY/MM/DDTHH:MM:SSZ ). |
auditTrail | Object | Contains logging details about the verification process. |
auditTrail.workId | String | Unique ID of the verification attempt. |
auditTrail.workStatus | String | Status of the work (PASS , FAIL ). |
auditTrail.workStartTst | String | Timestamp when the verification started. |
auditTrail.workEndTst | String | Timestamp when the verification ended. |
auditTrail.workResult | String | Summary of the verification result. |
fraudAlerts | Object | Contains fraud detection-related data. |
fraudAlerts.fraudAlertDetail | Array | List of detected fraud alerts (if any). |
fraudAlerts.aggregateFraudAlertScore | Number | Overall fraud risk score (0 = no risk ). |
croppedImages | Object | Cropped images extracted from the document. |
croppedImages.front | String | Base64-encoded image of the front side. |
croppedImages.portrait | String | Base64-encoded portrait image from the document. |
croppedImages.signature | String | Base64-encoded signature image. |
croppedImages.back | String | Base64-encoded image of the back side. |
croppedImages.selfie | String | Base64-encoded selfie image (if applicable). |
Example Request
Example Response
1.4 Verify with Age and Disability Check
Endpoint
POST /verify/age
Description
Performs an optional age/disability verification after documents are submitted.
Checks if the user meets certain age or disability thresholds.
Note: ageFrom
and ageTo
are mutually exclusive—do not use both in the same request.
Required Headers
Header | Value |
---|---|
Content-Type | application/json |
Authorization | Bearer yourAccessToken |
Request Body Parameters
Request Body Parameters
Request Body Parameters
Parameter | Type | Description |
---|---|---|
ageFrom | Number | Minimum age for eligibility (can’t combine with ageTo ). |
ageTo | Number | Maximum age for eligibility (can’t combine with ageFrom ). |
minDisabilityPercentage | Number | Minimum disability percentage required for eligibility. |
Response Structure
Response Structure
Response Structure
Parameter | Type | Description |
---|---|---|
journeyId | String | Unique identifier for the verification journey. |
status | String | Status of the verification process (ageAndDisabilityVerificationComplete ). |
ageResult | String | Indicates if the individual meets the age requirement (yes or no ). |
disabilityResult | String | Indicates if the individual meets the disability criteria (eligible or not eligible ). |
Example Request
Example Response
2. Single-Step Verification
Description
This section describes the single-step approach, bypassing the journey creation. You must provide all images in one request.
2.1 Verify in One Step
Endpoint
POST /verify/single
Description
Bypasses the journey build-up and processes all images in one request. No feedback is provided if pages are missing—all must be submitted at once.
Required Headers
Header | Value |
---|---|
Content-Type | application/json |
Authorization | Bearer yourAccessToken |
Request Body Parameters
Request Body Parameters
Request Body Parameters
Parameter | Type | Required | Description |
---|---|---|---|
images | Array | Yes | List of image objects for verification. |
imageName | String | Yes | Name of the uploaded image. |
imageSide | String | Yes | Specifies document side (front , back , etc.). |
imageData | String | Yes | Base64-encoded image data (or file upload via multipart). |
Response Structure
Response Structure
Response Structure
Parameter | Type | Description |
---|---|---|
journeyId | String | Unique identifier for the verification journey. |
status | String | Status of the verification process (e.g., verificationComplete ). |
identitySubject | Object | Contains extracted identity details from the document. |
identitySubject.type | String | Type of identity subject (e.g., "person" ). |
identitySubject.fullName | String | Full name as extracted from the document. |
identitySubject.nameStructure | Object | Breakdown of the name details. |
identitySubject.nameStructure.firstName | String | First name of the individual. |
identitySubject.nameStructure.lastName | String | Last name of the individual. |
identitySubject.nameStructure.nativeFullName | String | Native full name of the individual. |
identitySubject.gender | String | Gender (M , F , or X ). |
identitySubject.nationality | String | Nationality code (ISO 3166, e.g., "DE" ). |
identitySubject.dob | String | Date of birth (YYYY/MM/DD ). |
identitySubject.addressSingleLine | String | Extracted address in single-line format. |
identitySubject.email | String | Extracted email (if available). |
identitySubject.mobileNumber | String | Extracted mobile number (if available). |
authoritativeData | Object | Contains verified details from the identity document. |
authoritativeData.identityDocument | Object | Identity document details. |
authoritativeData.identityDocument.type | String | Type of document (passport , IDCard , etc.). |
authoritativeData.identityDocument.idNumber | String | Document ID number. |
authoritativeData.identityDocument.issuingCountry | String | Country that issued the document. |
authoritativeData.identityDocument.expeditor | String | Issuing authority (e.g., "BH Neunkirchen" ). |
authoritativeData.identityDocument.expirationDate | String | Expiry date of the document (YYYY/MM/DD ). |
authoritativeData.identityDocument.verificationChannel | String | How verification was performed (optical , manual , etc.). |
proofOfWork | Object | Contains metadata related to proof of verification. |
proofOfWork.type | String | Type of proof (e.g., "image" ). |
proofOfWork.titleOfProof | String | Title describing the proof (e.g., "IDFront" ). |
proofOfWork.timestampOfProof | String | Timestamp when the proof was collected (YYYY/MM/DDTHH:MM:SSZ ). |
auditTrail | Object | Contains logging details about the verification process. |
auditTrail.workId | String | Unique ID of the verification attempt. |
auditTrail.workStatus | String | Status of the work (PASS , FAIL ). |
auditTrail.workStartTst | String | Timestamp when the verification started. |
auditTrail.workEndTst | String | Timestamp when the verification ended. |
auditTrail.workResult | String | Summary of the verification result. |
fraudAlerts | Object | Contains fraud detection-related data. |
fraudAlerts.fraudAlertDetail | Array | List of detected fraud alerts (if any). |
fraudAlerts.aggregateFraudAlertScore | Number | Overall fraud risk score (0 = no risk ). |
croppedImages | Object | Cropped images extracted from the document. |
croppedImages.front | String | Base64-encoded image of the front side. |
croppedImages.portrait | String | Base64-encoded portrait image from the document. |
croppedImages.signature | String | Base64-encoded signature image. |
croppedImages.back | String | Base64-encoded image of the back side. |
croppedImages.selfie | String | Base64-encoded selfie image (if applicable). |
Example Request
3. Error Handling & Codes
Below is how the Document Verification API handles errors. This section is divided into:
- General HTTP Status Codes - which apply across all endpoints.
- Generic Error Response Structure - the standard JSON format returned in error cases.
- Endpoint-Specific Error Scenarios - a reference table detailing common error codes for each endpoint.
3.1 General HTTP Status Codes
HTTP Status | Meaning | Description |
---|---|---|
200 | OK | Request succeeded. See response body for details. |
400 | Bad Request | The request was invalid or missing required parameters. |
401 | Unauthorized | Authentication failed or the user lacks valid credentials. |
403 | Forbidden | The user does not have permission to perform this operation. |
404 | Not Found | Resource or endpoint not found. |
422 | Unprocessable Entity | The request is understood, but cannot be processed (e.g., malformed base64 or missing data). |
429 | Too Many Requests | Rate limit exceeded. |
500 | Internal Server Error | A generic server-side error occurred. |
3.2 Generic Error Response Structure
When an error occurs (i.e., a 4xx
or 5xx
status code), the API returns a JSON body with the following format:
Response Structure
Response Structure
Response Structure
Field | Type | Description |
---|---|---|
errorCode | String | A short code identifying the specific error scenario, e.g., invalidImageData . |
errorMessage | String | A human-readable description of the error. |
details | Object | Additional context (e.g., invalid field, expected values vs. actual). |
Example Response
errorCode
is particularly useful for programmatic checks in client applications.errorMessage
should help developers quickly understand what went wrong.details
can be omitted if no extra info is needed.
3.3 Endpoint-Specific Error Scenarios
Each endpoint may have unique validation or domain-specific constraints. The table below summarizes common error codes per endpoint. All error responses conform to the Generic Error Response Structure above.
Endpoint | Error Code | HTTP Status | Error Message | Description |
---|---|---|---|---|
/openJourney | journeyAlreadyExists | 400 | A journey already exists for this user/session. | Occurs if the client tries to open a new journey while one is still active. |
/addImage | invalidImageData | 400 | Base64 string is malformed or missing. | Triggered if imageData is not valid base64 or is absent. |
journeyNotFound | 404 | No active journey with the given journeyId . | The provided journeyId does not exist or has already been closed. | |
/verify | journeyNotFound | 404 | No active journey with the given journeyId . | Attempted verification on an invalid or missing journeyId . |
missingImages | 422 | Required images (front/back/selfie) were not all provided. | Verification could not be completed because essential images are missing. | |
/verify/age | mutuallyExclusive | 400 | ageFrom and ageTo cannot both be specified. | The request included both ageFrom and ageTo , which is not allowed. |
journeyNotFound | 404 | No active journey with the given journeyId . | As above. | |
/verify/single | missingImages | 422 | Not all necessary images (front/back) were provided. | Single-step verification requires all images in a single request. |
invalidImageData | 400 | Base64 string is malformed or missing. | Same as above, but specifically applies to single-step scenarios. |
3.4 Handling Errors
- Check the HTTP status code returned from the API.
- Parse the JSON if the status code indicates an error (
4xx
or5xx
). - Use
errorCode
to determine the type of error (e.g.,JOURNEY_NOT_FOUND
), and handle it in your client application (e.g., show a specific user message). - Look at
errorMessage
for a human-readable explanation of the issue. - Examine
details
if present, to get more granular context (e.g., which field triggered the error).