Signing incl. verifying ID (v3)

Preview

DOC_ID_SIGNING:v3 is in preview. The step API is not yet finalised and may change before general availability. Use DOC_ID_SIGNING:v2 for production flows.

Identity verification combined with electronic signature, with cancellation routing (v3)

Extends Signing incl. verifying ID (v2) with an explicit cancelled output route that lets flows handle user-initiated or agent-initiated session cancellations without throwing an error. Use DOC_ID_SIGNING:v3 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 Signing incl. verifying ID (v2) — QES and contract signing modes, document verification, unified Verification data block, signed documents package.
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	Description
`signingMode`	string (enum)	Yes	Signing mode: `QES` (Qualified Electronic Signature) or `CONTRACT_SIGNING` (standard contract signing).
`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.
`inputSources.basicIdentity`	string	Yes	ID of an upstream step whose `BasicIdentity` output provides identity data for verification and signing.
`inputSources.documentsToSign`	string	Conditional	ID of an upstream step whose `DocumentsToSign` output provides the documents to sign. Required when `signingMode` is `CONTRACT_SIGNING`; not required for `QES`.
`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`.
`enableCancellation`	boolean	No	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

QES mode:

{
  "signingMode": "QES",
  "config": {
    "live": { "shortname": "acme-live" },
    "staging": { "shortname": "acme-staging" }
  },
  "inputSources": {
    "basicIdentity": "SPHINX"
  }
}

Contract signing mode:

{
  "signingMode": "CONTRACT_SIGNING",
  "config": {
    "live": { "shortname": "acme-live" },
    "staging": { "shortname": "acme-staging" }
  },
  "inputSources": {
    "basicIdentity": "SPHINX",
    "documentsToSign": "COLLECT_DOCUMENTS"
  }
}

Wiring cancellation routing with a retry prompt

[
  {
    "id": "DOC_ID_SIGNING",
    "type": "DOC_ID_SIGNING:v3",
    "options": {
      "signingMode": "QES",
      "inputSources": { "basicIdentity": "SPHINX" },
      "config": {
        "live": { "shortname": "acme-live" },
        "staging": { "shortname": "acme-staging" }
      }
    },
    "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": "DOC_ID_SIGNING",
        "type": "rollback",
        "rollback": { "maxAttempts": 3 }
      }
    ]
  }
]

Input data blocks

Data block	Required	Mode	Description
`BasicIdentity`	Yes	Both	Identity data from the upstream step (typically DocIDV). Used for verification and as signer identification in the signature process.
`DocumentsToSign`	Conditional	CONTRACT_SIGNING	Documents to sign. Required when `signingMode` is `CONTRACT_SIGNING`; not required for `QES`.

File size limit

Each file referenced in DocumentsToSign must not exceed 20 MB. Exceeding this limit returns HTTP 422 with error code FILE_TOO_LARGE at session creation.

Routes

Route	Condition	Description
`verified`	Always available	Identity verification succeeded and documents were signed successfully. Status from the signature service is either `SUCCESS` or `SUCCESS_DATA_CHANGED`.
`fraud_detected`	Always available	Identity verification failed due to fraud detection. Fraud was detected and confirmed after review. Identity data and verification information may be available for further analysis.
`cancelled`	When `enableCancellation: true`	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`, `SignedDocumentsPackage`, `DocumentImages` (unless `capture.documentImages: false`), `BiometricSamples` (unless `capture.biometricSample: false`)	All blocks populated; signed documents and audit trail returned in `SignedDocumentsPackage`.
`fraud_detected`	`BasicIdentity`, `ExtendedIdentity`, `DocumentData`, `Verification`, `DocumentImages` (unless `capture.documentImages: false`), `BiometricSamples` (unless `capture.biometricSample: false`)	`SignedDocumentsPackage` not produced on the fraud path.
`cancelled`	`Verification`	Identity data blocks populated only when an agent cancelled with a business reason.

Step compatibility

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

Example payloads

BasicIdentity — verified

{
  "dataBlockId": "a10d3bc6-92d7-4aff-9776-3417d4fb7d61",
  "type": "BasicIdentity",
  "givenName": "Jean",
  "familyName": "Dupont",
  "name": "Jean Dupont",
  "birthDate": "1985-03-22",
  "birthPlace": "Paris"
}

ExtendedIdentity — verified

{
  "dataBlockId": "89f5f7a0-433b-4365-808d-0568d5896a7a",
  "type": "ExtendedIdentity",
  "portrait": {
    "$ref": "vault",
    "$id": "01960000-43d8-7000-8000-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": "bf05a1ae-ebc1-4be4-ae1f-dade455b8c5d",
  "type": "DocumentData",
  "documentType": "ID",
  "documentNumber": "D123456789",
  "expiryDate": "2030-06-15",
  "issuanceDate": "2020-06-15",
  "issuingCountry": "FR",
  "issuingAuthority": "Préfecture de Paris"
}

Verification — verified

{
  "dataBlockId": "f191782c-8d19-4fd2-aa48-e40bfce0ae81",
  "type": "Verification",
  "status": "verified",
  "terminationReason": null,
  "methods": [
    {
      "type": "documentCheck",
      "checks": [
        { "checkType": "dataIntegrity", "result": "passed" },
        { "checkType": "documentAuthenticity", "result": "passed" }
      ]
    },
    {
      "type": "electronicSignature",
      "signatureLevel": "QES",
      "signingStatus": "SUCCESS"
    }
  ],
  "provider": "IDnow",
  "trustFramework": "eidas",
  "assuranceLevel": "high",
  "verifiedAt": "2026-02-10T14:00:01.000Z",
  "verificationProcessId": "txn-abc123"
}

SignedDocumentsPackage — verified

{
  "dataBlockId": "419c0f38-e027-4f55-aa16-4d1f3cca5404",
  "type": "SignedDocumentsPackage",
  "package": { "$ref": "vault", "$id": "01960000-7a2b-7000-8000-3f8e91c047d2" }
}

Verification — fraud_detected

{
  "dataBlockId": "8f8f2b04-b4b5-4cae-a582-c85b8950df09",
  "type": "Verification",
  "status": "fraudDetected",
  "terminationReason": {
    "code": "FRAUD_SUSPICION_CONFIRMED",
    "message": "Document fraud confirmed after review"
  },
  "methods": [
    {
      "type": "documentCheck",
      "checks": [{ "checkType": "documentAuthenticity", "result": "failed" }]
    }
  ],
  "provider": "IDnow",
  "trustFramework": "eidas",
  "assuranceLevel": null,
  "verifiedAt": "2026-02-10T14:05:33.000Z",
  "verificationProcessId": "txn-def456"
}

Verification — cancelled

{
  "dataBlockId": "bee4432b-5cef-4f13-87d7-ec24e185b4ea",
  "type": "Verification",
  "status": "canceled",
  "terminationReason": {
    "code": "USER_CANCELLED",
    "message": null
  },
  "methods": [],
  "provider": "IDnow",
  "trustFramework": null,
  "assuranceLevel": null,
  "verifiedAt": "2026-02-10T14:02:15.000Z",
  "verificationProcessId": "txn-ghi789"
}

Relationship to Signing incl. verifying ID (v2)

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

Identity verification combined with electronic signature, with cancellation routing (v3)​

Key features​

Configuration​

Example configuration​

Wiring cancellation routing with a retry prompt​

Input data blocks​

Routes​

Output data blocks​

Example payloads​

Relationship to Signing incl. verifying ID (v2)​