Document ID signing (v2)

Preview

DOC_ID_SIGNING:v2 is in preview. The Verification datablock 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 datablock 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 datablock — 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 datablock instead.)
Signed documents package — Returns the signed documents and audit trail from the signature process.

Step versions

Version	Status	Output verification datablock
`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.
`inputSources.basicIdentity`	string	Yes	ID of an upstream step whose `BasicIdentity` output provides identity data for verification and signing.
`inputSources.documentsToSign`	string	Yes*	ID of an upstream step whose `DocumentsToSign` output provides the documents to sign. Required when `signingMode` is `CONTRACT_SIGNING`.
`templateIds`	string array	No	Optional array of template IDs to apply to the documents during signing.

* Required when signingMode is CONTRACT_SIGNING. Not needed for QES mode.

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 datablocks

Data block	Required	Description
`BasicIdentity`	Yes	Identity data from the upstream node (typically Sphinx). Used for verification and as signer identification in the signature process.
`DocumentsToSign`	Yes*	Documents to sign. Required when `signingMode` is `CONTRACT_SIGNING`. Omitted for `QES` mode.

* Required when signingMode is CONTRACT_SIGNING.

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 datablocks

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

`Verification` datablock (v2)

The Verification datablock 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 `"docIdSigning"`.
`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 datablock will have assuranceLevel: "high" and trustFramework: "eidas".

CONTRACT_SIGNING

Issues standard electronic signatures on customer-supplied contract documents without strict eIDAS requirements. The Verification datablock 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 datablocks​

Verdicts​

Output datablocks​

Verification datablock (v2)​

methods[].documentCheck​

Checks​

methods[].electronicSignature​

Signing modes​

QES (Qualified Electronic Signature)​

CONTRACT_SIGNING​