Verifying ID document (v3)

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 (v2)

Agent-assisted or automated document-based identity verification via IDnow's DocIDV service, with cancellation routing

This version extends Verifying ID document (v2) with an explicit cancelled output route that lets flows handle user-initiated or agent-initiated session cancellations without throwing an error. Use this step type version, when you want to route cancelled sessions to a Retry prompt (v1) step or to a rejection step, rather than relying on the generic error path.

Key features

All capabilities of Verifying ID document (v2) — VideoIdent, AutoIdent, Personalausweis (eID), handoff, pre-fill from upstream steps.
Explicit cancellation routing: When enableCancellation: true, cancelled sessions exit via the cancelled route, enabling flow-level handling (retry prompts, rejection paths). When false (the default), the session immediately aborts with an ABORTED outcome.
Configurable capture: Selectively disable biometric sample or document image capture to reduce data collection scope.

Configuration

Option	Type	Required	Default	Description
`inputSources`	object	No	—	Maps upstream step IDs to data blocks forwarded to DocIDV for cross-checking. See Input mapping.
`inputSources.basicIdentity`	string	No	—	ID of an upstream step whose `BasicIdentity` output should be forwarded for identity data cross-checking.
`inputSources.extendedIdentity`	string	No	—	ID of an upstream step whose `ExtendedIdentity` output should be forwarded 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 biometric sample (selfie) capture step is skipped and the `BiometricSamples` data block is not produced.
`capture.documentImages`	boolean	No	`true`	When `false`, the document image capture step is skipped and the `DocumentImages` data block is not produced.
`handoff`	boolean	No	`false`	When `true`, redirects the player immediately when the identification enters a pending review state 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 is constructed as the DocIDV web journey URL instead of the channel chooser URL.
`enableCancellation`	boolean	No	`false`	When `true`, cancelled sessions (user-initiated or agent-initiated) exit via the `cancelled` route. Must be `true` to use the `cancelled` route. When `false` or absent (default), the session immediately ends with an `ABORTED` outcome instead.

Example configuration

{
  "config": {
    "live": {
      "shortname": "acme-live"
    },
    "staging": {
      "shortname": "acme-staging"
    }
  },
  "webJourneyOnly": true
}

Input data blocks

Data block	Required	Description
`BasicIdentity`	No	Forwarded to DocIDV when `inputSources.basicIdentity` is configured.
`ExtendedIdentity`	No	Forwarded to DocIDV when `inputSources.extendedIdentity` is configured.

Routes

Route	Description
`verified`	Document successfully processed; identity data extracted.
`fraud_detected`	Document identified as fraudulent; identity data available for review.
`cancelled`	Available only when `enableCancellation` is `true`. User or agent cancelled; the end user can be routed to retry or a different step. Identity data blocks (`BasicIdentity`, `ExtendedIdentity`, `DocumentData`, `DocumentImages`, `BiometricSamples`) are only included for agent cancellation.

Wire Cancellation with Retry prompt (v1)

In case of cancellation - triggered by enduser or by agent - we recommend connecting this route to the Retry prompt (v1). So that the user may confirm to retry and go through the step again.

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`)
`cancelled`	`Verification` Available only when `enableCancellation` is `true`.

info

For Personalausweis flows, documentData.documentNumber is always null.

Step compatibility

The DocumentImages produced by this step 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. Empty on `verified` outcomes. 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.

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 DocIDV platform returns processtype: EID upon completion. This step 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.

Usage name vs birth name

Some users have two surnames: a usage name (e.g. a married surname) and a birth name. The Sphinx identification result carries them as two separate fields, mapped as follows:

Scenario	`basicIdentity.familyName`	`extendedIdentity.familyNameBirth`
Birth name present	Usage name (`lastname`)	Birth name (`birthname`)
No birth name	`lastname`	`null`

tip

Always use basicIdentity.familyName for identity comparison. It always reflects the name the user currently uses, regardless of whether they have changed their surname.

Example payloads

BasicIdentity — verified (no usage name)

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

BasicIdentity — verified (usage name present)

{
  "givenName": "Marie",
  "familyName": "Martin",
  "name": "Marie Martin",
  "birthDate": "1990-06-15",
  "birthPlace": "Lyon"
}

In this case the identification result contained lastname: "Martin" (usage name) and birthname: "Dupont" (birth name, surfaced in extendedIdentity.familyNameBirth).

ExtendedIdentity — verified

{
  "portrait": {
    "$ref": "vault",
    "$id": "020ff369-43d8-4b8a-94e7-6814c0bdc35a"
  },
  "nationality": "FRA",
  "personalAdministrativeNumber": null,
  "familyNameBirth": "Dupont",
  "givenNameBirth": null,
  "sex": 1,
  "emailAddress": null,
  "mobilePhoneNumber": null,
  "residentAddress": "24 RUE DANTON RENNES 35700 FRANCE",
  "residentStreet": "RUE DANTON",
  "residentHouseNumber": "24",
  "residentHouseName": null,
  "residentCountry": "FR",
  "residentState": "Bretagne",
  "residentCity": "RENNES",
  "residentPostalCode": "35700"
}

familyNameBirth is populated only when the identification result contains a birth name. When no birth name is returned, familyNameBirth is null.

DocumentData — verified

{
  "documentType": "ID",
  "documentNumber": "D123456789",
  "expiryDate": "2030-06-15",
  "issuanceDate": "2020-06-15",
  "issuingCountry": "FR",
  "issuingAuthority": "Préfecture de Paris"
}

Verification — verified

{
  "status": "verified",
  "terminationReason": null,
  "methods": [
    {
      "type": "documentCheck",
      "checks": [],
      "evidence": []
    }
  ],
  "provider": "idnow",
  "trustFramework": "eidas",
  "assuranceLevel": "high",
  "verifiedAt": "2026-02-10T14:00:01.000Z",
  "verificationProcessId": "txn-abc123"
}

Verification — fraud_detected

{
  "status": "fraudDetected",
  "terminationReason": {
    "code": "DOCUMENT_FRAUD",
    "message": "Document identified as fraudulent"
  },
  "methods": [
    {
      "type": "documentCheck",
      "checks": [],
      "evidence": []
    }
  ],
  "provider": "idnow",
  "trustFramework": null,
  "assuranceLevel": null,
  "verifiedAt": "2026-02-10T15:22:47.000Z",
  "verificationProcessId": "txn-def456"
}

Verification — cancelled

{
  "status": "canceled",
  "terminationReason": {
    "code": "USER_CANCELLED",
    "message": null
  },
  "methods": [],
  "provider": "idnow",
  "trustFramework": null,
  "assuranceLevel": null,
  "verifiedAt": "2026-02-10T16:05:33.000Z",
  "verificationProcessId": "txn-ghi789"
}

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, with cancellation routing​

Key features​

Configuration​

Example configuration​

Input data blocks​

Routes​

Output data blocks​

Verification data block​

methods[].documentCheck​

Checks​

methods[].eid (Personalausweis)​

Usage name vs birth name​

Example payloads​

Testing​