Getting started
API Reference
v1Send documents for signature, embed signing in your own app, and receive signed webhook events. Base URL https://www.sigpen.com/api/v1
Per-resource reference
Generated from the OpenAPI specUsing Claude, ChatGPT, Cursor, or another AI assistant? Connect it to SigPen. It can look things up, draft documents, and ask you to approve each send.
Quick Start
#Send your first document for signature in 3 steps. Copy any tab and run it.
Upload a document
POST a base64-encoded PDF (up to about 3 MB inline). For larger files, up to 25 MB, request a presigned URL fromPOST /api/v1/documents/upload-url, PUT the raw PDF to it, then create the document withupload_keyinstead of file. The response includes the documentidyou'll use in step 2.
printf '{"file":"%s","file_name":"contract.pdf","title":"Sales Agreement"}' \
"$(base64 < contract.pdf | tr -d '\n')" |
curl -X POST https://www.sigpen.com/api/v1/documents \
-H "Authorization: Bearer sp_live_YOUR_KEY" \
-H "Content-Type: application/json" \
--data-binary @-{
"id": "cm9abc123...",
"title": "Sales Agreement",
"file_name": "contract.pdf",
"status": "draft",
"external_id": null,
"metadata": {},
"created_at": "2026-03-30T12:00:00.000Z",
"updated_at": "2026-03-30T12:00:00.000Z"
}Send for signature
Each signer gets an invitation email with a signing link. A signer who hasn't signed gets one automatic reminder once the document has been out 2 days (a daily check, so it can land up to a day later).
Give every signer at least one field. The fields array here places a signature box; x and y are PDF points from the top-left corner of the page. The API doesn't stop you sending a document with nothing to sign, so check before you send. See Signing for every field type.
curl -X POST https://www.sigpen.com/api/v1/documents/DOC_ID/send \
-H "Authorization: Bearer sp_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"signers": [{
"email": "jane@example.com",
"name": "Jane Smith",
"fields": [{ "type": "signature", "page": 1,
"x": 72, "y": 640, "width": 180, "height": 48 }]
}],
"message": "Please sign this agreement.",
"expires_in_days": 30
}'{
"id": "cm9abc123...",
"status": "sent",
"signers": [
{
"id": "cm9xyz789...",
"email": "jane@example.com",
"name": "Jane Smith",
"status": "pending",
"order": 0,
"signed_at": null,
"viewed_at": null
}
],
"expires_at": "2026-04-29T12:00:00.000Z",
"sent_at": "2026-03-30T12:00:00.000Z"
}Download the signed copy
Returns the signed PDF binary. Only available once the document status iscompleted(all signers have signed). Subscribe to thedocument.completedwebhook to know the moment that happens.
A signed PDF over 4 MB comes back as a 302 redirect to a download link that works for 10 minutes, so follow redirects (curl -L). Node's fetch and Python's requests follow them on their own.
curl -L https://www.sigpen.com/api/v1/documents/DOC_ID/download \ -H "Authorization: Bearer sp_live_YOUR_KEY" \ -o signed-contract.pdf
Authentication
#All API requests require an API key passed as a Bearer token in the Authorization header. You can also use the X-API-Key header if you prefer.
Test mode: Use keys starting with sp_test_ for development. Test documents don't count toward your monthly limit, and they only go to your own email address (plus-aliases like you+signer@ work too). Sending to anyone else returns 422 TEST_MODE_RECIPIENT. Sending with a test key needs a verified account email, and every request with a live key (sp_live_) does too. Otherwise you get 403 EMAIL_NOT_VERIFIED.
API key prefixes
| Prefix | Mode | Usage |
|---|---|---|
| sp_live_ | Production | Real documents, counted toward limits |
| sp_test_ | Test | Sent only to your own address, not counted toward limits |
curl https://www.sigpen.com/api/v1/documents \ -H "Authorization: Bearer sp_live_YOUR_KEY"
Rate limits
| Plan | Requests / min | Requests / day | Burst / sec |
|---|---|---|---|
| Developer (free) | 10 | 200 | 3 |
| Professional | 30 | 500 | 5 |
| Business | 100 | 5,000 | 15 |
| Teams | 100 | 5,000 | 15 |
| Enterprise | 100 | 5,000 | 15 |
Test keys (sp_test_) get 10 requests a minute, 200 a day, and 3 a second on every plan. JSON responses carry X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset (Unix seconds) for the per-minute window. Going over a limit returns 429 RATE_LIMIT_EXCEEDED with a Retry-After header and a retry_after field, both in seconds. Wait that long, then retry. Repeated requests with a bad key from one IP address get the same 429.
The Developer plan includes 10 live documents a month and up to 3 webhook endpoints; paid plans allow up to 20 webhook endpoints. Past the monthly document limit you get 429 MONTHLY_QUOTA_EXCEEDED, with no retry time: the count resets on the 1st (UTC).
Webhooks Guide
#Receive real-time HTTP callbacks when document events occur. Manage endpoints via the Webhooks API or the Developer Dashboard. The HMAC secret is returned only at creation time, so store it securely.
Event types
| Event | Fires when |
|---|---|
| document.sent | Document is sent for signing |
| document.viewed | A signer opens the signing page for the first time |
| document.signed | An individual signer completes their signature |
| document.completed | All signers have signed and the document is fully executed |
| document.declined | A signer declines to sign (this also voids the document) |
| document.voided | The sender voids the document |
| document.expired | A signer’s signing deadline passes before they sign |
| test.webhook | Sent by POST /webhooks/:id/test so you can verify your endpoint |
Delivery format
Every delivery POSTs a JSON envelope and carries four headers: X-SigPen-Signature, X-SigPen-Timestamp, X-SigPen-Event, and X-SigPen-Delivery-ID. Reply with any 2xx status within 10 seconds. Anything else, including a timeout, is a failed delivery. The first attempt is immediate. A failed delivery is retried once a day and dropped 3 days after the event, so expect about four attempts in all. If 10 deliveries in a row fail that way, SigPen turns the endpoint off and emails you; turn it back on in the Developer Dashboard or with PATCH /webhooks/:id and "active": true. The X-SigPen-Delivery-ID header is the event id and stays the same on every retry, so use it to ignore duplicates.
Endpoints must use HTTPS and resolve to a public internet address. Private, local, and reserved addresses are refused, and redirects aren't followed, so a 3xx counts as a failed delivery. The test event reports your endpoint's status code, not its response body.
Always verify the signature to confirm the request came from SigPen. The signature is an HMAC-SHA256, keyed with your endpoint's secret (the whole whsec_ string), of the timestamp header, a period, and the raw body bytes. Don't re-serialize the JSON (key order and whitespace can differ). Compare in constant time, and reject a timestamp more than 5 minutes old so a captured request can't be replayed. Each retry is signed again with a fresh timestamp.
Event data
Request bodies use snake_case, but webhook data keys are camelCase. Every event's data has documentId, plus externalId and metadata when the document has them (they're left out, not null, when it doesn't). The rest depends on the event. Times are ISO 8601 strings.
| Event | Also in data |
|---|---|
| document.sent | title, signers [{ id, email }], signingSessions [{ id, signerEmail, signingUrl, expiresAt }] |
| document.viewed | signerEmail, viewedAt |
| document.signed | signerEmail, completedAt |
| document.completed | title |
| document.declined | title, signerEmail, reason (when the signer gave one), declinedAt |
| document.voided | title, reason |
| document.expired | title |
document.signed fires for each signer, the last one included, then document.completed fires once. document.expired comes from a daily check, so it can arrive up to a day after the deadline; the document stays sent. The test.webhook event has its own sample data, { document: { id, title, status, metadata } }, and is never retried.
When someone signs through a shareable link, they sign their own copy of the document. Events for that copy also carry publicLinkId and sourceDocumentId, the document you shared.
{
"id": "evt_mbq4x2k1_7f3a9c",
"type": "document.completed",
"created_at": "2026-06-10T18:05:00.000Z",
"data": {
"documentId": "cm9abc123...",
"externalId": "crm-7841",
"metadata": { "deal_id": "D-1042" },
"title": "Consulting Agreement"
}
}const crypto = require('crypto');
function verifyWebhook(body, signature, timestamp, secret) {
if (!signature || !timestamp) return false;
if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
const expected = 'sha256=' + crypto
.createHmac('sha256', secret)
.update(`${timestamp}.${body}`)
.digest('hex');
const a = Buffer.from(expected);
const b = Buffer.from(signature);
return a.length === b.length && crypto.timingSafeEqual(a, b);
}
// In your Express handler, verify against the RAW body bytes,
// not re-serialized JSON (key order/whitespace can differ):
app.post('/webhooks/sigpen', express.raw({ type: 'application/json' }), (req, res) => {
const sig = req.headers['x-sigpen-signature'];
const ts = req.headers['x-sigpen-timestamp'];
if (!verifyWebhook(req.body.toString('utf8'), sig, ts, WEBHOOK_SECRET)) {
return res.status(401).send('Invalid signature');
}
// Process the event...
res.sendStatus(200);
});Embedded Signing
#Generate a short-lived signing URL with POST /documents/:id/embedded-sign-url and render it in an iframe or with the embed.js widget. The embed token in the URL lasts 60 minutes. After that the link opens the regular signing page instead, without embed mode or events, until the document expires, so create a fresh URL each time and never share it.
Sending with skip_email: true skips the invitations only. SigPen still sends a pending signer one reminder once the document has been out 2 days, sends later signers their invitation at their turn in sequential signing, sends every signer the signed copy, and sends you a completion notice.
Tip: Listen for postMessage events from the iframe. Each message is { source: 'sigpen', event, ... }. The embed.js widget wires these to onReady/onSign/onError callbacks. Declining isn't offered in embedded signing (after the token expires the regular page shows, with Decline). A link that is already signed, voided, or expired shows a status page and sends no event. See the Embedded Signing reference and interactive sandbox for a full walkthrough.
Error Handling
#Every error comes back as one error object with a type (the kind of error), a code (the exact problem), a message for people, and a doc_url. Some errors add details (which field failed) or retry_after. Branch on code; messages can change. Successful calls return 200, 201 (created), 202 (bulk send accepted), or 204 (deleted).
| Status | type | code |
|---|---|---|
| 401 | authentication_error | INVALID_API_KEY: the key is missing, wrong, or revoked. |
| 403 | authorization_error | API_ACCESS_DENIED, ACCOUNT_SUSPENDED, EMAIL_NOT_VERIFIED, BULK_SEND_NOT_ALLOWED, FORMS_TIER_REQUIRED, WEBHOOK_LIMIT_REACHED, AI_DETECT_NOT_ALLOWED |
| 404 | not_found | NOT_FOUND: no such document, template, webhook, or signer in your account. |
| 409 | state_conflict | The document is in the wrong state, for example SEND_NOT_DRAFT, VOID_COMPLETED, ALREADY_VOIDED, DOWNLOAD_NOT_COMPLETED, REMIND_WRONG_STATUS, EMBED_WRONG_STATUS. |
| 422 | validation_error | The request failed a check, and code names it, for example FILE_CONFLICT, TEXT_TOO_LONG, INVALID_FIELD_BOUNDS, TEST_MODE_RECIPIENT, RECIPIENT_OPTED_OUT, VOID_REASON_REQUIRED. |
| 429 | rate_limit_exceeded | RATE_LIMIT_EXCEEDED: too many requests. Wait for Retry-After. |
| 429 | quota_exceeded | MONTHLY_QUOTA_EXCEEDED (documents) or AI_DETECT_LIMIT (AI field detection). Both reset on the 1st. |
| 500 | internal_error | INTERNAL_ERROR: something failed on our side. Retry, and contact support if it keeps happening. |
POST /documents/:id/send returns 404 for a missing document, 409 SEND_NOT_DRAFT for one already sent, and 403 EMAIL_NOT_VERIFIED for a test key on an unverified account. Every other refusal from send is a 422, including content review blocks (SEND_BLOCKED_MODERATION).
{
"error": {
"type": "validation_error",
"message": "The "reason" field is required and must be at least 10 characters.",
"code": "VOID_REASON_REQUIRED",
"doc_url": "https://www.sigpen.com/docs/api#errors",
"details": { "reason": "Must be at least 10 characters." }
}
}Changelog
#We try to keep v1 backward compatible. New fields and endpoints don't break existing integrations, and any change that can break one is marked Breaking in the changelog.
November 18, 2026 · SigPen is in Claude's connector directory
- SigPen is listed in Claude's connector directory. In Claude, open Customize, then Connectors, search for SigPen, and sign in, with no custom connector to set up. The MCP server is version 1.3.0; its changelog is at https://github.com/sigpenhq/sigpen-mcp.
November 17, 2026 · Library template field positions
- POST /documents/from-template puts the fields of SigPen's library templates where their PDFs draw them. Their saved positions came from an older one-page layout, so fields, signatures included, landed in the wrong places. The template PDF's own form boxes are flattened in the draft, as "Use template" does on the web.
- BreakingFields of SigPen-made forms and templates use their printed labels ("Party 1 Signature") with signature and date types, in GET /forms/:id field_labels, GET /templates/:id, and prefill keys. They were generated names like "Party_1_Signature_15", all of type text. Library template role names follow the signature labels, so the NDA's roles are "Party 1" and "Party 2" (they were "Party A" and "Party B") and the power of attorney's are "Principal", "Witness", and "Notary". Check GET /templates/:id for the current roles before sending role_assignments.
OpenAPI Specification
Fetch the spec as JSON or YAML to auto-generate client SDKs or import into tools like Postman, Swagger UI, or Insomnia. AI agents can start from llms.txt.
# Import into Postman # File → Import → paste URL: https://www.sigpen.com/openapi.json # Generate a TypeScript SDK npx openapi-generator-cli generate \ -i https://www.sigpen.com/openapi.json \ -g typescript-fetch \ -o ./sigpen-sdk