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_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXEach 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.
| Route | What it does |
|---|---|
POST /v1/documents | Create a document, and send it if you ask |
GET /v1/documents | List documents, filtered by status, reference and date |
GET /v1/documents/{id} | Status of the document and of each signer |
POST /v1/documents/{id}/send | Send a draft |
POST /v1/documents/{id}/remind | Remind whoever has not signed yet |
POST /v1/documents/{id}/cancel | Cancel |
GET /v1/documents/{id}/files | Temporary links to the signed PDF and the audit certificate |
GET /v1/templates | Your templates |
GET /v1/account | Plan, documents available and team |
POST /v1/exports | A 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.
| Event | When it arrives |
|---|---|
document.sent | The document went out for signature |
signer.viewed | A signer opened their link for the first time |
signer.signed | A signer signed |
signer.declined | A signer declined to sign |
document.completed | Everyone signed and the signed PDF is ready |
document.cancelled | The document was cancelled |
document.expired | The link expired before everyone signed |
nom151.issued | A NOM-151 certificate was issued (documents under Mexican law) |
nom151.failed | The 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
2xxin 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
idto skip repeats andcreadoto sort. TheSignSolu-Entregaheader identifies each delivery. GET /v1/webhooks/{id}/deliverieslists each delivery with its attempts, andPOST …/deliveries/{delivery}/retrysends it again right away.- Did the secret leak?
POST /v1/webhooks/{id}/rotate-secretgives 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_…" } }| HTTP | What happened |
|---|---|
| 400 | Something in the request is not valid, and mensaje says what |
| 401 | The key is missing, does not exist or was revoked |
| 403 | The key lacks the permission, or your plan has no documents left |
| 404 | It does not exist, or it is not your team’s |
| 409 | Conflict. The document status does not allow it, or the reference already exists |
| 422 | The PDF could not be read |
| 429 | You hit a rate limit. Wait what the Retry-After header says |
| 500 | Our error. Retry with the same Idempotency-Key |
Rate limits
livekey: 120 requests per minute and 10,000 per day.testkey: 30 requests per minute.- Every
POSTacceptsIdempotency-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.