IDCheck Headless (v2)
DOC_ID_HEADLESS:v2 is in preview. The Verification data block implementation is not yet finalized and may change before general availability.
This is version 2 of the Headless step. The key difference from v1 is that results are delivered in the unified Verification data block instead of DocumentVerification.
Headless document identity verification with unified Verification data block
Verifies identity using static evidence collected by your own front end and submitted to IDnow via API, with results delivered in the unified Verification data block format.
In Headless mode, your application is responsible for collecting and providing identity evidence, such as images of the ID document. IDnow then performs verification on these static inputs using AI-based analysis and data extraction modules. Unlike Capture mode, the Headless flow does not involve any user interaction within the IDnow front end; all evidence is provided directly by the customer's system.
Because verification relies solely on static images, certain checks that require dynamic interaction or live capture cannot be performed. These include NFC chip reading and dynamic document validation (for example, visual inspection of holograms under movement or live liveness actions). As a result, Headless verification provides a more limited level of accuracy compared to Capture mode and is not suitable for regulated use cases such as KYC or AML processes.
Instead, Headless mode is best suited for unregulated scenarios, such as document data extraction, image quality assessment, or pre-validation steps where full dynamic verification is not required.
Key features
- Customer-managed evidence collection – The customer application captures and submits document images via API.
- Static evidence processing – Verification is performed using only static images, without live interaction or dynamic capture.
- AI-based analysis – Automated checks assess document authenticity and extract identity data.
- Unified Verification data block – Results are delivered in the standardized Verification format, enabling seamless downstream processing and data aggregation.
- Lightweight integration – Ideal for API-based use cases that require automated data extraction or streamlined verification flows.
Configuration
| Parameter | Type | Required | Description |
|---|---|---|---|
config | Object | Yes | Environment-specific configuration. |
config.live.realm | String | Yes | The IDCheck.io realm used for document processing in the live environment. |
config.staging.realm | String | Yes | The IDCheck.io realm used for document processing in the staging environment. |
Input data blocks
Input requirements for this step.
| Data block type | Required | Description |
|---|---|---|
DocumentImages | Yes | Contains vault references ({ "$ref": "vault", "$id": "<uuid>" }) to the identity document images. This data block is always required. |
Each file referenced in DocumentImages is subject to a per-file size limit (20 MB by default). Exceeding it returns HTTP 422 with error code FILE_TOO_LARGE at session creation. See File size limits for details.
Routes
| Route | Description |
|---|---|
verified | Document was successfully processed and identity data was extracted. |
not_verified | Document verification failed; no identity data could be extracted. |
fraud_detected | Document was identified as fraudulent; identity data extracted for manual review. |
Output data blocks
Data blocks produced per route.
| Route | Data blocks produced | Description |
|---|---|---|
| verified | BasicIdentity, ExtendedIdentity, DocumentData, DocumentImages, Verification | Successful document processing with identity extraction |
| not_verified | Verification | Document verification failed, no processing possible |
| fraud_detected | BasicIdentity, ExtendedIdentity, DocumentData, DocumentImages, Verification | Document identified as fraudulent, identity data extracted for manual review |