DocIDV (v3)

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

Extends DocIDV (v2) with an explicit cancelled output route that lets flows handle user-initiated or agent-initiated session cancellations without throwing an error. Use SPHINX:v3 when you want to route cancelled sessions to a RETRY_PROMPT:v1 step or to a rejection end node, rather than relying on the generic error path.

Key features

All capabilities of DocIDV (v2) — VideoIdent, AutoIdent, Personalausweis (eID), handoff, pre-fill from upstream steps.
Explicit cancellation routing — Cancelled sessions always exit via the cancelled port instead of throwing, enabling flow-level handling (retry prompts, rejection paths).
Configurable capture — Selectively disable biometric sample or document image capture to reduce data collection scope.

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.
`handoff`	boolean	No	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. Default: `false`.
`webJourneyOnly`	boolean	No	When `true`, the redirect URL is constructed as the DocIDV web journey URL instead of the channel chooser 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 for cross-checking.
`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.

Example

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

Wiring cancellation routing with a retry prompt

[
  { "id": "SPHINX", "type": "SPHINX:v3",
    "options": { ... },
    "next": [
      { "port": "verified",   "id": "END_ACCEPTED" },
      { "port": "fraud_detected", "id": "END_REJECTED" },
      { "port": "cancelled",  "id": "RETRY_PROMPT" }
    ]
  },
  { "id": "RETRY_PROMPT", "type": "RETRY_PROMPT:v1", "options": {},
    "next": [
      { "port": "retry",   "id": "SPHINX", "type": "rollback", "rollback": { "maxAttempts": 3 } }
    ]
  }
]

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	Condition	Description
`verified`	Always available	Document successfully processed; identity data extracted.
`fraud_detected`	Always available	Document identified as fraudulent; identity data available for review.
`cancelled`	Always available	Session cancelled by the user or agent. Carries a `Verification` data block; identity data blocks present only on agent-initiated cancellations.

Output data blocks

The verified and fraud_detected routes always produce BasicIdentity, ExtendedIdentity, DocumentData, and Verification. DocumentImages and BiometricSamples are included unless suppressed by capture options.

The cancelled route always carries Verification. Identity data blocks (BasicIdentity, ExtendedIdentity, DocumentData, DocumentImages, BiometricSamples) are populated only when an agent cancelled with a business reason; on user-initiated cancellations they are absent.

Relationship to DocIDV (v2)

SPHINX:v3 is a superset of SPHINX:v2. Existing SPHINX:v2 flows do not need to migrate — use SPHINX:v3 for new flows that require explicit cancellation handling.

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

Key features​

Configuration​

Example​

Wiring cancellation routing with a retry prompt​

Input data blocks​

Routes​

Output data blocks​

Relationship to DocIDV (v2)​