Signaturios API

Signaturios is a developer-first REST API for legally-binding electronic signatures. POST a base64-encoded PDF with signer details; get back a hosted signing URL in one call. When the signer completes the flow, you receive a PAdES-signed PDF with a cryptographic audit trail — no SDK, no enterprise sales call, no per-envelope pricing.

Two signature tiers are supported out of the box: SES (email-verified consent, US ESIGN Act) and AES-eID (government-issued national eID, eIDAS Advanced Electronic Signature) with seven European identity methods.

Authentication

All developer endpoints require an API key passed as a Bearer token. Keys are prefixed esign_live_ and remain valid until revoked.

Get a key

Create a free account at /signup — your first API key is generated on the spot and shown once. Additional keys and revocation are available in the dashboard.

Send the key

Include it on every request to a developer endpoint:

Authorization: Bearer esign_live_...

$ curl https://esign-api-gt01.onrender.com/health \
    -H "Authorization: Bearer esign_live_Ue0GGV8..."

{ "status": "ok", "service": "esign-api", "version": "0.1.0" }

Quickstart

From zero to a legally-binding signed PDF in four steps.

1. Create a signature request

POST the document (base64-encoded PDF), signer info, and the signature tier. The response contains a signing_url — a hosted page where the signer reviews and signs the document. Email it to them; you don't build any frontend.

$ curl -X POST https://esign-api-gt01.onrender.com/v1/signature-requests \
    -H "Authorization: Bearer esign_live_..." \
    -H "Content-Type: application/json" \
    -d '{
          "document_base64": "'"$(base64 -i contract.pdf)"'",
          "document_title":  "Service Agreement",
          "signer": { "name": "Jane Doe", "email": "jane@example.com" },
          "tier": "ses"
        }'

import base64, requests

API_KEY = "esign_live_..."
BASE    = "https://esign-api-gt01.onrender.com"

with open("contract.pdf", "rb") as f:
    doc_b64 = base64.b64encode(f.read()).decode()

resp = requests.post(
    f"{BASE}/v1/signature-requests",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "document_base64": doc_b64,
        "document_title":  "Service Agreement",
        "signer": {"name": "Jane Doe", "email": "jane@example.com"},
        "tier": "ses",
    },
)
data = resp.json()
print("Signing URL:", data["signing_url"])

{
  "request_id":  "req_01HKx9mP3Qrt7wbA",
  "signing_url": "https://esign-api-gt01.onrender.com/sign/req_01HKx9mP3...",
  "status":      "pending",
  "tier":        "ses"
}

2. Choose the signature tier

Set "tier" on the request body:

For aes_eid, also set "eid_method" to pre-select the signer's national eID. If omitted, the signer is shown a selector page to choose their own.

eID methods (aes_eid tier)

Seven European national identity methods are supported. Pass the key as "eid_method":

{
  "document_base64": "JVBERi0x...",
  "signer": { "name": "Erik Svensson", "email": "erik@example.se" },
  "tier":       "aes_eid",
  "eid_method": "se_bankid"
}

3. Send the signing URL to your signer

Email signing_url to the signer. Signaturios serves the entire hosted signing experience — you build nothing. For the SES tier, the signer reviews the document inline and checks a consent box. For AES-eID, the signer authenticates through their national eID provider before the signature is applied. The signed PDF is produced automatically once the flow completes.

4. Poll for completion and retrieve the signed document

$ curl https://esign-api-gt01.onrender.com/v1/signature-requests/req_01HKx9mP3Qrt7wbA \
    -H "Authorization: Bearer esign_live_..."

import time, base64

request_id = data["request_id"]

while True:
    r = requests.get(
        f"{BASE}/v1/signature-requests/{request_id}",
        headers={"Authorization": f"Bearer {API_KEY}"},
    ).json()

    if r["status"] == "signed":
        pdf = base64.b64decode(r["signed_document_base64"])
        with open("signed.pdf", "wb") as f:
            f.write(pdf)
        print("Done. Audit trail:", r["audit_trail"])
        break

    time.sleep(5)  # poll every 5 s

{
  "request_id":             "req_01HKx9mP3Qrt7wbA",
  "status":                  "signed",
  "tier":                    "ses",
  "created_at":             "2026-06-18T09:00:00Z",
  "signer": { "name": "Jane Doe", "email": "jane@example.com" },
  "signed_at":              "2026-06-18T09:04:32Z",
  "captured_ip":            "203.0.113.42",
  "signed_document_base64": "JVBERi0x...",
  "audit_trail": {
    "signer": {
      "name":                "Jane Doe",
      "identifier":          "jane@example.com",
      "verification_method": "email_link",
      "tier":               "ESIGN (US) / eIDAS SES",
      "ip_address":          "203.0.113.42"
    },
    "intent_to_sign":        true,
    "consent_to_electronic": true,
    "timestamp_utc":         "2026-06-18T09:04:32Z",
    "document": {
      "sha256_before_signing": "a3b4c5d6e7f8a9b0...",
      "sha256_after_signing":  "c1d2e3f4a5b6c7d8..."
    },
    "signature_standard": "PAdES (ETSI EN 319 142) / ETSI.CAdES.detached"
  }
}

API Reference

$ curl -X POST https://esign-api-gt01.onrender.com/v1/signature-requests \
    -H "Authorization: Bearer esign_live_..." \
    -H "Content-Type: application/json" \
    -d '{
          "document_base64": "...",
          "signer": { "name": "Jane Doe", "email": "jane@example.com" },
          "anchor": { "text": "", "width": 220, "height": 70 }
        }'

resp = requests.post(
    f"{BASE}/v1/signature-requests",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "document_base64": doc_b64,
        "signer": {"name": "Jane Doe", "email": "jane@example.com"},
        "anchor": {"text": "", "width": 220, "height": 70},
    },
)

$ curl -X POST https://esign-api-gt01.onrender.com/v1/signatures \
    -H "Authorization: Bearer esign_live_..." \
    -H "Content-Type: application/json" \
    -d '{
          "document_base64": "'"$(base64 -i contract.pdf)"'",
          "signer": {
            "name":       "Jane Doe",
            "identifier": "jane@example.com"
          }
        }'

import base64, requests

with open("contract.pdf", "rb") as f:
    doc_b64 = base64.b64encode(f.read()).decode()

resp = requests.post(
    f"{BASE}/v1/signatures",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "document_base64": doc_b64,
        "signer": {"name": "Jane Doe", "identifier": "jane@example.com"},
    },
)
data = resp.json()
signed_pdf = base64.b64decode(data["signed_document_base64"])

<!-- 1. A container for the signing widget -->
<div id="sign-widget" style="width:100%;max-width:720px;border:1px solid #e5e5ea;border-radius:8px;overflow:hidden"></div>

<!-- 2. Embed SDK (served from your API domain) -->
<script src="https://esign-api-gt01.onrender.com/static/js/esign-embed.js"></script>

<!-- 3. Mount the widget -->
<script>
  var signer = SignaturiosEmbed.init({
    container: '#sign-widget',
    embedUrl:  '',  // from your server-side API response

    onLoaded: function(e) {
      console.log('Widget ready');
    },
    onSigned: function(e) {
      console.log('Signed!', e.request_id, e.signed_at);
      signer.unmount();          // remove the widget
      showSuccessMessage();      // your own UI
    },
    onError: function(e) {
      console.error('Error:', e.message);
    },
    onCancelled: function() {
      console.log('Cancelled');
    },
  });
</script>

{
  "error": {
    "message": "Invalid or inactive API key.",
    "status":  401
  }
}

Webhooks

Instead of polling GET /v1/signature-requests/{id}, register a webhook endpoint and receive a signed HTTP POST the moment a document is signed. Every delivery is HMAC-SHA256 signed so you can verify it originated from Signaturios.

Webhooks respect the live/test split: test-key requests trigger test webhooks; live-key requests trigger live webhooks. Register separate endpoints per environment in the dashboard.

Register an endpoint

Go to your dashboard, scroll to Webhook Endpoints, enter your HTTPS URL, choose the environment, and click Register endpoint. The signing secret is shown once — copy it to your secrets manager before leaving the page.

The endpoint must be publicly reachable and return a 2xx response within 10 seconds. Signaturios will retry up to 5 times on failure (see Retries).

Managing endpoints via the dashboard

Each registered endpoint shows its URL, environment badge, and a Disable button. Disabled endpoints stop receiving events; re-register if you need to replace one.

Event types

Payload shape

Signaturios POSTs a JSON body to your endpoint. The top-level envelope wraps the full GET /v1/signature-requests/{id} object under data, including the structured audit trail.

{
  "event":   "signature_request.completed",
  "created": "2026-06-18T20:00:00Z",
  "livemode": true,
  "data": {
    "request_id": "Voh6hSbwxDUCIMc30vb...",
    "livemode":   true,
    "status":     "signed",
    "tier":       "ses",
    "created_at": "2026-06-18T19:58:00Z",
    "signed_at":  "2026-06-18T20:00:00Z",
    "captured_ip": "185.1.2.3",
    "signer": { "name": "Jane Doe", "email": "jane@example.com" },
    "audit_trail": {
      "document": { "sha256": "a3f...", "pages": 3 },
      "signer": {
        "name": "Jane Doe",
        "identifier": "jane@example.com",
        "verification_method": "email_link",
        "tier": "ESIGN (US) / eIDAS SES",
        "ip": "185.1.2.3"
      },
      "signed_at": "2026-06-18T20:00:00Z",
      "signature": { "algorithm": "RSA-SHA256", "subfilter": "ETSI.CAdES.detached" }
    },
    "signed_document_base64": "JVBERi0x..."
  }
}

Request headers

Verify the signature

Every delivery includes an X-Signaturios-Signature header of the form sha256=<hex>. The hex value is HMAC-SHA256 of the raw request body using your endpoint's signing secret as the key. Always verify this before processing the event.

Use constant-time comparison (hmac.compare_digest) to prevent timing attacks.

import hmac, hashlib

def verify_esign_webhook(secret: str, body: bytes, header: str) -> bool:
    """Return True only if the delivery is authentic."""
    expected = "sha256=" + hmac.new(
        secret.encode(), body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, header)


# Flask handler example
@app.post("/webhooks/esign")
def handle_esign_webhook():
    sig = request.headers.get("X-Signaturios-Signature", "")
    if not verify_esign_webhook(WEBHOOK_SECRET, request.data, sig):
        abort(401)           # reject unknown origin

    event = request.get_json()
    if event["event"] == "signature_request.completed":
        data      = event["data"]
        audit     = data["audit_trail"]
        signed_pdf = base64.b64decode(data["signed_document_base64"])
        # ... store audit + PDF ...

    return "", 200  # acknowledge within 10 s

Retries & delivery guarantees

If your endpoint returns a non-2xx response or does not respond within 10 seconds, Signaturios retries up to 5 attempts with exponential backoff:

Each attempt is logged (endpoint, event type, HTTP status, success/failure). After 5 failures the delivery is marked failed and no further retries occur. The HMAC signature is identical across all retries for the same event, so you can verify any attempt with the same code path.

To avoid double-processing, treat deliveries as at-least-once: use data.request_id as an idempotency key in your handler.

Pricing & billing

Usage-based per-completed-signature pricing. You are only ever charged for work that actually happened — a signer opened the link, consented, and the PDF was cryptographically signed. Failed attempts, expired links, and test-mode signatures are always free.

Free allowance

Every developer account includes 10 completed live signatures free — enough to fully test your integration end-to-end with real documents before spending anything. The free allowance never expires.

Test mode is always free

Requests made with a esign_test_… key are never billed, never counted against the free allowance, and never require a payment method. Use test keys freely in CI, staging, and development.

What is never billed

• Signatures made with a esign_test_… key
• Pending or expired signing requests that were never completed
• Signing attempts that returned an error (PDF rejected, eID auth failed, etc.)
• API calls that returned 4xx / 5xx before signing began

How billing works

Add a payment method via your dashboard. Each completed live signature above the free allowance is posted as a Stripe invoice line-item immediately. Stripe collects all items into a monthly invoice and charges your card automatically. You can view past invoices and update your card via the Stripe Customer Portal (linked from the dashboard).

Rate limits

Limits are enforced per API key. Test keys and live keys have independent buckets. Signing pages (/sign/…) and the health endpoint are not rate-limited so real signers are never blocked.

429 response

When a limit is exceeded the API returns HTTP 429 with the standard error envelope and a Retry-After header (seconds until the current window resets).

HTTP/1.1 429 Too Many Requests
Retry-After: 42
Content-Type: application/json

{
  "error": {
    "message": "Rate limit exceeded: 10 per 1 minute.",
    "status":  429
  }
}

How It Works & Legal Validity

Understanding the underlying mechanism helps you explain the legal strength of these signatures to your customers — and why they're materially stronger than a JPEG stamped onto a PDF.