# Signclad

> Document eSigning through a REST API, embedded signing, and MCP. Email delivery only.

API base URL: https://api.signclad.com/api/v1
Authenticate server-side with X-Api-Key. API and MCP access require Light or above.
Use sandbox keys (sk_test_) for development. Test mode never bills, delivers real emails with a [TEST] subject prefix, and watermarks documents as not legally binding; use recipient addresses you control.
Never share real API keys with an AI assistant or expose them in client code.
Use the OpenAPI schema for exact request and response shapes. No client library is published to npm yet, so call the API over plain HTTP or generate a client from the schema.

This pack is the prose guides only — no OpenAPI document. For the complete machine-readable contract, fetch https://signclad.com/openapi/signclad.v1.yaml (or .json), or https://signclad.com/llms-full.txt for both in one file.

## Contents

- LLMs.txt: integrate with AI
- Getting started
- Authentication and keys
- Sandbox and test mode
- Creating a document
- Templates and create-from-template
- Text tags
- Embedded signing
- Embedded builders and the compatibility shim
- Webhooks
- Errors and rate limits
- MCP
- Migrating to Signclad
- Compatibility reference

---

# LLMs.txt: integrate with AI

> Download the Signclad integration docs and API schema as plain text for your AI assistant.

Source: https://signclad.com/docs/llms/

Give your AI assistant the documentation it needs to build a Signclad integration. The downloads are generated from these guides and the published API schema on every site build.

## Download the docs

- <a href="https://signclad.com/llms-guides.txt" download="signclad-guides.txt">Download the guides pack (.txt)</a> — every prose guide in one file, without the schema. Start here: it is an order of magnitude smaller than the full pack, and it is the half an assistant actually reads.
- <a href="https://signclad.com/llms-full.txt" download="signclad-integration.txt">Download the full integration guide (.txt)</a> — the same guides plus the complete OpenAPI schema. Large, and mostly specification, so reach for it when your assistant has the context window and needs exact field shapes inline.
- <a href="https://signclad.com/llms.txt" download="llms.txt">Download llms.txt</a> — a short index: the four downloads with their measured sizes, then every guide with a link to its Markdown version. Use this with an assistant that can fetch URLs, or to let it pick a file it can hold.
- <a href="https://signclad.com/openapi/signclad.v1.yaml" download="signclad.v1.yaml">Download the OpenAPI schema (.yaml)</a> — every published operation, request, response, and error schema. The same document is at <a href="https://signclad.com/openapi/signclad.v1.json" download="signclad.v1.json">/openapi/signclad.v1.json</a> for tools that only read JSON.

Both packs cover authentication, creating and sending documents, templates, text tags, embedded signing and builders, webhook delivery and verification, errors, rate limits, test mode, migration, the compatibility reference, and MCP.

The sizes in `llms.txt` are measured from the files that build emitted, so they cannot drift from what you download.

## A starter prompt

Attach the full integration guide, then describe your application and the workflow you need:

```text
Help me integrate Signclad into my application using the attached documentation.
My stack is [language and framework].
I want to [describe the document workflow and recipients].

Use the included OpenAPI schema for exact endpoints and request fields.
Start with a sandbox key stored server-side in an environment variable.
Use recipient addresses I control: test mode sends real emails.
Add idempotency keys, error handling, and verified webhook processing.
Never include API keys in browser code, logs, or the conversation.
Ask about missing requirements instead of inventing API capabilities.
Explain how to test the integration before switching to a live key.
```

## Before you start

API and MCP access require Light or above. Create a sandbox key in your workspace's API settings and keep it in your application's secret store. Share the documentation with your assistant, not your credentials or private documents.

Test documents send real emails with a test notice and carry a watermark stating that they are not legally binding. They do not count toward billable usage. Use addresses you control while developing.

No Signclad client library is published to npm, so `npm install` will not find one and an assistant that writes `import { createClient } from '@signclad/sdk'` is writing against something you cannot install. Call the API over plain HTTP, or generate a client from the OpenAPI schema — which is what the schema is there for.

## Smaller context windows

Start with [llms.txt](https://signclad.com/llms.txt), then load only the Markdown guides relevant to your workflow and the API schema. Each guide has a plain Markdown version at `/docs/markdown/{guide-name}.md`, such as [Getting started](https://signclad.com/docs/markdown/getting-started.md). Links inside the downloads are rewritten to absolute URLs, so they still resolve once the file is outside the website.

Downloaded files are snapshots. Download a fresh copy when revisiting an integration. For an assistant that should operate on documents directly, see the [MCP integration guide](https://signclad.com/docs/mcp/).

---

# Getting started

> Create a key, send your first document in test mode, and watch the events arrive. About ten minutes end to end.

Source: https://signclad.com/docs/getting-started/

This walks you from nothing to a signed document. Everything here runs against a sandbox key, so emails are marked as test documents, documents are watermarked, and nothing is billed. Use email addresses you control.

## 1. Get a key

Create an account and choose Light or above for API access, then open [Settings → API keys](https://app.signclad.com/app/settings/api-keys) and create a key. Sandbox keys are prefixed `sk_test_`, live keys `sk_live_`. Use the sandbox one for everything below.

The key identifies both your workspace and the mode. There is no separate "test mode" flag to remember and no environment variable to get wrong — if the key starts with `sk_test_`, the request is a test request.

## 2. Send a document

Signclad fetches your file from a URL, so a presigned S3 link, a public URL, or anything your server can hand out for a few minutes all work. You can also upload the bytes with `POST /files` first and pass the returned `file_id`. Documents and templates take PDF, `.doc` and `.docx` — up to 20 files per document, 25 MB each.

```bash
curl -X POST https://api.signclad.com/api/v1/documents \
  -H "X-Api-Key: $SIGNCLAD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Loan agreement",
    "subject": "Please sign your loan agreement",
    "message": "<p>Two signatures, about a minute.</p>",
    "reminders": true,
    "expires_in": 30,
    "metadata": { "loan_id": "48213" },
    "files": [
      { "name": "loan-agreement.pdf",
        "file_url": "https://files.example.com/loan-agreement.pdf?X-Amz-Expires=7200" }
    ],
    "recipients": [
      { "id": "signer-1", "name": "Jane Doe", "email": "jane@example.com" }
    ],
    "fields": [[
      { "api_id": "borrower_signature", "type": "signature", "recipient_id": "signer-1",
        "page": 1, "x": 375, "y": 206, "width": 180, "height": 44, "required": true },
      { "api_id": "borrower_date", "type": "date", "recipient_id": "signer-1",
        "page": 1, "x": 375, "y": 262, "width": 120, "height": 24,
        "lock_sign_date": true, "date_format": "MM/DD/YYYY" }
    ]]
  }'
```

The same call from Node (18+, no dependencies) and from Python with `requests`:

```js
import { randomUUID } from 'node:crypto';

const body = {
  name: 'Loan agreement',
  subject: 'Please sign your loan agreement',
  files: [
    { name: 'loan-agreement.pdf', file_url: 'https://files.example.com/loan-agreement.pdf' },
  ],
  recipients: [{ id: 'signer-1', name: 'Jane Doe', email: 'jane@example.com' }],
  fields: [[
    { api_id: 'borrower_signature', type: 'signature', recipient_id: 'signer-1',
      page: 1, x: 375, y: 206, width: 180, height: 44, required: true },
  ]],
};

const response = await fetch('https://api.signclad.com/api/v1/documents', {
  method: 'POST',
  headers: {
    'X-Api-Key': process.env.SIGNCLAD_API_KEY,
    'Idempotency-Key': randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(body),
});

if (!response.ok) throw new Error(`${response.status}: ${await response.text()}`);
const document = await response.json();
console.log(document.id, document.status); // "Created" — the transient value
```

```python
import os
import uuid

import requests

body = {
    "name": "Loan agreement",
    "subject": "Please sign your loan agreement",
    "files": [
        {"name": "loan-agreement.pdf", "file_url": "https://files.example.com/loan-agreement.pdf"}
    ],
    "recipients": [{"id": "signer-1", "name": "Jane Doe", "email": "jane@example.com"}],
    "fields": [[
        {"api_id": "borrower_signature", "type": "signature", "recipient_id": "signer-1",
         "page": 1, "x": 375, "y": 206, "width": 180, "height": 44, "required": True}
    ]],
}

response = requests.post(
    "https://api.signclad.com/api/v1/documents",
    headers={
        "X-Api-Key": os.environ["SIGNCLAD_API_KEY"],
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json=body,
    timeout=30,
)
response.raise_for_status()
document = response.json()
print(document["id"], document["status"])  # "Created" — the transient value
```

Two things about the response will look wrong if you are not expecting them, and both are deliberate:

- **`status` is `Created`**, whatever you passed for `draft`. It is a transient value. The settled status — `Draft` or `Sent` — appears on the next `GET`.
- **`files[].pages_number` is `0`** and `files[].status` is not yet `ready` — it reads `uploaded`, then `processing`. Ingest has not finished. The real page count arrives on the next `GET`.

Signing URLs in the response are valid immediately, so you can hand a recipient their link before ingest finishes.

## 3. Read it back

```bash
curl https://api.signclad.com/api/v1/documents/8f14e45f-ea8f-4b2c-9f0e-1b2c3d4e5f60 \
  -H "X-Api-Key: $SIGNCLAD_API_KEY"
```

Once the send job has run, `status` is `Sent`, `pages_number` is real, `files[].status` is `ready`, and each recipient carries a `status` of its own. Read it immediately after the create and you may still catch `Created` or `Sending`. Fields come back grouped by type rather than in the order you sent them, and `width` and `height` are decimal strings while `x`, `y`, and `page` stay numbers. That is the compatibility contract, quirks included.

## 4. Sign it

Test mode emails the recipients with a clear test notice. Open the link in the email or the recipient's `embedded_signing_url` and sign the watermarked test document. If you lose the URL, mint a new one rather than recreating the document:

```bash
curl -X POST \
  https://api.signclad.com/api/v1/documents/{id}/recipients/signer-1/signing_url \
  -H "X-Api-Key: $SIGNCLAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "expires_in_minutes": 60 }'
```

## 5. Watch the events

Create a webhook endpoint pointed at your receiver — or at the hosted inbox in **Settings → Webhooks**, which records requests so you can look at real payloads before writing any code.

```bash
curl -X POST https://api.signclad.com/api/v1/webhook_endpoints \
  -H "X-Api-Key: $SIGNCLAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://app.example.com/webhooks/signclad",
    "description": "Local development",
    "event_types": ["document_sent", "document_viewed", "document_signed", "document_completed"],
    "include_test_mode": true,
    "verify": true
  }'
```

`verify: true` sends a `ping` before the endpoint goes live and shows you the result: the endpoint starts paused and only activates if your receiver answers `2xx`. Without it the endpoint is active immediately and nothing is pinged. Note `include_test_mode` too — without it, test-mode documents produce no deliveries.

## 6. Download the evidence

When every signer has finished:

```bash
curl -L https://api.signclad.com/api/v1/documents/{id}/completed_pdf \
  -H "X-Api-Key: $SIGNCLAD_API_KEY" -o completed.pdf
```

Before that, this endpoint returns `404` — not `403`, and not an empty `200`. It is the one place where a `404` does not mean "no such document".

The completed PDF carries the audit page and a digital seal using a self-issued certificate. `audit_trail_url` on the document gives you the same evidence as signed JSON.

## Common questions

### Which languages does the Signclad eSignature API support?

Any language that can make an HTTPS request. Signclad is a plain REST API — JSON in, JSON out, one
`X-Api-Key` header — so curl, Node's `fetch`, Python's `requests`, PHP's Guzzle, Ruby's `Net::HTTP`,
and Go's `net/http` all work without a library. The samples above are Node and Python; the
[API reference](https://signclad.com/docs/api/) gives the request shape for every operation, and
[the OpenAPI document](https://signclad.com/openapi/signclad.v1.yaml) generates a typed client for most languages.
There is no published Signclad SDK package yet.

### Why is `status` still `Created` after I sent the document?

Because the create and send responses answer with a transient status, deliberately: `POST /documents`
answers `Created` and `POST /documents/{id}/send` answers `Draft`, whatever you passed. The settled
status — `Draft`, `Sent`, `Completed` — appears on the next `GET /documents/{id}`. Never branch on
the status in a create response; read the document back, or wait for the webhook.

### Does test mode send real email?

Yes. A sandbox key (`sk_test_`) delivers real messages to the recipients, marked as a test and
watermarked as not legally binding, and never bills. That means a send to an address you do not
control really bounces. Use addresses you own, or set `embedded_signing: true` — which already
defaults every recipient's `send_email` to `false` — to get signing links without any mail at all.
See [Sandbox and test mode](https://signclad.com/docs/sandbox-and-test-mode/).

## What to read next

- [Authentication and keys](https://signclad.com/docs/authentication/) — key types, rotation, and scopes.
- [Sandbox and test mode](https://signclad.com/docs/sandbox-and-test-mode/) — what test mode does and does not do.
- [Creating a document](https://signclad.com/docs/creating-a-document/) — every option on the create call.
- [Webhooks](https://signclad.com/docs/webhooks/) — signatures, health, and replay.
- [Errors and rate limits](https://signclad.com/docs/errors-and-rate-limits/) — the exact error shapes.

---

# Authentication and keys

> API keys, OAuth for applications acting on a workspace, signer sessions, and how each one is scoped, rotated, and revoked.

Source: https://signclad.com/docs/authentication/

Signclad has three ways to authenticate, and they never overlap. A signer session cannot call the management API; an API key cannot act as a signer.

## API keys

The default for server-to-server work.

```http
X-Api-Key: sk_live_9f2a...
```

| Prefix | Mode | Behaviour |
|---|---|---|
| `sk_live_` | Live | Bills, sends real email, subject to the normal rate limits. |
| `sk_test_` | Sandbox | Never bills. Delivers test emails to recipients. Subject to the same rate limits as live keys. |

A key belongs to one workspace. Every key acts with the same permissions — the admin capabilities of that workspace, which is what `GET /me` reports as its role — with one deliberate exception: a key cannot touch billing, so a leaked integration key cannot cancel the subscription or transfer ownership. There is no per-key `read` or `write` scope; narrow a credential by using a sandbox key, not by scoping a live one.

Keys are shown once at creation and stored hashed. A workspace holds at most 25 unrevoked keys.

Creating a key needs the API access your plan includes — Light and above — and creating a sandbox key needs the same. A sandbox key can create only sandbox keys, so the first live key has to come from the app or from another live key.

### Rotation

Rotation issues a new key and gives the old one a fixed 24-hour expiry, so you can deploy the new value before the old one stops. Both keys work during the overlap and both appear in the request log, so you can see when the last caller moved over. The rotate response carries the new plaintext and the old key's `stops_working_at`.

Rotation is not revocation, and the overlap is not adjustable. If a key leaks, revoke it: `DELETE /api_keys/{id}` stops it immediately. A key cannot revoke itself — that answers `409 self_revoke` — so revoke it with another credential or from the app.

### What a sandbox key may reach

A sandbox key is confined to an allow-list of route families, and anything outside it answers `403 sandbox_key_not_allowed`. Documents, templates, files, bulk sends, webhook endpoint configuration, the event catalog, its own keys and `/me` are in. The workspace address book, suppression list, webhook delivery logs and replay, data exports, members, billing, workspace settings and OAuth applications are out — they hold live data with nothing to filter test rows on.

## OAuth 2.0

For an application acting on behalf of a workspace that is not yours — an integration you distribute, or a product embedding Signclad for its own customers.

Authorization code with PKCE. PKCE is required and `S256` is the only accepted method — a request without `code_challenge_method=S256` is refused rather than defaulted. Discovery lives at `/.well-known/oauth-authorization-server`. The workspace being acted on needs API access, the same Light-and-above entitlement an API key needs.

Scopes:

| Scope | Grants |
|---|---|
| `documents:read` | Documents, recipients, fields, events, and completed files. |
| `documents:write` | Create, send, update, cancel, and delete documents. |
| `templates:read` | Templates and placeholders. |
| `templates:write` | Create, update, duplicate, and delete templates. |
| `webhooks:read` | Webhook endpoint configuration and delivery logs. |
| `webhooks:write` | Manage webhook endpoints. |
| `account:read` | The membership, account, and workspace. |
| `offline_access` | Issues a refresh token. Without it, an authorization lasts one access token. |

A write scope satisfies its read half, so asking for `documents:write` alone is enough to read documents too. Ask for the narrowest set that works.

Access tokens are bearer tokens, passed as `Authorization: Bearer <token>`, and live an hour. An authorization code lives ten minutes and is single use. Refresh tokens rotate on every use and the whole family is revoked if an old one is replayed.

## Signer sessions

A short-lived opaque bearer token held by the signer app, obtained by exchanging a signing link or an embedded signing URL and passing whatever gate the document has — a passcode or nothing. Only a hash of it is stored, like an API key.

- Thirty minutes from issue. It does not extend with use.
- Scoped to **one recipient of one document**. It cannot read another recipient's fields, let alone another document.
- Revoked by bumping the recipient's or the document's token version, which is what happens when a document is cancelled or a recipient reassigns.
- Accepted only by the `Signer` operations, and by nothing else.

You will not normally issue these yourself; they exist so that the signer app can be a normal client of the same API.

## Working out who you are

```bash
curl https://api.signclad.com/api/v1/me -H "X-Api-Key: $SIGNCLAD_API_KEY"
```

Returns the identity behind the credential: `user`, `role`, and an `account` object with the plan tier, the active template and user counts, and whether another template or document may be created right now. `workspace` is a **verbatim duplicate of `account`**, not a separate object — the real tenant id is `current_workspace_id`. For an API key there is no membership of its own, so `user` is the workspace owner and `role` is `admin`.

Useful as a health check and for showing "connected as" in your own settings screen.

## Keeping keys safe

- Never put a live key in client-side code. Embedded signing and the builders use short-lived URLs precisely so that you do not have to.
- Restrict who can create keys: only owners and admins can, and every key creation is recorded in the audit log.
- The request log at [Settings → API keys → Request log](https://app.signclad.com/app/settings/api-keys/log) keeps 30 days of method, path, status, latency, error code, IP, user agent, and request id per key. No request or response body is ever stored, and credential-shaped query parameters — anything containing `key`, `token`, `secret`, `password`, `passcode`, `signature`, `code` — are redacted before the row is written. Each entry comes with a `copy_as_curl` line that reproduces the shape of the request, with the key replaced by its display prefix.
- If a key leaks, revoke it rather than rotating it. Rotation always leaves the old value working for 24 hours.

## Related

- [Sandbox and test mode](https://signclad.com/docs/sandbox-and-test-mode/)
- [Errors and rate limits](https://signclad.com/docs/errors-and-rate-limits/)

---

# Sandbox and test mode

> Send test emails and sign watermarked documents without billing.

Source: https://signclad.com/docs/sandbox-and-test-mode/

Test mode exists so you can build and run a full integration — send, sign, complete, webhook, download — without usage charges. Recipients receive real emails explicitly marked as test documents. Use addresses you control.

## How a request becomes a test request

Two ways, and they agree:

1. **The key.** Any request with an `sk_test_` key is a test request, and nothing the caller sends can turn that off.
2. **The flag.** `test_mode: true` on a create makes that document a test document even with a live key.

There is nothing else to configure. If your code has an `if (env === 'staging')` branch deciding whether to set a flag, delete it and use a sandbox key instead.

Both routes need the plan entitlement that sandbox keys come with: Light and above. On Free, `test_mode: true` is refused.

## What test mode does

| | Test mode |
|---|---|
| Billing | Never counted. A test document never touches the monthly counters and can never be refused for being over them. |
| Email | Delivered to recipients with “This is a test document” in the message and `[TEST]` in the subject. |
| Signing | Works normally. Open the signing URL and sign. |
| Artifacts | Every page is watermarked “Not legally binding -- test mode,” including the completed PDF. |
| Webhooks | Delivered only to endpoints with `include_test_mode: true`. |
| Rate limit | The same buckets and the same numbers as live keys: 120/min general, 10/min for `POST`, `PUT` and `PATCH`, 120/min for `POST /files`. |
| Document limits | Unlimited. |

## Real delivery in test mode

Invitations, reminders, passcodes, and completed copies go to the intended recipients. Test emails include an explicit notice, and test documents are not legally binding. Invalid recipient addresses can bounce just as they do in live mode.

## What a sandbox key cannot reach

A sandbox key is not merely filtered to test rows; it is confined to a list of route families, and everything else answers `403 sandbox_key_not_allowed`. Documents, templates, files, bulk sends, webhook endpoint configuration, the event catalog, its own API keys and `/me` are allowed. The address book, the suppression list, webhook delivery logs and replay, the debug inbox, data exports, members, billing, workspace settings and OAuth applications are not — they hold live data with no test-mode column to filter on.

Webhook endpoints are allowed but partitioned: a sandbox key sees and can change only the endpoints a sandbox key registered, so the production callback is a `404` to a staging credential. Delivery is not partitioned — an endpoint a sandbox key registered still receives the live events it subscribed to.

A sandbox key also creates only sandbox keys. Asking it for a live key is a `422` on `mode`, and a live key reached by id is a `404`.

## Sending test events

Every webhook endpoint has a "send test event" action for each event type: `POST /webhook_endpoints/{id}/ping` with an `event_type` sends a realistic sample of that event, synchronously, and never counts towards the endpoint's health. Creating an endpoint with `verify: true` sends a plain `ping` first and activates the endpoint only if your receiver answers `2xx`. Both let you exercise a receiver before there is a real document to exercise it with.

## Moving to live

1. Create a live key — from the app or with another live key, since a sandbox key cannot mint one — and put it wherever your sandbox key was.
2. Register your production webhook endpoint with the live key. A sandbox key's endpoints stay visible only to sandbox keys.
3. Check `include_test_mode` on your webhook endpoints — most production endpoints should have it off.
4. Nothing else changes. The paths, bodies, statuses, and event names are identical.

## Related

- [Authentication and keys](https://signclad.com/docs/authentication/)
- [Webhooks](https://signclad.com/docs/webhooks/)
- [Migrating to Signclad](https://signclad.com/docs/migration/)

---

# Creating a document

> Every option on POST /documents — files, recipients, fields, settings, drafts, and the transient status that catches everyone once.

Source: https://signclad.com/docs/creating-a-document/

`POST /documents` is the single call that turns files into a document and sends it. Everything else on the sending side is a variation of it.

## The minimum

```json
{
  "name": "Loan agreement",
  "files": [
    { "name": "loan-agreement.pdf", "file_url": "https://files.example.com/loan-agreement.pdf" }
  ],
  "recipients": [
    { "id": "signer-1", "name": "Jane Doe", "email": "jane@example.com" }
  ],
  "text_tags": true
}
```

With `text_tags: true`, the fields come out of the document itself. Without it, pass a `fields` array.

## Sending the call

The same request in curl, Node, and Python. Everything else on this page is a property of the body
these three send.

```bash
curl -X POST https://api.signclad.com/api/v1/documents \
  -H "X-Api-Key: $SIGNCLAD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d @document.json
```

```js
import { readFile } from 'node:fs/promises';
import { randomUUID } from 'node:crypto';

const response = await fetch('https://api.signclad.com/api/v1/documents', {
  method: 'POST',
  headers: {
    'X-Api-Key': process.env.SIGNCLAD_API_KEY,
    'Idempotency-Key': randomUUID(),
    'Content-Type': 'application/json',
  },
  body: await readFile('document.json', 'utf8'),
});

if (!response.ok) {
  // 422 bodies are `{ "errors": { field: "message" | { code: "message" } } }`.
  throw new Error(`${response.status}: ${await response.text()}`);
}
const { id, status } = await response.json();
```

```python
import json
import os
import uuid

import requests

with open("document.json") as handle:
    body = json.load(handle)

response = requests.post(
    "https://api.signclad.com/api/v1/documents",
    headers={
        "X-Api-Key": os.environ["SIGNCLAD_API_KEY"],
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json=body,
    timeout=30,
)
if response.status_code >= 400:
    raise RuntimeError(f"{response.status_code}: {response.text}")
document = response.json()
```

Log `X-Request-Id` from the response headers on both paths. It is the one value support can trace.

## Files

Three ways to supply a file, and one document may mix them:

| Property | Use when |
|---|---|
| `file_url` | Your server can hand out a URL Signclad can fetch — a presigned S3 link, for example. Signclad fetches it once, through SSRF protection. |
| `file_base64` | The file is small and you would rather not host it. |
| `file_id` | You uploaded it first with `POST /files` (multipart). Good for large files and for reusing the same file across documents. |

Exactly one of the three per file — sending two is a `422` on `files`. Several files concatenate in order into one document, up to 20 of them, 25 MB each and 500 pages in total.

Formats: **PDF, `.doc` and `.docx`**, and nothing else. The type is sniffed from the bytes rather than taken from the name, so a file called `contract` is fine and a `.pdf` that is really a spreadsheet is not; anything outside those three is refused with "Only PDF and Word (.doc, .docx) files are supported."

A PDF that already carries form fields has the widgets Signclad can map to a field type imported as editable Signclad fields. Widget types it cannot map are flattened into the page appearance instead, and the file records a warning saying which.

## Recipients

```json
{
  "id": "signer-1",
  "name": "Jane Doe",
  "email": "jane@example.com",
  "role": "signer",
  "send_email": true,
  "send_email_delay": 0,
  "passcode": "4821",
  "subject": "Your loan agreement",
  "message": "Your copy of the agreement."
}
```

- `id` is **yours**. Fields reference recipients by it, and it comes back unchanged.
- Duplicate email addresses are accepted. One person signing in two roles is a real case, and recipients are rows rather than users.
- A recipient whose email matches the requester's is accepted too.
- `role: "cc"` marks someone who receives the completed document but does not sign. The default is `signer`.
- `signing_order` is **response-only**. Recipients are numbered by the order you send them, always, and `apply_signing_order` decides whether that order is enforced rather than whether it is reported. Sending a `signing_order` of your own changes nothing.
- `send_email` defaults to true on a normal document and false on an embedded one, and is honoured either way. `send_email_delay` holds an invitation for up to 60 minutes.
- `subject` and `message` override the document's for this one recipient. `language` is a document setting, not a recipient one.
- A passcode is at least 4 characters. Turning on `passcode_delivery.enabled` without a passcode stored or supplied is a `422`: it would produce a document nobody can open.

## Fields

`fields` is an array of arrays — one inner array per file, in the same order as `files`.

```json
{
  "api_id": "borrower_signature",
  "type": "signature",
  "recipient_id": "signer-1",
  "page": 1,
  "x": 375,
  "y": 206,
  "width": 180,
  "height": 44,
  "required": true
}
```

Coordinates are in **API units**, not PDF points: CSS pixels at 96 DPI, one unit being exactly 0.75 pt, with the origin at the top left of the page and `y` increasing downward. A US Letter page is 816 x 1056 units. Multiply by `0.75` to get points.

Types: `signature`, `initials`, `date`, `text`, `checkbox`, `dropdown`, `select`, and the autofill family — `autofill_name`, `autofill_first_name`, `autofill_last_name`, `autofill_email`, `autofill_company`, `autofill_phone`, `autofill_title`, `autofill_date_signed`. There is no bare `autofill` type and no `attachment` type; files a signer must upload are `attachment_requests`, not fields.

Field notes worth knowing:

- `api_id` is your stable handle. Use it to prefill values later and to read values back. Make it meaningful.
- `height` is capped at 200 units for `signature` and `initials` and 74 for everything else.
- `lock_sign_date: true` on a date field fills it at signing and refuses to be set. If you send a value anyway, Signclad ignores it and adds an entry to `warnings[]` rather than failing the request.
- Validation lives on text fields, and it is a plan feature: `validation` needs the entitlement that starts on Business, and a document that carries one on a lesser plan is refused with `not_available_on_plan`. The accepted values are `no_text_validation`, `numbers`, `letters`, `email_address`, `us_phone_number`, `us_zip_code`, `us_ssn`, `us_age`, `alphanumeric`, `us_bank_routing_number`, `us_bank_account_number`, and `custom` — which uses `validation_regex` and `validation_regex_error_message`.
- `date_format` is one of `MM/DD/YYYY`, `DD/MM/YYYY`, `YYYY/MM/DD`, `Month DD YYYY`, `MM/DD/YYYY hh:mm:ss a`.
- On the response, `width` and `height` come back as decimal strings while `x`, `y`, and `page` stay numbers.

## Document settings

| Field | Effect |
|---|---|
| `draft` | Keeps it editable and returns a document-level `embedded_edit_url` instead of sending. |
| `subject`, `message` | The invitation email. `message` accepts limited HTML. |
| `apply_signing_order` | Invite recipients in order rather than all at once. |
| `reminders` | A boolean. On by default, at 3, 6 and 10 days after sending. |
| `expires_in` | Days until the links stop working and the document is marked expired. 1 to 365. |
| `allow_decline`, `allow_reassign` | Whether a recipient may refuse or hand it on. Both default to true. |
| `language` | One of fifteen, per document: `en`, `fr`, `es`, `de`, `pl`, `pt`, `da`, `nl`, `it`, `ru`, `sv`, `ar`, `el`, `tr`, `sk`. |
| `embedded_signing` | Makes recipient URLs embeddable. |
| `custom_requester_name`, `custom_requester_email` | Send on behalf of someone else — the usual case when your product sends for its own users. |
| `api_application_id` | Applies that application's branding and allowed domains. |
| `metadata` | Up to 50 key/value pairs, returned unchanged. Values **must** be strings, at most 500 characters each. |
| `with_signature_page` | Appends a generated signature page with a field per signer. |
| `test_mode` | Marks it as a test document even with a live key. |

Conditional rules and attachment requests are plan features too, starting on Business, and at most 10 conditional rules per document.

Unknown properties are dropped silently. Almost no request is rejected for carrying a key this document does not define, and unknown keys are not echoed back either. The one exception is `recipients[].passcode_delivery.otp`, which is refused outright rather than ignored: it named a factor that was never minted or checked, and accepting it would let you configure something that does not exist.

## The response

```json
{
  "id": "8f14e45f-ea8f-4b2c-9f0e-1b2c3d4e5f60",
  "status": "Created",
  "files": [{ "file_id": "0a1b2c3d-...", "name": "loan-agreement.pdf", "pages_number": 0, "status": "uploaded" }],
  "recipients": [
    { "id": "signer-1", "status": "created", "signing_order": 1,
      "embedded_signing_url": "https://app.signclad.com/sign/embedded/9c8f2b1a4d6e?token=..." }
  ],
  "warnings": []
}
```

**Do not drive a state machine off this.** `status` is the transient `Created` whatever `draft` was, `pages_number` is `0`, and `files[].status` is whatever ingest has reached — `uploaded`, then `processing`, then `ready`. Read the document again for settled values. The same applies to `POST /documents/{id}/send` and `POST /document_templates/documents`, which both answer `Draft`.

## Safe retries

Put an `Idempotency-Key` on every create. It is scoped to the credential plus method plus path and kept 24 hours, so a retry after a timeout returns the original response instead of creating a second document. A request that is still in flight answers `409 idempotency_in_progress`, and the same key with a different body answers `422 idempotency_key_reused`.

A request that throws or answers `5xx` releases the key, so the retry you were told to make actually does the work.

## Editing a draft

`PATCH /documents/{id}` changes a draft's name, subject, message, settings, recipients, or fields.

Once a document is sent, its files and fields are frozen — that is what makes the revision manifest worth anything. Two corrections are still possible while it is `Sent`, `Viewed` or `Pending`: `PATCH /documents/{id}/recipients` fixes a recipient who has not started signing yet (a typo in an address, a passcode), and `PATCH /documents/{id}/authentication` changes the gate. A recipient who has already viewed or signed can have nothing but their passcode changed, and asking answers `409 document_not_active`.

## After sending

| Call | Does |
|---|---|
| `POST /documents/{id}/remind` | Nudges whoever has not signed. `reminded` in the response names who it reached, which can be nobody. |
| `POST /documents/{id}/cancel` | Stops it. Links die; the audit trail records why. |
| `POST /documents/{id}/complete` | Marks it complete manually, where your process allows. |
| `POST /documents/{id}/recipients/{rid}/reassign` | Moves it to the right person. |
| `POST /documents/{id}/recipients/{rid}/signing_url` | Fresh signing links for one recipient, no recreation. Optional `expires_in_minutes`, 1 to 1440, default 15. |
| `GET /documents/{id}/events` | The audit trail as structured data. |
| `GET /documents/{id}/completed_pdf` | The sealed file. `404` until every signer has finished. |

## Related

- [Templates and create-from-template](https://signclad.com/docs/templates/)
- [Text tags](https://signclad.com/docs/text-tags/)
- [Errors and rate limits](https://signclad.com/docs/errors-and-rate-limits/)

---

# Templates and create-from-template

> Building a template, filling its roles, prefilling fields, excluding placeholders, composing several templates, and replacing the file without redrawing fields.

Source: https://signclad.com/docs/templates/

A template holds a file, a set of roles, the fields belonging to those roles, and the document settings. Creating a document from one is a matter of saying who fills each role.

## Creating a template

```json
{
  "name": "Onboarding agreement",
  "draft": true,
  "text_tags": true,
  "files": [{ "name": "onboarding.pdf", "file_url": "https://files.example.com/onboarding.pdf" }],
  "placeholders": [{ "id": "borrower", "name": "Borrower" }],
  "fields": [[
    { "api_id": "borrower_signature", "type": "signature", "placeholder_id": "borrower",
      "page": 1, "x": 375, "y": 206, "width": 180, "height": 44 }
  ]]
}
```

`draft: true` returns an `embedded_edit_url` that opens the template builder, so a person can place fields visually rather than you computing coordinates. `PUT /document_templates/{id}` with `{ "draft": false }` publishes it, and unlike the create it answers the **settled** status.

Statuses: the create answers the transient `Created`; a later `GET` reads `Draft` or `Available`. Only an `Available` template can be used.

Field coordinates are API units — CSS pixels at 96 DPI, one unit being 0.75 PDF points, origin at the top left of the page. The same units the document API uses.

## Using a template

```json
{
  "template_id": "3f1c9a2e-6b7d-4c8e-9a0b-1c2d3e4f5a6b",
  "draft": false,
  "embedded_signing": true,
  "recipients": [
    { "id": "signer-1", "placeholder_name": "Borrower",
      "name": "Jane Doe", "email": "jane@example.com", "send_email": false }
  ],
  "exclude_placeholders": ["Co-borrower"],
  "template_fields": [
    { "api_id": "borrower_full_name", "value": "Jane Doe" },
    { "api_id": "borrower_start_date", "value": "2026-07-02T00:00:00Z" }
  ],
  "conditional_rules_mode": "append",
  "skip_invalid_fields": true,
  "metadata": { "loan_id": "48213" }
}
```

Send it to `POST /document_templates/documents`:

```bash
curl -X POST https://api.signclad.com/api/v1/document_templates/documents \
  -H "X-Api-Key: $SIGNCLAD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "3f1c9a2e-6b7d-4c8e-9a0b-1c2d3e4f5a6b",
    "draft": false,
    "recipients": [
      { "id": "signer-1", "placeholder_name": "Borrower",
        "name": "Jane Doe", "email": "jane@example.com" }
    ],
    "template_fields": [{ "api_id": "borrower_full_name", "value": "Jane Doe" }]
  }'
```

```js
import { randomUUID } from 'node:crypto';

const response = await fetch(
  'https://api.signclad.com/api/v1/document_templates/documents',
  {
    method: 'POST',
    headers: {
      'X-Api-Key': process.env.SIGNCLAD_API_KEY,
      'Idempotency-Key': randomUUID(),
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      template_id: '3f1c9a2e-6b7d-4c8e-9a0b-1c2d3e4f5a6b',
      draft: false,
      recipients: [
        { id: 'signer-1', placeholder_name: 'Borrower', name: 'Jane Doe', email: 'jane@example.com' },
      ],
      template_fields: [{ api_id: 'borrower_full_name', value: 'Jane Doe' }],
    }),
  },
);

if (!response.ok) throw new Error(`${response.status}: ${await response.text()}`);
const document = await response.json();
```

```python
import os
import uuid

import requests

response = requests.post(
    "https://api.signclad.com/api/v1/document_templates/documents",
    headers={
        "X-Api-Key": os.environ["SIGNCLAD_API_KEY"],
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "template_id": "3f1c9a2e-6b7d-4c8e-9a0b-1c2d3e4f5a6b",
        "draft": False,
        "recipients": [
            {
                "id": "signer-1",
                "placeholder_name": "Borrower",
                "name": "Jane Doe",
                "email": "jane@example.com",
            }
        ],
        "template_fields": [{"api_id": "borrower_full_name", "value": "Jane Doe"}],
    },
    timeout=30,
)
response.raise_for_status()
document = response.json()
```

Points worth knowing:

- **`placeholder_name` binds a recipient to a role.** Every field belonging to that role follows.
- **`exclude_placeholders`** drops a role by name, and its fields come off the document. This is how one template covers the single-signer and the co-signer case.
- **`template_fields`** prefills by `api_id`. Dates accept both ISO 8601 and bare `Y-m-d`; anything else is `invalid_date_format`, keyed by the `api_id` that failed.
- **`conditional_rules_mode`** is `replace`, `append`, or `none`.
- **`skip_invalid_fields: true`** drops entries that will not validate and lists them in `warnings[]` — as `template_field_skipped` — instead of failing the whole request. Without it, one bad value fails everything.
- **`files`** on this call are *appended* to the template's own files, never a replacement for them.
- The response status is the transient `Draft`. Read it back for the settled value.

## Composing several templates

Pass `template_ids` instead of `template_id`:

- Files concatenate in the order given.
- Placeholders with the same name merge into one recipient, so a packet of four templates is one signing session.
- Settings come from the first template unless the request overrides them.
- Field identity is the pair (source template, `api_id`). Every field in the response carries `template_id`, and conditional rules and checkbox groups resolve within their own source template.
- `template_fields` accepts `{api_id, value}` while the `api_id` is unique across the set, and requires `{template_id, api_id, value}` when it is not. An ambiguous bare reference is a `422` with `ambiguous_field_reference` and the candidates listed.

## Duplicating

```http
POST /document_templates/{id}/duplicate
{ "name": "Onboarding agreement (2027)" }
```

Copies the whole template — fields, coordinates, rules, groups, settings — and returns the new one. No reading and rebuilding.

## Template links

Publishing a template as a link gives you a public URL anyone can open to start their own copy. Each visitor's copy is a separate document with its own recipients, its own audit trail, and its own sealed file. The settings live on their own prefix — `GET` and `PUT /template_links/{template}` — and the feature starts on Light.

`POST /template_links/{template}/rotate` replaces the token, which is the only way to revoke a published link: the old URL stops working immediately, everywhere it was printed or pasted. Copies already in flight are ordinary documents and are unaffected.

## Replacing the file, keeping the fields

When the underlying document changes — legal edits a clause, the numbering shifts — you do not have to redraw the fields.

```http
PUT /document_templates/{id}/files/1
{
  "name": "loan-agreement-v2.pdf",
  "file_url": "https://files.example.com/loan-agreement-v2.pdf",
  "strategy": "anchors",
  "scale_to_page": true,
  "dry_run": true
}
```

| Strategy | Behaviour |
|---|---|
| `keep_positions` | Fields stay at the same coordinates. Right when only wording changed within lines. |
| `text_tags` | Fields are re-found from the tags in the new file. Right when the file is generated from a source that carries tags. |
| `anchors` | Each field is anchored to the text beside it and follows that text. Right when the layout moved. |

`anchors` is the default — it is the only strategy that works on fields nobody tagged. `scale_to_page` defaults to true. Send exactly one of `file_url`, `file_base64`, or `file_id`.

A dry run returns a report and changes nothing:

```json
{
  "revision": 7,
  "dry_run": true,
  "requires_review": true,
  "report": {
    "kept": [{ "api_id": "borrower_signature", "page": 1, "x": 375, "y": 206 }],
    "moved": [{ "api_id": "borrower_date", "page": 1, "x": 375, "y": 289,
                "previous_page": 1, "previous_x": 375, "previous_y": 262,
                "reason": "Anchor text moved down 27 points." }],
    "scaled": [],
    "orphaned": [{ "api_id": "witness_initials", "previous_page": 5,
                   "reason": "Page 5 does not exist in the new file." }]
  }
}
```

A field is never deleted by a replacement. One with nowhere to go is reported `orphaned` and left where it was, so a person can move it. `requires_review` is true when anything orphaned, or when a field travelled more than about half an inch.

Commit by repeating the call with `dry_run: false` and `expected_revision` set to the revision the dry run reported. If the template changed in between, the commit fails with `409 revision_mismatch` rather than applying a stale plan. Leaving `expected_revision` out means "apply this to whatever the template is now", which is the race the two-step design exists to prevent.

The same endpoint exists for drafts at `PUT /documents/{id}/files/{position}`. It never applies to a sent document.

## Listing and searching

```http
GET /document_templates?q=onboarding&archived=false&limit=50&cursor=...
```

Cursor-paginated, newest first, with the same filter vocabulary as documents: `status`, `label`, `updated_since`, `metadata`, `q`, `archived`, `test_mode`. `limit` caps at 100.

Revisions have their own pair: `GET /document_templates/{id}/revisions` lists them and `POST /document_templates/{id}/revisions/{number}/restore` puts one back.

## Related

- [Creating a document](https://signclad.com/docs/creating-a-document/)
- [Text tags](https://signclad.com/docs/text-tags/)
- [Embedded builders](https://signclad.com/docs/embedded-builders/)

---

# Text tags

> Put the fields in the document. Tag syntax, sizing, validation, and how to check a file before you send it.

Source: https://signclad.com/docs/text-tags/

Text tags let a document carry its own fields. Write a tag into the Word or PDF source, set `text_tags: true` on the create, and Signclad turns each tag into a field. The same syntax works for documents and templates.

This is the right approach when documents are generated by another system — a loan origination platform, a CRM, a mail-merge — because nobody has to open an editor and place boxes.

## Syntax

```
[type|modifier|modifier|...]
```

The first segment is the field type. The rest are modifiers in any order.

```
[sig|req|signer1]
[init|signer1]
[date|signer1|fmt:MM/DD/YYYY|lock]
[text|signer1|id:borrower_full_name|req]
[text|signer1|id:borrower_email|validate:email]
[check|signer1|id:consent_ach|req]
[drop|signer1|id:entity_type|opts:LLC,Corp,Individual]
[auto|signer1|value:name]
```

| Type | Field |
|---|---|
| `sig` | Signature |
| `init` | Initials |
| `date` | Date signed |
| `text` | Text |
| `check` | Checkbox |
| `drop` | Dropdown |
| `sel` | Select |
| `auto` | Autofill |

| Modifier | Meaning |
|---|---|
| `signerN` | Which recipient the field belongs to, by position. |
| `req` | Required. `opt` is the opposite, and is the default for a bracket tag. |
| `id:` | Sets the field's `api_id`. Give every field you intend to prefill or read one. |
| `label:`, `name:` | The label shown to the signer, and the internal name shown in the builder. |
| `lock` | On a date field, fills at signing and refuses a supplied value. |
| `fmt:` | Date format: `MM/DD/YYYY`, `DD/MM/YYYY`, `YYYY/MM/DD`, `Month DD YYYY`, or `MM/DD/YYYY hh:mm:ss a`. |
| `formula:` | A date formula, for example `sent_date + 10 days`. |
| `validate:` | `email`, `number`, `letters`, `phone`, `zip`, `ssn`, `age`, `alphanumeric`, `routing`, `bank_account`, or a regular expression. Anything unrecognised becomes a `custom` validation with that pattern. |
| `opts:`, `default:`, `other` | Options for `drop` and `sel`, which one is preselected, and whether the signer may type their own. |
| `value:` (or `prefill:`) | A prefilled value. On an `auto` tag it picks the source instead: `first_name`, `last_name`, `name`, `email`, `company`, `phone`, `title`, or `date_signed`. |
| `w:`, `h:` | Override the size the tag box would have given, in units. |
| `fixed` | Keep the drawn width instead of growing the box to fit the text. |

An `auto` tag without a supported `value:` is not a field at all — it is left in the document as literal text. So is any tag whose first segment is not a known type. Nothing rejects the document for it.

## Legacy compatibility

Signclad also accepts the positional `{{...}}` format used by imported templates, so they can move over without being rewritten:

```
{{signature:1:y:Please sign::borrower_signature:200:50}}
{{text:2:y:Full name::borrower_name:160:24:letters:y}}
{{date:1:y:Signed::signed_on:110:24:y:mm/dd/yyyy:sent_date + 10 days}}
{{af_e:2:n:::borrower_email}}
```

The positions are field type, signer number, required (`y` or `n`), label, prefill value, API ID, width, and height. Text fields may then specify validation and fixed width. Date fields may specify locked signing date, date format, and formula. Blank positions keep their defaults.

All legacy field names and short autofill aliases are accepted. Variables also work: define one with `{{set=a1:text:1:y:Age? }}` and reuse it with `{{a1}}`.

Use Signclad's bracket syntax for new templates. It names each modifier, so adding or removing one does not require a run of positional blanks.

## Sizing, and a deliberate improvement

The field takes the size of the tag box as it appears in the document, measured in **units** — CSS pixels at 96 DPI, one unit being 0.75 PDF points. Where a tag box is smaller than a field of that type can usefully be, Signclad applies a **minimum size for the type** instead of producing an unusably small field, anchored at the tag's top-left so the field grows right and down from where you put it.

| Type | Minimum |
|---|---|
| `sig` | 120 × 40 |
| `init` | 60 × 40 |
| `date` | 110 × 24 |
| `text` | 100 × 20 |
| `check` | 16 × 16 |
| anything else | 100 × 20 |

Practical guidance: give a signature tag roughly 180 × 44 units and a date tag roughly 120 × 24, and you will get exactly what you drew. `w:` and `h:` override the measured box outright, and the floor still applies afterwards. Height is capped at 200 units for `sig` and `init`, 74 for everything else.

## Making tags invisible

Tags remain part of the rendered page: nothing removes them. Colour the tag text to match its background in the source — white on white is the usual case — and it disappears from the output while still occupying exactly the space that sets the field's size. A small run inside a table cell is a reliable way to position a tag precisely.

Do that in the DOCX or the PDF before you upload. Signclad does not recolour tags for you.

## Checking before you send

There is no HTTP endpoint for this. The check lives in the MCP server as `validate_text_tags`, which reads a local DOCX, text-based PDF, or plain text — or a snippet of tag text — and parses it with the same syntax the API uses. Nothing is uploaded, so it works on a document you have not sent and on a workspace you have not connected. See [MCP](https://signclad.com/docs/mcp/).

It reports every tag it found, the field each one produces, the signers and `api_id`s the document expects, and a list of problems with the line each is on: an unknown field type, an unsupported modifier, a `signerN` below 1, an unknown validation or date format, a `drop` or `sel` with no options, a height over the maximum, a reference to a variable never defined with `set=`, a prefill on a signature field, and a duplicate `api_id`.

Two things it cannot tell you, because both need the rendered page: the field's page and coordinates, and whether a tag is large enough to avoid the minimum for its type. A scanned PDF has no text layer at all, and it says so plainly rather than reporting no tags.

One difference between the checker and the API is worth knowing. The checker calls a repeated `api_id` an error; the API does not fail on one — it keeps the first and suffixes the rest `_2`, `_3`. That is forgiving, and it also means a copy-pasted tag silently produces a field you cannot address by the name you expected.

## Combining tags with explicit fields

You can do both, and the explicit field wins. `fields` you pass are written during the create request; tag fields are imported afterwards, once the file has been converted and its text extracted, and a tag whose `api_id` already exists on the document is skipped. So naming a field in `fields` with the same `api_id` as a tag overrides that tag's position without editing the source document.

That import is also why fields from tags are not in the create response. They appear on the next `GET`, with the page count.

## Related

- [Creating a document](https://signclad.com/docs/creating-a-document/)
- [Templates and create-from-template](https://signclad.com/docs/templates/)

---

# Embedded signing

> Put the signer view inside your own product — URLs, the iframe, the message protocol, expiry, branding, and branding options.

Source: https://signclad.com/docs/embedded-signing/

Embedded signing puts the signer view in an iframe in your product, so your users never see a Signclad-branded page or leave your application.

## Getting a URL

Set `embedded_signing: true` when creating the document. Each recipient comes back with an `embedded_signing_url`:

```json
{
  "recipients": [
    { "id": "signer-1", "name": "Jane Doe", "email": "jane@example.com",
      "status": "sent",
      "embedded_signing_url": "https://app.signclad.com/sign/embedded/qN4vR7xJ2mLd...W8kZ" }
  ]
}
```

If you lose it, or it expires, mint a new one. You do **not** need to recreate the document:

```bash
curl -X POST \
  https://api.signclad.com/api/v1/documents/{id}/recipients/signer-1/signing_url \
  -H "X-Api-Key: $SIGNCLAD_API_KEY"
```

```json
{ "embedded_signing_url": "https://app.signclad.com/sign/embedded/7hB2pK9sVc4n...T1yQ",
  "signing_url": "https://app.signclad.com/sign/Lm3xD8fW5qZa...R6nJ",
  "expires_at": "2026-09-09T18:44:10Z" }
```

The token is sixty-four opaque characters and it is the **last path segment**, not a query parameter. Nothing about the document or the recipient is derivable from it.

Both forms come back on every call: `embedded_signing_url` for the iframe, `signing_url` for the hosted page you would put in your own email or a redirect. Regenerating supersedes the recipient's earlier links, so whatever you replaced stops working — which is the point of a regenerate button.

The embedded link is **single use** and has to be opened within **thirty minutes**; `expires_at` is that deadline. The hosted `signing_url` is reusable and lives as long as the document does. So mint the embedded one when the user asks to sign, not when you create the document — a URL that sat in your database for a week is a URL you have to handle expiring.

Also useful: `embedded_preview_url` on the document shows the whole document read-only, for a "review before signing" screen or for a party who is not a signer. It is `null` while the document is a draft and carries a URL once it has been sent. The URL carries its own read-only credential, so you can frame it for staff who have no Signclad account; treat it like any other signing link and do not publish it.

## Embedding it

```html
<iframe
  src="https://app.signclad.com/sign/embedded/qN4vR7xJ2mLd...W8kZ"
  allow="clipboard-read; clipboard-write"
  style="width: 100%; height: 800px; border: 0"
  title="Sign the agreement"
></iframe>
```

Give it real height. The signer view is a document; 800 pixels is a floor, not a target. That `allow` list is what the embed script puts on its own iframe by default (its `iframeAllow` option overrides it); nothing in the signer view asks for a camera or microphone, so do not delegate them — `clipboard-write` is the one the copy-a-link controls use.

The embed script appends `signclad_embedded_iframe=1` to the URL and starts a **20 second timer**. If `load` has not fired by then it raises `SC-document.error` with `errorCode: "request_timed_out"`, so a blocked iframe surfaces as an error rather than as a blank box forever.

## Messages

The iframe posts messages to the parent window. Listen and check the origin:

```js
window.addEventListener('message', (event) => {
  if (event.origin !== 'https://app.signclad.com') return;

  switch (event.data.type) {
    case 'SC-document.setId':          onReady(event.data); break;
    case 'SC-document.documentLoaded': hideSkeleton(); break;
    case 'SC-document.completed':      onSigned(event.data); break;
    case 'SC-document.declined':       onDeclined(event.data); break;
    case 'SC-document.closed':         closeModal(); break;
    case 'SC-document.error':          onError(event.data); break;
  }
});
```

The payload is a flat `{type, …}` object — the fields are on `event.data` itself, not on a nested `payload`.

| Message | Payload | When |
|---|---|---|
| `SC-document.setId` | `{id, apiAppStyles, newEditUrl, view}` | Once, as soon as the document is known. Nothing reaches you before this. |
| `SC-document.documentLoaded` | `{id}` | The document is rendered and interactive. |
| `SC-document.completed` | `{id, redirect, url}` | This recipient finished. Others may still be outstanding. |
| `SC-document.declined` | `{id, declineReason, url}` | This recipient declined, with the reason. |
| `SC-document.closed` | `{id}` | The user asked to close the embedded view. |
| `SC-document.clickedContinueBtn` | `{id, url}` | The user pressed the primary continue action. |
| `SC-document.error` | `{id, errorCode, errorMessage}` | Something went wrong. `errorCode` is stable; `errorMessage` is for humans. |
| `SC-Embedder.addLoader` / `.removeLoader` | `{}` | Show or hide your own loading overlay. |

For a signing view, `view` in `setId` is `recipient_side`.

An expired link does not get its own message: it arrives as `SC-document.error` with an error code, and the iframe shows a reason page. So does a session that has been revoked.

**Treat these as hints, not as truth.** A browser message is not a durable record: the tab may close before it fires. Webhooks are the source of truth for "did this get signed"; the messages are for updating your own UI promptly.

Your page can send messages back too — `SC-Embedder-SetAttr` with the options, `SC-Embedder.resizing`, `SC-Embedder.clickAway`, and `SC-document.completeSelfSigning`. The full table, including the flags `SetAttr` carries, is in [embedded builders](https://signclad.com/docs/embedded-builders/#messages-your-page--iframe).

## Branding

Create an API application and bind it to your key:

```json
{
  "name": "Acme Lending portal",
  "primary_color": "#1F6FEB",
  "button_text_color": "#FFFFFF",
  "link_text_color": "#1F6FEB",
  "buttons_border_radius": 8,
  "callback_urls": ["https://portal.acme.example"]
}
```

The logo is a separate upload — `POST /api_applications/{id}/logo` — not a URL in this body. It comes back on the application as a short-lived signed URL.

`callback_urls` entries are validated as **origins**: scheme and host, optionally a port, and nothing else. A bare host is read as `https`; a path, a query, or a wildcard is a `422` rather than a silent trim.

Pass `api_application_id` on the create and the embedded surfaces carry your branding. There is no embed allowlist to configure: an embedded page addresses your host using the origin the browser reports for your own first message, so framing works wherever you serve it from.

Branding resolves per value: the application first, then the workspace's own branding, then the Signclad default, so an application that sets only `primary_color` keeps the workspace's logo. Custom branding is plan-gated — on a plan without it the application's styles are ignored and the defaults render.

Use `custom_requester_name` and `custom_requester_email` so the document reads as coming from your customer rather than from you. Neither changes the display name on the invitation email, which stays the workspace's.

## Emails

An embedded document is silent by default. Your application is opening the iframe, so Signclad
does not also mail the recipient a "please sign" invitation, and it does not run the automatic
reminders on days 3, 6 and 10. Set `embedded_signing_notifications: true` on the create if you
want those anyway, in which case each recipient's own `send_email` still applies.

Two things are not covered by that default, and are worth knowing before you build your own:

- **A reminder you ask for is sent.** `POST /documents/{id}/remind` mails the recipient whatever
  `embedded_signing_notifications` is set to. The default is about prompts Signclad decides to
  send on its own; a call you made is not one of those. The response's `reminded` names who was
  actually reached, which can be nobody, so read it rather than the status code.
- **Everything that is not a prompt still goes out.** Passcodes, the completed copy, and the
  sender's own decline, bounce, complaint and expiry notices are unaffected. The switch that
  silences all mail to one person is their `send_email: false`.

A recipient is never reminded once they have finished, declined or been reassigned, and a `cc`
is never reminded at all — naming them explicitly does not change that.

## Expiry and errors

| Situation | What you get | What to do |
|---|---|---|
| The URL expired | `SC-document.error` with an expiry code, and the iframe shows a reason page | Mint a new URL |
| The document was cancelled | A reason page | Nothing; it is over |
| Another recipient must sign first | A waiting page | Nothing; they will be invited automatically |
| The recipient already signed | A completed page with the download | Nothing |

Signer sessions are thirty minutes, sliding, and scoped to one recipient of one document.

## Related

- [Embedded builders and the compatibility shim](https://signclad.com/docs/embedded-builders/)
- [Webhooks](https://signclad.com/docs/webhooks/)
- [Migrating to Signclad](https://signclad.com/docs/migration/)

---

# Embedded builders and the compatibility shim

> The document and template builders inside your product: the embed script, every message in both directions, the origin rules, and the message protocol.

Source: https://signclad.com/docs/embedded-builders/

The builders let your users prepare documents and templates without leaving your product: upload files, place fields, set recipients, and send. This page is the full contract between your page and the iframe, using the Signclad embed script and its message protocol.

## The shape of it

```
 your page (your origin)                       iframe (app.signclad.com)
 ┌───────────────────────────────┐             ┌────────────────────────────────┐
 │ <script src=".../embed.js">   │             │ Signclad embedded page         │
 │ new SigncladEmbed({url, …})   │──── src ───▶│  ?signclad_embedded_iframe=1   │
 │                               │             │                                │
 │  window.addEventListener      │◀── SC-* ────│  window.parent.postMessage(…)  │
 │    ("message", …)             │             │                                │
 │  iframe.contentWindow         │──── SC- ───▶│  window.addEventListener       │
 │    .postMessage(…)            │   Embedder  │    ("message", …)              │
 └───────────────────────────────┘             └────────────────────────────────┘
```

**Your host page never calls the Signclad API.** It has one URL — a signing link, an embedded signing link, or an embedded edit link — and everything after that happens between the page and the script over `postMessage`. Your server mints the URL; your browser code just frames it.

## Getting a URL

Create the document as a draft. The response carries a document-level `embedded_edit_url`:

```json
{
  "name": "Onboarding packet",
  "draft": true,
  "embedded_signing": true,
  "text_tags": true,
  "api_application_id": "5c1d9e7f-2a3b-4c5d-8e9f-0a1b2c3d4e5f",
  "files": [{ "name": "packet.docx", "file_url": "https://files.example.com/packet.docx" }],
  "recipients": [
    { "id": "signer-1", "name": "Jane Doe", "email": "jane@example.com", "send_email": false }
  ]
}
```

```json
{ "id": "8f14e45f-…", "status": "Created",
  "embedded_edit_url": "https://app.signclad.com/embed/document/Kp7wT2nR9vXc…" }
```

The token is sixty-four opaque characters and it is the last path segment, not a query parameter. Documents are at `/embed/document/<token>` and templates at `/embed/template/<token>` — both singular.

Templates work the same way:

```http
POST /document_templates
{ "name": "Onboarding agreement", "draft": true,
  "files": [...], "placeholders": [{ "id": "borrower", "name": "Borrower" }] }
```

When your user sends from inside the builder, the document sends. You do not call `send` yourself.

## Views

The builder opens narrowed to one job. `view` arrives in `SC-document.setId` and is one of:

| View | Shows |
|---|---|
| `document_builder` | Everything: files, recipients, fields, settings. |
| `template_builder` | The template equivalent. |
| `edit_files` | File management only — add, remove, reorder, replace. |
| `edit_recipients` | Recipients and signing order only. |
| `recipient_side` | The signer view, for embedded signing. |

Narrow views keep your own product's flow in charge. If your app already knows the recipients, open the file or field view and your user never sees a recipient form.

### The template builder's Sending tab

The template builder's right-hand panel has two tabs. **Roles & Fields** is the roles on the template and the fields on the page. **Sending** is what every document made from the template starts with — subject, message, expiry, reminders, the redirect after signing, whether a signer may decline or reassign, and the signing language. Setting them once on the template is the point: a use-template flow that asks for a subject line every time is a template that saved nobody anything.

If your application writes its own invitation email, hide the tab with `showSendingDefaults: false`:

```js
new SigncladEmbed({
  url: embeddedEditUrl,
  containerId: 'builder',
  showSendingDefaults: false,
}).open();
```

With the tab hidden, the builder leaves those settings exactly as the API has them rather than saving back what it never showed — whatever you set on the template through the API stays set. The option appends `sending_defaults=0` to the iframe URL, so a host that frames the URL itself can append that flag directly.

## Bootstrapping, step by step

1. The embed script appends `signclad_embedded_iframe=1` to the URL (plus `start=` and `type=` where the builder needs them) and loads it in an iframe. It starts a **20 second timer**; if `load` has not fired by then it raises `error` with `errorCode: "request_timed_out"`.
2. The page exchanges the token in its own URL for a session, holds the bearer token in memory and `sessionStorage`, and sends `Authorization: Bearer …` on every later call. **No cookies** — third-party cookies are partitioned or blocked in every current browser, and a cookie-based session would fail exactly where embedding matters.
3. The page fetches its own context — the view name, your branding, the allowed parent origins, whether the compatibility aliases are on, and the next edit URL. This request is between the page and Signclad; it is not something your host calls, though you will see it in the network panel.
4. The page posts `SC-document.setId`. **Nothing before this point is visible to your host.**

On a reload inside the iframe, step 2 reuses the session from `sessionStorage` rather than re-exchanging: an embedded link is single use, and a second exchange answers `410 link_already_used`.

## Messages: iframe → your page

Every message is `window.parent.postMessage(payload, targetOrigin)` where the payload is `{type, …}` and `targetOrigin` is your origin — never `"*"`.

| `type` | Payload | When |
|---|---|---|
| `SC-document.setId` | `{id, apiAppStyles, newEditUrl, view}` | Once, as soon as the document is known. |
| `SC-document.documentLoaded` | `{id}` | The document is rendered and interactive. |
| `SC-document.completed` | `{id, redirect, url}` | The signer finished, or the builder's send completed. `redirect` is a boolean; `url` is where to go when it is true. |
| `SC-document.declined` | `{id, declineReason, url}` | The signer declined. |
| `SC-document.closed` | `{id}` | The user asked to close the embedded view. |
| `SC-document.error` | `{id, errorCode, errorMessage}` | Anything you should know about. `errorCode` is stable and machine-readable; `errorMessage` is for humans. |
| `SC-document.clickedContinueBtn` | `{id, url}` | The user pressed the primary continue action. |
| `SC-Embedder.addLoader` | `{}` | Show your loading overlay. |
| `SC-Embedder.removeLoader` | `{}` | Hide it. |

```js
window.addEventListener('message', (event) => {
  if (event.origin !== 'https://app.signclad.com') return;

  switch (event.data.type) {
    case 'SC-document.setId':          onReady(event.data); break;
    case 'SC-document.documentLoaded': hideSkeleton(); break;
    case 'SC-document.completed':      onSent(event.data); break;
    case 'SC-document.declined':       onDeclined(event.data); break;
    case 'SC-document.closed':         closeModal(); break;
    case 'SC-document.error':          onError(event.data); break;
    case 'SC-Embedder.addLoader':      showOverlay(); break;
    case 'SC-Embedder.removeLoader':   hideOverlay(); break;
  }
});
```

**Treat these as hints for your own UI, not as the record.** A browser message is not durable: the tab can close before it fires. [Webhooks](https://signclad.com/docs/webhooks/) — `document_sent`, `document_completed`, `template_created` — are the source of truth.

### `setId` in detail

```js
{
  type: "SC-document.setId",
  id: "9c8f2b1a-…",            // the document (or template) id
  view: "document_builder",
  apiAppStyles: {
    primary_color: "#1B4DFF",
    button_text_color: "#FFFFFF",
    link_text_color: "#1B4DFF",
    buttons_border_radius: 6,
    logo_url: "https://…"      // short-lived signed URL, may be null
  },
  newEditUrl: "https://app.signclad.com/embed/document/…"  // edit views only
}
```

`apiAppStyles` is your API application's branding, verbatim. **Your page does not inject CSS across the origin boundary**; you configure an API application and the iframe styles itself from it.

### `newEditUrl` is how edit links renew

An embedded edit URL is **single use**. The page mints the *next* one and hands it to you inside `setId`; the embed script stores it as a property you read:

```js
const next = embed.newEditUrl; // a property, not a call
```

There is no host-side regeneration call in the browser. If you lose the value, mint another server-side:

```http
POST /documents/{id}/embedded_edit_url
POST /document_templates/{id}/embedded_edit_url
```

Both return `{ "embedded_edit_url", "expires_at" }`, and both mint a fresh single-use URL that retires the previous one. The document route only works while the document is still a **draft**: once it has been sent there is nothing left to build, and you get a `409` saying which state it is in.


## Messages: your page → iframe

| `type` | Payload | Meaning |
|---|---|---|
| `SC-Embedder-SetAttr` | All the embed options | Your configuration, sent once the iframe is listening. |
| `SC-Embedder.resizing` | `{width, height}` | Your container changed size. |
| `SC-Embedder.clickAway` | `{}` | The user clicked outside the modal. |
| `SC-document.completeSelfSigning` | `{}` | Finish a self-signing flow programmatically. |

### `SetAttr` flags

`SC-Embedder-SetAttr` carries the whole configuration in one message:

| Group | Keys |
|---|---|
| Booleans | `allowDecline`, `allowClose`, `allowDownload`, `showHeader`, `allowRedirect`, `iframeRedirect`, `allowShareLink`, `showSendButton`, `allowAddContacts`, `allowCC`, `allowRemoveContacts`, `showProgressBar` |
| Context | `isEmbedded`, `isEmbeddedModal`, `isLargeDevice` |
| Values | `signatureDefaultName`, `primaryColor`, `redirectionUrl`, `declineRedirectionUrl`, `requestingRedirectUrl` |

**Note the name.** `SC-Embedder-SetAttr` uses a hyphen where every other message uses a dot. That is what the vendored script sends, so it is what Signclad accepts. Do not "fix" it in your own code either.

## Origin rules

These are not optional on either side.

- The page **learns your origin from the browser.** `event.origin` is stamped by the browser on every message it delivers and cannot be forged by the sender, so the first message your embed script sends identifies your page. That origin is pinned for the rest of the session, and anything arriving later from a different one is ignored.
- The page **always passes a specific `targetOrigin`** on every outbound message, never `"*"`. Outbound payloads carry a fresh builder URL, which is a live credential.
- **Your listener must check too.** Compare `event.origin` against the Signclad origin before you read `event.data`. The snippet above is the minimum.

There is nothing to allowlist. Earlier versions asked you to register every origin that might frame a builder on your API application; a missing or stale entry produced a builder that looked and saved perfectly normally while Send, Close and your own options silently went nowhere, which is a bad trade for a list that never restricted framing in the first place.

Because nothing goes out until your page speaks first, an embed script that never sends its opening message will see no events at all. The bundled script sends it on iframe load, so this only bites a hand-rolled host.

## Loading state

A builder loads a PDF renderer and the document's pages. Give the user something immediately: the preparing state should be visible within 500 ms and the iframe interactive within three seconds. Render your own skeleton until `SC-document.documentLoaded` arrives rather than showing an empty rectangle, and honour `SC-Embedder.addLoader` / `removeLoader` for the moments the page asks for your overlay.

Give the iframe real height. Below roughly 700 pixels the builder is unpleasant to use.

## Related

- [Embedded signing](https://signclad.com/docs/embedded-signing/)
- [Templates and create-from-template](https://signclad.com/docs/templates/)
- [Webhooks](https://signclad.com/docs/webhooks/) and the [webhook event catalog](https://signclad.com/docs/webhook-events/)
- [Migrating to Signclad](https://signclad.com/docs/migration/)

---

# Webhooks

> Both signature schemes, the full event catalog, health states, retry schedule, the delivery log, and replay.

Source: https://signclad.com/docs/webhooks/

Webhooks are how you find out what happened without polling. Signclad's are built to be operated: you can tell when an endpoint is failing, see every attempt, and replay anything you missed.

## Creating an endpoint

```bash
curl -X POST https://api.signclad.com/api/v1/webhook_endpoints \
  -H "X-Api-Key: $SIGNCLAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://app.example.com/webhooks/signclad",
    "description": "Production receiver",
    "event_types": ["document_completed", "document_declined", "document_error"],
    "include_test_mode": false
  }'
```

The same call from Node and Python:

```js
const response = await fetch('https://api.signclad.com/api/v1/webhook_endpoints', {
  method: 'POST',
  headers: {
    'X-Api-Key': process.env.SIGNCLAD_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: 'https://app.example.com/webhooks/signclad',
    description: 'Production receiver',
    event_types: ['document_completed', 'document_declined', 'document_error'],
    include_test_mode: false,
  }),
});

if (!response.ok) throw new Error(`${response.status}: ${await response.text()}`);
const endpoint = await response.json();
// endpoint.secret is returned exactly once. Store it now.
```

```python
import os

import requests

response = requests.post(
    "https://api.signclad.com/api/v1/webhook_endpoints",
    headers={"X-Api-Key": os.environ["SIGNCLAD_API_KEY"]},
    json={
        "url": "https://app.example.com/webhooks/signclad",
        "description": "Production receiver",
        "event_types": ["document_completed", "document_declined", "document_error"],
        "include_test_mode": False,
    },
    timeout=30,
)
response.raise_for_status()
endpoint = response.json()  # endpoint["secret"] is returned exactly once.
```

The secret is shown once. Store it. If your receiver already has a signing key in its configuration, send your own as `secret` instead — at least 32 characters — and skip the deploy that would otherwise exist only to learn ours.

The endpoint is **active immediately** and no `ping` is sent. Add `verify: true` and it goes the other way: the endpoint is created paused, one `ping` is delivered, and it activates only if that lands. The ping's result comes back on the create response as `ping`.

Omit `event_types` to subscribe to everything, now and later; `["*"]` means the same thing, and `events` is accepted as a spelling of the same field. Add `api_application_id` to receive only events for documents created by one application.

## The payload

```json
{
  "event": {
    "id": "evt_01J9K3P2S5N7Q8R1T2V3W4X5",
    "hash": "6f4a9c2e8b1d3f5a7c9e0b2d4f6a8c1e3b5d7f9a0c2e4b6d8f0a2c4e6b8d0f2a",
    "time": 1789050255,
    "type": "document_completed",
    "sequence": 9,
    "related_signer": { "email": "jane@example.com", "name": "Jane Doe" }
  },
  "data": {
    "account_id": "9e0f1a2b-3c4d-5e6f-7a8b-9c0d1e2f3a4b",
    "workspace_id": "4d5e6f7a-8b9c-0d1e-2f3a-4b5c6d7e8f9a",
    "object": {
      "id": "8f14e45f-ea8f-4b2c-9f0e-1b2c3d4e5f60",
      "status": "Completed",
      "name": "Loan agreement",
      "completed_at": "2026-09-09T17:44:15Z",
      "completed_pdf_url": null,
      "audit_trail_url": null,
      "recipients": [
        { "id": "signer-1", "name": "Jane Doe", "email": "jane@example.com",
          "status": "completed", "signed_at": "2026-09-09T17:44:12Z", "bounced": false }
      ]
    }
  }
}
```

`data.object` is the same body `GET /documents/{id}` returns, plus `workspace_id` and `account_id`. That means the artifact URLs are `null` here, as they are everywhere else: a completed document's PDF comes from `GET /documents/{id}/completed_pdf`, and its audit trail from the same path with `?audit_only=true`. Fetch them when `document_completed` arrives rather than looking for a link in the payload.

Payloads are **snapshots** taken when the event happened. They never change, on a retry or a replay.

## Headers

| Header | Value |
|---|---|
| `X-Signclad-Signature` | `t=<unix>,v1=<hex hmac-sha256(secret, "<t>.<raw body>")>` |
| `X-Signclad-Event` | The event type. |
| `X-Signclad-Event-Id` | The stable `event.id`. Identical across retries and replays. **Dedupe on this.** |
| `X-Signclad-Delivery` | Delivery id, fresh per attempt. |
| `X-Signclad-Attempt` | 1-based attempt number. |

## Verifying: two schemes

### Body signature (use this)

```js
import crypto from 'node:crypto';

function verify(rawBody, header, secret, toleranceSeconds = 300) {
  const parts = Object.fromEntries(
    header.split(',').map((p) => p.split('=').map((s) => s.trim()))
  );
  const timestamp = Number(parts.t);
  if (!Number.isFinite(timestamp)) return false;
  if (Math.abs(Date.now() / 1000 - timestamp) > toleranceSeconds) return false;

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${rawBody}`)
    .digest('hex');

  // The header can carry several v1= values during a secret rotation.
  return header
    .split(',')
    .filter((p) => p.trim().startsWith('v1='))
    .some((p) => {
      const given = Buffer.from(p.trim().slice(3), 'hex');
      const want = Buffer.from(expected, 'hex');
      return given.length === want.length && crypto.timingSafeEqual(given, want);
    });
}
```

The same check in Python, against the raw request body your framework received:

```python
import hashlib
import hmac
import time


def verify(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
    parts = [piece.strip() for piece in header.split(",")]
    stamps = [piece[2:] for piece in parts if piece.startswith("t=")]
    if not stamps or not stamps[0].isdigit():
        return False
    timestamp = int(stamps[0])
    if abs(time.time() - timestamp) > tolerance:
        return False

    expected = hmac.new(
        secret.encode(),
        f"{timestamp}.".encode() + raw_body,
        hashlib.sha256,
    ).hexdigest()

    # The header can carry several v1= values during a secret rotation.
    return any(
        hmac.compare_digest(piece[3:], expected)
        for piece in parts
        if piece.startswith("v1=")
    )
```

Verify against the **raw body**, before any JSON parsing or middleware re-serialisation. Compare in constant time. The tolerance is five minutes.

During a secret rotation the header carries one `v1=` value per valid secret, so rotation needs no cutover on your side.

### Compatibility hash (legacy)

Endpoints registered through the compatibility `POST /hooks` route also include a legacy event hash:

```
event.hash === hex(HMAC-SHA256(key = <hook id>, data = "<event.type>@<event.time>"))
```

This is computed over the header line, not the body, so it does not attest to the payload you received. It exists so an existing integration keeps working unchanged. Move to the body signature when you can.

## The event catalog

Every event Signclad emits — with what makes it fire, how often, what arrives in
`data.object`, and whether it is wire-compatible or a Signclad addition — is on its own page,
generated from the OpenAPI document at build time so it cannot drift:

**[Webhook events →](https://signclad.com/docs/webhook-events/)**

Three cadences catch people out, so they are worth repeating here:

- `document_viewed` fires on **every** view, not just the first.
- `document_in_progress` fires **once**, the first time any value is saved.
- `document_signed` fires **per recipient**, so a two-signer document emits it twice.

## Delivery, retry, and ordering

- At least once. 10-second timeout. Any `2xx` counts as delivered.
- Retries at 1 m, 5 m, 15 m, 1 h, 3 h, 8 h, 24 h, 48 h with jitter of ±10% — nine attempts in all, the first plus eight retries, over about three and a half days.
- `Retry-After` is honoured in one direction only: it can push the next attempt out, up to the 48-hour ceiling, and it can never pull one in ahead of the schedule. A `410` pauses the endpoint immediately, keeping the events replayable rather than dropping them.
- Events are dispatched in per-document `sequence` order, **but a failing delivery never blocks later events.** Each retries independently.

So: dedupe on `event.id`, and where order matters, sort by `event.sequence` within a document rather than assuming arrival order.

Respond quickly and process asynchronously. A receiver that does its work before answering will hit the 10-second timeout and be retried, which is how duplicate processing happens.

## Health states

| State | Trigger | What happens |
|---|---|---|
| `healthy` | Deliveries land. | Nothing. |
| `degraded` | Failures for 15 minutes without a success (at least 3 in a row), or over 25% failures in an hour (minimum 20 deliveries) while the latest attempt is still failing. | Email to workspace admins, in-app banner, daily digest while it persists. |
| `failing` | 25 consecutive failures, or 100% over 24 hours. | Circuit breaker stops attempting and probes hourly. |
| `disabled` | 5 days of continuous failure. | Endpoint switched off, with a notice and one-click re-enable that offers to replay everything missed. |

A brief blip on your side, such as a burst of `503`s while you deploy, does not raise an alert: those deliveries are retried anyway. An endpoint leaves `degraded` once the latest attempt succeeds and the last hour is back under 25% failures, so one that fails intermittently stays `degraded` instead of flapping, and recovery after a busy outage can take up to an hour.

```http
GET /webhook_endpoints/{id}/health
```

```json
{ "state": "healthy", "consecutive_failures": 0,
  "success_rate_1h": 1, "success_rate_24h": 0.998, "p95_latency_ms": 210,
  "last_success_at": "2026-09-09T17:43:58Z",
  "last_failure_at": "2026-09-08T22:11:04Z",
  "last_failure_reason": "502 Bad Gateway", "pending_count": 0 }
```

## The delivery log

```http
GET /webhook_endpoints/{id}/deliveries?status=failed&cursor=...
```

Every delivery with its attempt timeline, the request headers and body, the response status and a body excerpt, and the latency of each attempt. Filter by event type, status, or document. Dead letters are kept 30 days.

## Replay

```http
POST /webhook_endpoints/{id}/deliveries/{delivery_id}/replay
```

Replay one delivery, a selection, or a date range, or resend everything that failed since a moment you choose. On a replay `event.id`, `event.time`, and the payload are unchanged; the signature timestamp, `X-Signclad-Delivery`, and `X-Signclad-Attempt` are fresh.

## Rotating a secret

```http
POST /webhook_endpoints/{id}/rotate_secret
```

Both secrets are valid during the overlap and the signature header carries a `v1=` value for each. Deploy the new secret, confirm deliveries verify, then end the overlap.

## Debugging before you have a receiver

Every workspace has a hosted inbox URL that records requests. Point an endpoint at it and look at real payloads before writing a line of code.

## Related

- [Webhook events](https://signclad.com/docs/webhook-events/) — the generated catalog, with cadence and compatibility per event.
- [Errors and rate limits](https://signclad.com/docs/errors-and-rate-limits/)
- [Sandbox and test mode](https://signclad.com/docs/sandbox-and-test-mode/)
- [Embedded builders and the compatibility shim](https://signclad.com/docs/embedded-builders/) — why browser messages are hints and these are the record.

---

# Errors and rate limits

> The exact error bodies for every status, the rate-limit buckets, the headers on every response, and how idempotency interacts with both.

Source: https://signclad.com/docs/errors-and-rate-limits/

These shapes are pinned by recorded fixtures because a client that branches on them cannot afford them to change. Where a shape looks odd, it is odd on purpose: it matches the compatibility target byte for byte.

## Errors

Every response — error or not — carries `X-Request-Id`, and a `request_id` header with the same value. Supply either header yourself and Signclad echoes it back, so your trace id and ours are the same string; otherwise it is a UUID. Some envelopes repeat it in the body as `request_id`: `409`s, `410`s, and the code-keyed `422` under `errors.base`. The field-validation `422` does not carry one — read the header.

### An unparseable body

There is no distinct status for this. A `Content-Type: application/json` request whose body is not valid JSON is read as an **empty body**, so it fails validation like an empty request would: `422`, with `errors.files` and `errors.recipients` telling you a field is missing rather than that your JSON is broken. If you get a `422` complaining about fields you are certain you sent, check that what you sent parses.

### 401 — bad or missing key

```json
{
  "message": "Missing or invalid authorization key",
  "meta": {
    "error": "api_key_unauthorized_error",
    "message": "Not valid authorization token",
    "messages": ["Not valid authorization token"]
  }
}
```

Note that `meta` carries `message` **and** `messages[]`, not just `error`.

### 403 — not allowed

```json
{
  "message": "Forbidden",
  "meta": {
    "error": "insufficient_permissions",
    "message": "You are not allowed to do this.",
    "messages": ["You are not allowed to do this."]
  }
}
```

`message` is always the bare `Forbidden`; `meta` is always present, so there is one branch to write rather than "some 403s carry a code and some do not". Codes you will meet include `insufficient_permissions`, `api_key_not_a_person`, and `sandbox_key_not_allowed`; some add keys of their own, such as `required_capability` and `role`.

Authenticated, but not permitted: insufficient role, a credential type the route refuses, a sandbox key outside its allow-list, or a signer acting out of turn. A plan that does not include the feature is a `422` under `errors.base`, not a `403`.

### 404 — no such record

```json
{
  "message": "Not found",
  "meta": {
    "error": "record_not_found",
    "message": "Couldn't find the document requested",
    "messages": ["Couldn't find the document requested"]
  }
}
```

`meta.message` names the resource: "document" for everything the compatibility surface also has — documents, templates, recipients, fields, files — and its own noun for Signclad's additions ("Couldn't find the API key requested", "Couldn't find the webhook endpoint requested").

**A `404` from Signclad is authoritative.** It means the record does not exist for your workspace. It is also what a record in *another* workspace answers, deliberately, so no id is ever confirmed by a permission error.

The one exception is `GET /documents/{id}/completed_pdf`, which answers `404` until every signer has finished, with a body byte-identical to a genuine `404`. Do not treat that as "document missing".

### 409 — wrong state

```json
{
  "message": "Document is no longer active",
  "meta": {
    "error": "document_not_active",
    "message": "Document is no longer active",
    "messages": ["Document is no longer active"],
    "state": "completed"
  },
  "request_id": "3f1c9a2e-6b7d-4c8e-9a0b-1c2d3e4f5a6b"
}
```

One envelope for every conflict: `message`, then `meta` with `error`, `message` and `messages[]`, then `request_id`. Whatever the domain adds — `state`, `expected_revision` — is strictly on top of that.

Codes you will see here: `document_not_active`, `document_finalizing` (the document is being sealed; nothing races the seal), `revision_mismatch`, `idempotency_in_progress`, `self_revoke`.

### 410 — gone

```json
{
  "message": "This signing link is no longer valid",
  "meta": {
    "error": "link_not_found",
    "message": "This signing link is no longer valid",
    "messages": ["This signing link is no longer valid"]
  },
  "request_id": "3f1c9a2e-6b7d-4c8e-9a0b-1c2d3e4f5a6b"
}
```

The link or session was revoked, superseded, used, or expired. The code is one of `link_not_found`, `link_revoked`, `link_expired`, `link_already_used`, `link_superseded`, and it is what the signer app switches on to pick a page. An unknown token and a revoked one answer identically on purpose: anything else would let a probe tell a real recipient id from a fabricated one.

### 422 — validation failed

This is the envelope worth studying. `errors` maps a field name to **a message string, or to an object keyed by an error code or a per-item key. Values are never arrays.**

```json
{ "errors": { "files": "At least one file should be present." } }
```

```json
{ "errors": { "recipients": { "unknown_recipient": "This document has no recipient with id signer-9." } } }
```

```json
{
  "errors": {
    "template_id": {
      "not_in_account": "There's no template with id 0000... in your account."
    },
    "recipients": {
      "recipient_1": {
        "unexisting_placeholder_name": "This placeholder_name is not present in the template(s): signer."
      }
    }
  }
}
```

Only the first message per attribute survives, so a leaf is a string and never a list. Note there is no `request_id` in this envelope — take it from the `X-Request-Id` header.

Per-field errors on `template_fields` arrive keyed by `api_id`:

```json
{ "errors": { "template_fields": { "borrower_start_date": { "invalid_date_format": "..." } } } }
```

That shape is what lets you fix one value and retry, instead of sanitising everything and resending.

If you would rather not fail at all, `skip_invalid_fields: true` drops the offending entries and reports them in `warnings[]`.

A refusal that belongs to the request as a whole rather than to one attribute arrives under `errors.base`, keyed by a machine-readable code, with a `request_id` alongside:

```json
{
  "errors": { "base": { "not_available_on_plan": "Conditional rules are not included on this plan." } },
  "request_id": "3f1c9a2e-6b7d-4c8e-9a0b-1c2d3e4f5a6b"
}
```

Codes here include `not_available_on_plan`, `account_read_only`, `template_read_only`, `document_limit_reached`, `unprocessable_entity`, and `file_rejected`.

One `422` is shaped differently again, because its attribute is a header rather than a body field:

```json
{
  "errors": { "Idempotency-Key": { "idempotency_key_reused": "This Idempotency-Key was already used with a different request body. Use a new key." } },
  "meta": { "error": "idempotency_key_reused" }
}
```

### 429 — rate limited

```json
{
  "message": "Too many requests. 429 Too Many Requests",
  "meta": {
    "error": "rate_limit_exceeded",
    "message": "Too many requests. 429 Too Many Requests",
    "messages": ["Too many requests. 429 Too Many Requests"]
  }
}
```

Wait `Retry-After` seconds. The message keeps the `429 Too Many Requests` substring that existing integrations match on.

## Warnings

`warnings[]` is where Signclad tells you it accepted something the compatibility target would have rejected. Warnings never fail a request.

```json
{
  "warnings": [
    { "code": "lock_sign_date_value_ignored",
      "message": "A value was supplied for borrower_date, which fills itself on signing. It was ignored.",
      "pointer": "/fields/0/1/value" }
  ]
}
```

Codes include `lock_sign_date_value_ignored`, `field_skipped` and `template_field_skipped` (what `skip_invalid_fields` drops), `field_api_id_collision`, `pre_signed_content_superseded`, and `no_text_tags_found` on a file replacement. Log them: a warning today is often a bug in your mapping that would have been a `422` elsewhere.

## Rate limits

Per minute, per credential, and the bucket is chosen from the request **method**, not from a list of endpoints:

| Bucket | Limit | Applies to |
|---|---|---|
| General | 120/min | Every `GET`, `HEAD` — and every `DELETE`. |
| Creates and mutations | 10/min | Every `POST`, `PUT` and `PATCH`, with one exception below. |
| Uploads | 120/min | `POST /files`. Each file in a batch is its own request, and uploading must not spend the budget for creating the document. |
| Unauthenticated | 50/min | Requests with no resolved credential, keyed by IP. A request that never matched a route lands here too, so probing for paths is not free. |

`DELETE` counts as general on purpose: the tight bucket exists to slow document *creation* down, and a client cleaning up after a failed batch should not exhaust its create budget doing so.

Sandbox keys use the same buckets and the same limits as live keys.

**A failed create still charges the create bucket.** A run of `422`s will exhaust it, so fix validation before retrying in a loop.

There is no separate bucket for test mode.

### Headers, on every response

| Header | Meaning |
|---|---|
| `x-ratelimit-limit` | The bucket's limit. |
| `x-ratelimit-remaining` | What is left in this window. |
| `x-ratelimit-reset` | **An ISO 8601 timestamp**, e.g. `2026-09-09T20:56:00+00:00`. Not a seconds count. |
| `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset` | The standard headers, added alongside. `RateLimit-Reset` **is** in seconds. |
| `Retry-After` | On `429`, in seconds. |
| `X-Request-Id` | On every response. Quote it when you ask us about a request. |

The difference between the two reset headers catches people. If your client parses `x-ratelimit-reset` as a number, it will get `NaN`.

### Backing off

Respect `Retry-After`. Where it is absent, exponential backoff with jitter, capped at a minute. Never retry a `422` unchanged — the input is wrong and the create bucket is being spent on it.

## Idempotency

`Idempotency-Key` on any write, scoped to the credential — API key or OAuth token — plus method plus path, kept 24 hours. A browser session has no stable actor to scope it to, so the header is ignored there.

- A retry with the same key and the same body returns the original response, including its original status, with `Idempotent-Replay: true` on it.
- A request that is still in flight answers `409 idempotency_in_progress`.
- The same key with a different body answers `422 idempotency_key_reused`. It is never a silent overwrite.
- A request that fails with a `5xx`, or throws, **releases** the key, so the retry you were told to make actually does the work. Only a completed response is stored.
- Use one key per logical operation: a UUID generated when your job starts, not when the HTTP call is made, so a retried job reuses it.

## A practical client checklist

- Read `X-Request-Id` into your logs on every response, success or failure — or send your own and have it echoed.
- Branch on `meta.error` for the envelopes that have one, and on the code key under `errors.base` for the rest. Never on the human-readable `message`.
- Treat `404` from `completed_pdf` as "not ready", and `404` from anything else as "does not exist".
- Never parse `x-ratelimit-reset` as a number.
- Put an idempotency key on every create.
- Log `warnings[]`.

## Related

- [Creating a document](https://signclad.com/docs/creating-a-document/)
- [Webhooks](https://signclad.com/docs/webhooks/)

---

# MCP

> Connect an MCP client to Signclad: the endpoint, the OAuth sign-in, the tool list, the guardrails, and what shows up in the audit trail.

Source: https://signclad.com/docs/mcp/

Signclad runs a Model Context Protocol server so an assistant can send documents, check what is outstanding, and read audit trails, with the same permissions and limits as any other client.

## Connect

One URL, and nothing to install:

```
https://api.signclad.com/mcp
```

Add it to your client as a remote or custom MCP server. There is no package to download: Signclad hosts the server, so there is no local copy to keep up to date and no version of it that can fall behind the API.

The first connection signs you in. Your client discovers the sign-in page from the endpoint, you sign in to Signclad in a browser, and you approve which workspace the assistant may act in and what it may do. Your client stores the resulting token, so you never paste an API key into a config file.

To end a connection, remove the server in your client and revoke the authorization with `DELETE /v1/oauth/authorizations/{id}`; `GET /v1/oauth/authorizations` lists what is connected. Revoking takes effect within sixty seconds and touches no other integration.

| Client | Where to add it |
|---|---|
| Claude | Settings → Connectors → Add custom connector |
| Claude Code | `claude mcp add --transport http signclad https://api.signclad.com/mcp` |
| Cursor | Settings → MCP → Add server, as an HTTP server |
| Anything else | Wherever it takes a remote or Streamable HTTP MCP server URL |

To try things without sending real documents, connect from a sandbox workspace: its documents are watermarked and excluded from billing. Sandbox emails are still delivered, so use addresses you control.

## Tools

Generated from the same OpenAPI document as the SDKs and the reference, so a tool schema cannot drift from what the API accepts.

| Tool | Does | Needs `confirm` |
|---|---|---|
| `upload_file` | Upload a local file and return its ID | no |
| `send_document` | Create and send from files | yes |
| `create_document_from_template` | Assign recipients and fields, then send | yes |
| `list_documents` | Filter and search documents | no |
| `get_document` | Read a document, including fields | no |
| `get_document_status` | Check signing progress | no |
| `download_completed_pdf` | Get the completed PDF | no |
| `remind` | Email recipients who have not finished | yes |
| `cancel_document` | Stop signing | yes |
| `list_templates` | List templates and placeholders | no |
| `get_template` | Read placeholders and field IDs | no |
| `create_template_link` | Create a public template link | no |
| `get_audit_trail` | Read document events | no |
| `validate_text_tags` | Validate local PDF or DOCX tags | no |
| `list_webhook_endpoints` | List subscriptions and receiver health | no |
| `get_webhook_health` | Diagnose webhook delivery problems | no |

## Resources and prompts

Documents and templates are exposed as MCP resources, so an assistant can read one without calling a tool: `signclad://documents/{id}`, `signclad://templates/{id}`, and the listings `signclad://documents`, `signclad://documents?status={status}`, and `signclad://documents?q={q}`. Every tool result carries a `resource_uri` so the two halves join up.

Two prompts ship with the server:

- **`send-for-signature`** ("Send something for signature") walks from a file or a template to a sent document, asking for the recipients it does not have. It takes optional `what` and `who` arguments.
- **`whats-waiting-on-me`** ("What's waiting on me") lists outstanding documents grouped by who is holding them up, optionally narrowed to one `email`.

## Guardrails

An assistant sending contracts is a real risk. These are not optional:

- **Use sandbox keys for development.** Test documents are watermarked and excluded from billing, but emails are delivered.
- **Confirm before sending.** Sending, reminding, and cancelling require `confirm: true`. Show the preview and ask for approval before calling again.
- **The key decides, not the tool.** Every tool the server registers is offered to the assistant; what it can actually do is whatever the API key behind the connection can do, checked on the server the same way any other client is. There is no client-side widening.
- **Files travel as upload URLs**, never as base64 in tool arguments, so document contents never pass through a model's context window.
- **Provenance is recorded.** Every request the server makes carries `X-Signclad-Source: mcp`, and a document created that way is stamped `source: mcp`, so "did a person or an assistant send this" has an answer. It is a label, never a permission: it changes nothing about authorization, billing, or rate limits.
- **Same limits as anything else.** The same rate limits, plan allowances, and permission matrix. MCP is not a back door.

## A worked example

> **You:** Send the standard NDA to jane@example.com, and use the sandbox.
>
> **Assistant:** calls `list_templates`, finds "Mutual NDA", calls `create_document_from_template` with `confirm: false` to preview the recipients and fields, shows you what it will send, then calls it again with `confirm: true`.
>
> **You:** What is waiting on me?
>
> **Assistant:** calls `list_documents` filtered to `status=Sent`, groups by the recipient who has not signed, and offers `remind` per document.

## Troubleshooting

| Symptom | Cause |
|---|---|
| The client asks you to sign in again and again | The connection was revoked, or the token expired and your client did not refresh it. Remove the server from the client and add it back. |
| Tools appear but every call is refused | The connection is to a workspace on a plan without API access, or the scopes you approved do not cover what was asked. Check it under **Settings → Connected applications**. |
| `send_document` returns a confirmation prompt every time | Working as intended. The assistant must pass `confirm: true` explicitly. |
| No email arrives | Check the recipient address and delivery status. Test mode sends real emails too. |
| Rate limited quickly | Creates and mutations share a 10-a-minute bucket, on sandbox and live keys alike. `upload_file` is the exception: uploads have their own 120-a-minute bucket, so a batch of files does not spend the sending budget. |

## Related

- [Authentication and keys](https://signclad.com/docs/authentication/)
- [Sandbox and test mode](https://signclad.com/docs/sandbox-and-test-mode/)
- [The MCP overview page](https://signclad.com/mcp/)

---

# Migrating to Signclad

> Move a DocuSign, Dropbox Sign, or PandaDoc integration to the Signclad eSignature API: what maps to what, when a base-URL swap is enough, and the order to do it in.

Source: https://signclad.com/docs/migration/

Move your integration in stages: test document creation and signing, recreate your templates, then switch new documents to Signclad.

## Configure your integration

Create an API key in [Settings → API keys](https://app.signclad.com/app/settings/api-keys). API access requires Light or above.

```sh
SIGNCLAD_BASE_URL=https://api.signclad.com/api/v1
SIGNCLAD_API_KEY=sk_test_...
```

Use the [API reference](https://signclad.com/docs/api/) to map your existing requests and responses to Signclad. Verify recipient roles, field coordinates, signing order, metadata, and webhook handling before sending live documents.

## Test the full signing flow

Create a test document, send it to addresses you control, sign it, and download the completed PDF. Test mode sends real emails with an explicit test notice. Documents are watermarked as not legally binding and excluded from billing.

Register a webhook endpoint with `include_test_mode: true` and verify the request signature. Confirm that your integration handles repeated events without repeating work.

## Recreate templates

Upload your original files and recreate the recipients, fields, and settings in Signclad. Store the new template IDs alongside your internal records. Test each template before switching it into production.

See [Templates](https://signclad.com/docs/templates/) and [Text tags](https://signclad.com/docs/text-tags/).

## Switch new documents

Use a live key for production. Direct new signing requests to Signclad and let documents already sent through your previous provider finish there. Keep the provider and document ID on each internal record so status updates reach the correct document.

Archive completed PDFs and audit records before closing your previous account. Cancel and recreate unfinished requests only when that is appropriate for the parties involved.

## When a base-URL swap is enough

Signclad's `/api/v1` is wire-compatible with one existing third-party eSignature API — the
**compatibility target** described in the [compatibility reference](https://signclad.com/docs/compatibility/). If that
is the API you are on today, the migration really is two lines: point the base URL at
`https://api.signclad.com/api/v1` and use a Signclad key. Paths, request fields, response fields,
status strings, error envelopes, and webhook event names are all preserved, quirks included.

If you are coming from any other provider, the swap does not apply and this is a port: the concepts
line up closely, the field names do not. The sections below map the concepts so you know what you
are looking for in the [API reference](https://signclad.com/docs/api/).

## From DocuSign

| DocuSign | Signclad |
|---|---|
| Envelope | Document — `POST /documents` |
| `envelopeId` | `id` (UUID) |
| Recipients: signers, carbon copies, certified deliveries | `recipients[]`, each with your own `id`; copy-only parties are `copied_contacts[]` |
| Recipient `routingOrder` | `signing_order` on the recipient, with `apply_signing_order: true` on the document |
| Tabs (`signHere`, `dateSigned`, `text`, `checkbox`) | `fields[][]` entries with `type` `signature`, `date`, `text`, `checkbox` |
| Anchor text (`anchorString`) | [Text tags](https://signclad.com/docs/text-tags/) — `text_tags: true`, then `[sig\|signer1\|req]` in the file |
| Templates and template roles | Templates and `placeholders[]`; a role is filled by `placeholder_name` on the recipient |
| Composite templates | `template_ids[]` on `POST /document_templates/documents` — several templates composed into one document |
| Connect webhooks | [Webhook endpoints](https://signclad.com/docs/webhooks/) with `event_types[]` and an HMAC body signature |
| Envelope status `sent` / `delivered` / `completed` | Document status `Sent` / `Viewed` / `Completed` — **capitalised** |
| Combined document download | `GET /documents/{id}/completed_pdf` — `404` until every signer has finished |

Authentication is the biggest structural difference: there is no account-scoped base URI to
discover and no OAuth token to refresh. One `X-Api-Key` header, and the key identifies the
workspace and the mode. Field coordinates are absolute, in units of 0.75 pt from the top-left of
the page, rather than anchor-relative offsets — or skip coordinates entirely and use text tags.

## From Dropbox Sign

| Dropbox Sign | Signclad |
|---|---|
| Signature request | Document — `POST /documents` |
| `signature_request_id` | `id` |
| `signers[]` with `order` | `recipients[]` with `signing_order` |
| `file_url[]` / `file[]` | `files[]` with `file_url`, `file_base64`, or a `file_id` from `POST /files` |
| `send_with_template` | `POST /document_templates/documents` with `template_id` |
| Template signer roles | `placeholders[]` on the template, bound by `placeholder_name` |
| `custom_fields` / prefill | `template_fields: [{ api_id, value }]` |
| Text tags (`[sig\|req\|signer1]`) | Text tags — Signclad's own syntax is nearly identical, and the compatibility target's positional syntax is accepted too |
| `test_mode: 1` | `test_mode: true` on the create body, or — better — a sandbox key (`sk_test_`), which makes every document from that key a test one and takes the flag out of your code path. |
| Callbacks with `event_hash` | Webhook endpoints. Signclad emits a compatibility hash *and* a real body signature; verify the body signature. |
| `is_complete` / `is_declined` booleans | A single `status` string, plus per-recipient `status` |

API keys move over as a header rather than HTTP Basic auth, and every response carries
`X-Request-Id` and the rate-limit headers — the lowercase `x-ratelimit-*` trio the compatibility
target sends, plus the additive seconds-based `RateLimit-*` trio most client libraries look for.

## From PandaDoc

| PandaDoc | Signclad |
|---|---|
| Document | Document |
| `Authorization: API-Key <key>` | `X-Api-Key: <key>` |
| Recipients with `role` | `recipients[]` with `placeholder_name` matching a template role |
| Template + tokens | Template + `template_fields` prefill by `api_id` |
| `document.uploaded` → `document.draft` polling | The transient `Created` status on the create response, settled on the next `GET` — same idea, one hop shorter |
| `document.completed` webhook | `document_completed` |
| Download `/documents/{id}/download` | `GET /documents/{id}/completed_pdf` |
| Content-authoring blocks | Not a Signclad concept. Signclad signs the files you supply — PDF, DOCX, images, HTML — and places fields on them. |

PandaDoc's proposal and quoting features have no Signclad equivalent. If you use PandaDoc purely to
collect signatures on files you already generate, the port is small; if you author content inside
it, keep authoring there and send the rendered PDF to Signclad.

## Recipient and role vocabulary

Whatever you are coming from, three rules hold:

- **Recipient `id` is yours.** You choose the string, fields reference recipients by it, and it comes
  back unchanged. Do not wait for the server to hand you a recipient id.
- **A template role is a `placeholder`.** Recipients bind to it by `placeholder_name`, and inherit
  every field belonging to that role.
- **A finished recipient is `completed`, never `signed`** — and recipient statuses are lowercase
  while document statuses are capitalised. See the
  [compatibility reference](https://signclad.com/docs/compatibility/).

## Verify before retiring the old integration

- Every active template has a tested Signclad template ID.
- New documents use the production key and intended recipients.
- Webhook signatures are verified and repeated events are handled safely.
- Completed PDFs and audit records remain accessible.
- No in-flight documents depend on credentials you are about to revoke.

## Related

- [Compatibility reference](https://signclad.com/docs/compatibility/) — the measured wire behaviour, including the quirks.
- [Getting started](https://signclad.com/docs/getting-started/)
- [Sandbox and test mode](https://signclad.com/docs/sandbox-and-test-mode/)
- [Webhooks](https://signclad.com/docs/webhooks/)
- [Embedded signing](https://signclad.com/docs/embedded-signing/)

---

# Compatibility reference

> Measured wire behaviour Signclad reproduces on purpose: status casing, transient create statuses, the "t" checkbox literal, the 0.75 pt coordinate unit, and the error envelopes — with the quirks it deliberately does not reproduce.

Source: https://signclad.com/docs/compatibility/

Signclad's `/api/v1` is wire-compatible with an existing third-party eSignature API, here called
**the compatibility target**. Every operation that is not marked `x-signclad-extension: true` in
[the OpenAPI document](https://signclad.com/openapi/signclad.v1.yaml) has the same path, method, request fields,
response fields, status strings, error envelopes, and webhook event names. A working client against
that API works against Signclad after changing two things: the base URL and the API key.

This page is the behavioural half of that promise — the part OpenAPI cannot express. It was
measured, not inferred: recorded against the compatibility target's live API in test mode, then
reproduced and pinned by Signclad's own test suite. If you are porting an integration, read this
before you read anything else; most of what breaks in a migration is on this page.

## Conventions

| Item | Signclad |
|---|---|
| Base URL | `https://api.signclad.com/api/v1` |
| Auth | `X-Api-Key: <token>` — sandbox keys are prefixed `sk_test_`, live keys `sk_live_` |
| Trailing slashes | Every path routes with and without one. `/documents/{id}` and `/documents/{id}/` return byte-identical bodies. |
| Unknown request keys | Silently dropped. Never rejected, never echoed back. Every request body is `additionalProperties: true`. |
| Success codes | `200` on GET/PUT/PATCH, `201` on create/send/remind, `204` on DELETE |
| Rate limits | **120/min** general, **10/min** creates and mutations, **50/min** unauthenticated. Failed creates still charge the create bucket. Two details are easy to trip on: `DELETE` is charged to the **general** bucket, not the tight one — the fixtures recorded `x-ratelimit-limit: 120` on every delete — and `POST /files` has its own **120/min** upload bucket, so a batch of files cannot exhaust the create budget before you send anything. |
| `x-ratelimit-reset` | An **ISO 8601 timestamp**, not a seconds count. The additive `RateLimit-Reset` is in seconds. |
| Pagination | The compatibility surface paginates only bulk-send documents: `limit` 1–50 (default 10), `page` ≥ 1, with `current_page`, `next_page`, `previous_page`, `total_count`, `total_pages`. Extension list endpoints are cursor-paginated instead. |
| IDs | UUIDs for server objects. Recipients, placeholders, and field `api_id`s are **caller-supplied strings**. |
| `metadata` | Up to 50 pairs. Keys under 40 characters, values under 500, values must be strings. |

## Statuses

Document and template statuses are **capitalised**. Recipient statuses are **lowercase**. They are
not the same vocabulary, and no amount of wishing makes them one.

- Documents: `Draft, Created, Sending, Sent, Pending, Viewed, Completed, Manually completed, Declined, Canceled, Bounced, Blocked, Error, Expired`.
- Templates: `Created, Draft, Available`. Only an `Available` template can spawn a document.
- Recipients: `created, draft, sent, viewed, completed, declined, bounced`. A finished recipient is
  **`completed`**, never `signed`.

### Create and send answer with a transient status

`POST /documents` and `POST /document_templates` answer `"Created"` regardless of what you passed
for `draft`. `POST /documents/{id}/send` and `POST /document_templates/documents` answer `"Draft"`.
The settled status appears only on the next `GET`.

This catches every integration once. If your code reads `status` off a create response and decides
anything from it, it is reading a placeholder. Read the record back, or wait for the webhook.

## Field serialisation on the wire

These are the details that make a naive port fail its first test:

- **`width` and `height` come back as strings** (`"200.0"`, `"50.0"`). `x`, `y`, and `page` are
  numbers.
- **A checked checkbox serialises as `"t"`**, the Postgres boolean literal — not `true`.
- **`files[].pages_number` is `0` in the create response** and carries the real count on the next
  `GET`. Page counting is asynchronous. The extension field `files[].status` is `processing` until
  ingest finishes.
- **`GET` reorders fields by type.** The create response echoes your request order; a later `GET`
  regroups the same fields by field type. Never key off array index — use `api_id`.
- **There is no document-level `embedded_signing_url`**, not even on a document with exactly one
  embedded signer. Only `recipients[].embedded_signing_url` exists.
- **`signing_url` is regenerated on send.** A recipient URL captured from a draft response is dead
  once the document is sent. Mint a fresh one rather than caching it.
- **`completed_pdf_url` is not returned on the document object**, even when the document is
  `Completed`. Fetch `GET /documents/{id}/completed_pdf` for the bytes.

## Coordinates

The origin is the **top-left of the visible page, with y increasing downward**, and
**1 API unit = 0.75 PDF points** — CSS pixels at 96 DPI, so a US Letter page is 816 × 1056 units.
The signing viewer lays the page out at exactly that size and positions each field at its API
`x`/`y` 1:1.

Size limits: signature and initials fields up to 200 units tall, every other field up to 74.

> The compatibility target's own completed-PDF stamper measures 0.7528125 pt per unit — 0.37%
> larger, up to about 2.3 pt of drift across a letter page. That is a rendering wart, not the
> intended model. Signclad implements 0.75 and does not reproduce the drift, so a field lands in the
> same place in the signing view and in the sealed PDF.

## Error envelopes

`401` — a JSON body, not a plain string:

```json
{
  "message": "Missing or invalid authorization key",
  "meta": {
    "error": "api_key_unauthorized_error",
    "message": "Not valid authorization token",
    "messages": ["Not valid authorization token"]
  }
}
```

`404` — and `GET /documents/{id}/completed_pdf` before completion returns exactly this, byte for
byte. There is no marker distinguishing "not finished yet" from "no such document", so a retry loop
must treat `404` on that endpoint as "not ready", not as "gone":

```json
{
  "message": "Not found",
  "meta": {
    "error": "record_not_found",
    "message": "Couldn't find the document requested",
    "messages": ["Couldn't find the document requested"]
  }
}
```

`422` — `{"errors": {…}}`, where each value is either a **string** or a **nested object keyed by an
error code** (or by a per-item key, then a code). **No arrays appear anywhere.** Model it as
`string | { [code_or_item]: string | object }`:

```json
{ "errors": { "files": "At least one file should be present." } }
```

```json
{ "errors": { "recipients": { "duplicated_emails": "These emails are duplicated: dup@example.com." } } }
```

```json
{ "errors": { "template_fields": { "tdate1": { "invalid_date_format": "DateField value must be in Iso8601 format." } } } }
```

The last one is keyed by the field's `api_id`, then by the error code, and `Iso8601` is capitalised
exactly so. `template_fields` dates need a full ISO 8601 value (`2026-07-02T00:00:00Z`); a bare
`Y-m-d` is rejected. The accepted value comes back rendered through the field's `date_format`.

See [Errors and rate limits](https://signclad.com/docs/errors-and-rate-limits/) for the full catalogue, including the
Signclad-only fields added alongside these.

## Test mode does not suppress email

Test mode excludes a document from billing and watermarks it as not legally binding. It does **not**
stop mail going out. A send to an address that does not exist really bounces: the *document* moves
to `Bounced` while the recipients stay `sent` with `bounced: true`. `send_email: false` on a
non-embedded document is echoed back as `false` and the mail still goes — the flag is not an
indicator of delivery.

The only genuinely mail-free send is `embedded_signing: true` together with `send_email: false`.
Use addresses you control for everything else. [Sandbox and test mode](https://signclad.com/docs/sandbox-and-test-mode/)
covers the rest.

## Webhook events

The preserved event names are `document_created`, `document_sent`, `document_viewed` (every view,
not just the first), `document_in_progress` (once), `document_recipients_updated`,
`document_signed` (per recipient), `document_completed`, `document_expired`, `document_canceled`,
`document_declined`, `document_bounced`, `document_error`, `template_created`, and
`template_error`.

The compatibility payload is:

```json
{
  "event": { "hash": "…", "time": 1789050255, "type": "document_completed",
             "related_signer": { "email": "jane@example.com", "name": "Jane Doe" } },
  "data": { "object": { "…": "the full document or template" }, "account_id": "…" }
}
```

`hash` is `hex(HMAC-SHA256(key = webhook id, data = "<type>@<time>"))`. It authenticates nothing
about the body: there is no body signature and no timestamp tolerance in that scheme. Signclad
accepts it for compatibility and adds a real one — `X-Signclad-Signature`, an HMAC over the raw
body with a timestamp — which is what you should verify against. Signclad's `data` also carries
`workspace_id` beside `account_id`, and its events carry a stable `event.id` to dedupe on.

[Webhooks](https://signclad.com/docs/webhooks/) has both schemes in full, and
[Webhook events](https://signclad.com/docs/webhook-events/) is the complete catalogue, generated from the
specification, with every additive event marked as such.

## Text tags

Signclad's preferred syntax is `[type|modifier|modifier]`, for example
`[sig|signer1|req|id:borrower_signature]`.

For migration, the compatibility target's positional syntax —
`{{type:signer:required:label:prefill:api_id:width:height}}`, with blanks keeping defaults
(`{{signature::y}}`) — is also accepted, including its long and short type names, its text and date
trailing options, and its variables (`{{set=a1:text:1:y:Age}}` followed by `{{a1}}`). Both formats
may appear in the same file. Enable either with `text_tags: true` on the document or the template.
See [Text tags](https://signclad.com/docs/text-tags/).

## What Signclad deliberately does not reproduce

Compatibility is not bug-for-bug. These are the intentional divergences:

- **The coordinate drift.** 0.75 pt per unit everywhere, in the viewer and in the sealed PDF.
- **Excluding a role that has fields.** `exclude_placeholders` naming a role with assigned fields is
  a `422` rather than a silent drop of the recipient and its fields.
- **A single bad prefill failing the whole request.** Send `skip_invalid_fields: true` and invalid
  `template_fields` entries are reported in `warnings[]` instead.
- **Unsigned webhooks.** The compatibility hash is still emitted; a real body signature is emitted
  alongside it.
- **Silent webhook failure.** Endpoints carry health states, a delivery log, and replay.

## Related

- [Migrating to Signclad](https://signclad.com/docs/migration/) — the staged plan, and per-vendor mapping.
- [Creating a document](https://signclad.com/docs/creating-a-document/) — every option on the create call.
- [API reference](https://signclad.com/docs/api/) — the generated reference, one page per endpoint group.