E-signature API for developers

With API v1 your system creates documents, sends them for signature by email or WhatsApp and hears about every signature as it happens. Each document carries the same evidence as one sent from the dashboard, an audit certificate and the SHA-256 hash of the file.

Base URL: https://signsolu.com/api/v1

API keys

Create keys in your dashboard, under Developers. There are two kinds. ssk_live_… keys create real documents and ssk_test_… keys are for testing. The full key is shown only once. Keep it in your secrets manager, never in browser code or a mobile app.

Send it on every request in the Authorization header.

Authorization: Bearer ssk_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Each key has permissions. They are documents:read, documents:write, templates:read, account:read, webhooks:read, webhooks:write and exports:write, and write includes read. Give each system only what it needs. If a key leaks, revoke it in the dashboard and it stops working right away.

Your first document

Send the PDF in Base64, the signers and enviar: true. The referencia field is your internal number, such as an order, a case file or a loan. It is unique within your team, so repeating the request never creates two documents. Field names are the same in every language.

curl https://signsolu.com/api/v1/documents \
  -H "Authorization: Bearer $SIGNSOLU_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042" \
  -d '{
    "titulo": "Lease agreement - Apt 3B",
    "referencia": "order-1042",
    "pdf_base64": "JVBERi0xLjcK...",
    "firmantes": [
      { "nombre": "Ana Lopez", "correo": "ana@example.com", "canal": "email", "orden": 1,
        "campos": [{ "pagina": 3, "x": 0.12, "y": 0.8, "w": 0.3, "h": 0.06 }] },
      { "nombre": "Luis Perez", "telefono": "+12025550143", "canal": "whatsapp", "orden": 2,
        "campos": [{ "ancla": "Tenant signature" }] }
    ],
    "orden_estricto": true,
    "vence_en_dias": 30,
    "enviar": true
  }'

The response returns the document id, its status and each signer’s link. Signature boxes go in fractions of the page, from 0 to 1 starting at the top left corner. You can also place them with an ancla, a piece of text in the PDF, and the box starts where that text starts. To create from one of your templates, send template_id and datos. You can also upload the file as multipart/form-data with file and datos.

RouteWhat it does
POST /v1/documentsCreate a document, and send it if you ask
GET /v1/documentsList documents, filtered by status, reference and date
GET /v1/documents/{id}Status of the document and of each signer
POST /v1/documents/{id}/sendSend a draft
POST /v1/documents/{id}/remindRemind whoever has not signed yet
POST /v1/documents/{id}/cancelCancel
GET /v1/documents/{id}/filesTemporary links to the signed PDF and the audit certificate
GET /v1/templatesYour templates
GET /v1/accountPlan, documents available and team
POST /v1/exportsA ZIP with the signed documents of a period, their certificates and an index of hashes

Webhooks

Instead of polling every minute, register an https address and we notify you of every change. Only public https addresses are accepted.

curl https://signsolu.com/api/v1/webhooks \
  -H "Authorization: Bearer $SIGNSOLU_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://your-system.example.com/signsolu/events",
        "eventos": ["document.completed", "signer.declined"] }'

The response returns the secreto (whsec_…) only once. Leave out eventos to receive every event. POST /v1/webhooks/{id}/test sends you a test event right away.

EventWhen it arrives
document.sentThe document went out for signature
signer.viewedA signer opened their link for the first time
signer.signedA signer signed
signer.declinedA signer declined to sign
document.completedEveryone signed and the signed PDF is ready
document.cancelledThe document was cancelled
document.expiredThe link expired before everyone signed
nom151.issuedA NOM-151 certificate was issued (documents under Mexican law)
nom151.failedThe NOM-151 certificate could not be issued, with the motivo

Each notice is a POST with this body. It carries the minimum, so fetch the document by its id for the details. It never includes signers’ emails, phone numbers or identity data.

{
  "id": "evt_8f2c1a0e5b6d4c3a9e7f1b2d3c4a5e6f",
  "tipo": "document.completed",
  "creado": "2026-11-14T18:22:05.000Z",
  "modo": "live",
  "datos": {
    "documento": { "id": "0b1c…", "estado": "completed", "referencia": "order-1042" },
    "completado_at": "2026-11-14T18:22:04.913Z"
  }
}

ALWAYS check the signature before you trust a notice. The SignSolu-Firma header carries t, in Unix seconds, and v1, the hex HMAC-SHA256 of t + "." + body with your secret. Use the body exactly as it arrived, without serializing it again, and reject anything older than 5 minutes.

// Node.js (Express): keep the raw body, no JSON.parse before verifying
import crypto from "node:crypto";

function isValidSignature(header, body, secret, toleranceSec = 300) {
  let t = null;
  const signatures = [];
  for (const part of String(header ?? "").split(",")) {
    const [k, v = ""] = part.trim().split("=", 2);
    if (k === "t" && /^\d{1,12}$/.test(v)) t = Number(v);
    if (k === "v1" && /^[0-9a-f]{64}$/.test(v)) signatures.push(Buffer.from(v, "hex"));
  }
  // Outside the window = an old notice replayed: reject it.
  if (t === null || signatures.length === 0 || Math.abs(Date.now() / 1000 - t) > toleranceSec) return false;
  const expected = crypto.createHmac("sha256", secret)
    .update(Buffer.concat([Buffer.from(`${t}.`), Buffer.from(body)])).digest();
  // Always the same length (32 bytes), so timingSafeEqual never throws.
  return signatures.some((s) => crypto.timingSafeEqual(s, expected));
}

app.post("/signsolu/events", express.raw({ type: "application/json" }), (req, res) => {
  if (!isValidSignature(req.get("SignSolu-Firma"), req.body, process.env.SIGNSOLU_WHSEC)) {
    return res.status(400).send("invalid signature");
  }
  const event = JSON.parse(req.body);
  // Store event.id: if you already processed it, answer 200 and do nothing
  // (within those 5 minutes someone could replay the same notice).
  res.sendStatus(200);
});
# Python (Flask)
import hashlib, hmac, os, re, time
from flask import Flask, request, abort

app = Flask(__name__)

def is_valid_signature(header, body, secret, tolerance=300):
    t, signatures = None, []
    for part in (header or "").split(","):
        k, _, v = part.strip().partition("=")
        if k == "t" and re.fullmatch(r"\d{1,12}", v):
            t = int(v)
        if k == "v1" and re.fullmatch(r"[0-9a-f]{64}", v):
            signatures.append(v)
    # Outside the window = an old notice replayed: reject it.
    if t is None or not signatures or abs(time.time() - t) > tolerance:
        return False
    expected = hmac.new(secret.encode(), f"{t}.".encode() + body, hashlib.sha256).hexdigest()
    return any(hmac.compare_digest(expected, s) for s in signatures)

@app.post("/signsolu/events")
def events():
    body = request.get_data()  # bytes, exactly as they arrived
    if not is_valid_signature(request.headers.get("SignSolu-Firma"), body, os.environ["SIGNSOLU_WHSEC"]):
        abort(400)
    event = request.get_json()
    # Store event["id"]: if you already processed it, answer 200 and do nothing.
    return "", 200
  • Answer with a 2xx in under 10 seconds and do the work afterwards. A redirect counts as a failure.
  • If you fail, we retry with growing waits of 1 min, 5 min, 15 min, 1 h, 3 h, 6 h, 12 h and then every 24 h, for 72 hours.
  • If you accept no delivery in 72 hours, the webhook is switched off. Turn it back on with POST /v1/webhooks/{id}/enable.
  • The same event can reach you twice, and not always in order. Use id to skip repeats and creado to sort. The SignSolu-Entrega header identifies each delivery.
  • GET /v1/webhooks/{id}/deliveries lists each delivery with its attempts, and POST …/deliveries/{delivery}/retry sends it again right away.
  • Did the secret leak? POST /v1/webhooks/{id}/rotate-secret gives you a new one and the old one stops working.

Test mode

With an ssk_test_… key everything works the same, but documents are marked as test documents. They carry a watermark, do not count against your plan and send no email. Their events only reach webhooks you registered with a test key. Use test keys for your development environment and your automated tests.

NOM-151 certificate for documents under Mexican law

For documents signed under Mexican law, SignSolú can issue the NOM-151 retention certificate of the signed document through a certification service provider accredited by Mexico’s Ministry of Economy. It is turned on for your team on request.

When it is issued you get nom151.issued and download it from GET /v1/documents/{id}/files. If it could not be issued, nom151.failed arrives with the motivo. Test documents never request it.

Errors

Every error has the same shape. Keep the request_id if you write to support. Error codes are the same in every language.

{ "error": { "codigo": "documento_no_encontrado", "mensaje": "…", "request_id": "req_…" } }
HTTPWhat happened
400Something in the request is not valid, and mensaje says what
401The key is missing, does not exist or was revoked
403The key lacks the permission, or your plan has no documents left
404It does not exist, or it is not your team’s
409Conflict. The document status does not allow it, or the reference already exists
422The PDF could not be read
429You hit a rate limit. Wait what the Retry-After header says
500Our error. Retry with the same Idempotency-Key

Rate limits

  • live key: 120 requests per minute and 10,000 per day.
  • test key: 30 requests per minute.
  • Every POST accepts Idempotency-Key. Repeat the request with the same key within 24 hours and you get the same response, with nothing done twice.
  • Up to 10 webhooks per account and mode.

Need more, or want help with the integration? Write to us at info@solufintech.com.

Pricing and terms

Test keys cost nothing. Live keys come with the paid plans at no extra cost. Each document you create through the API counts against your plan or your team’s document pack, the same as in the dashboard. The plan includes 200 documents a month. For more, write to us and we will build a plan for your volume.

Who it is for and what it solves, in short: e-signature API for businesses. Prices are on the pricing page. Use of the API is governed by the API terms.