For developers
SignThis API, webhooks and OAuth
Send documents for signature from your own software. The REST API uploads PDFs, prepares drafts, sends them, reports who has signed and downloads the sealed copy. Webhooks tell you when something happens, and apps can connect with OAuth instead of a key.
Getting a key
- In SignThis, open your workspace's settings, then Security & integrations, and turn on Allow API, webhook and MCP access. Only a workspace's owners can do this.
- Create a named key and choose its scopes. The key is shown once, so store it in a secret manager.
- Send it on every request:
Authorization: Bearer YOUR_API_KEY.
API keys and webhooks are part of the Professional and Secure plans and every business plan; the plans are described on the home page. An OAuth connection works on every plan, including the free plan (see OAuth connections).
Keys expire after 90 days unless you choose another length (1 to 365 days). To rotate a key, create a replacement and revoke the old one. Changing the workspace's security settings revokes its keys and retires its webhook endpoints, so set those first. Keep keys out of browser code, source control, query strings and screenshots.
curl 'https://signthis.pro/api/v1/documents?status=sent&limit=25' \
-H "Authorization: Bearer $SIGNTHIS_API_KEY"Scopes
| Scope | Allows |
|---|---|
documents:read | List and read documents, signing status, templates, original and final PDFs and certificates. Every key has it. |
documents:write | Upload and edit drafts, create drafts from templates, delete drafts and cancel documents that are out for signature. |
documents:send | Send signature invitations and reminders, which email real people. Needs the read and write scopes too. |
A key belongs to one workspace and acts with the permissions of the owner who made it. It is accepted only at /api/v1 and /api/mcp; it does not sign anyone in to the app, and cookies do not authenticate these endpoints. Requests from another website's pages (a different Origin) are refused, so call the API from a server.
REST API
Routes are relative to https://signthis.pro/api/v1.
| Method and route | Scope | Result |
|---|---|---|
GET /documents | read | A page of documents and nextCursor. Optional limit (1 to 100), cursor, status and changedSince. |
POST /documents | write | Uploads a PDF as a new draft: multipart file, optional title. Answers 201 with id and hasForm. |
GET /documents/:id | read | The whole document: recipients, fields, values, current state and the verified audit trail. |
GET /documents/:id/status | read | Compact signing progress: who signed, who it is waiting on, and the document's address in SignThis. |
PUT /documents/:id | write | Replaces a draft's title, message, routing, recipients, fields and options. |
DELETE /documents/:id | write | Deletes a draft. |
POST /documents/:id/send | send | Sends a prepared draft for signature, with the same checks as the app. |
POST /documents/:id/remind | send | Emails signers who haven't signed. Optional recipientId. Answers ok and count. |
POST /documents/:id/cancel | write | Cancels a document that is out for signature. Optional reason. |
GET /documents/:id/original | read | The original PDF. |
GET /documents/:id/final | read | The completed, sealed PDF, once everyone has signed. |
GET /documents/:id/certificate | read | The audit certificate, once everyone has signed. |
GET /documents/:id/verysecure | write | The palm-verification cost of the current draft. Reads only: nothing is charged or sent. |
GET /templates | read | Saved templates and the recipient slots each one has. |
POST /templates/:id/documents | write | Creates a draft from a template, optionally filled in. Answers 201. Nothing is sent. |
Documents
Each document in a list has id, title, status, record, createdAt, updatedAt, sentAt, completedAt and expiresAt. A list is ordered by document ID, not by date; pass nextCursor back unchanged to get the next page.
statusis one ofdraft,sent,completed,declined,cancelledorexpired.changedSincetakes epoch milliseconds or an ISO 8601 time, and returns documents whose draft was edited or that recorded an event (sent, viewed, signed, declined, completed, reminded and so on) at or after that time.
GET /documents/:id/status returns the document's id, title, status, record, its times, url (the document in SignThis), recipients (id, name, email, role, order, status, viewedAt, signedAt, declinedAt, bounced) and waitingOn, the signers whose turn it is. It leaves out fields, values and history, so it is much smaller than the whole document.
Uploading and sending
curl 'https://signthis.pro/api/v1/documents' \
-H "Authorization: Bearer $SIGNTHIS_API_KEY" \
-F 'file=@agreement.pdf;type=application/pdf' \
-F 'title=Service agreement'A PDF can be up to 5 MB and 60 pages. Then set the draft's recipients and fields with PUT /documents/:id and send it with POST /documents/:id/send.
A draft edit replaces the draft; it is not a partial patch. Read the document first, then send back all the recipients, fields, routing and options you want to keep, with your changes. Make UUIDs for new recipient and field IDs; each field's recipientId names one of the signers, and positions are in PDF points. A draft's JSON can be up to 3 MB. Sending is its own request, and no route signs for a recipient.
Drafts from templates
Save a template in SignThis, then list it with GET /templates to see its recipient slots. Slots are filled in the order listed, and each keeps the template's role, signing order and fields.
curl 'https://signthis.pro/api/v1/templates/TEMPLATE_ID/documents' \
-H "Authorization: Bearer $SIGNTHIS_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"title":"NDA - Acme","recipients":[{"name":"Ada Lovelace","email":"ada@example.com"},{"name":"Grace Hopper","email":"grace@example.com"}]}'The body takes title (up to 200 characters), message (up to 2,000) and recipients, one for each slot, with name, email and an optional accessCode of 4 to 40 characters. The wrong number of recipients answers 422 recipient_count; invalid people answer 400 invalid_recipients. The answer is the compact document, with recipient IDs and its url for review. Saved templates need a plan that includes them.
Palm-verified documents
A draft can require a palm check from its signers (VerySecure, on eligible paid plans). Before sending one, read GET /documents/:id/verysecure and show the person its quote: units (the document's one envelope), checks (palm-verified signatures: one for each signer whose email address the workspace hasn't asked for a palm scan before; addresses asked before use none), palm (this month's included ones left and the purchased balance) and autoPay (what auto pay would add for this send and charge to the saved card, in cents). Then send with the values they reviewed:
{"verySecureQuote":{"pricingVersion":"PRICING_VERSION_FROM_THE_QUOTE","units":1,"checks":2}}If the cost went up since, the send answers 409 verysecure_quote_changed with the current quote and nothing is sent. Show the new quote and ask again. When the workspace hasn't enough palm-verified signatures and auto pay can't add them, the send answers 402 verysecure_palm_short.
Errors
A failure is JSON with error (a sentence) and code, sometimes with more details. A missing, expired or revoked key answers 401; a missing scope answers 403; an unknown ID and another workspace's document both answer 404.
Limits and retries
| Budget | Limit |
|---|---|
| Requests for each key | 60 a minute |
| Requests for each workspace | 300 a minute |
| Changes for each key | 10 a minute |
| Changes for each workspace | 30 a minute |
| Requests from one network address | 180 a minute |
| Active keys in a workspace | 20 |
Answers carry X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (seconds until the key's minute ends). Over a limit, the answer is 429 with code: "rate_limited" and a Retry-After in seconds: wait that long, add a little randomness, and don't retry in parallel. More keys don't raise a workspace's limits.
Some actions have longer limits as well: 30 uploads and 40 sends an hour for each account, one reminder an hour for each signer, and 1,000 email recipients a day. Those answer 429 with code: "hourly_limit" or "daily_limit" and a Retry-After that can be many minutes. Every send also counts toward the plan's own allowance.
A workspace's documents also reach a limited number of recipients in any 24 hours: on a paid plan 50 in the workspace's first 7 days, then 1,000 (fair use), unless a different limit was agreed. A send past it answers 429 with code: "recipient_daily_limit", the limit, how many are used and left, and a Retry-After when the document fits again. A send to someone who reported an earlier email from the workspace or its sender answers 422 with code: "recipient_blocked" and the addresses in recipients.
Reading is safe to retry. Uploading and creating from a template have no idempotency key: after a timeout, list recent documents with changedSince before creating again, and check a document's status before sending it a second time.
Webhooks
Owners add up to 5 HTTPS endpoints for a workspace under Security & integrations, then Webhooks, and choose the events each receives. The signing secret (whsec_…) is shown once, when the endpoint is created. Webhooks are managed in the app, not through the API.
| Event | When |
|---|---|
document.sent | A draft was sent for signature. |
recipient.viewed | A signer opened the document. |
recipient.signed | A signer finished signing. |
document.completed | Everyone signed, and the sealed PDF and certificate are ready. |
document.declined | A signer declined; the document is closed. |
document.cancelled | The sender cancelled the document. |
document.expired | The document expired before everyone signed. |
recipient.delivery_failed | An email to a recipient could not be delivered. |
Each event is a POST with a small JSON body. It holds IDs only, with no titles, names, email addresses or document content; read the details with the API.
{
"id": "evt_4f1c…",
"type": "recipient.signed",
"createdAt": "2026-11-06T15:04:05.000Z",
"workspaceId": "…",
"data": { "documentId": "…", "recipientId": "…" }
}Check every request. The SignThis-Signature header is t=<unix seconds>,v1=<hex HMAC-SHA256>, computed over "<t>.<raw body>" with the endpoint's secret. Compare in constant time and refuse a time more than five minutes old. In Node.js:
import crypto from "node:crypto";
export function verifySignThis(rawBody, header, secret) {
const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
const t = Number(parts.t);
if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false;
const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
const given = Buffer.from(String(parts.v1 ?? ""));
return given.length === expected.length && crypto.timingSafeEqual(given, Buffer.from(expected));
}The other headers are SignThis-Event-Id, SignThis-Event-Type, SignThis-Delivery-Id and User-Agent: SignThis-Webhooks/1.0.
- Answering: reply with any 2xx within 10 seconds. Redirects aren't followed.
- Retries: a failed delivery is tried again up to 8 times over about 44 hours (after 1 minute, 5 minutes, 30 minutes, then 2, 6, 12 and 24 hours).
- Order and repeats: an event can arrive more than once and out of order. Deduplicate on
idand read the document again before acting. - Testing: Send test in the app delivers a signed
webhook.testevent and shows the result. - Pausing: an endpoint that keeps failing for 3 days is paused until an owner resumes it. Events during a pause aren't replayed; catch up with
GET /documents?changedSince=…. - Addresses:
https://on the standard port at a public host name. IP addresses and local names are refused.
Prefer webhooks to polling. If you poll, use changedSince with the time of your last successful poll.
OAuth connections
An app can ask a person to connect their SignThis workspace instead of pasting a key. SignThis is an OAuth 2.1 authorization server for public clients, with PKCE.
| Step | Where |
|---|---|
| Discovery | https://signthis.pro/.well-known/oauth-authorization-server and https://signthis.pro/.well-known/oauth-protected-resource |
| Register a client | POST /api/oauth/register (dynamic client registration; no client secret) |
| Ask for access | GET /api/oauth/authorize with PKCE (S256). The person signs in, picks a workspace they own and what the app may do. |
| Get tokens | POST /api/oauth/token, form-encoded or JSON |
| Disconnect | POST /api/oauth/revoke |
- The authorization code is single-use and lasts 60 seconds. An access token lasts 1 hour; the refresh token lasts 90 days and changes each time it is used. A connection lasts at most 365 days.
- Scopes are the same three as for keys, and the person can grant fewer than the app asked for.
- Redirect addresses are
https,httpon localhost, or an app's own scheme, and have to match the registration. - A client that hasn't been used for a week is removed; register again to use it.
- A token works at
/api/v1and at/api/mcp, within one workspace, and follows that workspace's security settings like a key.
A connection works on every plan. When a workspace's plan doesn't include API access, each account can send 3 documents through connected apps; reading documents and preparing drafts aren't counted. After that a send answers 402 with code: "free_agent_sends_used". Owners see and end connections under Security & integrations, then Connected apps.
AI assistants (MCP)
The same documents are available to AI assistants through an MCP server at https://signthis.pro/api/mcp (Streamable HTTP), with OAuth sign-in or an API key. Its tools, limits and privacy are on the page for AI assistants.
claude mcp add --transport http signthis https://signthis.pro/api/mcp \
--header "Authorization: Bearer $SIGNTHIS_API_KEY"Security and records
- Each request is checked against the key's or connection's expiry, the owner's membership, the workspace's security settings and its plan.
- Creating and revoking keys, connecting and disconnecting apps, and requests for workspace data are recorded in the workspace's audit log, without the key or the document's content.
- Downloads come through the API itself; there are no storage links to share.
How documents are encrypted and sealed is on the Security page. The Privacy Policy and the Terms apply.
Help
Questions, or something here that doesn't match what you see? Write to support@signthis.pro. This page describes the service as it works on the date above. It is a description, not a commitment, and the Terms govern the service.