Using QES with the API

Send documents for Qualified Electronic Signature (QES) using Signable’s envelope API. Add QES fields to identify which signers need to apply a qualified signature to each document. Signable then manages the signing and identity-verification journey.

A QES field includes a visible signature, but completing that field is only part of the process. The signer must also complete the QES verification and signing step before the envelope can finish.

You need:

• A Signable account enabled for QES. API access alone does not confirm QES availability.

• An API key for the account sending the envelope.

• Enough available QES credits for the whole envelope.

• A PDF containing QES tags, or a template with QES fields assigned to the appropriate signer roles.

For QES enablement and additional credits, contact your Signable account contact. Confirm the available purchasing route with Signable. Confirm the test-key setup with Signable before testing; the general API test-key documentation does not establish a QES sandbox journey.

Keep API credentials on your server. Use the portal’s authentication instructions to configure your requests.

For an eligible company, use GET /settings to read setting_qes_enabled and PUT /settings to change it. This setting is not available to sub-accounts and does not itself confirm that QES is currently available for use. Alternatively, you can toggle QES availability in the Signable app's company settings.

Choose the approach that suits your documents:

The QES requirement comes from the fields on each document. A document can contain both ordinary signature fields and QES fields. Only the signers assigned QES fields need to complete the QES step for that document.

Place this tag where you want the signer’s visible signature to appear:

{qes:signer1:Your+Signature}

Keep the tag on one line, use lowercase for the field type and role, and replace spaces in the label with +. See Signable tags for general tag guidance.

For a document where one person needs QES and another needs an ordinary signature, use:

{qes:signer1:Customer+Signature}
{signature:signer2:Company+Signature}

For uploaded documents, field placement is defined by tags in the PDF; there is no separate field-definition parameter in the upload request.

Check signer assignment carefully. In these examples, use exactly the same role name in the tag and request. A QES field that is left unassigned can be ignored while the envelope still sends. A successful create response therefore does not prove that the intended signer will complete QES. Verify the processed fields and their assignments before relying on your integration.

Use the existing envelope endpoint:

POST https://api.signable.co.uk/v1/envelopes

This example uses a PDF containing {qes:signer1:Your+Signature}:

{
  "envelope_title": "Agreement requiring QES",
  "envelope_parties": [
    {
      "party_name": "Alex Morgan",
      "party_email": "alex@example.com",
      "party_role": "signer1"
    }
  ],
  "envelope_documents": [
    {
      "document_title": "Agreement",
      "document_file_name": "agreement.pdf",
      "document_file_content": "REPLACE_WITH_BASE64_ENCODED_TAGGED_PDF"
    }
  ]
}

Replace the sample recipient and document content before sending. The signer supplies their mobile details during the QES journey. The example follows the existing public send contract; it does not add an unverified QES-specific mobile parameter.

Uploaded documents process asynchronously. Store the returned envelope fingerprint and retrieve the envelope after processing. See sending an uploaded document.

Configure the QES fields in your template, then retrieve its details:

GET https://api.signable.co.uk/v1/templates/{template_fingerprint}

Use the template’s actual party identifier to map the recipient to the role with the QES fields:

{
  "envelope_title": "Template agreement requiring QES",
  "envelope_parties": [
    {
      "party_name": "Alex Morgan",
      "party_email": "alex@example.com",
      "party_id": "REPLACE_WITH_TEMPLATE_PARTY_ID",
      "party_role": "signer"
    }
  ],
  "envelope_documents": [
    {
      "document_title": "Agreement",
      "document_template_fingerprint": "REPLACE_WITH_TEMPLATE_FINGERPRINT"
    }
  ]
}

The template supplies the QES field placement. See sending with a template for role mapping and other request options.

Retrieve the envelope using its fingerprint:

GET https://api.signable.co.uk/v1/envelopes/{envelope_fingerprint}

QES fields are identified by field_type: "qes", as described in the API guide. Check that the intended document has QES fields and that they are assigned to the intended signer. The same field type identifies QES fields in template responses.

Do not use a successful POST response, the presence of a tag in your source PDF, or the visible signature alone as evidence that qualified signing has completed.

Sending a draft QES envelope through POST /envelopes/{envelope_fingerprint}/send reserves the required QES credits. Its envelope_qes response includes the QES field and credit summary, plus credits_remaining when the balance is available. If the credits cannot be reserved, the endpoint returns 403 Forbidden. credits_remaining is not available for sub-accounts.

You can cancel a QES envelope while it is being signed through PUT /envelopes/{envelope_fingerprint}/cancel. This releases the QES credit reservations for unconsumed credits. Where QES is available, the cancellation response includes the envelope_qes summary and the remaining balance when available.

The signing journey has two stages:

1. Complete the document. Recipients fill in their assigned fields, including visible signatures.

2. Complete QES signing. Once document fields are complete, Signable prepares the document and takes each required QES signer through verification and qualified signing using Evrotrust. Depending on when they finish the first stage, they may continue in the same session or return through an email link.

QES signers are processed sequentially, including when the envelope’s initial field-completion stage uses parallel signing. This allows each qualified signature to be added while preserving earlier signatures.

Signers need a mobile phone, the Evrotrust app and a supported identity document. Confirm supported countries and identity documents with Signable for your use case.

Your integration should allow for this additional step. Do not show the envelope as complete simply because its visible fields have been filled in or a signer has returned to your application.

Use the envelope fingerprint to retrieve the envelope:

GET https://api.signable.co.uk/v1/envelopes/{envelope_fingerprint}

Wait for confirmed envelope completion before treating the downloaded PDF as the final QES document. Signable’s flow finishes the required qualified signatures and document finalisation before entering its existing envelope-completion flow.

Treat the QES-in-progress stage as unfinished. The existing public completion status is signed; check envelope completion before downloading documents for downstream use. A signer returning to your application is not sufficient.

The public status reference has not yet documented the QES status value. Confirm its exact serialisation and QES completion webhook contract with Signable before adding strict enum handling.

Preserve the completed PDF returned by Signable. Regenerating, flattening or otherwise changing it can affect its embedded digital signatures.

The branding email endpoints include new qes-contract-send and qes-id-verification templates for QES-eligible companies. These templates include branding_email_reminder_subject, which you can update only on a QES template.

QES usage is counted per signer, per document requiring their qualified signature.

The full credit requirement is reserved before the envelope is sent. Reserved credits immediately reduce the available balance. Several QES fields for the same signer on the same document still require only one credit.

Do not infer an envelope’s historical credit use from its current balance-related response fields. The limitation below explains why those values may be misleading.

Sub-accounts use the partner’s QES credit pool rather than an independent balance. A sub-account can send QES through the Public API when its partner has sufficient credits. Sub-accounts cannot send QES through the web app, and the partner's credit balance is not exposed to them. Confirm the account arrangement with Signable when enabling a partner integration.

Each signer can apply QES to a maximum of 20 documents in one envelope. This is a per-signer limit: an envelope with 30 documents can be supported if one signer needs QES on 15 and another signer needs QES on the other 15.