Document ID signing (v2)

Preview

DOC_ID_SIGNING:v2 is in preview. The Verification data block implementation is not yet finalized and may change before general availability.

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

Combines document-based identity verification (Sphinx AutoIdent or VideoIdent) 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 Sphinx (VideoIdent or AutoIdent) 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. (v2 only — v1 produces the legacy DocumentVerification data block instead.)
Signed documents package — Returns the signed documents and audit trail from the signature process.

Step versions

Version	Status	Output verification data block
`DOC_ID_SIGNING:v1`	Current/Stable	`DocumentVerification`
`DOC_ID_SIGNING:v2`	Preview	`Verification`

Use DOC_ID_SIGNING:v1 for all production flows. DOC_ID_SIGNING:v2 is in preview — its implementation is not yet finalized and is not recommended for new flows.

Configuration

Parameter	Type	Required	Description
`signingMode`	string (enum)	Yes	Signing mode: `QES` (Qualified Electronic Signature) or `CONTRACT_SIGNING` (standard contract signing).
`config.live.shortname`	string	Yes	Sphinx shortname for the live environment. Provided by IDnow during onboarding.
`config.staging.shortname`	string	Yes	Sphinx 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 (`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 Sphinx web journey URL (derived from the onboarding base URL, shortname, and identification ID) instead of the channel chooser redirect URL. Default: `false`.
`inputSources`	object	Yes	Maps upstream step IDs to input data blocks. See Input mapping.
`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`.

Example

QES mode (no contract documents required):

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

Contract signing mode (requires documents):

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

Input data blocks

Data block	Required	Mode	Description
`BasicIdentity`	Yes	Both	Identity data from the upstream node (typically Sphinx). 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.

Verdicts

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

Output data blocks

Verdict	Data blocks produced
`verified`	`BasicIdentity`, `ExtendedIdentity`, `DocumentData`, `DocumentImages`, `Verification`, `BiometricSamples`, `SignedDocumentsPackage`
`fraud_detected`	`BasicIdentity`, `ExtendedIdentity`, `DocumentData`, `DocumentImages`, `Verification`, `BiometricSamples`

`Verification` data block (v2)

The Verification data block produced by DOC_ID_SIGNING:v2 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 Trust Services"`.
`trustFramework`	string \| null	Regulatory framework. `"eidas"` when achieving eIDAS compliance (QES); `null` for standard processes.
`assuranceLevel`	string \| null	Identity assurance level achieved. `"high"` for eIDAS-compliant QES processes; `null` for standard modes.
`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 one `documentCheck` method and one `electronicSignature` method.

`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. A successful session 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.
`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[].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.

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: "high" and trustFramework: "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​

Step versions​

Configuration​

Example​

Input data blocks​

Verdicts​

Output data blocks​

Verification data block (v2)​

methods[].documentCheck​

Checks​

methods[].electronicSignature​

Signing modes​

QES (Qualified Electronic Signature)​

CONTRACT_SIGNING​