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 route 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

Option	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

Route	Data blocks produced	Notes
`verified`	`BasicIdentity`, `ExtendedIdentity`, `DocumentData`, `Verification`, `DocumentImages` (conditional), `BiometricSamples` (conditional)	`DocumentImages` and `BiometricSamples` are included unless suppressed by `capture` options.
`fraud_detected`	`BasicIdentity`, `ExtendedIdentity`, `DocumentData`, `Verification`, `DocumentImages` (conditional), `BiometricSamples` (conditional)	Same conditional logic as `verified`.
`cancelled`	`Verification`	Identity data blocks (`BasicIdentity`, `ExtendedIdentity`, `DocumentData`, `DocumentImages`, `BiometricSamples`) populated only on agent-initiated cancellations; absent on user-initiated cancellations.

Step compatibility

The DocumentImages produced by SPHINX:v3 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.

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.

Example payloads

BasicIdentity — verified

{
  "dataBlockId": "019271a0-0000-7000-8000-000000000001",
  "type": "BasicIdentity",
  "givenName": "Jean",
  "familyName": "Dupont",
  "name": "Jean Dupont",
  "birthDate": "1985-03-22",
  "birthPlace": "Paris"
}

ExtendedIdentity — verified

{
  "dataBlockId": "019271a0-0000-7000-8000-000000000002",
  "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": "24 RUE DANTON 35700 RENNES FRANCE",
  "residentStreet": "RUE DANTON",
  "residentHouseNumber": "24",
  "residentHouseName": null,
  "residentCountry": "FR",
  "residentState": "Bretagne",
  "residentCity": "RENNES",
  "residentPostalCode": "35700"
}

DocumentData — verified

{
  "dataBlockId": "019271a0-0000-7000-8000-000000000003",
  "type": "DocumentData",
  "documentType": "ID",
  "documentNumber": "D123456789",
  "expiryDate": "2030-06-15",
  "issuanceDate": "2020-06-15",
  "issuingCountry": "FR",
  "issuingAuthority": "Préfecture de Paris"
}

Verification — verified

{
  "dataBlockId": "019271a0-0000-7000-8000-000000000004",
  "type": "Verification",
  "status": "verified",
  "terminationReason": null,
  "methods": [
    {
      "type": "documentCheck",
      "documentType": "ID",
      "issuingCountry": "FR"
    }
  ],
  "provider": "IDnow",
  "trustFramework": "eidas",
  "assuranceLevel": "high",
  "verifiedAt": "2026-02-10T14:00:01.000Z",
  "verificationProcessId": "txn-abc123"
}

Verification — fraud_detected

{
  "dataBlockId": "019271b0-0000-7000-8000-000000000001",
  "type": "Verification",
  "status": "fraudDetected",
  "terminationReason": {
    "code": "DOCUMENT_FRAUD",
    "message": "Document identified as fraudulent"
  },
  "methods": [
    {
      "type": "documentCheck",
      "documentType": "PASSPORT",
      "issuingCountry": "DE"
    }
  ],
  "provider": "IDnow",
  "trustFramework": null,
  "assuranceLevel": null,
  "verifiedAt": "2026-02-10T15:22:47.000Z",
  "verificationProcessId": "txn-def456"
}

Verification — cancelled

{
  "dataBlockId": "019271c0-0000-7000-8000-000000000001",
  "type": "Verification",
  "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"
}

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)​

Example payloads​