Verifying ID document - API only (IDC) (v2)

Preview / Alpha

This version of this step type is in preview / alpha. The functionality and subsequently the documentation can still change.
The stable / GA version of this step is Verifying ID document - API only (IDC) (v1)

Automated verification using pre‑captured document and face images

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. As a result, this IDV method provides a more limited level of accuracy and is not suitable for regulated use cases such as KYC or AML processes.

Instead, this step 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.

Step compatibility

This step, Verifying IBAN - API only (v1), and Verifying proof of address - API only (v1) each require a different document type and cannot be combined in the same flow.

---

Configuration

Option	Type	Required	Description
config	object	Yes	Environment-specific configuration.
config.live.realm	string	Yes	The IDCheck.io realm used for document processing in this environment. (live)
config.staging.realm	string	Yes	The IDCheck.io realm used for document processing in this environment. (staging)

Example configuration

{
  "config": {
    "live": { "realm": "your-live-realm" },
    "staging": { "realm": "your-staging-realm" }
  }
}

---

Input data blocks

Data block	Required	Description
DocumentImages	Yes	Contains vault references ({ "$ref": "vault", "$id": "<uuid>" }) to the identity document images. This data block is always required. File size limit: 4MB.

Specific requirements for DocumentImages

The DocumentImages data block supplied to this step must carry an ID-category document type (passport, driving licence, national ID card, etc.)

---

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

Route	Data blocks produced
verified	BasicIdentity, ExtendedIdentity, DocumentData, DocumentImages, Verification
not_verified	Verification
fraud_detected	BasicIdentity, ExtendedIdentity, DocumentData, DocumentImages, Verification

Verification data block

This data block carries evidence artefacts under methods[].evidence[]. Because this step being API-only and subsequently only processes only static images (no live capture), this step can only produce the following evidence types, each present only when the corresponding artefact is available:

• documentFrontOriginalImage,
• documentBackOriginalImage,
• analysisReport

Example payloads

The examples below show the data blocks produced on the verified route for a French national ID card.

BasicIdentity — verified

{
  "dataBlockId": "65da79c1-d048-4fbc-9161-dcf3784755ba",
  "type": "BasicIdentity",
  "givenName": "Jean",
  "familyName": "Dupont",
  "name": "Jean Dupont",
  "birthDate": "1985-03-22",
  "birthPlace": "Paris"
}

ExtendedIdentity — verified

{
  "dataBlockId": "9ec818de-504e-4dd8-ab54-62de951b6841",
  "type": "ExtendedIdentity",
  "portrait": {
    "$ref": "vault",
    "$id": "020ff369-43d8-4b8a-94e7-6814c0bdc35a"
  },
  "nationality": "FRA",
  "personalAdministrativeNumber": null,
  "familyNameBirth": "Dupont",
  "givenNameBirth": "Jean",
  "sex": 1,
  "emailAddress": null,
  "mobilePhoneNumber": null,
  "residentAddress": null,
  "residentStreet": null,
  "residentHouseNumber": null,
  "residentHouseName": null,
  "residentCountry": null,
  "residentState": null,
  "residentCity": null,
  "residentPostalCode": null
}

DocumentData — verified

{
  "dataBlockId": "0c9dca49-7a44-4e59-aec0-7d10092db9b5",
  "type": "DocumentData",
  "documentType": "ID",
  "documentNumber": "D123456789",
  "expiryDate": "2030-06-15",
  "issuanceDate": "2020-06-15",
  "issuingCountry": "FR",
  "issuingAuthority": "Préfecture de Paris"
}

Verification — verified

{
  "dataBlockId": "b5fc0a4a-73cb-4486-b050-93973a474923",
  "type": "Verification",
  "status": "verified",
  "terminationReason": null,
  "methods": [
    {
      "type": "documentCheck",
      "checks": [
        {
          "technique": "documentValidity",
          "sources": [],
          "outcome": "passed",
          "issues": [],
          "performedBy": null,
          "performedAt": null
        },
        {
          "technique": "electronicRecord",
          "sources": [{ "type": "internalRegister", "id": null }],
          "outcome": "passed",
          "issues": [],
          "performedBy": null,
          "performedAt": null
        },
        {
          "technique": "dataCrosscheck",
          "sources": [
            { "type": "mrz", "id": null },
            { "type": "ocr", "id": null }
          ],
          "outcome": "passed",
          "issues": [],
          "performedBy": null,
          "performedAt": null
        },
        {
          "technique": "securityFeatures",
          "sources": [],
          "outcome": "passed",
          "issues": [],
          "performedBy": null,
          "performedAt": null
        }
      ],
      "evidence": [
        {
          "type": "documentFrontOriginalImage",
          "ref": { "$ref": "vault", "$id": "3f8a1c2e-..." }
        },
        {
          "type": "documentBackOriginalImage",
          "ref": { "$ref": "vault", "$id": "7b2d9e4a-..." }
        },
        {
          "type": "analysisReport",
          "ref": { "$ref": "vault", "$id": "c1e6f0b8-..." }
        }
      ]
    }
  ],
  "provider": "idnow",
  "trustFramework": null,
  "assuranceLevel": null,
  "verifiedAt": "2026-02-10T14:00:01.000Z",
  "verificationProcessId": "a7a6ee22-5660-44cc-ad54-45f55a342c91"
}

---