DocIDV (v2)

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 datablock — Produces a structured record describing the checks performed, the provider, and whether the session completed, was canceled, or ended due to fraud.

Configuration

Parameter	Type	Required	Description
`config.live.shortname`	string	Yes	DocIDV shortname for the live environment. Provided by IDnow during onboarding.
`config.staging.shortname`	string	Yes	DocIDV shortname for the staging environment. Provided by IDnow during onboarding.
`enableRetry`	boolean	No	When `true`, adds a `retry` output route that can be used to handle user cancellations. Defaults to `false`.
`handoff`	boolean	No	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. Default: `false`.
`webJourneyOnly`	boolean	No	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. Default: `false`.
`capture.biometricSample`	boolean	No	When `false`, the biometric sample (selfie) capture step is skipped and the `BiometricSamples` data block is not produced. Default: `true`.
`capture.documentImages`	boolean	No	When `false`, the document image capture step is skipped and the `DocumentImages` data block is not produced. Default: `true`.
`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.

Example

{
  "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 when `enableRetry: true`. User cancelled and can retry.

Output data blocks

Route	Data blocks produced
`verified`	`BasicIdentity`, `ExtendedIdentity`, `DocumentData`, `Verification`, `DocumentImages` (conditional), `BiometricSamples` (conditional)
`fraud_detected`	`BasicIdentity`, `ExtendedIdentity`, `DocumentData`, `Verification`, `DocumentImages` (conditional), `BiometricSamples` (conditional)
`retry`	`Verification`

DocumentImages is included when capture.documentImages is not false (default). BiometricSamples is included when capture.biometricSample is not false (default).

note

For Personalausweis flows, documentData.documentNumber is always null.

`Verification` data block

The Verification data block produced by SPHINX: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

Checks are only present on non-verified outcomes. When the DocIDV service returns a reason code that maps to a specific technique, a single check entry is produced with outcome: failed. Sessions that complete successfully produce no check entries.

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.
`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. SPHINX: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. `protocol` is `"proprietary"`. `subjectId` is the eID chip pseudonym returned by AusweisApp. `sessionId` and `transactionId` are `null`. `null` on aborted or canceled flows.
`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.

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​

Input data blocks​

Routes​

Output data blocks​

Verification data block​

methods[].documentCheck​

Checks​

methods[].eid (Personalausweis)​