Signing incl. verifying ID (v2)

Stable / GA

This is the current stable version of this step type. A successor version of this step is in preview / alpha: Signing incl. verifying ID (v3)

Identity verification combined with qualified or contract electronic signature via document-based process.

Combines DocIDV with electronic signature capabilities. Verifies the end user's identity through document analysis and then issues an electronic signature (either QES for qualified signatures under eIDAS or standard contract signing). Results are returned as a unified Verification data block describing the checks applied, the provider, and the assurance level achieved.

Key features

Document-based identity verification: Uses DocIDV to verify identity through document analysis, security feature checks, face matching, and liveness detection.
Qualified Electronic Signature (QES): Issues legally binding signatures under the eIDAS framework with the same legal effect as a handwritten signature. Requires strict identity verification before signature creation.
Contract signing mode: Issues standard electronic signatures on customer-supplied contract documents without QES requirements.
Unified Verification< data block: Produces a structured record describing the identity verification checks performed, the provider, and the trust framework and assurance level achieved.
Signed documents package: Returns the signed documents and audit trail from the signature process.

Configuration

Option	Type	Required	Default	Description
`signingMode`	string	Yes	—	Signing mode: `QES` (Qualified Electronic Signature) or `CONTRACT_SIGNING` (standard contract signing). Accepted values: `CONTRACT_SIGNING`, `QES`.
`inputSources`	object	No	—	Deprecated: use `inputMapping` instead.
`inputSources.basicIdentity`	string	Yes	—	ID of an upstream step whose `BasicIdentity` output provides identity data for verification and signing.
`inputSources.documentsToSign`	string	No	—	ID of an upstream step whose `DocumentsToSign` output provides the documents to sign.
`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 `BiometricSamples` data block is not included in the output.
`capture.documentImages`	boolean	No	`true`	When `false`, the `DocumentImages` data block is not included in the output.
`handoff`	boolean	No	`false`	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.
`webJourneyOnly`	boolean	No	`false`	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.
`enableRetry`	boolean	No	`false`	When `true`, adds a `retry` output route that can be used to handle user cancellations.

Example configuration

QES mode (no contract documents required):

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

Contract signing mode (requires documents):

{
  "signingMode": "CONTRACT_SIGNING",
  "config": {
    "live": {
      "shortname": "acme-live"
    },
    "staging": {
      "shortname": "acme-staging"
    }
  }
}

Deprecated: the legacy inputSources option is retained for backwards compatibility only. New flows must wire inputs via the top-level inputMapping field.

Input data blocks

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

basicIdentity — and documentsToSign in contract signing mode — are input slots wired via the top-level inputMapping field, keyed by slot alias:

"inputMapping": {
  "basicIdentity": "<step-id>",
  "documentsToSign": "<step-id>",
}

File size limit

Each file referenced in DocumentsToSign must not exceed 4 MB.

Routes

Route	Description
`verified`	Identity verification succeeded and documents were signed successfully. Status from the signature service is either SUCCESS or SUCCESS_DATA_CHANGED.
`fraud_detected`	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.
`retry`	Available only when `enableRetry` is `true`. User cancelled and can retry.

Output data blocks

Route	Data blocks produced
`verified`	`BasicIdentity`, `ExtendedIdentity`, `DocumentData`, `Verification`, `SignedDocumentsPackage` 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`)
`retry`	`Verification` Available only when `enableRetry` is `true`.

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

info

For Personalausweis flows, documentData.documentNumber is always null.

`Verification` data block

The Verification data block produced by this step contains the outcome and the checks applied during the identity verification and signature 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 this step. The eIDAS/QES qualification is reflected in `methods[].electronicSignature.signatureType` (`"qes_eidas"` for QES) instead.
`assuranceLevel`	string \| null	Always `null` for this step. The eIDAS/QES qualification is reflected in `methods[].electronicSignature.signatureType` (`"qes_eidas"` for QES) instead.
`verifiedAt`	string	ISO 8601 timestamp at which the verification and signature process completed.
`verificationProcessId`	string \| null	Session or transaction reference from the provider.
`terminationReason`	object \| null	Present when the process ended before completion. Contains `code` (string) and `message` (string \| null).
`methods`	array	Verification methods applied. Contains either a `documentCheck` method and an `electronicSignature` method, or an `eid` method and an `electronicSignature` method (when the underlying process type is EID / Personalausweis).

`methods[].documentCheck`

Describes the identity verification checks performed on the document and user biometrics.

Field	Type	Description
`type`	string	Always `"documentCheck"`.
`checks`	array	Techniques applied during the process. See below.
`evidence`	array	References to evidence artifacts (e.g. liveness recordings, analysis reports) stored in the Vault.

Checks

Checks are reason-driven, not session-type-driven. 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`

When the underlying IDnow process type is EID (Personalausweis), the first method entry is of type eid instead of documentCheck.

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; 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.

`methods[].electronicSignature`

Describes the electronic signature method used and the signature metadata.

Field	Type	Description
`type`	string	Always `"electronicSignature"`.
`signatureType`	string \| null	Signature qualification level from the PAdES certificate. `"qes_eidas"` for QES, `"aes_eidas"` for AES; `null` if absent.
`issuer`	string \| null	QTSP common name from the signing certificate. `null` if not available.
`serialNumber`	string \| null	Signing certificate serial number. `null` if not available.
`issuedAt`	string \| null	ISO 8601 datetime — certificate signing time from the PAdES structure. `null` if not available.
`evidence`	array	References to evidence artifacts (e.g. signed PDFs, PAdES structures) stored in the Vault.

Example payloads

BasicIdentity — verified

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

ExtendedIdentity — verified

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

DocumentData — verified

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

Verification — verified (QES, document-based)

{
  "status": "verified",
  "provider": "idnow",
  "trustFramework": null,
  "assuranceLevel": null,
  "verifiedAt": "2026-02-10T14:00:01.000Z",
  "verificationProcessId": "P12345678",
  "terminationReason": null,
  "methods": [
    {
      "type": "documentCheck",
      "checks": [],
      "evidence": [
        {
          "type": "document",
          "ref": {
            "$ref": "vault",
            "$id": "7f3a1b2c-8d4e-5f6a-9b0c-1d2e3f4a5b6c"
          }
        }
      ]
    },
    {
      "type": "electronicSignature",
      "signatureType": "qes_eidas",
      "issuer": "IDnow QES CA",
      "serialNumber": "0123456789abcdef",
      "issuedAt": "2026-02-10T14:00:00.000Z",
      "evidence": [
        {
          "type": "document",
          "ref": {
            "$ref": "vault",
            "$id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
          }
        }
      ]
    }
  ]
}

Verification — fraud_detected

{
  "status": "fraudDetected",
  "provider": "idnow",
  "trustFramework": null,
  "assuranceLevel": null,
  "verifiedAt": "2026-02-10T15:22:44.000Z",
  "verificationProcessId": "P98765432",
  "terminationReason": null,
  "methods": [
    {
      "type": "documentCheck",
      "checks": [
        {
          "technique": "securityFeatures",
          "sources": [],
          "outcome": "failed",
          "issues": [],
          "performedBy": null,
          "performedAt": null
        }
      ],
      "evidence": []
    }
  ]
}

Signing modes

QES (Qualified Electronic Signature)

Issues legally binding signatures under the eIDAS framework with the same legal effect as a handwritten signature. Requires strict identity verification via document analysis before the signature is created. The Verification data block will have assuranceLevel: null and trustFramework: null — the QES qualification is instead reflected in methods[].electronicSignature.signatureType as "qes_eidas".

CONTRACT SIGNING

Issues standard electronic signatures on customer-supplied contract documents without strict eIDAS requirements. The Verification data block will have assuranceLevel: null and trustFramework: null.

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.

Identity verification combined with qualified or contract electronic signature via document-based process.​

Key features​

Configuration​

Example configuration​

Input data blocks​

Routes​

Output data blocks​

Verification data block​

methods[].documentCheck​

Checks​

methods[].eid​

methods[].electronicSignature​

Example payloads​

Signing modes​

QES (Qualified Electronic Signature)​

CONTRACT SIGNING​

Testing​