Electronic Signature

Electronic Signature lets the person you just verified sign your documents in the same flow. They go through each document, add their signature, initials and any data you ask for, and confirm with a one-time code sent to the email or phone they verified earlier. Didit returns each document signed with an advanced electronic signature (AES), plus an evidence PDF that ties the signature to the verified identity. It works for User Verification (KYC), where the verified person signs, and for Business Verification (KYB), where the company’s legal representatives or key people sign on its behalf.

Signature levels

Level	Availability	What it is
AES, advanced electronic signature	Available	Each document is signed in PAdES, the PDF signature format, with a long-term validation profile (`PAdES-B-LT`): the signature carries a trusted timestamp and the revocation data needed to validate it later. It’s uniquely linked to the signer through their verified identity and the one-time code they confirmed, and any change to the document after signing breaks it.
QES, qualified electronic signature	Coming soon	Signed with a qualified certificate issued to the signer. The console shows the option as Coming soon, and saving `signature_level: "qes"` through the API returns `400` with `qes_provider_not_configured`.

AES signs in PAdES only. The signature_format values xades and cades are refused for AES with signature_format_not_supported.

How it works

The workflow verifies the signer first

The signature step runs after the steps that establish who is signing: ID Verification, and Email or Phone Verification for the contact the code goes to. See Before you start.

Didit prepares the documents

When the signer reaches the step, Didit copies the documents and their fields into the session and records each document’s SHA-256. Later changes to the workflow can’t change what this signer sees.

The signer goes through each document

For a document with fields, the signer is guided from field to field. They adopt a signature once and it’s applied to every signature and initials field, and they fill in text and checkbox fields. Values Didit takes from the verified identity, the session or your system are already on the page. For a document without fields, they read it and agree to it.

The signer confirms with a code

When any document has fields, the signer first agrees to sign the documents electronically. Didit then sends a six-digit code to the email or phone they verified earlier in the session. Entering it authorizes the signature on every document in the step.

Didit signs and seals

Didit fills in the date signed, stamps every field value into each PDF, appends the evidence page, then applies the PAdES signature and timestamp, so the signature covers everything on the page.

You get the results

The decision and the session webhooks carry signatures[] with the signer, the confirmation, the certificate, the timestamp, each document’s hashes and every field’s value. You download the signed PDFs and the evidence PDF, and Didit can email the signer a copy.

Before you start

The signer must be verified before they can sign. Didit takes their name and contact from the session’s own verified records, never from what you or the signer type in. For User Verification (KYC), put these steps before Electronic Signature in the workflow:

ID Verification, approved, with a readable name. Without it, the step records SIGNATURE_IDENTITY_NOT_VERIFIED.
Email Verification when the code goes by email (the default), or Phone Verification when it goes by SMS. The code is only sent to a contact verified in the same session.
If the workflow also has Liveness, it must be approved.

To email the signer a copy of the signed documents, the session also needs a verified email, even when the code goes by SMS. For Business Verification (KYB), the signers are the company’s key people, each with their own approved KYC:

`signature_signer`	Who signs
`legal_representative`	Every key person with the role `representative` or `authorized_signatory`
`key_people`	Every individual key person with a KYC session

A KYB step has between 1 and 20 signers, and each one needs an approved KYC by the time they sign. Each one signs their own copy of the documents and confirms with a code sent to the contact verified in their own KYC session. The name declared for the key person must match their verified name, ignoring case and spacing, or the step records SIGNATURE_NAME_MISMATCH. The step finishes once every signer has signed or declined.

Documents

Where the documents come from

signature_documents_source sets where a step gets its documents:

Value	Documents
`workflow` (default)	The documents you uploaded to the workflow in the console. Every session signs the same ones.
`session`	The documents you send in `sign.documents` when you create the session. Each session signs its own.
`both`	The workflow documents first, then the session’s documents.

Per-session documents are the way to have a person sign a contract with their own name, amount or terms already filled in by your system.

Supported files

	Limit
PDF	Up to 20 MB and 100 pages each. No password, scripts or attached files.
Word (`.docx`)	Up to 20 MB. Converted to PDF when you upload it or create the session, and the converted PDF has the same limits as a PDF. `.doc`, `.docm`, `.odt` and `.rtf` files are refused with `unsupported_type`.
Per signer	Up to 20 documents and 50 MB in total.

When you upload a Word document, Didit converts it to PDF while the upload runs, in at most 60 seconds. The converted pages are what the signer sees and signs, so check them before you place fields: line breaks can differ slightly from Word. The Word file and its PDF belong to the same document and are deleted with it. The evidence PDF records the conversion and the SHA-256 of both files. Didit refuses a Word file with signature_document_not_supported and a reason when what would be signed is ambiguous: it has macros (macros), unaccepted tracked changes (tracked_changes), links to external content (external_links) or embedded objects (embedded_objects). Accept or reject tracked changes before you upload, so the PDF shows the text you agreed. A file that can’t be converted is refused with signature_document_conversion_failed and one of these reasons:

`reason`	What went wrong
`docx_password_protected`	The file has a password. Remove it and upload again.
`docx_unreadable`	The file isn’t a readable Word document.
`docx_too_many_pages`	The converted PDF has more than 100 pages.
`docx_too_large`	The file is too large to convert.
`conversion_timeout`	The conversion took too long. Try again, or upload the document as a PDF.

Fields on the document

Fields turn a document into a template the signer fills in, the way you would prepare an envelope in a desktop signing tool. A document without fields keeps the simpler flow: the signer reads it and agrees.

Type	What the signer does	Value
`signature`	Taps it to apply their adopted signature. The first signature or initials field opens the step where they adopt it.	`true` once applied
`initials`	Taps it to apply their adopted initials.	`true` once applied
`text`	Types a value, checked against the field’s validation. It can be pre-filled.	String
`checkbox`	Ticks or unticks it. A required checkbox must be ticked.	Boolean
`email`	Nothing when the session has a verified email, which fills it read-only. Otherwise types it.	String
`full_name`	Nothing: Didit fills in the verified name, read-only.	String
`date_signed`	Nothing: Didit fills in the date the documents are signed.	String
`data`	Nothing: Didit fills in a value from the verified identity, the session or your system, read-only. Set where it comes from in `prefill`.	String

There’s no date picker in this version. Use a text field for a date the signer enters. A field has these properties:

Property	Rules
`id`	Set by Didit.
`key`	Names the field in the results and in `sign.field_values`. Lowercase letters, digits and underscores, starting with a letter, up to 64 characters (`^[a-z][a-z0-9_]{0,63}$`), and unique within the document.
`type`	One of the types above.
`role`	Who fills it, with the values of `signature_signer`: `verified_person`, `legal_representative` or `key_people`. On a session document it defaults to the step’s signer.
`page`	From 1 to the document’s page count. For a Word document, a page of the converted PDF.
`x`, `y`, `width`, `height`	Fractions of the page as it’s displayed (from `0` to `1`), measured from the top-left corner and rounded to 4 decimals. The field must fit inside the page. It’s at least `0.02` wide and `0.012` high, and a signature at least `0.12` by `0.035`.
`required`	`signature` and `initials` are required unless you set `false`. `full_name`, `date_signed` and `data` are always required.
`label`	1 to 80 characters, shown to the signer and in the results.
`placeholder`	`text` and `email` only. Up to 80 characters.
`position`	The order the signer is guided in, from `0`. Didit sets it from where the field sits: by page, then top to bottom, then left to right.
`validation`	`text` only. See Validation.
`prefill`	Where the value comes from. See Pre-filled values.
`editable_when_prefilled`	`text` and `email` only: the signer can change a pre-filled value. Default `false`.
`checked_by_default`	`checkbox` only: the box starts ticked.
`date_format`	`date_signed` only: `DD/MM/YYYY` (default), `MM/DD/YYYY`, `YYYY-MM-DD` or `D MMMM YYYY`.

{
  "id": "6a2f1c0e-4d8b-4f5e-9a51-0c7b2e9d3f10",
  "key": "occupation",
  "type": "text",
  "role": "verified_person",
  "page": 1,
  "x": 0.34,
  "y": 0.4618,
  "width": 0.57,
  "height": 0.0325,
  "required": true,
  "label": "Occupation",
  "placeholder": "For example, nurse",
  "position": 5,
  "validation": { "kind": "any", "min_length": 0, "max_length": 80, "pattern": null, "message": null },
  "prefill": null,
  "editable_when_prefilled": false,
  "checked_by_default": false,
  "date_format": null
}

A document takes up to 200 fields, and one signer up to 500 across their documents. A step fills and stamps only the fields of its own signer. A document can carry fields for several roles only when several Signature steps of the workflow use it: each step fills the fields of its own role and leaves the others empty on its copy. A field for a role that no Signature step of the workflow uses is refused with role_not_used. Every role that has fields on a document needs at least one signature or initials field there, or the workflow version can’t be published (signature_field_missing).

Validation

validation applies to text fields:

{ "kind": "any", "min_length": 0, "max_length": 80, "pattern": null, "message": null }

kind: any; letters (letters in any script, spaces, hyphens and apostrophes); number (digits with an optional decimal separator); email; or pattern.
min_length: from 0 up to max_length.
max_length: from 1 to 500. Default 120.
pattern: required with kind: "pattern". A regular expression of up to 200 characters that the whole value must match. Lookarounds and backreferences aren’t supported.
message: up to 120 characters, shown instead of the default error.

The console preview, the signing flow and the API apply the same rules.

Pre-filled values

prefill names the source of a field’s value:

`prefill`	Value
`identity.full_name`, `identity.first_name`, `identity.last_name`	The name as on the signer’s verified ID.
`identity.date_of_birth`	From the verified ID, as `DD/MM/YYYY`.
`identity.nationality`, `identity.document_number`, `identity.document_type`, `identity.issuing_country`	From the verified ID.
`identity.address`	The formatted address from the verified ID, or from a proof of address in the same session.
`contact.email`, `contact.phone`	The signer’s verified email or phone.
`company.name`, `company.registration_number`, `company.address`, `company.country`	The verified company, for KYB.
`session.vendor_data`	The session’s `vendor_data`.
`metadata.<key>`	The value of `<key>` in the session’s `metadata`, as a string.
`api.<key>`	The value of `<key>` in `sign.field_values`, sent when you create the session.

A data field must have a prefill. A full_name field always uses identity.full_name and an email field uses contact.email, and a text field can have one too. The values of data, full_name and verified email fields are fixed when the signer starts signing: later changes to the session don’t change them. A pre-filled text or email field is read-only unless you set editable_when_prefilled. When a required field’s source has no value at that point, for example a session without an address, the field isn’t shown empty. The step raises SIGNATURE_FIELD_DATA_MISSING and applies signature_field_data_missing_action (default REVIEW). With NO_ACTION, the signer can still sign and the field stays empty.

Set it up in the console

Go to Workflows, open a workflow and add the Electronic signature step after the steps that verify the signer.
In Documents, select Upload to add PDF or Word files, and drag them into the order the signer sees them. Word files are converted to PDF: check the converted pages before you place fields. Replace swaps a document’s file and keeps its fields, except those on pages the new file no longer has.
Under Place fields on the documents, select Open editor. Drag a field from the palette onto the page, or select it and click where it goes, then move and resize it. For each field, set Who fills it, its label, whether it’s Required, what it accepts, where its value comes from and its API key (the field’s key). Preview as signer shows the document as the signer sees it on a phone or a desktop. The editor saves as you go (Saved to draft) and lists what to fix before you select Done.
Still in Documents, choose where documents come from: This workflow, Each session or Both. For documents without fields, choose whether the signer must Read to the end before signing and give One consent per document.
In Signature, choose the Signer, the Level (Advanced (AES)), the Format and where the code goes (One-time code by).
In Rules, set what each warning does to the verdict.
In Advanced, choose whether to Email the signed copy and Add an evidence page, and how many days the signing link stays valid. You can also add custom status rules.
Save the workflow.

To configure the same step through the API, see Workflow feature configs. Workflow documents and their fields are managed in the console; through the API, send documents and fields per session.

The signing experience

The signing step runs in the hosted verification page, the Web SDK and the native SDKs, on desktop and on phones. You don’t need to build any signing UI.

Intro. The signer sees the documents they’re about to sign.
Each document, in order. For a document with fields, the signer is guided through its fields in position order. The first signature or initials field opens a sheet where they adopt a signature. Optional fields are marked Optional. Values Didit filled in show on the page with a lock and aren’t steps. Tapping a field on the page jumps to it. On a phone, one field at a time shows in a panel that stays above the keyboard. On a screen at least 1200 px wide, the page sits beside the list of fields. Finishing a document with a required field still empty shows how many are left and jumps to the first. A document without fields is read and agreed to, as you configured.
Review. The signer sees the documents again and, when any of them has fields, agrees to sign them electronically.
Code. The signer asks for their code. It’s valid for 5 minutes, a new one can be sent after 60 seconds, and a signer gets up to 5 codes and 3 wrong attempts. Running out records SIGNATURE_OTP_FAILED.
Signed. After signing, the signer can download their signed documents. If you enabled it, Didit also emails them a copy.
Decline. The signer can decline instead of signing. This records SIGNATURE_DECLINED. A decline can be reopened while the signing link is valid, so the signer can still sign if they change their mind.

The flow tells the signer when their code expired, a document changed, signing failed or the signing link expired. The signing link stays valid for signature_link_validity_days (1 to 30, default 7), counted from when the session was created. The session stays open at least that long.

Native SDKs show the signing step starting with the release that adds it, listed in the native SDK overview when it ships. Documents with fields need a release that supports fields: an older release can’t show them, and the step shows an error instead. Documents without fields work in every release with the signing step. Until your app runs a release that supports what your workflow uses, send people to the hosted page or the Web SDK.

Adopting a signature

The signer adopts their signature and initials once, in one sheet, the first time a document asks for either:

Typed: their verified name in a handwriting style they choose, marked From your ID. They can’t type a different name. Typed initials are the first letters of that name.
Drawn: drawn with a finger or a mouse, both the signature and the initials.

Every later signature or initials field applies with one tap, and tapping an applied one takes it off again.

Results

Each signer’s result is an item of signatures[] in the session decision and in the decision of session webhooks. There is no separate signature webhook: the session’s status.updated event tells you when to fetch the decision. You get the signed PDF of every document, an evidence PDF for each signer, and the SHA-256 of every original and signed file, so you can prove later that nothing changed. For documents with fields, you also get every field’s value, where it came from and when it was filled, plus the adopted signature and when the signer agreed to sign electronically. See the Electronic Signature report for every field, the downloads and how to validate a signature again. In the console, the session’s Signature tab shows the documents, then a Fields block with a preview of each page, the adopted signature and initials, and every field’s value, time and source. The PDF report includes a signature section, and an Electronic signature · fields page when the documents have fields.

Pricing

Electronic Signature is charged once per signed session, whatever the number of documents, signers or signature steps it has. A signature that is declined, fails or expires is not charged.

Deleting signature data

When you delete a session, its signature data is deleted with it: the documents sent with the session and their original Word files, the copies prepared for each signer, the signed PDFs, the evidence PDFs, the adopted signature and initials images, and every field value. Their download links stop working. The same happens when a session is deleted at the end of your data retention period. Deletion can’t be undone, so download anything you need to keep first.

The signed documents of a Business Verification belong to the company’s session. Deleting that session deletes them.
Removing a document from a workflow deletes it, with its fields and its original Word file. A signer who already started signing keeps the copy they were shown, as part of their session, until you delete that session. Remove documents only from workflows with no sessions waiting to be signed.
A copy Didit already emailed to the signer is in their mailbox and isn’t affected.

Electronic Signature report: signatures[], the signed PDF, the evidence PDF and downloads.
Electronic Signature warnings: every warning and the rule that controls it.
Create session: send documents, fields and field values per session.
Workflow feature configs: every setting of the step.

Authentication

Verification

Monitoring

Platform

Signature levels

How it works

Before you start

Documents

Where the documents come from

Supported files

Fields on the document

Validation

Pre-filled values

Set it up in the console

The signing experience

Adopting a signature

Results

Pricing

Deleting signature data

​Signature levels

​How it works

​Before you start

​Documents

​Where the documents come from

​Supported files

​Fields on the document

​Validation

​Pre-filled values

​Set it up in the console

​The signing experience

​Adopting a signature

​Results

​Pricing

​Deleting signature data

​Related

Signature levels

How it works

Before you start

Documents

Where the documents come from

Supported files

Fields on the document

Validation

Pre-filled values

Set it up in the console

The signing experience

Adopting a signature

Results

Pricing

Deleting signature data

Related