e-Signature.eu REST API — electronic signatures (SES, AES, QES)

1. Overview

The e-Signature.eu REST API lets your application send documents for electronic signature (simple SES, advanced AES or qualified QES under eIDAS) without using our website. You send the PDF and the signers; we handle the identity verification, the signature and the follow-up; you get the signed document back through the API or a callback.

This documentation describes API v3. Already using API v2 (https://api.e-signature.eu/v2/signature/)? See the Changelog.

2. Authentication

Your credentials are available in My account > Signatures API once you are logged in on e-signature.eu:

• User ID: sent in the URL as the userid parameter of every call;
• API token: sent in the x-api-key HTTP header of every call.

curl -X GET "https://api.e-signature.eu/v3/signature/requestBalance?userid=123" \
  -H "x-api-key: YOUR_API_TOKEN"

Keep your token secret: it gives full access to your account through the API. Calls must be made from your server, never from a browser or a mobile app.

3. Conventions

Requests and responses

• HTTPS only. Request bodies are JSON (Content-Type: application/json).
• Every response is JSON, in one of these two forms:

{ "success": true,  "result": { ... } }
{ "success": false, "error": "Readable error message" }

Limits

4. Credits

Requests are paid with your prepaid e-signature.eu credits. The price of a method can be retrieved with getMethods (it takes your specific prices into account). Your balance is returned by requestBalance and in every request object (credits_balance).

Automatic credit recharge

To avoid running out of credits, you can let your account recharge itself automatically. It is set up once in My account > Signatures API, not through the API:

1. Choose a threshold (in credits) and the credit pack to order.
2. Save a payment method with our payment provider Mollie (card, or SEPA Direct Debit through Bancontact, iDEAL…). A verification payment of €0.01 is requested once.
3. Whenever credits are debited and your balance falls below the threshold, an order for the chosen pack is created and paid automatically with the saved payment method. The invoice is sent to you by email.

5. How a signature request works

1. You create the request with the PDF, the signers and the accepted signing methods. The credits are debited.
2. Each signer receives an email with a personal signing link (or you send the signature_link yourself when send_email is false).
3. The signer verifies his identity with one of the accepted methods (itsme®, Evrotrust, Veriff, OTP…) and signs.
4. When everybody signed, the request is finished: the signed PDF (PAdES) is available through getRequest and sent in the callback.

Signing order

By default all signers sign in parallel. To define an order, set sign_first: true on the signers of the first group: they are invited immediately, possibly several of them in parallel. The other signers are invited only when the whole first group has signed. Two groups at most.

Two integration modes

Do not poll the API

Do not call getRequest repeatedly to follow the status of a request: rely on the callbacks, sent automatically at each change. Excessive calls trigger an automatic throttling that temporarily suspends the processing of your requests.

6. Create a signature request

{
  "title": "Sales agreement 2026-114",
  "lang": "en",
  "methods": [
    "itsme-qes-signature",
    "evrotrust-signature"
  ],
  "signature_place": "position_auto",
  "reminder": 3,
  "send_email": true,
  "email_notification": false,
  "note_html": "Please sign the agreement before Friday.",
  "signature_redirect": "https://www.example.com/thank-you",
  "external_reference": "QUOTE-2026-114",
  "metadata": {
    "crm_deal_id": 8812
  },
  "callback_url": "https://erp.example.com/hooks/esignature",
  "signers": [
    {
      "firstname": "Ann",
      "lastname": "Peeters",
      "email": "[email protected]",
      "phone": "+32475111222",
      "sign_first": true
    },
    {
      "firstname": "Marc",
      "lastname": "Dubois",
      "email": "[email protected]",
      "sign_first": false
    }
  ],
  "pdf_file_base64": "JVBERi0xLjcKJeLjz9MK..."
}

Signing methods

Prices are the standard prices: getMethods returns the methods available and the prices for your account. Only a qualified electronic signature (QES) is legally equivalent to a handwritten signature under the eIDAS Regulation. otp-email-non-qualified covers both email and SMS: the code is sent by SMS when the signer has a phone, otherwise by email, at the same price.

Body fields

Signer fields

Cost

Price of the most expensive method in methods × number of signers. The credits are debited when the request is created. Credits of signers who did not sign are refunded when the request is cancelled or stopped.

Response 201 Created

{
  "success": true,
  "result": {
    "id_sign": 4521,
    "lang": "en",
    "doc_name": "Sales-agreement-2026-114",
    "send_email": true,
    "from_api": true,
    "signature_redirect": "https://www.example.com/thank-you",
    "status_id": "pending",
    "date_status": "2026-10-20 10:15:02",
    "last_reminder": null,
    "timezone": "Europe/Brussels",
    "credits": 2,
    "credits_balance": 38.4,
    "signers": {
      "1": {
        "firstname": "Ann",
        "lastname": "Peeters",
        "email": "[email protected]",
        "phone": "+32475111222",
        "sign_first": true,
        "status": "pending",
        "signature_link": "https://www.e-signature.eu/en/sign/?key=…"
      },
      "2": {
        "firstname": "Marc",
        "lastname": "Dubois",
        "email": "[email protected]",
        "sign_first": false,
        "status": "pending",
        "signature_link": "https://www.e-signature.eu/en/sign/?key=…"
      }
    },
    "external_reference": "QUOTE-2026-114",
    "metadata": {
      "crm_deal_id": 8812
    }
  }
}

7. Signature placement

position_auto (default)

Place the markers #SIG01, #SIG02… (also accepted: #SIG01#) as text in your document, where each signer must sign (#SIG01 = first signer of the signers array). The signature is placed at the top left of the marker. If the same marker appears several times, its first occurrence is used. A marker is skipped when its signature area would overlap a signature already placed (or an existing signature): the signer then takes the next free marker. A marker so close to the page edge that the signature has to be moved is only used as a last resort.

Document not signed yet

If the document contains no marker, or if the marker of a signer is missing, a signature page containing the markers is added at the end of the document and all signatures are placed on this page (6 signers on the first added page, then 10 per additional page).

Document already signed

No page can be added to a PDF that is already signed electronically: it would invalidate the existing signatures. With position_auto, the signatures are placed on the free markers, i.e. the markers whose signature area does not cover an existing signature. Free markers are assigned to the signers in order (#SIG01, #SIG02…).

position_manual

Give the position of each signature, in centimetres, for each signer:

{ "lastname": "Peeters", "email": "[email protected]", "sign_page": 3, "sign_left": 2.5, "sign_bottom": 6 }

sign_left and sign_bottom give the top left corner of the signature. The signature is placed below and to the right of this point.

The limits depend on the actual size of the page and on the size of the visual stamp: the whole signature must stay at least 2 cm from every edge of the page. When several signing methods are accepted, the largest stamp is used. If a value is out of range, the error message gives the allowed range for that page.

A signature may not overlap another signature of the request, nor an existing signature when the document is already signed.

8. The signature request object

Returned by request, getRequest, cancel, skip, remind, delete and sent in the callbacks.

Signer

{
  "1": {
    "firstname": "Ann",
    "lastname": "Peeters",
    "email": "[email protected]",
    "status": "signed",
    "signing_time": "2026-10-20 11:02:47",
    "signing_method": "itsme-qes-signature",
    "verified_firstname": "Ann",
    "verified_lastname": "Peeters"
  }
}

9. Other endpoints

All endpoints take userid in the URL and x-api-key in the headers. id_sign is passed in the URL.

List the requests

status_id (optional): pending, finished or skipped. external_reference (optional): only the requests with this reference.

{
  "success": true,
  "result": [
    {
      "id_sign": 4521,
      "status_id": "pending",
      "external_reference": "QUOTE-2026-114"
    },
    {
      "id_sign": 4498,
      "status_id": "finished"
    }
  ]
}

Get a request

Returns the signature request object, with the signed PDF once the request is finished. To follow the status of a request, use the callbacks rather than repeated calls.

Send a reminder

Sends a reminder email to the signers with status: pending of the group currently invited (sign_first group first). Request pending only. Works also for requests created with send_email: false.

Stop a request (keep the signatures already made)

Possible when at least one signer has signed and at least one has not. The request becomes skipped, the partially signed PDF is available and the credits of the signers who did not sign are refunded.

Cancel a request

Possible as long as nobody has signed; to end a partially signed request, use skip. The response contains the request with status_id: cancelled; the request and its document are then removed from your dashboard, the signing links stop working and the credits are refunded.

Delete a request

Requests finished or skipped only. Deletes the documents and the request. The response contains the request one last time, with status_id: deleted: download the signed PDF before deleting.

Download the audit trail

Not available while the request is pending (HTTP 412). Returns the request object with audit_trail_base64: a PDF with the history of the request (dates, methods, verified identities).

Get the credit balance

{ "success": true, "result": { "credits_balance": 38.4 } }

List the signing methods

Methods accepted in methods, with the price in credits per signer for your account. lang (optional) translates the labels.

{
  "success": true,
  "result": [
    {
      "id": "itsme-qes-signature",
      "label": "itsme® | QES",
      "credits": 1
    },
    {
      "id": "evrotrust-signature",
      "label": "Evrotrust | QES",
      "credits": 1
    },
    {
      "id": "veriff-advanced-signature",
      "label": "Veriff | AES",
      "credits": 0.7
    },
    {
      "id": "otp-email-non-qualified",
      "label": "OTP by Email/SMS | SES",
      "credits": 0.4
    }
  ]
}

10. Callbacks (webhooks)

Define your callback URL in My account > Signatures API (HTTPS, publicly reachable). You can also set a callback_url per request. The callback is a POST with a JSON body containing the full current state of the request (same format as getRequest), sent for requests created through the API.

Event fields

Event types

The body always contains the full current state: your integration can rely on status_id and on the status of each signer rather than on the event type alone.

Headers

Verifying the signature

Your signing secret is shown in My account > Signatures API, where it can also be regenerated. v1 is the HMAC-SHA256 of "<t>.<raw request body>" with your secret, hex encoded. Use the raw body, before any JSON parsing, and reject callbacks older than 5 minutes.

PHP

$body   = file_get_contents( 'php://input' );
$header = $_SERVER['HTTP_X_ESIG_SIGNATURE'] ?? '';
preg_match( '/t=(\d+),v1=([a-f0-9]{64})/', $header, $m );
$valid = $m
    && abs( time() - (int) $m[1] ) <= 300
    && hash_equals( hash_hmac( 'sha256', $m[1] . '.' . $body, $secret ), $m[2] );

Node.js

const crypto = require('crypto');
function verify(rawBody, header, secret) {
  const m = /t=(\d+),v1=([a-f0-9]{64})/.exec(header || '');
  if (!m || Math.abs(Date.now() / 1000 - Number(m[1])) > 300) return false;
  const expected = crypto.createHmac('sha256', secret).update(`${m[1]}.${rawBody}`).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(m[2]));
}

C# (.NET)

using System.Security.Cryptography; using System.Text; using System.Text.RegularExpressions;
static bool Verify(string rawBody, string header, string secret) {
    var m = Regex.Match(header ?? "", @"t=(\d+),v1=([a-f0-9]{64})");
    if (!m.Success || Math.Abs(DateTimeOffset.UtcNow.ToUnixTimeSeconds() - long.Parse(m.Groups[1].Value)) > 300) return false;
    using var h = new HMACSHA256(Encoding.UTF8.GetBytes(secret));
    var expected = Convert.ToHexString(h.ComputeHash(Encoding.UTF8.GetBytes(m.Groups[1].Value + "." + rawBody))).ToLowerInvariant();
    return CryptographicOperations.FixedTimeEquals(Encoding.ASCII.GetBytes(expected), Encoding.ASCII.GetBytes(m.Groups[2].Value));
}

Responses and retries

• Reply with HTTP 2xx as soon as the callback is received, and process it asynchronously if needed.
• On network error, timeout (30 s), HTTP 429 or 5xx, the callback is sent again every hour with the same event_id, up to 24 attempts. Other 4xx answers are considered final. If the request changes again before a successful delivery, the next callback carries a new event and the full current state. The current state remains available at any time through getRequest.
• Redirects are followed (the POST method is kept). localhost and private addresses can not be used.

11. Errors

Errors are returned with "success": false and a readable error message. Rely on the HTTP code for your logic: messages may be improved over time.

Errors by endpoint

Validation messages on creation (request, HTTP 400)

The message names the field or the problem; … stands for a value of your request. Rely on the HTTP code in your code, and show the message to help correct the request.

12. Retention

Signed documents can be downloaded for 30 days after completion, through getRequest or the request.completed callback. The audit trail is kept for the period defined in our DPA. Archive the signed document and the audit trail on your side within 30 days.

13. Changelog

API v3 — differences with API v2

API v2 (https://api.e-signature.eu/v2/signature/) remains available and unchanged. Endpoints, parameters and authentication are identical in both versions: to move to API v3, replace the base URL with https://api.e-signature.eu/v3/signature/. You can switch endpoint by endpoint.

The previous URLs (https://www.e-signature.eu/wp-json/signature/ for API v2 and https://www.e-signature.eu/wp-json/esig/v3/signature/ for API v3) remain valid. We recommend using the api.e-signature.eu URLs.

Callbacks follow the version used to create the request: a request created with API v2 keeps receiving API v2 callbacks.