For developers
How to add e-signatures to your app
Adding e-signatures to an app takes one HTTPS call to send the PDF, one webhook to learn it was signed, and one call to download the certified copy. This tutorial does all three with the Signathing API, in curl, Node and Python. The first 100 documents a month are free with no card, so you can build and test the whole flow without paying.
Before you start: get a key
Sign in at signathing.com with your email address or mobile number, open API in the dashboard, and create a key. Creating a key asks you to verify a US mobile number by text, once. No card is asked for. The key starts with sk_live_ and is shown one time, so copy it then and keep it where your app keeps its secrets, for example an environment variable.
Every request sends the key as a bearer token to https://signathing.com/api/v1. To try a call without reaching anyone, add test=1: every message goes to your own account email in place of the people you named, it costs nothing, it is marked [TEST] and it erases itself after 7 days (up to 50 a month).
export SIGNATHING_API_KEY="sk_live_..."Step 1: send a PDF for signature
The send is a multipart POST to /api/v1/documents with three parts: the PDF as file, a title, and signers as a JSON array. Each signer needs a name and an email address or a US mobile number. Signathing emails or texts each signer a private link; they sign in a browser and need no account.
curl https://signathing.com/api/v1/documents \
-H "Authorization: Bearer $SIGNATHING_API_KEY" \
-F "file=@contract.pdf" \
-F "title=Service agreement" \
-F 'signers=[{"name":"Pat Lee","email":"pat@example.com"}]'What comes back
The response is the document as JSON, with HTTP status 201. Keep the id. Each entry in signers carries its own signing_url, the same private link Signathing already delivered, so you can also link to it from inside your own app. The billing block says what the send cost; charged_tenths is 0 while you are inside the free 100. The sample below is trimmed to the parts most apps use.
{
"id": 71,
"object": "document",
"status": "sent",
"title": "Service agreement",
"signers": [
{
"id": 118,
"name": "Pat Lee",
"email": "pat@example.com",
"status": "pending",
"signing_url": "https://signathing.com/sign/..."
}
],
"downloads": {
"original": "https://signathing.com/api/v1/documents/71/download?which=original",
"signed": null
},
"billing": { "charged_tenths": 0, "unit_this_month": 1, "balance_tenths": 0 }
}The same call from Node
Node 18 and later have fetch, FormData and Blob built in, so there is nothing to install. Save this as send.mjs and run it with node send.mjs.
import { readFile } from "node:fs/promises";
const form = new FormData();
form.append("file", new Blob([await readFile("contract.pdf")], { type: "application/pdf" }), "contract.pdf");
form.append("title", "Service agreement");
form.append("signers", JSON.stringify([{ name: "Pat Lee", email: "pat@example.com" }]));
const res = await fetch("https://signathing.com/api/v1/documents", {
method: "POST",
headers: { Authorization: "Bearer " + process.env.SIGNATHING_API_KEY },
body: form,
});
const doc = await res.json();
if (!res.ok) throw new Error(doc.error.code + ": " + doc.error.message);
console.log(doc.id, doc.status, doc.signers[0].signing_url);The same call from Python
With the requests library, the PDF goes in files and the other parts go in data.
import json
import os
import requests
with open("contract.pdf", "rb") as pdf:
res = requests.post(
"https://signathing.com/api/v1/documents",
headers={"Authorization": "Bearer " + os.environ["SIGNATHING_API_KEY"]},
files={"file": ("contract.pdf", pdf, "application/pdf")},
data={
"title": "Service agreement",
"signers": json.dumps([{"name": "Pat Lee", "email": "pat@example.com"}]),
},
)
doc = res.json()
if not res.ok:
raise SystemExit(doc["error"]["code"] + ": " + doc["error"]["message"])
print(doc["id"], doc["status"], doc["signers"][0]["signing_url"])Step 2: find out when it is signed
Set one HTTPS webhook URL in the API section of your dashboard. Signathing posts JSON to it for each event; the one most apps wait for is document.completed, sent when every signer has signed. The body is an object with id, event, created_at and data, where data is the same document shape the send returned.
Check the Signathing-Signature header before trusting a webhook. It reads t=<unix seconds>,v1=<hex>, where v1 is the HMAC-SHA256 of t, a period and the raw request body, keyed with your webhook secret. Reply with any 2xx status within ten seconds; anything else is retried. If your app cannot receive webhooks, poll GET /api/v1/documents/:id and read status instead.
import crypto from "node:crypto";
// rawBody is the request body exactly as received, before any JSON parsing.
export function isFromSignathing(rawBody, header, secret) {
const [t, v1] = header.split(",").map((part) => part.split("=")[1]);
const expected = crypto.createHmac("sha256", secret).update(t + "." + rawBody).digest("hex");
return v1.length === expected.length && crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected));
}Step 3: download the certified PDF
Once status is completed, the signed copy is one GET away. It is the original with the signatures stamped in, plus a certificate page that lists each signer, the time they signed and a verification code anyone can check at signathing.com/verify.
curl "https://signathing.com/api/v1/documents/71/download?which=signed" \
-H "Authorization: Bearer $SIGNATHING_API_KEY" \
-o signed.pdfPut the signature where you want it
With no fields, signers sign on a certificate page added to the end of the PDF, which is enough for many documents. To put the signature on a line in your own layout, add a fields part to the send: a JSON array of boxes measured in percent of the page from the top left corner. signerIndex is the signer's position in your signers array, starting at 0. When the PDF is someone else's form and you do not know the coordinates, give a field an anchor instead: the words printed beside the line, such as "Signature:", and the box is placed against them. If the words are not in the PDF the call fails and nothing is sent.
Field types are signature, initials, date, name, email, text, number, checkbox, radio, dropdown and attachment. The developers page lists the options for each.
-F 'fields=[{"id":"sig1","type":"signature","signerIndex":0,"page":1,"x":10,"y":70,"w":28,"h":5.5},
{"id":"date1","type":"date","signerIndex":0,"page":1,"x":45,"y":70,"w":16,"h":3.2}]'Limits to know while you build
The first 100 documents each month are free. After that a document costs $0.06, falling with volume, paid from a prepaid balance; there is no subscription. A new account can send 10 API documents a day for its first 7 days, and that limit lifts on its own. A document takes up to 25 signers and a PDF up to 50 MB, and the API accepts 120 requests a minute.
Errors come back as an object with error.code and error.message and a matching HTTP status: 401 for a bad key, 400 for a bad request, 402 when the free documents are used and the balance is empty, and 429 when you are sending too fast.
Common questions
- Is there a sandbox or test mode?
- Yes. Send with test=1 (test: true on the MCP tool) and every message goes to your own account email in place of the people you named. Their addresses and numbers are not stored. It is free, uses none of your monthly documents, is marked [TEST], and erases itself after 7 days. The signing links work, so you can walk the whole flow. Up to 50 test documents a month.
- Do the people signing need a Signathing account?
- No. Each signer opens a private link from an email or a text and signs in a browser. Only your app has a key.
- Can I show the signing page inside my own app?
- Link to the signing_url or open it in a new tab or an in-app browser. The signing page cannot be placed in a frame on another site.
- Is there an SDK for my language?
- None is needed. The API is plain HTTPS with multipart and JSON, and the OpenAPI description at signathing.com/api/v1/openapi.json can generate a client for most languages.
- Are signatures collected this way recognized?
- Electronic signatures are recognized under the federal ESIGN Act and state UETA laws. Each signer agrees to sign electronically before signing, and the certificate page records who signed and when.
Prices and limits shown are Signathing's own as of November 2026. Signathing provides the signing service and is not a party to any agreement signed through it.
More in learn
Free, and not the kind of free with a catch
Unlimited documents, up to 25 signers each, certified PDFs on every one. No trial clock and no card to start.
Start signing free