Verifying ID document (IDC) (v4)

Preview

DOC_ID:v4 is in preview. The step API is not yet finalised and may change before general availability. Use DOC_ID:v3 for production flows.

End-to-end, compliant document-based identity verification (v4)

Verifies identity using secure identity documents through multiple verification modes, adapted to business and regulatory needs.

In Capture mode, the end user completes verification through the IDnow frontend, which guides them step by step in providing the required identity evidence. This includes capturing document images, performing biometric checks (such as face matching and liveness detection), and optionally reading electronic document chips via NFC.

info

DOC_ID:v4 is the successor to DOC_ID:v3. It uses a realm-based configuration instead of the shortname-based environment config used in earlier versions.

---

Key features

• Automated visual verification: AI-based analysis of ID document authenticity, integrity, and visual security features.
• Automated NFC verification: Secure reading and validation of embedded NFC chips in electronic identity documents.
• Agent-assisted verification: Expert review for complex, regulated, or escalated cases.
• Configurable capture: Document types, biometric sample types, and liveness detection can be configured per deployment.
• Explicit cancellation routing: When enableCancellation: true, cancelled sessions (user-initiated or agent-initiated) exit via the cancelled route, enabling flow-level handling (retry prompts, rejection paths). When false or absent (default), the session immediately ends with an ABORTED outcome.

---

Configuration

Option	Type	Required	Description
capture.documentTypes	string[]	Yes	Document types accepted for capture. Accepted values: "ID", "PASSPORT", "RESIDENT_PERMIT", "VISA", "DRIVING_LICENSE", "HEALTH_CARD".
capture.biometricSampleTypes	string[]	Yes	Biometric sample types to collect (e.g. face image, liveness).
capture.biometricConsentHandling	"SDK" | "CUSTOMER"	No	Who handles biometric consent. Defaults to "SDK".
capture.withDocLiveness	boolean	No	Whether to require document liveness detection.
config.live.realm	string	Yes	Realm identifier for the live environment.
config.staging.realm	string	Yes	Realm identifier for the staging environment.
handoff	boolean	No	Whether the step supports handoff to another device. Defaults to false.
inputSources	Object	No	Specifies the workflow step IDs to use for sourcing data. If omitted, the step uses the latest available data blocks from the workflow. See Input mapping.
inputSources.basicIdentity	String	No	The ID of the step providing the BasicIdentity data block.
inputSources.extendedIdentity	String	No	The ID of the step providing the ExtendedIdentity data block.

Example configuration

{
  "capture": {
    "documentTypes": ["ID", "PASSPORT"],
    "biometricSampleTypes": ["SELFIE"]
  },
  "config": {
    "live": { "realm": "your-live-realm" },
    "staging": { "realm": "your-staging-realm" }
  }
}

---

Input data blocks

Data block	Required	Description
BasicIdentity	No	Pre-filled identity data to associate with the verification.
ExtendedIdentity	No	Extended identity data to associate with the verification.

---

Routes

Route	Condition	Description
verified	—	Document verified and identity extracted successfully.
not_verified	—	Document verification failed; no identity data could be extracted.
fraud_detected	—	Document identified as fraudulent; identity data extracted for manual review.
cancelled	When enableCancellation: true	Session was cancelled (user-initiated or agent-initiated); only a Verification data block is emitted — identity data blocks are not populated.

---

Output data blocks

Route	Data blocks produced	Notes
verified	BasicIdentity, ExtendedIdentity, DocumentData, DocumentImages, Verification, BiometricSamples	BiometricSamples only present when biometricSampleTypes is non-empty.
not_verified	Verification
fraud_detected	BasicIdentity, ExtendedIdentity, DocumentData, DocumentImages, Verification, BiometricSamples	BiometricSamples only present when biometricSampleTypes is non-empty.
cancelled	Verification	Only Verification is emitted — identity data blocks (BasicIdentity, ExtendedIdentity, DocumentData, DocumentImages, BiometricSamples) are never populated, regardless of whether the cancellation was user-initiated or agent-initiated. Unlike SPHINX:v3 and DOC_ID_SIGNING:v3, DOC_ID:v4 does not enrich identity data on agent-initiated cancellations.

Step compatibility

The DocumentImages produced by DOC_ID:v4 are ID-category images (passport, driving licence, etc.). They cannot be used as input to IBAN_VERIFICATION:v1 or PROOF_OF_ADDRESS:v1, which require bank or address documents respectively.

The Verification data block carries evidence artefacts under methods[].evidence[]. This Step can produce the following evidence types, each present only when the corresponding artefact is available: documentFrontRecording, documentBackRecording, livenessRecording, documentFrontOriginalImage, documentBackOriginalImage, analysisReport.

Example payloads

BasicIdentity — verified

{
  "dataBlockId": "e3685434-18ce-4c49-b96d-6729934a8303",
  "type": "BasicIdentity",
  "givenName": "Jean",
  "familyName": "Dupont",
  "name": "Jean Dupont",
  "birthDate": "1985-03-22",
  "birthPlace": "Paris"
}

ExtendedIdentity — verified

{
  "dataBlockId": "26ea319f-a171-4fbb-b1ad-85b9f3cc1801",
  "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": "7c07de62-48f4-4c07-92da-7a8681ba576a",
  "type": "DocumentData",
  "documentType": "ID",
  "documentNumber": "D123456789",
  "expiryDate": "2030-06-15",
  "issuanceDate": "2020-06-15",
  "issuingCountry": "DE",
  "issuingAuthority": "Bürgeramt Berlin"
}

Verification — verified

{
  "dataBlockId": "c05eae97-cdec-4bf4-addf-bb626ef0fd3f",
  "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
        },
        {
          "technique": "faceMatch",
          "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": "d59cf1d1-d715-406e-ba47-4027fb8918f0"
}

Verification — not_verified

{
  "dataBlockId": "f8d0f864-2dec-45d6-a9ca-b6012efcc3d2",
  "type": "Verification",
  "status": "rejected",
  "terminationReason": null,
  "methods": [
    {
      "type": "documentCheck",
      "checks": [
        {
          "technique": "documentValidity",
          "sources": [],
          "outcome": "failed",
          "issues": [
            {
              "code": "DOC_EXPIRATION_DATE",
              "severity": "error",
              "message": "There are some warnings concerning the document expiration date"
            }
          ],
          "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
        },
        {
          "technique": "agentReview",
          "sources": [],
          "outcome": null,
          "issues": [],
          "performedBy": null,
          "performedAt": null
        }
      ],
      "evidence": [
        {
          "type": "analysisReport",
          "ref": {
            "$ref": "vault",
            "$id": "7634dfe5-8dda-43d9-927a-4f69c4be84ca"
          }
        },
        {
          "type": "documentFrontOriginalImage",
          "ref": {
            "$ref": "vault",
            "$id": "e7389b6a-2d05-4a8f-9920-e47798c9f919"
          }
        },
        {
          "type": "documentBackOriginalImage",
          "ref": {
            "$ref": "vault",
            "$id": "71541e7d-e1dc-4826-a700-8c606f4e2dd3"
          }
        }
      ]
    }
  ],
  "provider": "idnow",
  "trustFramework": null,
  "assuranceLevel": null,
  "verifiedAt": "2026-02-10T14:05:30.000Z",
  "verificationProcessId": "3a128c6d-4960-45fd-b4d1-5922f44a61be"
}

---