Electronic Signature Warnings

An Electronic Signature step raises a warning when a signer can’t or won’t sign: they decline, run out of codes, or can’t be matched to a verified identity, a document no longer matches what they were shown, or a field has no value to pre-fill. Every warning stops that signer’s signature, so no signed document is issued for it, with one exception: SIGNATURE_FIELD_DATA_MISSING set to NO_ACTION lets the signer sign with the field left empty. What the warning does to the verdict is up to you.

Overview

A warning appears in two places:

On the signer’s item of signatures[], as { "code": "SIGNATURE_DECLINED", "node_id": "feature_signature" } in warnings[]. See the Electronic Signature report.
In the session’s activity, tagged with feature SIGNATURE, with its title and description. The console shows it in the session’s Signature tab, and additional_data.signature_id points to the signer.

Each code maps to a rule. Set the rule to DECLINE, REVIEW or NO_ACTION per workflow step, in the console’s Rules tab or in the step’s config. The rule sets the signer’s verdict (Declined, In Review or Approved) and the warning’s severity (error, warning or information). Custom status rules on the step apply after it.

A rule decides the verdict, not whether the documents are signed. NO_ACTION lets the workflow carry on, but the signer still hasn’t signed, except with SIGNATURE_FIELD_DATA_MISSING, where they can sign with the field empty. Check that status is signed before you rely on a signature.

Warnings produced

Code	When it’s raised	Rule and default
`SIGNATURE_DECLINED`	The signer declined to sign. No signed copy is issued and nothing is charged.	`signature_declined_action`, default `REVIEW`
`SIGNATURE_OTP_FAILED`	The signer entered 3 wrong codes, or asked for more than 5 codes.	`signature_otp_failed_action`, default `DECLINE`
`SIGNATURE_NAME_MISMATCH`	KYB: the name declared for the key person doesn’t match their verified name, ignoring case and spacing.	`signature_name_mismatch_action`, default `DECLINE`
`SIGNATURE_IDENTITY_NOT_VERIFIED`	The signer has no approved ID verification with a name, a liveness check in their session isn’t approved, or the ID verification changed after the signer started.	`signature_identity_not_verified_action`, default `DECLINE`
`SIGNATURE_DOCUMENT_CHANGED`	A document no longer matches the SHA-256 recorded when it was shown to the signer.	`signature_document_changed_action`, default `DECLINE`
`SIGNATURE_FIELD_DATA_MISSING`	A required field takes its value from the verified identity, contact or company, or from the session, and that source has no value when the signer starts signing: for example an address field in a session without an address. With `NO_ACTION`, the signer can still sign and the field stays empty, with `value_unavailable_reason: "source_empty"`.	`signature_field_data_missing_action`, default `REVIEW`

The identity and name checks run when the signer asks for their code and again when they enter it, so these warnings appear at that point rather than when the step opens.

Declines can be reopened

SIGNATURE_DECLINED is the only warning a signer can undo. While the signing link is valid, a signer who declined can reopen the step and sign. Reopening clears the signer’s warning and their reading and agreement on each document, so they go through the documents again. The warning leaves the session’s activity once no signer of the step is still declining. Reopening doesn’t reset their code attempts. The other warnings are final for that signer.

Problems the signer sees

These stop the signer without raising a warning. The flow tells them what happened.

Situation	What happens
The signing link expired	The step can’t be opened or completed after `expires_at`. The link lasts `signature_link_validity_days` from when the session was created.
The code expired	Codes last 5 minutes. The signer asks for a new one.
A new code was asked for too soon	The signer waits 60 seconds between codes.
No verified contact	The code goes only to an email or phone verified earlier in the session. Add Email Verification or Phone Verification before the signature step.
A required field is empty	The signer can’t finish a document until every required field on it has a value. The flow shows how many are left and jumps to the first.
A field’s value is refused	A value that breaks its field’s validation, for example too long or not a number, is refused and the flow says why.
The app is too old for fields	A native SDK release without support for fields can’t show a document with fields, and the step shows an error. Documents without fields still work. See The signing experience.

Example

{
  "signatures": [
    {
      "id": "0e6c2a8e-6c2f-4b8e-9a51-3f2f6a7d9b10",
      "node_id": "feature_signature",
      "status": "declined",
      "verdict": "In Review",
      "warnings": [
        { "code": "SIGNATURE_DECLINED", "node_id": "feature_signature" }
      ],
      "declined_at": "2026-11-03T10:41:40.320Z",
      "declined_action": "REVIEW",
      "signed_at": null,
      "certificate": null,
      "timestamp": null,
      "evidence_file": null
    }
  ]
}

The example shows only the fields that change. Every other field of the signature object is still present.

Warning types

Each warning’s severity follows the rule you set. Severities fall into three categories:

Authentication

Verification

Monitoring

Platform

Overview

Warnings produced

Declines can be reopened

Problems the signer sees

Example

Warning types

​Overview

​Warnings produced

​Declines can be reopened

​Problems the signer sees

​Example

​Warning types

​Related

Overview

Warnings produced

Declines can be reopened

Problems the signer sees

Example

Warning types

Related