Verifying ID document (v2)

Stable / GA

This is the current stable version of this step type.
A successor version of this step is in preview / alpha: Verifying ID document (v3)

Agent-assisted or automated document-based identity verification via IDnow's DocIDV service

Verifies the end user's identity by routing the session to IDnow's DocIDV service, which performs document analysis through either a live video session with an agent (VideoIdent) or a fully automated process (AutoIdent). The service examines document security features, performs face matching and liveness detection, and optionally cross-checks identity data supplied by an upstream step. Results are returned as a unified Verification data block describing the checks applied and the assurance level achieved.

Key features

Agent-assisted verification (VideoIdent): A trained IDnow agent guides the user through document capture and checks security features, face match, and liveness in a live session.
Automated verification (AutoIdent): Fully AI-driven analysis of document authenticity, security features, face matching, and liveness without human involvement.
Pre-fill from upstream steps: Optional inputSources bindings allow identity data collected earlier in the flow to be forwarded to DocIDV for cross-checking.
Unified Verification data block: Produces a structured record describing the checks performed, the provider, and whether the session completed, was canceled, or ended due to fraud.

Configuration

Option	Type	Required	Default	Description
`inputSources`	object	No	—	Maps upstream step IDs to data blocks forwarded to DocIDV. See Input mapping.
`inputSources.basicIdentity`	string	No	—	ID of an upstream step whose `BasicIdentity` output should be forwarded to DocIDV for identity data cross-checking.
`inputSources.extendedIdentity`	string	No	—	ID of an upstream step whose `ExtendedIdentity` output should be forwarded to DocIDV for identity data cross-checking.
`config`	object	Yes	—	Environment-specific configuration.
`config.live.shortname`	string	Yes	—	DocIDV shortname for the environment (live or staging). Provided by IDnow during onboarding. (live)
`config.staging.shortname`	string	Yes	—	DocIDV shortname for the environment (live or staging). Provided by IDnow during onboarding. (staging)
`capture`	object	No	—	Capture configuration for optional output data blocks.
`capture.biometricSample`	boolean	No	`true`	When `false`, the `BiometricSamples` data block is not included in the output.
`capture.documentImages`	boolean	No	`true`	When `false`, the `DocumentImages` data block is not included in the output.
`handoff`	boolean	No	`false`	When `true`, redirects the player immediately when the identification enters a pending review state (`REVIEW_PENDING`, `CHECK_PENDING`, or `FRAUD_SUSPICION_PENDING`) and resumes polling in the background. Uses the session `redirectUrl` if configured; otherwise shows a submission-complete message.
`webJourneyOnly`	boolean	No	`false`	When `true`, the redirect URL returned to the player is constructed as the DocIDV web journey URL (derived from the onboarding base URL, shortname, and identification ID) instead of the channel chooser redirect URL.
`enableRetry`	boolean	No	`false`	When `true`, adds a `retry` output route that can be used to handle user cancellations.

Example configuration

{
  "config": {
    "live": {
      "shortname": "acme-live"
    },
    "staging": {
      "shortname": "acme-staging"
    }
  },
  "inputSources": {
    "basicIdentity": "COLLECT_DATA"
  }
}

Input data blocks

Data block	Required	Description
`BasicIdentity`	No	Identity data forwarded to DocIDV when `inputSources.basicIdentity` is configured. Used for cross-checking against document data.
`ExtendedIdentity`	No	Extended identity data forwarded to DocIDV when `inputSources.extendedIdentity` is configured. Used for cross-checking against document data.

Routes

Route	Description
`verified`	The document was successfully processed and identity data was extracted. The DocIDV service accepted the result — either the automated or agent-assisted analysis passed.
`fraud_detected`	The document was identified as fraudulent. Identity data may have been extracted and is available for manual review.
`retry`	Available only when `enableRetry` is `true`. User cancelled and can retry.

Output data blocks

Route	Data blocks produced
`verified`	`BasicIdentity`, `ExtendedIdentity`, `DocumentData`, `Verification` conditionally: `DocumentImages` (unless `capture.documentImages` is `false`) `BiometricSamples` (unless `capture.biometricSample` is `false`)
`fraud_detected`	`BasicIdentity`, `ExtendedIdentity`, `DocumentData`, `Verification` conditionally: `DocumentImages` (unless `capture.documentImages` is `false`) `BiometricSamples` (unless `capture.biometricSample` is `false`)
`retry`	`Verification` Available only when `enableRetry` is `true`.

info

For Personalausweis flows, documentData.documentNumber is always null.

Step compatibility

The DocumentImages produced by Verifying ID document (v2) are ID-category images (passport, driving licence, etc.). They cannot be used as input to Verifying IBAN - API only (v1) or Verifying proof of address - API only (v1), which require bank or address documents respectively.

`Verification` data block

The Verification data block produced by Verifying ID document (v2) contains the outcome and the checks applied during the DocIDV process.

Field	Type	Description
`status`	string	Verification status. One of: `verified`, `rejected`, `fraudDetected`, `canceled`, `aborted`, `error`.
`provider`	string	Always `"idnow"`.
`trustFramework`	string \| null	Always `null` for DocIDV processes.
`assuranceLevel`	string \| null	Always `null` for DocIDV processes.
`verifiedAt`	string	ISO 8601 timestamp at which the DocIDV process completed.
`verificationProcessId`	string \| null	DocIDV session or transaction reference.
`terminationReason`	object \| null	Present when the process ended before completion. Contains `code` (string) and `message` (string \| null).
`methods`	array	Always contains exactly one entry. Its type is `documentCheck` for standard VideoIdent and AutoIdent processes, or `eid` for Personalausweis processes — see sections below.

`methods[].documentCheck`

For standard VideoIdent and AutoIdent processes, the methods array contains exactly one entry of type documentCheck.

Field	Type	Description
`type`	string	Always `"documentCheck"`.
`checks`	array	Techniques that failed during the process. May contain agent involvement checks on `verified` outcomes for VideoIdent sessions. See below.
`evidence`	array	References to evidence artifacts (e.g. session recordings, analysis reports) stored in the Vault.

Checks

Agent involvement checks (agentInterview, agentReview) are always added when an agent was part of the session — regardless of outcome. A successful session with no agent involvement produces checks: []. A failed or fraud-detected session produces exactly one check entry for the technique that the IDnow DocIDV reason code maps to, with outcome: failed. The agentReview check on the agent-cancel path has outcome: null.

Technique	Reason codes (examples)	Description
`securityFeatures`	`ID_SECURITY_FEATURE`, `WARNING_DIGITAL_DOCUMENT`, `WARNING_FAKED_MANIPULATED_ID`, …	Physical or visual document security element failed.
`documentValidity`	`ID_BROKEN`, `ID_DAMAGED`, `ID_EXPIRED`, `ID_NOT_SUPPORTED`, `WARNING_FAKED_SPECIMEN`, …	Document format, integrity, or validity check failed.
`dataCrosscheck`	`ID_BLURRY`, `ID_DATA`, `ID_WRONG_SIDE`, `WARNING_MANIPULATED_DATA`, …	MRZ/OCR/VIZ reading or data consistency check failed.
`faceMatch`	`SELFIE_BLURRY`, `USER_OBSCURED`, `WARNING_SELFIE_DISGUISED`, …	Portrait-to-live-capture comparison failed.
`liveness`	`WARNING_SELFIE_NO_REAL_PERSON`, `WARNING_SELFIE_REAL_PERSON`	Live person detection failed.
`agentInterview`	—	Added on all VideoIdent (VIDEO process type) sessions; `outcome: null`.
`agentReview`	`WARNING_IDENTITY_THEFT`, `WARNING_FRAUD_OTHER`, `WARNING_MONEY_MULE`	Generic fraud or compliance conclusion raised during agent review.

Reason codes that describe process interruptions (USER_CANCELLATION_*, APP_CANCELLATION_*, TSP_*, PAY_*, IDENT_*) do not produce a check — they populate terminationReason only.

`methods[].eid` (Personalausweis)

When a shortname is configured for a Personalausweis process (via AusweisApp), the Sphinx platform returns processtype: EID upon completion. Verifying ID document (v2) detects this automatically and produces an eid method entry instead of documentCheck. No additional configuration is required.

Field	Type	Description
`type`	string	Always `"eid"`.
`schemeId`	string	Always `"personalausweis"`.
`authority`	string	Always `"Bundesministerium des Innern (BMI)"`.
`countryCode`	string	Always `"DE"`.
`evidence`	array	Contains the analysis report vault reference when a PDF was produced by the process; empty otherwise.
`sessionBinding`	object \| null	Session and subject identifiers from the eID chip. `null` only when the eID protocol was never initiated (e.g. the user cancelled before presenting their card). Present when the protocol was attempted.
`sessionBinding.protocol`	string	The wire protocol used for the eID authentication. Always `"proprietary"` for AusweisApp-based Personalausweis.
`sessionBinding.subjectId`	string \| null	The eID chip pseudonym assigned to the user by AusweisApp. Populated on successful authentication; `null` when the protocol was attempted but failed technically (e.g. card blocked or unreadable).
`sessionBinding.sessionId`	null	The session identifier from the eID protocol. Always `null` for this method.
`sessionBinding.transactionId`	null	The transaction identifier from the eID protocol. Always `null` for this method.
`issues`	array	Present when a technical eID method failure occurred (e.g. card blocked or unreadable). Empty on successful processes and on deliberate user cancellations.

Example payloads

BasicIdentity — verified

{
  "givenName": "Jean",
  "familyName": "Dupont",
  "name": "Jean Dupont",
  "birthDate": "1985-03-22",
  "birthPlace": "Paris"
}

ExtendedIdentity — verified

{
  "portrait": {
    "$ref": "vault",
    "$id": "020ff369-43d8-4b8a-94e7-6814c0bdc35a"
  },
  "nationality": "FR",
  "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

{
  "documentType": "ID",
  "documentNumber": "D123456789",
  "expiryDate": "2030-06-15",
  "issuanceDate": "2020-06-15",
  "issuingCountry": "FR",
  "issuingAuthority": null
}

Verification — verified

{
  "status": "verified",
  "provider": "idnow",
  "trustFramework": null,
  "assuranceLevel": null,
  "verifiedAt": "2026-02-10T14:00:01.000Z",
  "verificationProcessId": "TST-ABCDEF",
  "terminationReason": null,
  "methods": [
    {
      "type": "documentCheck",
      "checks": [],
      "evidence": [
        {
          "type": "document",
          "ref": {
            "$ref": "vault",
            "$id": "7f3a1c2d-9e4b-4f8a-b1d2-3c4e5f607081"
          }
        }
      ]
    }
  ]
}

Verification — fraud_detected

{
  "status": "fraudDetected",
  "provider": "idnow",
  "trustFramework": null,
  "assuranceLevel": null,
  "verifiedAt": "2026-02-10T15:30:22.000Z",
  "verificationProcessId": "TST-XYZFRD",
  "terminationReason": null,
  "methods": [
    {
      "type": "documentCheck",
      "checks": [
        {
          "technique": "securityFeatures",
          "outcome": "failed"
        }
      ],
      "evidence": []
    }
  ]
}

Testing

Before going live, it is important to verify that your integration handles the full range of identification outcomes correctly — from successful verifications to fraud detections, aborts, and review delays.

IDnow provides a Test-Robot service on the TEST environment that simulates the agent side of an identification automatically. This lets you trigger and observe different end-to-end scenarios — such as a happy path, a fraud case, or a canceled ident — and confirm that your application correctly receives and processes the results (e.g. via webhook or API response). Test-Robot is not a replacement for QA engineers, but a tool to validate your integration during development.

Two identification types are supported:

AutoIdent (AI): Fully automated, app-based identification. See the AutoIdent Test-Robot documentation.
VideoIdent (VI): Agent-assisted video identification. See the VideoIdent Test-Robot documentation.

Agent-assisted or automated document-based identity verification via IDnow's DocIDV service​

Key features​

Configuration​

Example configuration​

Input data blocks​

Routes​

Output data blocks​

Verification data block​

methods[].documentCheck​

Checks​

methods[].eid (Personalausweis)​

Example payloads​

Testing​