# SignSealer documentation

> Every page of the SignSealer docs (https://signsealer.com/docs) as Markdown, in the order the docs list them.
> The API is at https://api.signsealer.com; the OpenAPI description is https://signsealer.com/openapi.json.

---

Source: https://signsealer.com/docs (SignSealer API documentation)

# SignSealer API documentation

Signatures, and the evidence behind them. One API for waivers, rental agreements, NDAs and contracts.

What makes an electronic signature enforceable under ESIGN and UETA is evidence of five things. Cryptography is how that evidence is kept tamper-evident, and SignSealer uses it throughout; it is the record it protects that a court reads.

- **Intent** — the signer meant this act to be their signature.
- **Consent** — they agreed to do business electronically, *before* signing.
- **Association** — the signature is attached to this record and no other.
- **Attribution** — it can be shown to be them.
- **Retention** — the record can be accurately reproduced later.

Courts have thrown signatures out for missing the fourth. So SignSealer records each of the five as its own event, hashes the exact text into every one, chains the trail so nothing can be edited afterwards, and seals the finished document so that a single changed byte shows, with the time of sealing fixed by an independent RFC 3161 timestamp authority.

## What that means in practice

- Consent is recorded as its own event, before the signature is accepted — not alongside it, because a system that records both in the same instant cannot show that consent came first.
- The rendered text is stored on the document and hashed into every event. A document edited after signing no longer matches, and we say so.
- A published template cannot be edited. Revising it makes a new version, because editing one changes what people signed last week.
- The trail is append-only. A record that can be edited is a record of what somebody was willing to leave behind.

## Where to start

- [How-to videos](https://signsealer.com/guides): Short films of each part of SignSealer, from the first day to the API, each with its guide.
- [Quickstart](https://signsealer.com/docs/quickstart): Send a document for signature in four calls, with curl or the Node client.
- [Node client](https://signsealer.com/docs/sdk): @signsealer/sdk: no dependencies, retries with idempotency keys, the API's own error sentences.
- [AI assistants (MCP)](https://signsealer.com/docs/mcp): Connect Claude, ChatGPT, Codex or your editor, and send and check documents by asking.
- [Templates and versions](https://signsealer.com/docs/templates): Create, publish and revise the text people sign, over the API, with every version kept.
- [Signing inside your product](https://signsealer.com/docs/embedding): The signing page in a frame on your own site, and the events it sends you.
- [Waivers and workflows](https://signsealer.com/docs/waivers): A public form, a QR at the counter, a kiosk: people start their own document.
- [Signing a PDF](https://signsealer.com/docs/pdf): A lease with initials in the margin: the file kept whole, the boxes on the page, the signed copy still theirs.
- [Reservations and packets](https://signsealer.com/docs/packets): Several documents about one booking, several people, one link, one ready state.
- [Webhooks](https://signsealer.com/docs/webhooks): Signed events with a retry ladder, so your system hears back without polling.
- [Platforms and partners](https://signsealer.com/docs/partners): Embedding signing in your own product, and sharing in the revenue of every business you bring.

## How it fits together

```text
  your application ──── POST /v1/documents ──────▶  SignSealer API
        ▲                                                │
        │                                    mints one link per signer
        │                                                │
        │                              email · text · QR · kiosk · your own message
        │                                                │
        │                                                ▼
        │                                           the signer
        │                                  reads · consents · answers · signs
        │                                                │
        │                                                ▼
        │                          append-only trail  +  certificate  +  sealed PDF
        │                                                │
        └──────── signed webhook: signing.completed ─────┘
```

Every arrow is in the reference. The signer's page is ours and loads no script; what your application sees is JSON in and a signed event out.

## Recipes, by outcome

- [Send a signing request](https://signsealer.com/docs/quickstart) — template, publish, prepare, send.
- [Change a template people have already signed](https://signsealer.com/docs/templates) — revise, publish, and ask them to sign again.
- [Show the signing page inside your app](https://signsealer.com/docs/embedding) — an embedded signer and a framed link.
- [Put a waiver behind a QR code or a link on your site](https://signsealer.com/docs/waivers) — a public workflow.
- [Take waivers on a tablet at the counter](https://signsealer.com/docs/waivers) — the kiosk.
- [Get every guest on a booking to sign before check-in](https://signsealer.com/docs/packets) — a packet with a ready state.
- [Handle a minor and a guardian](https://signsealer.com/docs/packets) — roles in a packet, the guardian judged on the day.
- [Download the evidence after signing](https://signsealer.com/docs/evidence) — the package and the sealed PDF.
- [Verify a certificate](https://signsealer.com/docs/evidence) — without an account, from the code and the document.
- [Hear when a document completes](https://signsealer.com/docs/webhooks) — and verify the event's signature.
- [Send and check documents from Claude, ChatGPT or Codex](https://signsealer.com/docs/mcp) — the MCP server.

## Done in the dashboard

Some things you will look for in the API are done by a person in the dashboard, and have no route. This is where each one is, and what the API sees of it.

| What | Where | What the API sees |
| --- | --- | --- |
| Sending one agreement to a list of people, from a CSV file or a pasted list: a column for the name, one for the email and one for each blank, up to 250 rows, and every row checked before any is sent. | [Send to a list](https://app.signsealer.com/send/list) | A document for each row, each with its one signer, listed by `GET /v1/documents` and reported to your webhooks like any other. To send a list from your own system, prepare and send a document for each person. |
| The activity log: every send, void, setting changed and key issued in the account, in order and append-only, each entry sealed to the one before it and the newest re-checked when the page opens. Owners and admins see it unless a person's permissions say otherwise. | [Activity](https://app.signsealer.com/activity) | Nothing. No route reads it. |
| The words a signer reads: the signing request by email and by text, the reminder by email and by text, the confirmation by text, the signed copy, the renewal reminder and the link for somebody added to a booking, each in the business's own words with blanks such as `{{link}}`. | [Messages](https://app.signsealer.com/settings/messages) | No route sets or reads them, and a send carries no wording of its own: whatever starts a document, its messages go out in the words set here. |
| Creating, changing and deleting a workflow: the template it runs, its roles (the participant, any fixed signers, and their order), how long a link lives, when to remind, its public address and its questions; and for a public address, its checks before it goes live, the email check and its limits ([Waivers and workflows](https://signsealer.com/docs/waivers), "A signing link on your own website"). | [Forms & QR](https://app.signsealer.com/workflows) | `GET /v1/workflows` lists them, with `signer_roles`, `sequential`, `public_slug`, `email_check`, the link's limits (`stop_after_signed`, `closes_on`, `once_within_days`), `closed`, why a link takes no more signatures, and `needs_attention`, the check a live link fails. `POST /v1/workflows/{id}/start` starts one and `GET /v1/workflows/{id}/qr` draws its public address. No route creates, changes or deletes one. |
| Documents for bookings: which documents a booking owes and who signs each one, from which bookings, with a default for the rest. A connected booking system has its own on its page; the bookings sent through the API have theirs. | [Documents for bookings](https://app.signsealer.com/integrations/documents) | `PUT /v1/subjects` builds the packet from them, and `GET /v1/packets/{id}` shows who owes what ([Reservations and packets](https://signsealer.com/docs/packets)). No route lists or changes them. |

Whether SignSealer itself is up is not in the API either. [status.signsealer.com](https://status.signsealer.com) shows it, and `https://status.signsealer.com/status.json` is the same as JSON, with no key, cached for a minute: `all_operational`, each component's `state` with ninety days of checks, and the incidents.

---

Source: https://signsealer.com/docs/quickstart (Quickstart)

# Quickstart

Four calls: create a template, publish it, prepare a document, send it.

Watch it done: [Connect your software: the API, the SDK and the docs](https://signsealer.com/guides/your-first-api-call) (2:38)

## 1. Create a template

Placeholders are `{{like_this}}`, and every one of them has to be declared. Publishing checks that, so a contract cannot ship with an unfilled placeholder in it.

```
curl https://api.signsealer.com/v1/templates \
  -H "Authorization: Bearer $SIGNSEALER_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "code": "rental-agreement",
    "name": "Short-term rental agreement",
    "kind": "contract",
    "variables": ["guest_name", "property", "arrival"],
    "body": "This agreement is between Harbour Rentals and {{guest_name}} for {{property}}, arriving {{arrival}}."
  }'
```

## 2. Publish it

The create answers `{"template_id": "…"}`. Publishing that version freezes its text. From then on it is immutable and `POST /v1/templates` with the same code is refused — revise it instead (`POST /v1/templates/{id}/revise`), which makes version 2 and leaves version 1 exactly as the people who signed it saw it. [Templates and versions](https://signsealer.com/docs/templates) has the whole of it.

```
curl -X POST https://api.signsealer.com/v1/templates/$TEMPLATE/publish \
  -H "Authorization: Bearer $SIGNSEALER_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
```

## 3. Prepare a document

The rendered text is stored on the document, not a reference to the template. That is what retention means: the template can change, and the whole point of versioning it is that it might.

```
curl https://api.signsealer.com/v1/documents \
  -H "Authorization: Bearer $SIGNSEALER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template_code": "rental-agreement",
    "values": { "guest_name": "Dana Reyes", "property": "River Bend Cabin", "arrival": "3 October" }
  }'
```

## 4. Send it

You get one link per signer, once. The tokens are never stored — only their hashes — so a database dump is not a set of signing links, and a lost link is replaced rather than looked up: `POST /v1/documents/{id}/signers/{signer}/remind` sends a fresh one.

Each signer needs an `email`, a `phone`, or both. Given both, the same link goes out twice — by mail and by text — because a person who does not check one inbox checks the other. A text goes only where the business holds consent for `signing.link`; where it does not, the email still goes and the reason is on the evidence trail.

A new business sends to a few people an hour at first, and to more as it is trusted ([Limits and paging](https://signsealer.com/docs/limits)); past that the send is `429` and nobody on it is sent anything. Every message is read before it leaves, so the answer means the links were made, not that they arrived.

```
curl https://api.signsealer.com/v1/documents/$DOC/send \
  -H "Authorization: Bearer $SIGNSEALER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"signers":[{"email":"dana@example.signsealer.com","phone":"+16155550142","full_name":"Dana Reyes"}]}'
```

## The same in Node

`@signsealer/sdk` has no dependencies and runs anywhere `fetch` does. It adds the idempotency key itself and retries only the failures worth retrying.

```
import { SignSealer } from "@signsealer/sdk";

const signsealer = new SignSealer({ apiKey: process.env.SIGNSEALER_KEY! });

const { template_id } = await signsealer.createTemplate({
  code: "rental-agreement", name: "Short-term rental agreement", kind: "contract",
  variables: ["guest_name", "property", "arrival"],
  body: "This agreement is between Harbour Rentals and {{guest_name}} for {{property}}, arriving {{arrival}}.",
});
await signsealer.publishTemplate(template_id);

const { document_id } = await signsealer.prepareDocument({
  template_code: "rental-agreement",
  values: { guest_name: "Dana Reyes", property: "River Bend Cabin", arrival: "3 October" },
  external_ref: "RES-88213",   // yours; every webhook about it carries it back
});

const { links } = await signsealer.send(document_id, [
  { email: "dana@example.signsealer.com", phone: "+1 615 555 0142", full_name: "Dana Reyes" },
]);
```

## The same in Python

No client library yet; the API is small enough that `requests` is the client. Send your own `Idempotency-Key` on the writes, and retry only `429` and `500`.

```
import os, uuid, requests

API = "https://api.signsealer.com"
headers = {"Authorization": f"Bearer {os.environ['SIGNSEALER_KEY']}"}

def post(path, body):
    r = requests.post(API + path, json=body, timeout=15,
                      headers={**headers, "Idempotency-Key": str(uuid.uuid4())})
    r.raise_for_status()
    return r.json()

doc = post("/v1/documents", {
    "template_code": "rental-agreement",
    "values": {"guest_name": "Dana Reyes", "property": "River Bend Cabin", "arrival": "3 October"},
})
links = post(f"/v1/documents/{doc['document_id']}/send", {
    "signers": [{"email": "dana@example.signsealer.com", "phone": "+16155550142", "full_name": "Dana Reyes"}],
})["links"]
```

> **Then what?** Add a [webhook](https://signsealer.com/docs/webhooks) and wait for `signing.completed`. Polling works and is the wrong shape: a completion is an event, and the event carries everything you need to act without a second call.

---

Source: https://signsealer.com/docs/authentication (Authentication)

# Authentication

A bearer key, scoped to what it may do.

```
Authorization: Bearer mk_live_1a2b3c4d…
```

Keys are shown once, when issued, and stored only as their SHA-256 — the same way a signing token is, and for the same reason. A key that is lost is replaced, not recovered.

## Scopes

A key's scopes are its capabilities. There is no "full access" scope, because the useful question about an integration is not whether it is trusted but what it needs.

The four parts of `signing:write` below are for connected apps, so that the person connecting one can let it send without letting it void. A key made in the dashboard takes `signing:write` whole, or not at all ([Teams, roles and sign-in](https://signsealer.com/docs/teams)).

| Scope | What it carries |
| --- | --- |
| signing:read | Read templates, documents, certificates and packets. |
| signing:write | Prepare, send, remind and void documents; void a packet; hand out signing links to frame; record consent to text. All four of the next scopes. |
| signing:send | Prepare and send documents, and record consent to text. Part of `signing:write`. A connected app’s, not a key’s. |
| signing:remind | Remind a signer who has not signed. Part of `signing:write`. A connected app’s, not a key’s. |
| signing:links | Hand out a fresh signing link, or one to frame. Part of `signing:write`. A connected app’s, not a key’s. |
| signing:void | Void a document or a packet. Part of `signing:write`. A connected app’s, not a key’s. |
| signing:templates | Create templates, change drafts, publish, revise and discard them, and change their settings. |
| signing:workflows | Start a workflow for a participant. |
| signing:subjects | Import reservations, set guest lists, build and start packets. |
| signing:webhooks | Manage endpoints. |
| signing:devices | Manage counter tablets: add one and get its pairing code, list, re-pair, rename, stop. |

> **A booking integration wants `signing:subjects`, not `signing:write`.** The two are different trust levels: one is "act on my behalf", the other is "decide who my guests are".

## Only from where it should come from

A key can be pinned to addresses or ranges when it is made — one per line under *Only from these addresses*, up to twenty, IPv4 or IPv6. Presented from anywhere else it is refused exactly as a wrong key is (`401`, the same sentence), so a copy that leaks from a log or a laptop does nothing. A key with no list works from anywhere. The list travels with the key: to change it, make a new key and revoke the old one, the way scopes change.

The address checked is the one the request arrives from, as our edge sees it. An integration behind an egress with a fixed address pins to that; one whose address moves should not pin at all rather than pin to a range it does not control.

## Connecting through OAuth

A product that serves many businesses does not want to ask each one to paste a key. It sends the business to SignSealer once, the business agrees, and the product is handed tokens — an access token that is a scoped key for an hour, and a refresh token that gets the next one. This is OAuth 2.0 with the authorization code flow and PKCE, and nothing else: no implicit flow, no password grant, and `S256` is the only challenge method accepted. Register your product with [partners@signsealer.com](mailto:partners@signsealer.com) (a name, a homepage, the exact redirect address or addresses, and the scopes it will ask for); you get a `client_id` and, shown once, a `client_secret`. A WordPress site running our plugin does not need any of this: the plugin registers a client for that one site itself, after SignSealer has fetched the plugin's own page on the site to confirm it is there (`POST /oauth/register`), and the site owner only presses Connect and approves. Because such a client vouched for itself -- we checked that the site runs the plugin, not who runs the site -- its consent screen says so, it may have `signing:read`, `signing:write`, `signing:workflows` and `signing:webhooks` but never `signing:templates`, and a request we cannot answer is explained on our page rather than sent back to the site. A person pressing decline is sent back, with `error=access_denied`.

An AI assistant connecting to [the MCP server](https://signsealer.com/docs/mcp) needs none of it either. It finds this flow from the server's metadata and identifies itself, by registering (RFC 7591, `POST /oauth/register` with `redirect_uris`) or by using the https address of its own client metadata document as its `client_id`. Such an app is held to `signing:read` and `signing:write`, its consent screen says SignSealer has not checked it, and it may return to the loopback (`http://127.0.0.1:<port>/…`) when it runs on the person's own computer.

**1. Send the browser to authorize.**

```
GET https://api.signsealer.com/oauth/authorize
    ?response_type=code
    &client_id=ss_client_…
    &redirect_uri=https://your.product/callback
    &scope=signing:read%20signing:write
    &state=…                      # yours, returned untouched
    &code_challenge=…             # base64url(sha256(code_verifier))
    &code_challenge_method=S256
```

The person signs in if they are not already, sees your product's registered name, homepage and the scopes asked, and agrees or declines. The `redirect_uri` must match one you registered exactly — not a prefix, not a pattern — and a request whose client or redirect does not check out is answered as a page, never as a redirect. Everything else that is wrong comes back to your redirect as `error=` with `state`, the way RFC 6749 says -- for a client we registered. A client a site registered for itself gets a page instead (RFC 9700 &sect;4.11.2), and a scope it may not have is left out of the grant rather than refused. Agreement comes back as `?code=…&state=…`; the code lives sixty seconds and is good once.

**2. Exchange the code, server to server.**

```
POST https://api.signsealer.com/oauth/token
Authorization: Basic base64(client_id:client_secret)
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=…
&redirect_uri=https://your.product/callback
&code_verifier=…
```

```
{
  "access_token": "mk_live_…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "signing:read signing:write",
  "refresh_token": "…"
}
```

The access token is a key like any other on this page — send it as `Authorization: Bearer`, and every scope rule above applies. The client may also be sent as `client_id` and `client_secret` in the body. Refresh with `grant_type=refresh_token&refresh_token=…`; each refresh token is good once and the answer carries the next. A refresh token presented twice is treated as stolen: the connection is revoked, and the reason is on the business's audit trail. An AI app that registered itself without naming `refresh_token` in its `grant_types` is given no `refresh_token`: when its hour is up it sends the person through `/oauth/authorize` again ([AI assistants](https://signsealer.com/docs/mcp)).

The scopes a business can grant are the ones you registered, narrowed to what the person agreeing can do themselves. The person pressing Connect has to hold the permission to manage API keys, which only owners and admins have unless it is given to somebody else ([Teams, roles and sign-in](https://signsealer.com/docs/teams)). The business sees the connection under *Integrations → Connected apps* and can end it there at any time, with a reason on its audit trail; every token under it stops working that minute, and your next call answers `401`.

The connection is also the person's who agreed to it. If they are removed from the business, leave it, or are given a role or permissions that no longer include everything the connection holds, it ends the same way, with its tokens; and a refresh asks the same question every time, so one that changed any other way ends at the next refresh. A refresh token is good once, for thirty days. A refresh that is refused answers `400 invalid_grant` with a sentence saying why: send the business through `/oauth/authorize` again, as somebody who can still give what your app asks for.

## Testing

Build against your sandbox with a **test key** (`mk_test_`). Make one in the portal under *Integrations → API keys → + API key*, with *Test* chosen. The first one makes the sandbox: a second account beside yours, with your address and a copy of your published templates and forms as they are that moment. `GET /v1/account` answers `"mode": "test"` for a test key and `"live"` for any other.

- **Nothing is sent to anybody.** A document is prepared, sent and signed exactly as it is live, and the send's answer carries each signing link, but no email or text leaves: the sandbox is a rehearsal account, and the worker closes its messages without handing them to a provider.
- **Nothing is billed.** No usage is recorded for a sandbox at all, so nothing is drawn from credit, no allowance runs out, and it can never carry a card.
- **Webhooks are delivered** to the endpoints you register with the test key, signed the same way, so your handler is tested against the real thing.
- **It says so.** Every signing page and public form of the sandbox opens with a line saying it is a test document and not a real agreement.
- **It is framed where you are.** The sites your pages may be framed on and sent back to are your live account's, so an embedded test signing works on the site it will run on.
- **Nothing crosses over.** A test key sees only the sandbox and a live key only your account. Nothing made with a test key appears in your documents, your bill or your records.

Templates changed after the sandbox was made are changed in the sandbox, with the test key, like any other. Revoke a test key, with a reason, on the same page.

## Rate limits

Each key may make 300 requests a minute. Every answer to a keyed request says where it stands: `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset` (when the window turns over, in seconds since the epoch). Past it, `429` with `Retry-After`. A business holds ten live keys until it is paying and fifty from then, and how many people it may send signing links to in an hour and a day grows with how far it is trusted. [Limits and paging](https://signsealer.com/docs/limits) has the rest.

## Revoking

Revoking a key needs a reason, and the reason goes on the audit trail. A key revoked is a membership deactivated in the same statement — there is no window in which the key is "revoked but still working".

---

Source: https://signsealer.com/docs/idempotency (Idempotency)

# Idempotency

Your connection dropped. Did the waiver send?

You cannot tell a lost response from a lost request, so every write that creates something takes an `Idempotency-Key` header — your own key, 8 to 255 characters, one per logical operation.

```
Idempotency-Key: 7d3f9e2a-…
```

The semantics are Stripe's, deliberately, because you should not have to read our documentation to find out we were creative:

| You send | We answer |
| --- | --- |
| A key never seen before | Do the work, and store the response under the key. |
| The same key, the same body | The stored response, without doing the work again. |
| The same key, a *different* body | `409 conflict`. Refused, never absorbed. |
| The same key while the first is still running | `409`, and try again shortly. |
| The same key after a failure | Do the work. A failure is retried, not replayed. |

> **The third row is the one worth arguing about.** Returning the first response to a materially different request would be worse than an error: you would believe your second request happened, and it did not. So the request is fingerprinted, and a key reused across different bodies is reported. That is a bug in the caller, and a bug found loudly on the first test run is a kindness.

Keys live 24 hours — long enough for any retry a sane client makes, and no longer. The body itself is never stored; only a hash of it, so comparing two requests does not mean keeping somebody's name and address in a cache for a day to solve a plumbing problem.

Reads take no key. `PUT /v1/subjects` takes none either: it is keyed on `(provider, external_id)`, so importing the same reservation twice is one reservation and a key would be belt on braces.

---

Source: https://signsealer.com/docs/sdk (Node client)

# Node client

`@signsealer/sdk`. No dependencies; runs anywhere `fetch` does.

```
npm install @signsealer/sdk
```

Node 18 or later, every edge runtime, and the browser — though an API key belongs on a server. TypeScript types ship in the package, every version on npm is published by a workflow from a tagged commit, never from somebody's machine, and the changelog ships in the package.

## Three things it does that a hand-rolled client usually does not

- **Retries the failures worth retrying, with an idempotency key.** Every write that creates something gets one automatically, so a network blip does not become a second waiver. A `422` is never retried; it will be refused the same way every time, and the message says why. Pass your own key as the last argument when you have one, for example your order id. A write the server cannot de-duplicate — rotating a webhook secret, adding or pairing a tablet, a replay, the gate’s link — is never repeated after an answer that leaves it unknown whether it happened; it throws, and you decide.
- **Surfaces the API's own sentence.** `SignSealerError` carries `message`, `hint`, `code`, `status` and `requestId`. The message is frequently the database's own words, which are more specific than anything a client layer could write.
- **Keeps the request id.** Every response carries one; quote it and we can find the request.

## The client with a key

```
import { SignSealer, SignSealerError } from "@signsealer/sdk";

const signsealer = new SignSealer({
  apiKey: process.env.SIGNSEALER_KEY!,
  baseUrl: "https://api.signsealer.com",  // the default
  maxAttempts: 3,                          // total, the first included
});
```

| Method | Calls | Returns |
| --- | --- | --- |
| account() | GET /v1/account | Whose key this is: the business, the key's scopes, `live` or `test`, the sites its pages may be framed on, and whether it can text. |
| branding() | GET /v1/branding | The name, colors and logos the business shows its signers, and its signing host. |
| templates({ code? }) | GET /v1/templates | Every version of every template, or one template's versions; no text. |
| template(id) | GET /v1/templates/:id | One version whole: text, questions, settings, and every version of its code. |
| createTemplate(input, key?) | POST /v1/templates | `{ template_id }`: version 1, as a draft. |
| editTemplate(id, input) | PATCH /v1/templates/:id | A draft changed; a published version refuses. |
| publishTemplate(id, key?) | POST /v1/templates/:id/publish | The draft published: new documents use it, and its text is frozen. |
| reviseTemplate(id, input?, key?) | POST /v1/templates/:id/revise | The next version, as a draft, from the newest. |
| restoreTemplate(id, input?, key?) | POST /v1/templates/:id/restore | An older published version back, as a new draft above the newest. |
| discardTemplate(id) | DELETE /v1/templates/:id | A draft nothing was made from, gone. |
| setTemplateSettings(id, input) | PATCH /v1/templates/:id/settings | One-time, address, photographs in the copy, how long a signature lasts, reminders, sign again. |
| templatePdf(id) | GET /v1/templates/:id/pdf | Whether a template is an uploaded PDF, and whether every page is drawn. |
| documents({ status, q, external_ref, limit, offset }) | GET /v1/documents | Documents, newest first, with `total` and `has_more`. |
| document(id) | GET /v1/documents/:id | One document with its signers, trail, answers and your reference. |
| prepareDocument({ template_code, values, title, expires_at, sequential, external_ref, metadata, return_url, time_zone }, key?) | POST /v1/documents | `{ document_id }`. Refused with the placeholder's name if a value is missing. |
| send(documentId, signers, key?) | POST /v1/documents/:id/send | `{ links }`: one per signer, shown once, each with its `url`. Each needs an email, a mobile, or both; `delivery: "embedded"` sends them nothing. |
| remind(documentId, signerId, key?) | POST /v1/documents/:id/signers/:signer/remind | A fresh link, sent to them. |
| embedLink(documentId, signerId) | POST /v1/documents/:id/signers/:signer/embed | A fresh link to frame, with the sites it may be framed on. |
| void(documentId, reason, key?) | POST /v1/documents/:id/void | Every link dead; the reason on the trail. |
| certificate(documentId) | GET /v1/documents/:id/certificate | The certificate, or null before completion. |
| pdf(documentId) | GET /v1/documents/:id/pdf | `{ filename, bytes }`: the sealed PDF. |
| bundle(documentId) | GET /v1/documents/:id/bundle | `{ filename, bytes }`: the evidence bundle. |
| workflows() | GET /v1/workflows | Public forms, QR and kiosk workflows. |
| workflowQr(workflowId) | GET /v1/workflows/:id/qr | The public form's address as a QR code: SVG and a 1024px PNG. |
| startWorkflow(workflowId, participant, key?) | POST /v1/workflows/:id/start | A link for that person. With `expected_template_version` and `captured`, a start a tablet ran with no network; 409 `template_changed` if the form moved on. |
| workflowBundle(workflowId) · workflowPage(workflowId, n) | GET /v1/workflows/:id/bundle · /pages/:n | The published form, its wording and versions, and its PDF pages, to hold on a device ahead of time. |
| upsertReservation(input) | PUT /v1/subjects | A packet for the booking; idempotent on your reference, so it takes no key. |
| packet(id) | GET /v1/packets/:id | Every item, every person, and whether the packet is ready. |
| startPacket(id) · voidPacket(id, reason) | POST /v1/packets/:id/start · /void | Start everything it still owes, safe to repeat; or void what nobody has finished. |
| packetByCode(code) | GET /v1/packets/code/:code | A signing code from the receipt, resolved for a paired tablet: what is owed, by first name and last initial. |
| documentSigners(id) | GET /v1/documents/:id/signers | Who has signed one document, and nothing else; once signed, whether it is still good. |
| standing({ template, email?, phone? }) | GET /v1/standing | Whether a person's signature on a template is still good: `current`, `expired`, `resign` or `on_file`, with `valid_until`. |
| gateLink(documentId, signerId) | POST /v1/documents/:id/signers/:signer/link | A fresh link for a signer who has not signed, with a QR code as SVG. |
| reportProblem(input) | POST /v1/devices/report | A tablet's problem as names and numbers; never a message. |
| startPacketItem(itemId, key?) | POST /v1/packets/items/:id/start | A link for one item. |
| recordSmsConsent({ phone, obtainedVia, wording }, key?) | POST /v1/sms-consents | Consent you took on your own form. [What the wording must say](https://signsealer.com/docs/texting). |
| smsConsent(phone) | GET /v1/sms-consents | Whether you may text that number, and where the consent came from. |
| webhooks() · addWebhook(input, key?) · setWebhook(id, input) · removeWebhook(id, reason) | /v1/webhooks | Endpoints; the secret is shown once on add. |
| rotateWebhookSecret(id) · webhookDeliveries(id) · replayWebhookDelivery(deliveryId, key?) | /v1/webhooks/:id/rotate · /deliveries · /v1/webhooks/deliveries/:id/replay | A new secret, both signing for 24 hours; the last fifty deliveries; one sent again. |
| integrations() · integrationEvents(connectionId) | GET /v1/integrations · /:id/events | The booking systems it can connect and has, and what arrived from one. |
| devices() · addDevice(input) · newDeviceCode(id) · setDevice(id, input) · removeDevice(id, reason) | /v1/devices | Tablets from your own software; a pairing code is shown once. |
| pairDevice(input) · deviceHeartbeat(input?) | POST /v1/devices/pair · /heartbeat | On the tablet: trade a code for its own credential (no key), then say it is still here. |

Each method's request and response are the ones on the [API reference](https://signsealer.com/docs/api), which is generated from the router; the client adds nothing the API does not have.

## The signer's side, with no key

`SignSealerSigning` takes no API key, because on those routes a signing token is the whole credential. It is a separate class on purpose: a client that could send a key alongside a token would be a client that widens somebody's authority by accident. The one credential it will carry is a paired tablet's own, given as `deviceKey`, and only on a signature that says when it was taken offline (below).

```
import { SignSealerSigning } from "@signsealer/sdk";

const signing = new SignSealerSigning();

const link = await signing.link(token);
if (!link.ok) return show(link.reason);   // written for a person to read

await signing.consent(token);             // before signing, always
await signing.supply(token, "emergency_contact", "Sam Reyes, +1 503 555 0199");
await signing.sign(token, "typed", "Dana Reyes");
// or: await signing.decline(token, "wrong dates");

const result = await signing.verify("4KJ72M9PXQ3TVW8H");
// { certificate_found: true, still_matches_record: true, … }
```

Consent is a separate call and that is not an oversight: ESIGN requires consent to electronic records to precede the transaction, and a system that records both in the same instant cannot show that it did. If you would rather not build a signing page, send the signer to `https://api.signsealer.com/s/<token>` and skip all of it.

### Signing where there is no network

A paired tablet that took a signature offline passes `captured` with what the device thought the time was; the server records when it received the event and keeps the claim beside it, marked as a claim. The claim is kept only from a paired tablet of the business the link belongs to, because the day it carries is the day written into the document: build the client with the tablet's credential (the `key` `pairDevice` answered) and it is sent with that one call. From anybody else `captured` is left out without an error and the signature is dated when it arrives.

```
const signing = new SignSealerSigning({ deviceKey: tabletKey });
await signing.sign(token, "drawn", dataUri,
  { offline: true, at: capturedAt.toISOString(), device: "counter-2" });
```

### A template that is a PDF

When the template behind a link is an uploaded PDF, `link.pages` lists its pages and a field may carry a `place`. Draw the pages rather than `link.body`: a PDF template's body is a sentence naming the file and its fingerprint, so rendering it would show somebody a hash where their lease should be. [Signing a PDF](https://signsealer.com/docs/pdf) has the whole of it.

```
for (const p of link.pages ?? []) {
  const img = new Image();
  img.src = signing.pageUrl(token, p.n);   // no API key: the token is the credential
}

/* And on the keyed side, whether a template is one of these at all. */
const pdf = await signsealer.templatePdf(templateId);
if (pdf.has_pdf && !pdf.ready) { /* not every page is drawn; it cannot be published */ }
```

## Errors

```
try {
  await signsealer.prepareDocument({ template_code: "rental-agreement", values: {} });
} catch (e) {
  if (e instanceof SignSealerError) {
    console.error(e.status);    // 422
    console.error(e.code);      // "invalid"
    console.error(e.message);   // "no value for guest_name"
    console.error(e.hint);      // "A contract that ships with a placeholder…"
    console.error(e.requestId); // quote this and we can find the request
  }
}
```

## Other languages

Python, Ruby, PHP and Go clients are not written. The API is small enough that a hand-rolled client is a morning's work; the [quickstart](https://signsealer.com/docs/quickstart) shows the four calls in Python with `requests`, and [openapi.json](https://signsealer.com/openapi.json) feeds any generator.

## Versions

This page describes `@signsealer/sdk` 1.17.0. The package declares Node 18 or later (`engines` in its `package.json`), as it has since 1.0.0; outside Node it needs a runtime with `fetch`. On Node 18, use 1.11.1 or later: before it, every write not given its own idempotency key threw unless Node was started with `--experimental-global-webcrypto`. Each version's changes are in `CHANGELOG.md`, which ships in the package.

### What you have

```
npm ls @signsealer/sdk            # the version installed here
npm view @signsealer/sdk version  # the newest on npm
```

From code, the package exports its own `package.json` (from an ES module, make `require` with `createRequire`):

```
const { version } = require("@signsealer/sdk/package.json");
```

In TypeScript, calling a method your copy does not have is a compile error; in JavaScript it is a `TypeError` when the line runs.

### Numbers that never reached npm

Eight versions in the changelog were never published: 1.0.1, 1.1.0, 1.2.0, 1.3.0, 1.5.0, 1.6.0, 1.8.0 and 1.9.0. What each added first reached npm in the next version that was.

| Added in | First on npm in |
| --- | --- |
| 1.0.1, 1.1.0, 1.2.0, 1.3.0 | 1.4.0 |
| 1.5.0, 1.6.0 | 1.7.0 |
| 1.8.0, 1.9.0 | 1.10.0 |

### When each method arrived

The options listed are the ones you send. Fields in an answer are not listed: the client hands back whatever the API sends, so a newer version only declares them in its types.

| Method | Added in | Since then |
| --- | --- | --- |
| `new SignSealer({ apiKey, baseUrl, maxAttempts })` | 1.0.0 | 1.1.0: `apiKey` may be left out, for `pairDevice`. |
| `account()` | 1.0.0 |  |
| `branding()` | 1.0.0 | 1.11.0: the `Branding` type names what the API sends (`businessName`, `primaryColor`, `hasLogo`, `signingHost`, `logoUrl` and the rest). The names it declared before were never sent, so code written against them no longer compiles. |
| `templates({ code? })` | 1.0.0 | 1.6.0: `code`. |
| `template(id)` | 1.6.0 |  |
| `createTemplate(input, key?)` | 1.0.0 |  |
| `editTemplate`, `publishTemplate`, `reviseTemplate`, `discardTemplate`, `setTemplateSettings` | 1.6.0 | 1.7.0: `change_note` on `editTemplate` and `reviseTemplate`. 1.10.0: `photos_in_copy` on `setTemplateSettings`. |
| `restoreTemplate` | 1.7.0 |  |
| `templatePdf(id)` | 1.0.0 |  |
| `documents(filter)` | 1.0.0 | 1.0.1: `offset`. 1.6.0: `external_ref`. |
| `document(id)` | 1.0.0 |  |
| `prepareDocument(input, key?)` | 1.0.0 | 1.6.0: `external_ref`, `metadata` and `return_url`. 1.11.0: `time_zone`. |
| `send(documentId, signers, key?)` | 1.0.0 | 1.3.0: `phone` on a signer. 1.6.0: `delivery: "embedded"`. 1.14.0: a signer held for their turn has `token: null` and `held: true`. 1.16.0: `for_business` on a signer. |
| `remind`, `embedLink` | 1.6.0 |  |
| `void`, `certificate`, `pdf`, `bundle` | 1.0.0 |  |
| `workflows()`, `workflowQr(workflowId)` | 1.0.0 | 1.17.0: `email_check`, the website link's limits, `closed` and `needs_attention` on each workflow, and `address` among its questions' kinds. |
| `startWorkflow(workflowId, participant, key?)` | 1.0.0 | 1.1.0: `expected_template_version` and `captured`. 1.14.0: a fixed role held for their turn has `token: null` and `held: true`. 1.16.0: `for_business` on each link. |
| `workflowBundle`, `workflowPage` | 1.1.0 |  |
| `upsertReservation`, `packet`, `startPacketItem` | 1.0.0 |  |
| `startPacket`, `voidPacket` | 1.9.0 |  |
| `packetByCode`, `documentSigners`, `gateLink`, `reportProblem` | 1.2.0 |  |
| `standing({ template, email?, phone? })` | 1.5.0 |  |
| `recordSmsConsent`, `smsConsent` | 1.0.0 |  |
| `textingNumberInvitation(prefill?)` | 1.13.0 |  |
| `webhooks`, `addWebhook`, `setWebhook`, `removeWebhook`, `rotateWebhookSecret`, `webhookDeliveries`, `replayWebhookDelivery` | 1.0.0 |  |
| `integrations`, `integrationEvents` | 1.9.0 |  |
| `devices`, `addDevice`, `newDeviceCode`, `setDevice`, `removeDevice` | 1.1.0 | 1.7.0: `hand_off` and `gate` on `setDevice`. 1.11.0: `workflow_ids`. |
| `pairDevice`, `deviceHeartbeat` | 1.0.0 | 1.2.0: `queue_waiting`, `queue_refused` and `synced` on `deviceHeartbeat`. |
| `SignSealerSigning`: `link`, `consent`, `supply`, `sign`, `decline`, `verify`, `pageUrl` | 1.0.0 | 1.11.0: `deviceKey` on the constructor. |
| `SignSealerSigning`: `addParty`, `partyShare`, `partyLink` | 1.15.0 |  |
| `SignSealerPartner`: `profile`, `businesses`, `statements`, `SignSealerPartner.signupUrl` | 1.8.0 |  |

> **Retries changed in 1.6.0.** Before it, `rotateWebhookSecret`, `replayWebhookDelivery`, `pairDevice`, `addDevice`, `reportProblem` and `gateLink` were sent again after a lost answer or a `5xx`, and could happen twice. From 1.6.0 each is sent once and throws, and you decide. On npm that is 1.7.0 or later.

---

Source: https://signsealer.com/docs/mcp (AI assistants (MCP))

# AI assistants (MCP)

SignSealer is a remote MCP server at `https://api.signsealer.com/mcp`. Connect it to Claude, ChatGPT, Codex, Claude Code, Cursor or VS Code, and ask: "send the rental agreement to Ada Lovelace", "who still hasn't signed tomorrow's waivers?", "remind them".

The [Model Context Protocol](https://modelcontextprotocol.io) is how an assistant is given tools. Ours are the API: each tool makes the same `/v1` call a key would, with the same scopes, limits and answers, so an assistant can do exactly what the person who connected it allowed and nothing the API would refuse.

## Connect it

Every client below signs in the same way: it opens SignSealer's sign-in, you choose the business, see what it is asking for, and press **Connect**. There is no key to copy. You need the permission to manage API keys in that business, which owners and admins have ([Teams, roles and sign-in](https://signsealer.com/docs/teams)). You can disconnect it at any time under **Integrations → Connected apps**, and it stops that minute.

### Claude (claude.ai and Claude Desktop)

Settings → Connectors → **Add custom connector**. Name it SignSealer, give the URL `https://api.signsealer.com/mcp`, and press **Connect**.

### ChatGPT

Settings → Apps & Connectors. With developer mode on, create a connector with the URL `https://api.signsealer.com/mcp` and OAuth as its authentication.

### Claude Code

```
claude mcp add --transport http signsealer https://api.signsealer.com/mcp
```

Then `/mcp` in a session to sign in.

### Codex

In `~/.codex/config.toml`:

```
[mcp_servers.signsealer]
url = "https://api.signsealer.com/mcp"
```

```
codex mcp login signsealer
```

### Cursor

In `~/.cursor/mcp.json` for every project, or `.cursor/mcp.json` in one:

```
{
  "mcpServers": {
    "signsealer": { "url": "https://api.signsealer.com/mcp" }
  }
}
```

Cursor signs in when it first connects. To add it in one step instead, open this link in a browser on the computer Cursor is on:

```
cursor://anysphere.cursor-deeplink/mcp/install?name=signsealer&config=eyJ1cmwiOiJodHRwczovL2FwaS5zaWduc2VhbGVyLmNvbS9tY3AifQ==
```

### VS Code

In `.vscode/mcp.json` in a workspace, or in your own `mcp.json` (the command **MCP: Open User Configuration**):

```
{
  "servers": {
    "signsealer": { "type": "http", "url": "https://api.signsealer.com/mcp" }
  }
}
```

VS Code shows **Start** above the server, and signs in when it starts.

### Anything else

A client that speaks MCP over HTTP finds the sign-in by itself from the URL:

```
{
  "mcpServers": {
    "signsealer": { "url": "https://api.signsealer.com/mcp" }
  }
}
```

One that cannot sign in can send an API key instead, from **Integrations → API keys** with `signing:read` and `signing:write`, as a header:

```
{
  "mcpServers": {
    "signsealer": {
      "url": "https://api.signsealer.com/mcp",
      "headers": { "Authorization": "Bearer ${env:SIGNSEALER_KEY}" }
    }
  }
}
```

Keep the key in the environment, not in a file you commit. A key that holds only `signing:read` gives an assistant that can look but not send.

## What it can do

| Tool | What it does | Kind | Needs |
| --- | --- | --- | --- |
| signsealer_get_account | **Who am I connected as.** The SignSealer business this connection acts for: its name, what this connection may do (its scopes), whether it is a test sandbox where nothing reaches anybody, and whether the business can text people. Call it first, and tell the user which business they are connected to. | Reads | `signing:read` |
| signsealer_list_templates | **List templates.** The business's templates (the documents it sends), newest version first, with each one's code, title and whether it is published. Pass `code` for one template's versions. | Reads | `signing:read` |
| signsealer_get_template | **Read a template.** One template version: its text and the values it takes (the blanks a sender fills in), which signsealer_send_document's `values` answers. | Reads | `signing:read` |
| signsealer_list_documents | **List documents.** Documents sent for signature, newest first. Filter by `status` (draft, sent, completed, declined, expired, void, or open for draft and sent) or `q` (part of a title or a signer's name, email or number). Paged with `limit` and `offset`; the answer says `total` and `has_more`. | Reads | `signing:read` |
| signsealer_get_document | **Read a document and who has signed.** One document: its status and its signers, each with where they are (pending, signed, declined). Use it to answer "has everyone signed?". Personal detail is left out unless asked for: the text (include_text), the signers' answers to its questions (include_answers), and the event trail with addresses and devices (include_trail). | Reads | `signing:read` |
| signsealer_send_document | **Send a document for signature.** Prepares a document from a published template, fills in its values, and sends each signer their own link by email (or by text to a number that agreed to texts). This emails or texts real people: confirm the template, the values and every recipient with the user first. Answers with the document's id and each signer's link. If a send is refused after the document was prepared, the refusal names it: correct what it says and call this again with that document_id instead of template_code, so no second copy is made. | Changes something | `signing:send` |
| signsealer_remind_signer | **Remind a signer.** Sends one signer who has not signed a reminder with their link. Emails or texts a real person, at most as often as the business's reminder rules allow. | Changes something | `signing:remind` |
| signsealer_new_signing_link | **Make a fresh signing link.** A new signing link for one signer, to hand over yourself (in a chat, on a screen, as a QR code). The signer's previous link stops working. | Changes something | `signing:links` or `signing:workflows` |
| signsealer_void_document | **Void a document.** Cancels a document that is not finished: its links stop working and its signers are told. A completed document cannot be voided. Cannot be undone. | Changes something | `signing:void` |
| signsealer_get_certificate | **Read a document's certificate.** The certificate of completion of a signed document: who signed, when, from where, the fingerprint of what they signed, and the code anyone can check it with. | Reads | `signing:read` |

The four that change something are marked as such to the client, which asks you before it runs one. The server also tells the assistant to confirm the template, the values and every recipient with you before it sends anything, and never to send to an address you did not give it.

Sending takes an `idempotency_key` the assistant makes up for that one send (reminding and voiding take one too, if given). An assistant whose connection drops calls again with the same key and is answered with what the first call did, so a retry never sends a document twice. Reading a document gives its status and its signers; the text, the signers' answers and the event trail, with its network addresses and devices, come only when asked for.

## What you are asked to allow

An assistant asks for `signing:read`, `signing:send`, `signing:remind`, `signing:links`, `signing:void`. Reading documents, templates and who has signed is given when you connect it. Each of the four that reaches people or stops a link is a box on SignSealer's sign-in page, and none is ticked until you tick it:

- **Send documents for signature** (`signing:send`)
- **Remind a signer who has not signed** (`signing:remind`)
- **Make a fresh signing link** (`signing:links`)
- **Void a document that is not finished** (`signing:void`)

An assistant that only needs to tell you who has signed gets no box ticked. One asked to send a document is refused if *Send documents for signature* was left clear, and says so: nothing is sent. To change what it may do, connect it again and tick the boxes you want; what you tick replaces what it had, at once, even for the sign-in it already holds.

It is never given more than you hold yourself, and never the scopes that manage templates, webhooks, workflows or keys. An API key with `signing:write` holds all four.

The sign-in page says **Not checked by SignSealer** for an app that introduced itself, which every assistant does, and names where your browser goes back to afterwards: the assistant's own site, or *an app on this computer* for Codex and Claude Code. Connect it only when you started the connection yourself, just now.

## For client builders

| What | Where, and how |
| --- | --- |
| Transport | Streamable HTTP, stateless: one JSON-RPC message per `POST /mcp`, answered with one JSON object; a notification is answered `202`. No event stream (`GET` is `405`) and no session. Protocol version `2026-07-28`, with no handshake: each request names its version in `_meta`, and `server/discover` says which versions this server speaks. And, opened with `initialize`, `2025-11-25`, `2025-06-18`, `2025-03-26`, `2024-11-05`. |
| Without a token | `401` with `WWW-Authenticate: Bearer resource_metadata="https://api.signsealer.com/.well-known/oauth-protected-resource/mcp"` and the scopes. |
| Protected resource (RFC 9728) | `https://api.signsealer.com/.well-known/oauth-protected-resource/mcp` |
| Authorization server (RFC 8414) | `https://api.signsealer.com/.well-known/oauth-authorization-server` |
| Identifying your app | An OAuth Client ID Metadata Document: use its https address as `client_id`, and we read it, check its `client_id` is that address, and take its name and `redirect_uris`. Or register (RFC 7591) at `POST https://api.signsealer.com/oauth/register`. Redirects are https, or the loopback (`http://127.0.0.1`, `http://[::1]`, `http://localhost`) with any port. |
| The grant | Authorization code with PKCE (`S256` only). Refresh tokens only for an app that asks for them: name `refresh_token` in `grant_types`, in its registration or its metadata document; left out, the grant is the code alone, as RFC 7591 reads it. A `resource` (RFC 8707) must be this API, `https://api.signsealer.com` or `https://api.signsealer.com/mcp`; anything else is `invalid_target`. |
| Limits | The API's, per token: see [Limits and paging](https://signsealer.com/docs/limits). A tool's refusal is the API's own status, message and hint. |

Building on the API directly instead? The [quickstart](https://signsealer.com/docs/quickstart) and the [Node client](https://signsealer.com/docs/sdk) are the way in, and [llms-full.txt](https://signsealer.com/llms-full.txt) is every page of these docs as one text file, for a coding assistant to read.

---

Source: https://signsealer.com/docs/templates (Templates and versions)

# Templates and versions

The text people sign, and why it is never changed under them.

Watch it done: [Have a waiver drafted, then have it read](https://signsealer.com/guides/have-a-waiver-drafted-then-read) (2:49)

A template has a **code** (`rental-agreement`) and numbered **versions**. A version is a draft until it is published, and a published version is frozen: the database refuses to change or delete it, because somebody may have signed it. Changing the words means a new version. Each document records the exact version it was made from, and the certificate says which, so "what did they sign?" always has one answer.

## The lifecycle

| Step | Call | What happens |
| --- | --- | --- |
| Create | POST /v1/templates | Version 1, as a draft, with its text, placeholders, consent wording and questions. |
| Change the draft | PATCH /v1/templates/{id} | `name`, `body`, `body_format`, `variables`, `fields` (the whole list). Only while it is a draft. |
| Publish | POST /v1/templates/{id}/publish | New documents from this code use this version, and its text is frozen. Refused, by name, for a placeholder the template does not declare. |
| Revise | POST /v1/templates/{id}/revise | A new draft, one version higher, copied from the newest with whatever you change. Publish it to put it into use. |
| Go back | POST /v1/templates/{id}/restore | An older published version's text, questions, consent wording and file, as a new draft above the newest. Its `change_note` says where it came from. Not while a draft is open. |
| Throw a draft away | DELETE /v1/templates/{id} | Only a draft nothing was made from. The only version of a code going frees the code. |
| Read one | GET /v1/templates/{id} | The version whole, with `versions`: every version of its code, newest first. |
| List | GET /v1/templates?code= | Every version of every template, or one code's; no text. |

```
// A new clause for next season, without touching what people signed this one.
const current = await signsealer.template(templateId);
const next = await signsealer.reviseTemplate(current.template_id, {
  body: current.body + "\n\nHelmets are required on every trail.",
});
await signsealer.publishTemplate(next.template_id);
```

Revise only from the newest version. Revising an older one would quietly throw away every change made since, so it answers `409 conflict`, and the hint names the newest version's id. A draft is not revised; it is changed with `PATCH`.

**What changed, and going back.** Each version carries a `change_note` of up to 500 characters: set it on `revise` or with `PATCH` while it is a draft, and it is frozen with the version when it is published. `GET /v1/templates/{id}` lists every version with its note, name, whether it has a PDF and how many documents were made from it -- the same list as the dashboard's history page, which also compares any two versions line by line. To go back to an older wording, `POST /v1/templates/{id}/restore` on that version makes a new draft above the newest; the versions in between keep their numbers and their signatures.

## Questions and fields

A template's `fields` are what it asks besides the signature: a date of birth, a tick against each safety statement, a photo of the boat before it leaves. Send them as a list on `POST /v1/templates`, or as the whole list on `PATCH /v1/templates/{id}` and `POST /v1/templates/{id}/revise`, where the list you send replaces the one it had. `GET /v1/templates/{id}` answers with them in the same shape. A template asks at most fifty.

The list is checked twice. The API checks each question's shape and answers `422 invalid` naming the property. The engine then reads the list as a whole and refuses it with `422` and a sentence naming the question: a condition on a question below it, a block with two headings, a choice with one option. A refused list on a create leaves no template behind.

> **A property that is not in the table below is dropped without a word.** A misspelt `show_if` saves, answers `201`, and leaves a question that is always asked. Read the template back with `GET /v1/templates/{id}` when you are building the list.

### Kinds

Every answer is checked by the engine when it is given, whatever the page or your client did first. An empty answer to a required question is refused as required; an optional one may be left empty.

| Kind | What it accepts | How the signing page asks it |
| --- | --- | --- |
| `signature` | Anything that is not empty. Cannot be optional. | Placed on an uploaded PDF, it is the box the signature itself fills, and is never asked. Asked under the document, it is a typed line: a second signature, typed. |
| `initials` | Anything that is not empty. Cannot be optional. | A one-line box. On a page, up to six characters. |
| `checkbox` | Ticked is `true`, `yes`, `on` or `1`, in any case. A required one has to be ticked. | On its own, a button: *I confirm:* and the label, and *Leave it unticked* beside it when it is optional. In a block, a tickbox. |
| `text` | Anything that is not empty. | A one-line box. |
| `paragraph` | Anything that is not empty. No minimum length: "No damage" is an answer. | A box several lines tall. |
| `date` | `YYYY-MM-DD`, and a day the calendar has: `2026-02-31` is refused. | A date picker. Placed on a page with a signing-date key or label, it is filled by signing instead ([Signing a PDF](https://signsealer.com/docs/pdf)). |
| `birthdate` | As a date, and no later than tomorrow (a day of slack for time zones), with the year 1900 or later, so `0084-05-02` is refused. | Month and day picked, the year typed. On a page, a date picker. |
| `time` | `HH:MM` on a 24-hour clock: `14:30`, `9:05`. | A time picker. |
| `datetime` | `YYYY-MM-DDTHH:MM`, or a space for the `T`, on a day the calendar has. | A date-and-time picker. |
| `photo` | A JPEG or PNG, sent to the photo route. Text is refused. The answer becomes `sha256:<hex>`. | A camera button. An optional one offers *Carry on without a photo*. |
| `email` | Something, an `@`, then a domain with a dot in it, and no spaces. | An email box, with the email keyboard. |
| `phone` | At least seven digits; anything else in it is ignored for the count. | A country code to pick and the number to type. On a page, one box. |
| `address` | At least five characters. | A box several lines tall, rather than street, city and zip: those are not the shape of an address everywhere. |
| `number` | Digits, with a minus in front and a decimal point if needed: `12`, `-3`, `4.5`. No commas, no units. | A number box, with the number keyboard. |
| `choice` | Exactly one of its `options`, as written. | Six options or fewer are buttons to tap; more are a list. |

### Properties

| Property | Takes | What it does |
| --- | --- | --- |
| `key` | Required. A lower-case letter, then up to 58 lower-case letters, digits and underscores. Once per list. | Names the answer everywhere: in `answers`, on `POST /v1/sign/{token}/fields`, and in `values` for a box the sender fills. |
| `kind` | Required. One of the fifteen above. | What the answer must be, and the box it is asked in. |
| `label` | 1 to 200 characters. | What the signer reads. Without one, the key is shown. |
| `required` | `true` or `false`. `true` when absent. | The signature is refused until a required question is answered. An optional one can be passed, and the signature does not wait for it. A `signature` or `initials` cannot be `false`. |
| `hint` | Up to 200 characters. | A line under the question, read with it by a screen reader. |
| `options` | A `choice` only: 2 to 30 of them, each 1 to 80 characters, none blank. | What can be picked. Any other kind carrying `options`, even an empty list, is refused. |
| `sensitive` | `true` or `false`. `false` when absent. | The answer is masked wherever the business's staff read it back and in the API. It is not masked on the sealed PDF, because the PDF is the document that was signed. On the page the box turns off the browser's autofill and suggestions, and a box on a PDF page does not show the answer back. |
| `supplied_by` | `adult` (when absent), `per_child`, `staff` or `business`. | Who answers it: below. |
| `show_if` | An object: `field`, the key of a question earlier in the list, and one rule. Or several such rules, joined by all or any. | Asked only when those earlier answers match: below. |
| `flag_when` | An object with one rule, about this question's own answer. | Marks the answer for a person to read: below. |
| `block` | A name shaped like a key. | Questions with the same `block` are asked together, as one thing. |
| `block_label` | Up to 200 characters. | The block's heading. Given once, on any question in the block. Every block needs one; two different ones are refused, and so is one on a question with no `block`. |
| `block_intro` | Up to 2,000 characters. | A sentence or two under the heading, given once on the same terms. |
| `block_step` | `true` or `false`. | `true` on any question of a block gives the whole block a page of its own. Refused on a question with no `block`. |
| `place` | `{page, x, y, w, h}`: a page counted from one and no higher than the file has, and four fractions of the page from its top left, for a box with a width and a height that fits on it. | Where on an uploaded PDF's page the question is answered ([Signing a PDF](https://signsealer.com/docs/pdf)). |

`show_if`, `flag_when`, `block`, `block_label`, `block_intro`, `block_step` and `place` may also be `null`, which is the same as leaving them out.

### Conditions and flags

`show_if` and `flag_when` both take these four rules, exactly one of them per object:

| Rule | Matches |
| --- | --- |
| `{"ticked": true}` | A ticked box. A `checkbox` only. |
| `{"unticked": true}` | A box not ticked, including one never answered. A `checkbox` only. |
| `{"answered": true}` | Any answer that is not empty. |
| `{"equals": ["Yes", "Not sure"]}` | One of these answers, ignoring case and the spaces around it. Not for a `photo`. |

For `show_if` the rule is about the question it names, so `ticked` needs that question to be a checkbox: `{"field": "injured", "ticked": true}`. The named question has to be above this one, because a form is read top to bottom; one below it, or the question itself, is refused. A hidden question is not required, and the signature does not wait for it. Change the earlier answer so that a question is hidden again and its answer is cleared, along with any that depended on it, so nothing is kept in answer to a question the signed document never asked.

A `show_if` rule can also say more than the four:

| Rule | Matches |
| --- | --- |
| `{"not_equals": ["No"]}` | An answer, and none of these. An empty answer does not match, so the question waits for the one it depends on. Not for a `checkbox`, `photo`, `signature` or `initials`. |
| `{"contains": "allergy"}` | An answer with these words in it, ignoring case. A `text`, `paragraph`, `email`, `phone` or `address`. |
| `{"not_contains": "nuts"}` | An answer without these words in it, ignoring case. Like `not_equals`, an empty answer does not match. The same kinds as `contains`. |
| `{"gt": 10000}`, `{"lt": 500}` | A number above or below this one. A `number` only. |
| `{"age_under": 18}`, `{"age_at_least": 18}` | Whole years from the date in the answer to today, under or at least this many. A `birthdate`, `date` or `datetime`; from 1 to 120. |

Several rules, up to ten, are joined: `{"match": "all", "rules": [...]}` asks the question when every rule is met, and `"match": "any"` when one is enough. Each rule names its own question:

```
"show_if": {
  "match": "any",
  "rules": [
    { "field": "birthday", "age_under": 18 },
    { "field": "with_school", "ticked": true }
  ]
}
```

A part of a condition can be a group of two or more rules with its own `match`, which is how *(A and B) or C* is written. A group holds rules, not further groups, and a condition has at most ten rules in all, counting those in its groups. And `"action": "hide"` turns a condition round: the question is hidden when the condition holds, and asked otherwise.

```
"show_if": {
  "action": "hide",
  "match": "any",
  "rules": [
    { "match": "all", "rules": [
      { "field": "member", "unticked": true },
      { "field": "birthday", "age_under": 18 } ] },
    { "field": "injured", "answered": true }
  ]
}
```

In the dashboard's builder, the condition says **Show** or **Hide**, and **+ Add a group** adds one. In a form's lines the same are `hide if` in place of `show if` on every part, a group as `show if all: member is unticked; birthday is
under age: 18` (its rules between semicolons), and `show if notes
does not contain: nuts`.

A rule about a question that was itself not asked is not met, whatever it says: its answer was cleared when it was hidden.

### A paragraph that depends on an answer

A paragraph of the document can be there only when an answer says so: the treatment consent's extra clause for somebody who is pregnant, the photo release left out for somebody who said no. Put a line of its own above it and another below it, in the words a question's `show if` takes:

```
[[show if pregnant is: Yes]]
My doctor has cleared me for this treatment while pregnant.
[[end]]

[[show if birthday is under age: 18 | show if with_school is ticked | show if any]]
A parent or guardian has read this with me.
[[end]]

[[hide if photos is ticked]]
We will not take or use any photographs of you.
[[end]]
```

`[[hide if ...]]` leaves a paragraph out when its condition holds, and a group is written as on a question's line: `[[show if any: birthday
is under age: 18; with_school is ticked | show if notes does not contain:
cleared]]`.

In the dashboard, **Show a paragraph only if…** under the text writes the two lines for you. A paragraph can name a question the signer answers, or a box you fill in on an uploaded PDF; not one asked once per child, not a question your staff fill in that has no place on the page, since nobody answers it on the document, and not a box the signature fills in, such as the signing date, which has no answer until after the paragraphs are shown. The markers are refused when the text is saved if they cannot be read, and a question they name that the template does not have, or cannot name, is refused when it is published.

**The first signer's answers decide it**: the first person in signing order who is not only copied in. One document has one text, so it is decided once. That signer is asked every question before the document, optional ones too, and reads it with the paragraphs their answers called for; when they sign, which paragraphs applied is frozen, and anybody else on the document waits until then, so nobody signs a text that could still change. The signed copy has only the paragraphs that applied, and its certificate says how many and whose answers decided them. The fingerprint is of the text as it was sent, every paragraph and its condition included, and the answers that decided it are in the evidence. The printable blank copy and the previews show every paragraph, each with the sentence saying when it applies.

Over the API, `GET /v1/sign/{token}` says so under `paragraphs`, and a page that draws the document itself passes back which paragraphs it drew when it signs. While they are undecided, the first signer's signature is refused without that, so an app or an integration that predates it cannot freeze a paragraph its signer never saw; see [the API reference](https://signsealer.com/docs/api).

`flag_when` marks an answer somebody at the business should read: the shooter who left *I am not under the influence of alcohol* unticked. The rule is kept with the document when it is sent, and the mark is worked out from the rule and the answer, so it cannot disagree with either. A flagged answer is listed under **Needs review** in the dashboard once the document is finished, and comes back `flagged: true` in the API. The signer is never told: a page that said so would teach the next signer which answer avoids the question. The flag is not on the certificate either, which is evidence of what was said, not of what the business made of it.

### Who answers

Every question is put to every person on the document who signs, approvers and witnesses included, and to nobody copied in, except the person signing for the business. A document with two signers asks each of them the whole list, and each answers for themselves. `supplied_by` changes that:

- **`adult`**: the person signing. The ordinary case.
- **`per_child`**: asked once for each child the document covers, named, with the child's name after the label. A document knows its children when it was started from a packet ([Reservations and packets](https://signsealer.com/docs/packets)) or by a booking's party ([Signers, roles and order](https://signsealer.com/docs/signers)); one sent with `POST /v1/documents/{id}/send` covers nobody, so it asks none. It cannot be placed on a page: one box cannot hold an answer per child.
- **`staff`**: never asked of a signer. Placed on an uploaded PDF, it is filled in by whoever sends the document, under `values` on `POST /v1/documents` or `fields` or `values` on a workflow start, and a required one that is missing refuses the send. The signer sees it filled in and cannot change it. Such a box cannot be a signature, initials, a photo or the signing date, cannot be `sensitive`, and cannot have a `show_if`, because it is filled in before anybody has answered anything. `GET /v1/workflows` lists a workflow's as `sender_fields`.
- **`business`**: answered by the person who signs for the business, and nobody else. On an uploaded PDF, the business's own signature line, its date and its name. That person is the signer sent with `for_business: true`, or a workflow's fixed role with `business: true`. Everybody else's questions are not asked of them, so each box on the page has one person's answer. A `business` question's `show_if` can name only another `business` question, and nobody else's can name one. Sent with nobody for the business, its boxes stay empty.

### What the signer sees

The signing page runs no script, so every box is one the browser draws and checks itself. None of that is the check; the engine is.

- The questions come after the signer agrees to sign electronically and before the signature, under the document, in the order of the list. A workflow can ask them before the document instead (`document_after_questions` on `GET /v1/sign/{token}`).
- A block's questions are drawn under its heading and introduction. Several in a block are one form with one **Continue**, unless the block holds a photo or a per-child question; then each is asked on its own. The page groups a block's questions where they sit next to each other in the list, so keep them together.
- A block with `block_step` is a page of its own. The page always opens on the first step with anything left to answer, so a signer who comes back lands where they stopped, and a step whose questions are all hidden is skipped.
- An optional question says *(optional)* beside its label and can be passed: *Save or skip*, *Leave it unticked*, *Carry on without a photo*.
- A question placed on an uploaded PDF is a box on the page, filled in on the same step as the signature. A signature box and a signing-date box are filled by signing, and a box the sender filled is shown and not asked ([Signing a PDF](https://signsealer.com/docs/pdf)).

Your own signing screen reads the questions from `GET /v1/sign/{token}`, each with `visible`, the engine's own answer to its condition: draw only the visible ones. A screen that decides conditions itself as the answers come in has `rules_at_start`, the engine's answer to each rule on its own, for a rule about a question it does not ask, and `condition_zone`, the zone whose day an age is counted on. Answer with `POST /v1/sign/{token}/fields`, taking `key`, `value` (up to 20,000 characters) and, for a per-child question, `about`; a photo goes to `POST /v1/sign/{token}/fields/{key}/photo`. A refused answer is `422` with the engine's sentence, such as *Date of birth needs the year in full, like 1984*. While a required, visible question is unanswered, `POST /v1/sign/{token}` is refused with `422` naming each one: *still needed before signing: …*.

### An example

A kayak rental waiver: a safety statement that is optional but flagged when left unticked, a birthday, a section on its own page with a follow-up that is only asked after a yes, a medical note that is masked and always flagged when given, an optional photo, and initials.

```
"fields": [
  { "key": "swimmer", "label": "I can swim 50 metres unaided", "kind": "checkbox",
    "required": false, "flag_when": { "unticked": true } },
  { "key": "date_of_birth", "label": "Date of birth", "kind": "birthdate" },
  { "key": "paddled_before", "label": "Have you paddled before?", "kind": "choice",
    "options": ["Yes", "No"],
    "block": "experience", "block_label": "Your paddling",
    "block_intro": "So we can give you the right boat.", "block_step": true },
  { "key": "trips", "label": "Roughly how many trips?", "kind": "number",
    "block": "experience", "show_if": { "field": "paddled_before", "equals": ["Yes"] } },
  { "key": "medical", "label": "Anything medical we should know about?", "kind": "paragraph",
    "required": false, "sensitive": true, "hint": "Only what affects you on the water.",
    "flag_when": { "answered": true } },
  { "key": "hull_photo", "label": "Photo of the boat before you launch", "kind": "photo",
    "required": false },
  { "key": "rules_initials", "label": "Initial to confirm you read the safety rules",
    "kind": "initials" }
]
```

### How answers come back

`GET /v1/documents/{id}` carries `answers`: every question on the document, in the order the form asks it, for each signer in turn.

```
"answers": [
  { "signer_id": "5f0a…", "key": "swimmer", "label": "I can swim 50 metres unaided",
    "kind": "checkbox", "block": null, "about": null, "required": false,
    "sensitive": false, "asked": true, "value": "",
    "supplied_at": "2026-10-03T14:20:51Z", "flagged": true },
  { "signer_id": "5f0a…", "key": "medical", "label": "Anything medical we should know about?",
    "kind": "paragraph", "block": null, "about": null, "required": false,
    "sensitive": true, "asked": true, "value": "•••••••thma",
    "supplied_at": "2026-10-03T14:21:30Z", "flagged": true }
],
"flagged": 2
```

- `asked` is whether the question was on that signer's page. A question its condition hid is `asked: false`, has no value, and is never flagged.
- A `sensitive` value is masked: shorter than eight characters, it is all dots; longer, dots and its last four.
- A photo's value is `sha256:<hex>`, the fingerprint of the photograph kept with the document.
- `about` names the child a per-child answer is for, and `block` the block it was asked in.
- `flagged` on the document counts the flagged answers.
- A redacted document keeps its questions and gives up every value, and each child's name: `about` reads *Redacted child 1*, *Redacted child 2* and so on, the same child the same number on every question.

The AI assistants' `signsealer_get_document` leaves the answers out, and says how many there are, unless asked with `include_answers: true` ([AI assistants](https://signsealer.com/docs/mcp)).

Webhooks do not carry answers, on purpose: a webhook goes to whatever address was typed into a form, and some answers are about somebody's health. Two events come close. `signing.photo_supplied` names the question and the child it was about and carries the photo's SHA-256, never the image; and when the sender filled boxes on an uploaded PDF, `signing.created` lists their keys under `detail.filled_by_sender`, never the values ([Webhooks](https://signsealer.com/docs/webhooks)). Wait for `signing.completed`, then read the document.

### What is frozen, and when

The list is part of the version. While the version is a draft it changes freely; once it is published, `PATCH` answers `422`, and the way to ask something different is the next version, with `fields` on `POST /v1/templates/{id}/revise`. What you were asked to initial is part of what you agreed to.

Then each document keeps its own copy. When a document is sent, every question is written onto it for each signer: its label, kind, options, hint, whether it is required or sensitive, its block's heading and introduction, its condition, its flag rule and its place on the page. A later version changes nothing about a document already sent, so a flag rule changed next season does not decide what last season's answers meant.

## What happens to what was already sent

- **Documents already sent keep their version.** The text is stored on the document when it is prepared, and a new version changes nothing about a document on its way to a signer.
- **New documents use the newest published version.** A draft is never sent.
- **A tablet that ran the form with no network** names the version it showed (`expected_template_version`) when it catches up. If a newer one was published meanwhile, the start answers `409 template_changed` and nothing is sealed against words the person did not read.

## Settings that outlive a version

Some settings belong to the code, not one version, and carry over to every version after: `PATCH /v1/templates/{id}/settings` with any of

| Setting | Means |
| --- | --- |
| valid_months | How long a signature stays good, in months; `null` for as long as the document is kept. `GET /v1/standing` answers against it. |
| remind_days | Days before the end each signer is emailed a link to sign again. Needs `valid_months`. |
| resign | `true`: everybody who signed an older version must sign the newest published one; their standing reads `resign`. `false` lifts it. |
| one_time | Made to send once rather than reused. |
| show_address | The business's address printed under it. |
| photos_in_copy | The photographs a signer takes as answers are printed after the certificate in the signed PDF, each with its SHA-256, under the same seal. On unless turned off; the certificate keeps every hash either way. |

### What an NDA grants

An NDA's template can carry `grants`: a JSON object, set when the template is created (`POST /v1/templates`), recording what signing it gives the signer. SignSealer keeps it and does not act on it: who may see your material is for the system that holds the material to decide. A template of any other `kind` that carries one is refused with `422` (“only an NDA carries a grant”).

Grants belong to a version, as its text does. `PATCH` does not change them; a revision carries the newest version's forward, and a restore brings back the restored version's. They come back on the template (`GET /v1/templates/{id}`); on each document made from it, as `grants` on `GET /v1/documents/{id}`, where each signer whose role is `signer` is also marked `grants: true`; on the signing link (`GET /v1/sign/{token}`); and in the certificate, as `payload.document.grants` from `GET /v1/documents/{id}/certificate`, sealed into its hash when the document completes. The sealed PDF does not print them, and the `signing.completed` webhook does not carry them: read the document or its certificate when it arrives.

## A template that is a PDF

Uploading the file is a dashboard step, where the boxes are placed on its pages; there is no API route for the upload yet ([Signing a PDF](https://signsealer.com/docs/pdf)). Everything on this page works on it afterwards, except changing its text: a PDF's text is the file. Revise it to rename it or change its questions; to change what it says, start a new template from the new file.

---

Source: https://signsealer.com/docs/embedding (Signing inside your product)

# Signing inside your product

The person is already in your app. Do not send them to their inbox.

Watch it done: [Embedded signing in your own product](https://signsealer.com/guides/embedded-signing-in-your-own-product) (1:55)

Three ways to put signing in front of somebody, from least work to most:

- **Send them to our page.** The `url` in the send's answer, in a new tab or as a redirect; set `return_url` on the document and the signed page offers the way back.
- **Frame our page** on your own site. This page.
- **Build your own page** on the signing routes (`/v1/sign/{token}`), which take no key and answer a browser on any site. The [Node client](https://signsealer.com/docs/sdk)'s `SignSealerSigning` is that client.

## 1. Send without sending

Give the signer `delivery: "embedded"`. Nothing is emailed or texted to them, and the automatic reminders leave them alone: you are showing them the page yourself. They still need an email address or a mobile number, because the certificate records how they could be reached and the completed copy goes to them.

```
const { links } = await signsealer.send(documentId, [
  { email: "dana@example.signsealer.com", full_name: "Dana Reyes", delivery: "embedded" },
]);
```

## 2. A fresh link when the page is shown

Do not keep the link from the send in your database: it is a bearer credential. Mint one when the person opens the screen that shows it. The link they had stops working, and the trail records that one was shown.

```
const { url, frame_origins } = await signsealer.embedLink(documentId, signerId);
// POST /v1/documents/{id}/signers/{signer}/embed
```

## 3. Put it in a frame, on a site the business has proven

The signing page may be framed only on sites the business has proven are its own, and the browser enforces it (`frame-ancestors`): anywhere else the frame stays empty. A business proves a site in one of three ways, the same three that let a signed page send somebody back to it:

- a **signing domain** it verified (Settings, under *Your own domains*), and every host under it;
- a **company sign-in domain** it proved (Settings → Single sign-on), and every host under it;
- the **site of an app it connected**, such as a WordPress site running our plugin: that one host. Not an AI assistant's: connecting Claude does not make claude.ai one.

`frame_origins` on the embed answer, and on `GET /v1/account`, lists them. Empty means nowhere yet. The business's public forms (`/f/{business}/{form}`) may be framed on the same sites.

```
<iframe src="{url}" title="Sign your rental agreement"
        style="width:100%;border:0;min-height:640px"
        allow="camera; geolocation"></iframe>
```

`allow="camera"` lets a template that asks for a photograph use it; `geolocation`, one that asks where the signer is.

## 4. Hear what happened

Inside a frame the page posts a message to the page around it:

```
{ source: "signsealer", event, document_id, signer_id, height }
```

| event | When |
| --- | --- |
| ready | Every page, as it loads. |
| resize | The page's height changed: set the frame's height to `height` and there is no inner scrollbar. |
| signed | They have signed. Other signers may still be to come; `signing.completed` on your webhook is when everyone has. |
| declined | They declined. |

```
window.addEventListener("message", (e) => {
  if (e.origin !== new URL(url).origin) return;      // only the signing page
  const m = e.data;
  if (!m || m.source !== "signsealer") return;
  if (m.event === "resize" || m.event === "ready") frame.style.height = m.height + "px";
  if (m.event === "signed") showThanks();
  if (m.event === "declined") showDeclined();
});
```

Treat the message as a hint to update the screen, not as proof: anything that matters — releasing an order, unlocking a booking — waits for the webhook, which is signed, or for `GET /v1/documents/{id}`.

## What the page does and does not do in a frame

- It sets no cookie, so a browser that blocks third-party cookies changes nothing.
- It carries one script in a frame, pinned by its hash in the page's own policy, and none at all when opened in a tab. The message is the only thing it does.
- The way back on the signed page (`return_url`) leaves the frame for the whole window.
- A frame on a site that is not proven shows nothing, and that is the browser refusing on our instruction, not an error to work around.

---

Source: https://signsealer.com/docs/waivers (Waivers and workflows)

# Waivers and workflows

A gym or a rental counter does not prepare a document per customer. A workflow does it for them.

A **workflow** is a published template plus the rules for running it: who signs and in what order, whether the business countersigns, how long a link lives, when to remind, and what the form asks for beyond a name and an email.

## Two ways in

- **A public page.** Give the workflow a `public_slug` and a participant starts their own document by filling in a form at `/f/<your-slug>/<public_slug>` on signsealer.com. No API call from you at all. The portal draws the QR code for it (Forms & QR in the dashboard: a page, a PNG, a counter card to print, and a button to paste on your own website), and `GET /v1/workflows/:id/qr` hands the same code to your own system. The form itself offers the person a code to scan when it is open on a counter tablet, so they can fill it in and sign on their own phone instead.
- **An API call.** `POST /v1/workflows/{id}/start` with the participant's details. Use this when your system already knows who is coming.

## A signing link on your own website

A form with a public address is a website signing link: a visitor opens it, answers the form's questions, reads the document with their answers in it and signs, and the signed document is yours, under Documents. You set one up in the dashboard under [Forms & QR](https://app.signsealer.com/workflows), or from the last step of *New template* with *Make a website signing link*, which saves the template and opens the form with the link switched on and the template's blanks already asked as questions.

### Before the link goes live

The form's page lists the checks a link has to pass, with the way to fix each one. A save that would put the link live, or keep it live, while one of the first kind fails is refused with that check's sentence, beside the field it is about, and so is switching it back on.

- **Must pass:** the template is published; every visitor gives their name and email; no box on the document is one only your business fills in when it sends, unless the visitor is asked it (by a question of the form's, or by a blank of the same name in the document's text); a line for your business to sign has somebody on the form who signs for the business; everybody else on the form has a name and an email; and your account can send (it is not closed, and not waiting for you to agree to updated terms). A pause on your sending, which holds messages while we look at something, does not stop a link.
- **Said, not stopped:** blanks nothing else fills, which are asked as questions of their own (“Will be asked as …”); an optional box only your business fills in, which is left empty; and the email check below, when it is off.

Visitors are turned away only for the template not being published or your account not being able to send, which stopped them before these checks existed: the form's page says it is not ready yet. A link that was live before the checks keeps taking signatures whatever else it fails. The forms list and the form's own page mark it *Needs attention* and say what to fix; until it is fixed, a change to the form is not saved, and nobody is emailed about it.

### The email check

A visitor who signs on the device in front of them first types a six-digit code we email to the address they gave, so you know the address is theirs. A visitor who asks for the link by email proves it by opening that email. One who asks for it by text confirms their number with a code, which proves the number and not the address, so when they open the texted link they type the code we email them too. Until the address is proven, nobody else on the form is sent their link: on a form signed all at once, the others' links go the moment the code is typed (or the emailed link is opened and agreed to), and on one signed in order they wait for their turn as always. Somebody who takes a place from a party link on such a form confirms a code too. An address that asked you to stop emailing it (mail to it bounced, or its owner unsubscribed) cannot be sent the code, so the page says so beside the box and asks for another, and nothing is made; so does a form that emails every visitor (Limits, below).

It is on for a new form with a link, part of the form, and free: it is not the one-time passcodes under Settings, and nothing is counted for it. Turn it off only if the link sits behind your own login, since without it anyone could type anyone's email. A form made before the check keeps working as it did: its link stays live, with the check off until you tick it, and its page says so. A tablet at the counter is not asked.

### Limits

**Taking signatures**, on or off, at the top of the form's page: one tap stops the form, its link and a tablet alike. The limits below are the website link's, shown on a form that has one: a tablet at the counter and the API start the form whatever they say, and the documents those start are not counted.

- **Stop after this many signed**: the link closes once that many documents started from it are signed. Anybody part-way through can still finish.
- **Stop taking signatures after** a day: the link closes after it, on the form's own calendar. This is not how long each person's link lasts.
- **Somebody who signed recently**: off unless you choose it, since a waiver is often signed at every visit. Set to a number of days, the link emails every visitor rather than letting them sign on the page: a link to sign, or, to an address that signed within those days, its signed copy again rather than a new document. The page says the same to everybody, so nobody can learn whether an address signed by typing it. Each of those links is one of your signing links: once you have sent as many as your account allows for now, the form tells every visitor to try again later, and makes nothing.

A closed link says why on its page, before anybody types anything, and the forms list says *Link closed by its limits*.

### Sharing it

Once the link is live, the form's page has it in one place: the link with a Copy button; *Try it as a visitor*, which opens it in a new tab (use a private window to see exactly what a stranger sees); the QR code, with a counter card to print and a PNG; the button to paste into your website; and, once you have proven your website is yours (a verified signing domain, a company sign-in domain, or a connected app's site), the code that puts the form itself inside one of its pages.

### An address

A form's question can be an address: the visitor is asked the street, the city, the state or region and the ZIP or postal code, and the document gets them as one line (“12 Main St, Bend, OR 97701”) where the question's blank is, such as `{{address}}`. The street, city and ZIP or postal code are needed for a required one, and for an optional one that was begun; the state or region may be left empty, for a country without one.

## Sending them back afterwards

Either way in takes a way back: `return_url` on the start, or `?return=` on the public page's address. Once they have signed, the page offers a button back to it — "Back to shop.example" — so the person who came from an order lands on the order, and the person who came from a form lands on the page it was on.

It is honored on exactly three kinds of host, because anything else would be an open redirect with a signature on the end of it: a signing domain you have verified, a company sign-in domain you have proven, or the site an [application](https://signsealer.com/docs/partners) you connected lives on — the redirect address it registered, since the consent flow completed there. A subdomain of the first two counts. It must be https. Anything else is refused with a 422 that says so, and no document is made. The check runs again when the signed page reads it, so a domain that stops being proven stops being somewhere we send people.

## What comes back

The document id and one token per signer — the participant's and every fixed role's — so you can hand the participant straight on to theirs rather than making them wait for an email.

```
{
  "document_id": "…",
  "title": "Liability waiver — Dana Reyes",
  "expires_at": "2026-10-15T00:00:00Z",
  "signers": [
    { "signer_id": "…", "email": "dana@example.signsealer.com", "participant": true, "token": "…" }
  ]
}
```

## How long a signature stays good

A waiver signed once a year is only useful if somebody can tell, on the day, whether this person's year has run out. Set the period on the template in the dashboard (Templates → How long it lasts), to match what the document's own wording says. The wording is what binds; the period is how the engine reads it. Every signed document then carries `standing` and `valid_until` on `GET /v1/documents`, `GET /v1/documents/:id` and the gate's `GET /v1/documents/:id/signers`:

- `current`: inside its period.
- `expired`: past it; the person signs again.
- `resign`: signed on a version the business has since asked everybody to sign again, because the terms changed.
- `renewed`: the same person has signed the template again since. This one is history, not a problem.
- `on_file`: signed, and the template has no period.

Before a check-in, ask for one person by their email or phone:

```
GET /v1/standing?template=liability-waiver&email=dana%40example.com

{ "template": "liability-waiver", "found": true, "document_id": "…",
  "signed_at": "2026-10-03T14:22:09Z", "template_version": 2,
  "standing": "current", "valid_until": "2027-10-03T14:22:09Z" }
```

`found: false` means they have never signed it: send them the form. The period is read when you ask, not stamped on the document, so waivers signed before the period was set are judged by it too. With a reminder set, each signer is emailed the business's public form a chosen number of days before theirs runs out, once.

## One person, two roles

A signer role with `"self": true` is the participant again in a second role — a sole proprietor signing for the business and again as the personal guarantor, a parent for themselves and as guardian. The engine makes a second signer at the same address, named with the role's label after the person's name, emailed its own link rather than handed on, and in a sequential workflow that link refuses a signature until the earlier one is in. The [two-party demo](https://signsealer.com/f/demo/agreement) runs on it. Neither the API nor the dashboard's workflow editor can set it yet; to have one person sign twice over the API, send them as two signers at two steps ([Signers, roles and order](https://signsealer.com/docs/signers)).

## Fields beyond a signature

A template can require initials, a checkbox, a date or a photo, and the requirement travels with the template — it freezes when the template is published, because what you were asked to initial is part of what you agreed to.

A `per_child` requirement becomes one row per covered minor, *named*. A guardian initialling once for three children is not the same act as initialling three times, and a court asked which child a release covered should not be told "the template said per child".

> **The refusal is in the database, not the form.** A signature is refused while anything required is unsupplied — so a second interface, a kiosk or an API caller cannot go around it. Your step form checking first is a courtesy that stops somebody being bounced; it is not the guarantee.

---

Source: https://signsealer.com/docs/pdf (Signing a PDF where it is)

# Signing a PDF where it is

Some documents are a page rather than words. A lease with initials in the margin of page four; a county form with a box in the corner. Those get signed where they are.

Watch it done: [Sign a PDF you already have](https://signsealer.com/guides/sign-a-pdf-you-already-have) (3:19) · [Upload your own PDF, in depth: an equipment rental agreement](https://signsealer.com/guides/upload-a-pdf-in-depth) (7:57) · [What your signer sees](https://signsealer.com/guides/what-your-signer-sees) (2:34)

Most templates here are text: the wording is the template, and the certificate's fingerprint is of exactly those bytes. A PDF is a different job, because the layout *is* the document — the whole reason a business has one is that somebody cared where things sit. Extracting the text would throw away the thing they are trying to keep.

So the file is kept whole, byte for byte. The signer sees the pages. The signature goes where the business put it. And the finished document is that same file with the answers drawn on it and the certificate after it.

The one exception is anything in the file that could act on its own once it is signed, in a reader that is not ours: a script that runs when it is opened or a box is pressed, a file attached inside it, a form field somebody could still type in, a layer that shows one thing on screen and another on paper. Those are taken out when it is uploaded, a form field drawn onto the page as it looked, and the business is told what was taken. The file kept, fingerprinted and signed is the file without them. An XFA form, which only Adobe's reader can draw, is refused: printed to a PDF, it uploads.

## The boxes it asks for

Every PDF starts with a signature and the date. When the file says where they go, that is where they are put. The rest of what it asks becomes a question on its own box. That covers:

- A line to write on, typed as underscores or drawn, named by its label beside or under it: *Signature*, *Date*, *Initials*, *Printed name* or anything else. A blank inside a sentence is named by the words around it.
- A box to tick, typed (☐) or drawn. Two or more after a question (*Paid by: ☐ Cash ☐ Card*) are its answers, each a tick named for both, and any or all of them may be ticked. When the page says to pick one (*select one*, *check one*), only one can be: ticking one hides the others after it, as radio buttons are.
- A box drawn to write in, named by the words to its left, above it, or in its own top corner.
- A fillable form's own fields, named by their tooltip, their own name or the words beside them: a list as a choice, a radio button as a tick for its answer.

Text in square brackets, such as `[DATE]` or `[CLIENT NAME]`, is usually the template’s own words for you to replace, not a place anybody can write, so it is never a box. It is flagged instead, as a note for an attorney is. Every piece of it is highlighted where it is on the pages of the Place step, and listed with its page after the upload, on the Place step and on the Send screen, each with what to do about it:

- **A blank:** replace it, in the program that made the file, with the words it stands for or with a blank line (`__________`) where your signer fills it in. Upload the file again and that line gets its box.
- **Meant to be there** (*[Company seal]*, *[emphasis added]*): press *Keep it* beside it. It stays on the page as written, part of the document, and is not flagged again; SignSealer never fills it in or asks for it. A kept one is listed under *Kept as part of the document*, with *Flag it again* beside it. Keeping one changes nothing anybody signs, so a published template can have them kept too.

A footnote’s number (`[1]`), a letter changed in a quotation (`[t]he`) and the lines a finished agreement carries (*[Signature page follows]*, *[Intentionally left blank]*) are never flagged. Nor is a field already filled in, a line under a heading, or a box with writing in it, ever a box.

This works on a PDF with its own text: one saved from the program that made it. A scan is pictures of its pages, with nothing to read where it asks to be signed, so its boxes are yours to drag on; the next screen and the Place step say so, and name any page of a typed file that has no words on it.

The file can come from your computer or, with **Choose it from Google Drive** on the upload step, from your Google Drive: Google asks you to let SignSealer see the one file you pick, it is brought in exactly as an upload is, and a Google Doc comes as a PDF. Nothing of your Google account is kept. And to have each signed copy put in your Drive as well, connect **Google Drive** under Settings: every document completed from then on goes into a SignSealer folder there, as the same sealed PDF the completion email attaches.

Unless you switch on **Read scanned PDFs** under Settings. Then a scan is sent to Google Document AI, which reads the words on its first fifteen pages and where each one sits, and its boxes are placed from them within a minute or two, as a typed PDF's are at once; the checks and the AI review read those words too. Up to 100 pages a day. A scan you upload again is placed at once, from the reading already made.

On an agreement between two parties, the signature line under the customer's heading (*Client*, *Renter*, *Employee*) is the signer's. The business's own line is found too: one under its heading (*Coach*, *Company*), labelled as its own (*Landlord signature*), or the other party's line when the customer's is named. It becomes the business's signature, with its date and printed name, signed by whoever the Send screen names as signing for your business, once the person it is sent to has signed. Nobody else is asked for those boxes, and that person is asked for nothing else. A line for a witness or a notary is left without a box. The next screen says what was placed, and how many more places to sign the file has, and the Place step shows every box, the business's in their own colour, to move or remove before you publish.

## Where the pages are drawn, and why it matters

**By SignSealer, from the file that is signed.** The pictures a signer reads are drawn on our own servers, in the API's own process, from the exact bytes that are kept, fingerprinted and sealed; no other service sees the file. Each picture records the SHA-256 of the file it was drawn from, and a signer, a tablet or your own signing page is shown a picture only when that is the template's file now.

They were once drawn in the browser of the person who uploaded the file, which kept every lease off our servers and tied no picture to the file: a picture that said one price over a file that said another would have been read and the other sealed. Since 1 October 2026 the server draws them (00474), at upload and, for anything that missed it, within the minute after.

> A PDF that cannot be drawn fails *visibly*, at setup, to the person who chose it — rather than silently at a counter, to somebody who has never seen it before. Publishing is refused until every page has a picture drawn from the file.

## What a signer gets

One image per page, with ordinary HTML inputs positioned over them. The signing page carries `default-src 'none'` and **no script at all** — that is checkable in the response headers, and it does not change for a PDF. An image needs nothing relaxed.

A box on a page is filled in on the page. A question with no box is asked underneath the document, the way every field is. Both hold the signature back until they are answered, if they are required.

## Where a box sits

A placement is a page and a rectangle, as **fractions of the page a reader sees**, with the origin at the top left:

```
{
  "key": "tenant_sig",
  "label": "Sign here",
  "kind": "signature",
  "place": { "page": 2, "x": 0.12, "y": 0.71, "w": 0.3, "h": 0.05 }
}
```

Fractions rather than points, because the same box has to mean the same thing in three places that measure differently: a picture at whatever resolution the browser produced, a CSS box at whatever width the signer's phone is, and the PDF itself in points. A fraction survives all three; a pixel survives none of them.

Top-left rather than the PDF's own bottom-left origin, because two of those three are CSS and the third is one subtraction — which lives in the sealer, once, rather than in every screen.

Rotation is handled. A page carrying `/Rotate 90` is *shown* turned, so a fraction is a fraction of the turned page, and the mark is placed and drawn to match.

### What can be placed

- Any field the signing adult supplies.
- A staff field, which whoever sends the document fills in: it is shown to the signer filled, and never asked ([Questions and fields](https://signsealer.com/docs/templates#fields)). It cannot be a signature, initials, a photo or the signing date.
- **Not** a per-child field: one box cannot hold an answer for four children.

What cannot be placed is refused when the template is saved, rather than accepted and found empty at a counter.

## What the certificate says

A template's body is what the certificate fingerprints, and a PDF template has no text to fingerprint. So its body **names the file's own SHA-256**:

```
This agreement is the attached document: lease.pdf (4 pages).

The file is identified by its SHA-256 fingerprint 9f2c…8ab1. The signed
copy is that same file, with each answer drawn where it was placed on the
page, and the certificate of completion after it.
```

The signed fingerprint therefore commits to those exact bytes. Change one byte of the original and the certificate no longer describes it.

## The text, and why you cannot edit it

A PDF template's text is the sentence naming the file, and it is fixed. That is not tidiness: it is the sentence's whole job. The certificate fingerprints the body, so naming the file's SHA-256 there is what makes the signature commit to those exact bytes. Take the fingerprint out and the pages are still signed, but nothing in the record says which file they were.

So the dashboard shows it read-only, offers no tidying of it, and the engine refuses a change to it — including through the API. The name, the questions and the boxes change freely; none of those is what the certificate commits to. To change what the text says, use a different file.

## Setting one up

In the dashboard, under **Templates → a PDF, signed where it is**: choose the file, let the pages draw, then drag a box for each question — or type the page and four percentages, which is the same thing and works without JavaScript.

Publishing is refused until every page has a picture. A template with a missing page would send somebody a row of gaps.

## What the signer does

They agree to sign electronically, answer anything asked underneath the document, then fill in the boxes on the page, on one step with one **Continue**. A box that still needs them is red and turns green as they fill it in; an optional one stays blue. Then they sign. Nothing they type is ever on a step whose button posts something else, so nothing arrives blank on the next one.

Two kinds of box are never typed into, because signing fills them:

- **A signature box**, any signature question placed on a page. It carries the signature they type to sign. They sign once.
- **A signing-date box**: a date question placed on a page whose key is `date`, `signed_on`, `date_signed`, `signing_date` or `today`, or whose label reads *Date*, *Date signed*, *Signed on* or *Today's date*. It carries the day they signed, in your timezone (asked when you name your business, and under *Settings → Messages*; Central time until you set one). Any other date, such as *Date of arrival*, is still asked.

A written template works the same way. `{{date}}`, and the same names as above (`{{today}}`, `{{signed_on}}`, `{{date_signed}}` and the rest), is never asked for: it is the day the document is first signed, in your timezone, written out in words (*September 25, 2026*). The signing page shows today's date there; the signature writes it in. A date you mean for something else, such as the day of an event or a rental, needs its own name, like `{{event_date}}`.

Every time shown for a signing is in the same timezone, and says which: the document's page in the dashboard, the Activity log, the certificate and the verify page all read like *26 Sep 2026, 10:24 pm PDT*, with the UTC time the evidence records beside it. So a document signed late in the evening carries the same day in its text as on its record, and the certificate says which timezone that day was taken in. If you change your timezone later, a document already signed keeps the day it was signed with: its times are then shown in your new timezone, and the certificate and the verify page no longer name it as the one that day was taken in.

A blank's name also picks the box it is asked in. `{{trip_date}}` is a calendar; `{{tee_time}}` is a time; `{{rental_starts}}` and `{{rental_ends}}` are each a day and a time, which is how a rental of a few hours and one of several days are both written. What is picked goes into the document in words (*September 27, 2026 at 2:00 pm*), and a period whose end comes before its start is refused: `_starts` and `_ends`, `start_` and `end_`, `arrival` and `departure`, `drop_off` and `pick_up`, `check_in` and `check_out` are read as the two ends of one period. A question you add yourself can be a *time* or a *date and a time* too.

A box keyed `full_name` or `name` starts with the signer's name filled in, for them to check. Initials are written in the middle of their box, in the same letters as every other answer.

## Before it goes out

A PDF template's own text is the sentence naming the file, so SignSealer reads the words on its pages instead, once, as the file is uploaded, and keeps them with the file: a new version that keeps the file keeps its words. A file from before this, or one whose reading failed, is read within a minute.

Straight after the upload, and again on the last step before it is published, the walk says what the **pre-send checks** found on the pages: text in square brackets like *[insert name]* that you have not kept, *TBD*, *lorem ipsum*, a document that never says what signing it means. Each is named with its page. A line of underscores is not one of them: on a PDF it is where a box goes. The Send screen runs the same checks on the pages as it runs on a typed text, beside the ones about the people it is going to and the blanks that were filled in.

A **note for your attorney** on the pages, *[Attorney: …]*, is refused as it is in a typed text: the PDF is not published, and no document is made or sent from one published before the pages were read, and the refusal names the page. Settle it with your attorney and upload the file without it.

What was not read is said rather than passed over. A page with no words on it (a picture, or blank) is named, and a scanned PDF, whose pages are pictures of words, is said to have had nothing to read. Look at those pages yourself.

The **AI review** reads the same words, on the template's own page (**Check with AI**, when the business has switched AI review on under Settings). On a membership with the review switched on, it runs on its own as a PDF is uploaded: the upload asks for it, the review runs within a minute, and what it found is on the walk's last step and the template's page. It counts against the day's model runs like any other review. It never reads the naming sentence: that would put a reading of a fingerprint on the record as a reading of the agreement. A scanned PDF is refused in a sentence rather than reviewed as empty, unless Read scanned PDFs is on: then the review waits for Google's reading and reads its words. The review on the send screen still refuses a PDF, and points to the template's page.

The same holds on a public form at `/f/…`: the panel headed “What you are about to read” says what the document is and that its pages are on the next screen, rather than showing the fingerprint.

## From the API

Everything after setup is ordinary. A PDF template is a template: prepare a document from it, send it, read the link, supply fields, sign, and download the sealed copy exactly as for any other. `GET /v1/sign/{token}` carries the pages, so an integrator building their own signing screen gets the same pictures the hosted page uses:

```
{
  "title": "Tenancy — Flat 2",
  "body": "This agreement is the attached document: lease.pdf …",
  "pages": [
    { "n": 1, "width": 1275, "height": 1650 },
    { "n": 2, "width": 1275, "height": 1650 }
  ],
  "fields": [
    { "key": "tenant_sig", "label": "Sign here", "kind": "signature",
      "required": true, "supplied": false,
      "place": { "page": 2, "x": 0.12, "y": 0.71, "w": 0.3, "h": 0.05 },
      "at_signing": "signature", "placed_value": null, "placed_words": null }
  ]
}
```

`at_signing` marks a box that signing fills: draw it, do not ask for it, and `POST /v1/sign/{token}` will not refuse for it. `placed_value` is what a box carries, and `placed_words` the same as it is printed on the sealed copy — a date as `October 5, 2026`, a time as `9:00 am` — so your screen can show the page the way it will be sealed.

`from_sender` marks a box filled in by whoever sent the document: a question marked `staff` and placed on the page, such as `pickup_date | Pickup date | date | staff`. It is given when the document is sent — under `values` on `POST /v1/documents`, or under `fields` or `values` when a workflow starts — and a required one that is missing refuses the send, naming it. The signer's link carries it already answered: draw it with its `placed_value`, do not ask for it, and supplying it is refused.

Each page is an image at `GET /s/{token}/page?n=1` — the token is the whole credential, so no API key goes near it and an `<img>` can load it directly. The images are drawn by SignSealer from the template's file itself, so they are always pictures of the document being signed, and the file itself, before anything is filled in, is at `GET /s/{token}/document.pdf`.

`GET /v1/templates/{id}/pdf` says whether a template is a PDF one and whether it is ready to use:

```
{
  "has_pdf": true,
  "page_count": 4,
  "drawn": 4,
  "ready": true,
  "sha256": "9f2c…8ab1",
  "original_name": "lease.pdf"
}
```

> **Uploading the file itself is a dashboard step, not an API call.** If you need this from a server, say so and we will design it with you rather than guess.

## What is kept

- **The file**, exactly as uploaded, on the template version. A new version copies it; a new upload replaces it and takes the old pictures and every box with it, because a box chosen against a page that no longer exists is a signature in the margin of the wrong page.
- **A picture of each page**, drawn by SignSealer from the file, which is what a signer sees.
- **The placements**, frozen onto each document when it is prepared — so revising a template afterwards never moves a signature on a document somebody already signed.

Retention and redaction work as they do for any document: [evidence and certificates](https://signsealer.com/docs/evidence) explains the package, and the sealed copy is the same artifact with the customer's own pages at the front.

---

Source: https://signsealer.com/docs/packets (Reservations and packets)

# Reservations and packets

One booking. Four guests, two of them children. A rental agreement, house rules and a hot-tub waiver. One link, and one state your system can wait on.

## Import the reservation

`PUT /v1/subjects` is keyed on `(provider, external_id)`, so it is safe to call on every webhook from your PMS. Send the guest list with it and the packet is built in the same call.

```
{
  "provider": "hostaway",
  "external_id": "RES-88213",
  "label": "River Bend Cabin, 3–7 Oct",
  "starts_on": "2026-10-03",
  "facts": { "adults": 2, "minors": 2, "pets": 1, "amenities": ["hot_tub"] },
  "participants": [
    { "ref": "a1", "full_name": "Dana Reyes", "email": "dana@example.signsealer.com", "is_primary": true },
    { "ref": "c1", "full_name": "Sam Reyes", "date_of_birth": "2014-06-02", "guardian_ref": "a1" }
  ]
}
```

> **SignSealer is not a booking system.** No availability, no rates, no calendar. A subject is a thin shadow of your record, and it stays that way on purpose: the day we grow a booking engine we start competing with the platforms this integrates with.

## What each guest owes

The documents a booking needs are chosen in the dashboard, under **Documents for bookings**: on each connected booking system's own page, and, for reservations sent with `PUT /v1/subjects`, on [Bookings from Zapier, Make or the API](https://app.signsealer.com/integrations/documents). Each answers *whether* a document is needed, from the facts — a property with a hot tub needs the hot-tub waiver — and *who* owes it: the person who booked, every adult, or a parent or guardian for each minor. Two questions, kept apart, because folding them together is how a rules engine becomes a programming language nobody can debug.

A default answers for the bookings nothing else fits, and a person is asked for a document once however many choices want it of them. A reservation that matched nothing has an empty packet: `ready`, with nothing `required`. Check `required` before treating it as done.

## Minors

Minority is judged on the **arrival date**, not the signing date. A seventeen-year-old booking for the week of their eighteenth birthday is still a minor when they get on the water. A blank date of birth is refused rather than read as an adult — that is the one wrong answer, and it files a child as an adult with nobody's signature behind them.

## Readiness

A packet reports counts as well as a state, so a dashboard can say "3 of 5" and a door lock can wait on `ready` without either of them guessing what "partially complete" meant. A decline makes the packet `blocked`, not "still waiting" — somebody already answered.

Subscribe to `packet.ready` and it fires the moment the last required document completes. Not on a sweep: "ready ten minutes after the guest finished" is a guest standing outside a locked door.

---

Source: https://signsealer.com/docs/evidence (Evidence and certificates)

# Evidence and certificates

Somebody disputing a signature three years from now does not get a database. They get a PDF and a claim.

Watch it done: [What the evidence pack proves](https://signsealer.com/guides/what-the-evidence-pack-proves) (1:42) · [Every agreement, on one trail](https://signsealer.com/guides/every-agreement-on-one-trail) (1:09)

When a document completes, a **certificate** is issued: the document and its hash, every signer with the method and value of their signature, and the whole event chain with the address, the browser, the language and the device at each step. It is frozen at issue and hashed.

Where the address was, the certificate prints as *Network region (approximate)*: what the network edge in front of us resolved it to, and only when the request provably crossed that edge. A caller who reaches the API directly cannot supply it, so a signer cannot choose the place printed on their own certificate; nothing is looked up from anybody else either.

## Frozen, and checked against the live record

Freezing sounds like the wrong instinct — a derived value that has drifted is the one somebody quotes. But a certificate is *evidence*, and evidence says what was true at a moment. Deriving it later means the document somebody holds and the document we render can differ with nothing to compare.

So both properties are kept. The payload is frozen and hashed at issue, *and* verification re-derives it from the live record and reports any divergence:

```
{
  "certificate_found": true,
  "document_matches": true,
  "still_matches_record": false,
  "divergence": "The document text has changed since this certificate was issued."
}
```

> **A divergence is a finding, not a correction.** We report it and change nothing. A verification service that quietly re-derived would be unable to answer the one question it exists for.

## What the signer was told, and how the link reached them

A certificate does not only say *that* consent was given. For each signer it carries the consent disclosure in the words that were on the page, with its SHA-256 and a version reference (`consent/1`, plus the template's own consent wording when the business wrote one), the address and browser the agreement came from, and the statement that stood above the signature, hashed and versioned the same way. What the person agreed to is on the record, not reconstructed from a later copy of the page.

Each signer also carries an **assurance level**: what the signature proves about who was at the keyboard. None of these is an identity check, and the printed certificate says so in each case.

| Level | What it proves |
| --- | --- |
| `email_link` | A link we emailed to this address was used: control of the inbox. |
| `sms_link` | A link we texted to this number was used: control of the phone. |
| `email_otp` / `sms_otp` | As above, and a one-time code sent to the same address or number was entered before consent: control of that inbox or phone at the moment of signing, not only when the link arrived. |
| `in_person` | The signing was started by a tablet you paired, using that tablet's own credential: our record of which device opened it, not anything the signer's browser said. |
| `link` | A link handed over some other way — a public form, a QR code, your own application — was used: possession of the link. Also what a signature says when the link used was one shown at the gate or put in a frame after an email went out: an inbox proves nothing about who scanned a code. |
| `party_link` | When everybody in a booking's party signs: a link the person who booked was given to hand over — to somebody they added with no email address, or a number that has not agreed to your texts — was used. Possession of the link, which the person who booked also had; the signature's event names them (`handed_out_by`), and the printed certificate says the link was handed out by them. Anybody in the party with an email address is sent their own link, and the person who booked never sees it. |

The one-time code is a choice each business makes under Settings ("Ask signers for a code"). It applies to signers a link was delivered to; somebody signing at the counter is not asked. It comes with the membership: on Free no code is asked, and a choice made on the membership is kept for when it starts again. Over the API the step is `POST /v1/sign/{token}/code` and `/verify`. Certificates issued before these fields existed carry the times and addresses they always did, and nothing invented.

### ID Evidence

A business may ask the people it sends a link to for a photograph of a government-issued ID, and optionally of themselves, after consent and before the signature (Settings → "Ask signers for ID evidence"). The image is resized on the way in, kept encrypted under a key derived for that business, shown only to its team from the document's page (each look is audited), and dropped after thirty days or with a redaction. The certificate carries each capture by kind, SHA-256, type, size, time and the words the person was told, with `"verified": false` beside it and "not verified against anything" in print: it is evidence that somebody held that ID up when they signed, not a verification of who they are, and a certificate issued before the image is dropped still matches its record after. At the counter the tablet offers the same photo, and the customer may take it or skip it. ID Evidence comes with the membership: on Free nobody is asked, and a choice made on the membership is kept for when it starts again.

## The sealed PDF

`GET /v1/documents/{id}/pdf` returns the certificate as a PDF sealed with a detached digital signature (PAdES) and an RFC 3161 timestamp — over the signature, not over the document, which is what lets a reader tell when the seal was applied rather than when the file was made.

It is sealed **once**, when the document completes, and kept. Every download — from the API, the dashboard, the signer's own page or the completion email — is that file, byte for byte, so two copies of one agreement are the same copy, and a later change to the business's logo or to how we draw a certificate does not reach one already made. Its SHA-256 is recorded, and is what public verification compares a file with (below). A document that completed before copies were kept is sealed no later than its first download, and that copy is kept the same way.

The seal is **self-issued**, and the PDF's last page says so. It proves the file has not changed since it was sealed: alter a byte and a reader reports the signature as broken. It does not prove who produced the file — no certificate authority stands behind it, and a reader will show the sealer's identity as unverified. Identity is established by the verification code and the record it points to, not by the seal. If a counterparty requires a seal that validates as trusted in Adobe Reader (an AATL certificate), ask; it is not something SignSealer sells today.

### The photographs

When a document asked for photographs as answers (a field of kind **photo**), the sealed PDF prints them on pages after the certificate: each with its question, who took it and when, and its SHA-256, under the same seal as the rest of the file. A JPEG is embedded exactly as it was kept, so extracting it from the PDF and hashing it gives the fingerprint on the certificate; a PNG is redrawn into the PDF's own image format and says so. The images are decrypted only while the file is made. A business can leave them out for a template (`photos_in_copy: false`, or Templates in the dashboard); the certificate carries every hash either way, and a redacted document prints none. ID evidence is not among them: it is dropped after thirty days and stays off the signed copy.

## The evidence bundle

`GET /v1/documents/{id}/bundle` returns the same sealed PDF with the evidence package printed after the audit trail: every message sent about the document and whether it arrived, every webhook delivered to your systems, what an AI review flagged before it was sent (when the business ran one, and that it was sent anyway), and the record's state when the file was made — voided, redacted, still matching. The package's SHA-256 is on the last page, so the JSON and the PDF can be tied together if both are produced. One file, sealed as one, for an insurer, an adjuster or a court; the JSON stays the machine-readable form and is available before the document completes, when the bundle is not.

## Public verification

Every certificate carries a sixteen-character code, printable and typable: no I, L, O or U, because those are the four that get mistyped as 1, 1, 0 and V. Anybody holding the document can check the certificate without an account: the code alone confirms it exists, who issued it, when it completed, how many signed and that the record still matches. Add the SHA-256 of the sealed PDF you were sent — `shasum -a 256 the-file.pdf` — and, when it is the file we issued, the page says so and names the signers and shows the trail; the SHA-256 of the document's text is accepted too, as it always was. Over the API, `GET /v1/verify/{code}?sha256=` answers `copy_matches` when it was the file and `document_matches` for either. A copy handed out before copies were kept was never recorded, so its SHA-256 cannot match; its code still verifies. Email addresses are never on the public page; they are in the sealed PDF and your evidence package.

---

Source: https://signsealer.com/docs/partners (Platforms and partners)

# Platforms and partners

A point-of-sale system, a property manager, a booking engine: your product has customers of its own, and each of them signs waivers or agreements. This page is how that works, and who pays whom.

## How your customers get credentials

Every business you serve is a **business** in SignSealer — its own templates, documents, evidence and team, isolated from every other by SignSealer, not by anything your code has to get right. Our servers connect to the database as the owner of its tables, so the isolation they keep is in the functions they call: each checks which business the caller belongs to and filters what it reads and writes by that business. Row level security on every table binds anybody who reaches the tables directly through the data API. Today each one connects the same way any customer does: somebody at that business signs in to the portal, opens *Integrations → API keys*, and creates an API key with the scopes your integration needs (`signing:read` and `signing:write` for most). Your product stores that key for that business and sends it as `Authorization: Bearer`. Keys are scoped, revocable, and shown once; the [authentication](https://signsealer.com/docs/authentication) page has the details.

Or your product asks the business once. Send the person to `/oauth/authorize`, they agree on a consent screen that shows your registered name and the scopes you asked for, and your server exchanges the code at `/oauth/token` for an access token that works for an hour and a refresh token that gets the next one. It is standard OAuth 2.0 with PKCE; any client library speaks it, and the [authentication](https://signsealer.com/docs/authentication) page has the two requests in full. The business can end the connection under *Integrations → Connected apps* whenever it likes. Nothing about the key-based path changes.

## We handle the signing; you share in the revenue

The businesses you bring pay SignSealer directly, and we run everything for them — billing, support, the signing pages, the texts, the evidence. You share in what they pay, month after month, for as long as they stay. The terms are in your partner agreement; [tell us about your product](https://signsealer.com/partners) and we will send you yours.

- **Which businesses are yours.** One that signs up through your link, installs your app in its first weeks, or redeems a promotion code made for you. Once it is yours it stays yours. A business your own people own — somebody on your partner dashboard, or one of your addresses — is not one you bring, and is not counted.
- **When your share starts.** A person here looks at every new partner account first. Your link works from the day you enroll and businesses that sign up through it are recorded as yours; your share starts on the day we approve the account, on what they pay from then on.
- **When you are paid.** Each month closes into a statement that does not change afterwards: each business, what it added, and what you are owed.
- **Seeing it yourself.** Your partner dashboard shows your link, your businesses and every statement, and the same figures are in the API at `/v1/partner`, read with your OAuth client's credentials — never a business's key.

## Custom branding

The businesses you bring can sign on pages wearing your name, colors and logo, with **Powered by SignSealer** at the foot, and their mail says it was sent through you. You set it up yourself from your partner dashboard, at no charge. Each business that texts does so from a number of its own, registered in its own name (coming soon). A business that buys white label for itself shows its own brand instead.

## Texting numbers for the businesses you serve

Each business that texts does so from a number of its own, applied for by its owner or an admin under the business's legal name: the carriers register the business, not you, so you cannot apply for it. What you can do is take each owner to the right page with your answers already in it, and show where each one has got to on your own screen.

- **Which businesses need one.** `GET /v1/account` with each business's key or token: `texting.why_not` is `number` while it waits for its own, and `texting.application` says where its application has got to (`status`, `phone` once verified, `reason` when the carriers asked for a change), or null when it has not applied.
- **A link for its owner.** `POST /v1/texting/number/invitations` with what you know, in the application's own names (`legal_name`, `ein`, `website`, the address, the contact, the `kind` of number). Put the `url` it returns in front of the owner. It opens, after they sign in, on that business, with your answers filled in and your app named as the one that filled them; they read each one, tick that it is true and apply. Fourteen days, used up when they apply.
- **Each step as it happens.** Subscribe the business's endpoint to `texting.number_updated`, or to `*` ([Webhooks](https://signsealer.com/docs/webhooks)).

## Billing your customers yourself, by agreement

Where you would rather your customer paid you alone, a business can be **billed through a partner**: it pays SignSealer nothing, its billing page says who bills it, and its completed agreements roll up onto your monthly statement at a wholesale rate agreed with us. It is set up by hand, for the deal that needs it.

Either way, start with [the partner form](https://signsealer.com/partners): a few questions about your product and your customers, and a quote comes back to you by email.

## What stays the same

- **Isolation.** A key for one business reaches that business and no other, whoever holds it.
- **Evidence.** The certificate, the trail and the sealed PDF belong to the business that sent the document, and it can download them without you.
- **Webhooks.** Register your endpoint per business, or one endpoint that reads `tenant_id` from the payload; either way the signature is per business.
- **The signer's experience.** The signing page is served by us, in our name or with your custom branding over it; embed the link, text it, or open it on a tablet. It loads nothing from anywhere else.

## The partner API

Three routes, and all three only read: your program and this month so far, the businesses that are yours, and every month that has closed. They answer on `https://api.signsealer.com`, beside the rest of the API. Nothing you send changes what you earn; the share and the program are set by SignSealer.

### Credentials

Send your OAuth client's `client_id` (`ss_client_…`) and `client_secret` (`ss_secret_…`) by HTTP Basic, the same pair `/oauth/token` takes.

```
curl -u "$SIGNSEALER_CLIENT_ID:$SIGNSEALER_CLIENT_SECRET" https://api.signsealer.com/v1/partner
```

Your client id is on your partner dashboard, under *API and app installs*. The secret is shown once and kept only as a hash. A partner account set up from its quote is not sent one, so make it there: the dashboard's owner presses *Make a new client secret*, and only the owner can.

> **A new secret replaces the old one at once.** It is the same secret your app sends to `/oauth/token`, so give your app the new one at the same time: until it has it, exchanging a code or refreshing a token there fails.

The credentials work from the day you enroll, while your account is still under review. A business's API key or access token is refused, and so are a public client (one with no secret), a disabled client and a client that is not enrolled as a partner. Each of them gets the same `401 unauthorised` with a `WWW-Authenticate: Basic` header: which part was wrong is not the caller's to learn.

### GET /v1/partner

Your program, this month so far, and the link to hand a business. The figures in these examples are made up; your share is the one on your quote.

```
{
  "partner": "DeckPOS",
  "client_id": "ss_client_0123456789abcdef0123456789abcdef",
  "referral_code": "deckpos",
  "share_percent": 10,
  "active": true,
  "custom_branding": true,
  "review": "approved",
  "earning": true,
  "earning_since": "2026-09-02T15:04:05+00:00",
  "businesses": 12,
  "month_to_date": {
    "month": "2026-10-01",
    "businesses": 9,
    "gross_cents": 43900,
    "fees_cents": 1650,
    "sms_cost_cents": 1000,
    "revenue_cents": 41250,
    "share_bp": 1000,
    "share_cents": 4125
  },
  "signup_url": "https://app.signsealer.com/signup?partner=deckpos"
}
```

| Field | Means |
| --- | --- |
| `partner` | The name your OAuth client is registered under. |
| `referral_code` | The code on the end of your signup link. |
| `signup_url` | Your signup link: `https://app.signsealer.com/signup?partner=` and your code. |
| `share_percent` | Your share, as a percentage: `10` is 10%. |
| `active` | `false` while your program is paused. No new business is made yours; the ones you have stay yours and keep earning. |
| `custom_branding` | Whether your custom branding is on. |
| `review` | `pending`, `approved` or `declined`. `pending` until a person here has looked at your account. |
| `earning` | `true` once your account is approved. |
| `earning_since` | When your share started counting; `null` until you are approved. |
| `businesses` | How many businesses are yours, closed ones included. |
| `month_to_date` | This calendar month so far, in UTC, worked out the way its statement will be (below). `month` is its first day; `businesses` counts the ones that added something; `share_bp` is your share in hundredths of a percent; `share_cents` is truncated to the cent. |

Nothing accrues before your account is approved, so until then every amount in `month_to_date` is `0`. Businesses that sign up through your link meanwhile are still recorded as yours.

### GET /v1/partner/businesses

The businesses that are yours, newest first by when they became yours.

| Query | Means |
| --- | --- |
| `limit` | A whole number from 1 to 200; 50 when left out. |
| `offset` | How many to skip: 0 or more; 0 when left out. |

```
{
  "data": [
    {
      "tenant_id": "7d9c1c1e-7a57-4f55-9a86-0f7f3f9c2b11",
      "name": "Harbour Rentals",
      "status": "active",
      "source": "referral_link",
      "attributed_at": "2026-08-02T15:04:05+00:00",
      "month_to_date_cents": 1840
    }
  ],
  "has_more": false
}
```

There is no `total`. Ask again with `offset` plus `limit` until `has_more` is `false`. A business that becomes yours while you walk the list appears at the front and moves the rest along by one.

- **`status`** is `active`, `suspended` or `closed`.
- **`source`** is how it became yours: `referral_link` (it signed up through your link), `oauth_install` (it installed your app in its first thirty days), `promotion` (it redeemed a promotion code made for you) or `ops` (SignSealer set it).
- **`month_to_date_cents`** is what it has added this month after card fees and the carrier's cost of its texts. It counts from the latest of the start of the month, when the business became yours and when your account was approved, and it is `0` until you are approved. Credit SignSealer gave away earns nothing.

### GET /v1/partner/statements

Every closed month, newest first, under `data`. The list is not paged. A month closes on the first run of our sweep after midnight UTC on the 1st, and only for an approved account, so there are none while yours is under review. A statement is written once: afterwards only `paid` and `paid_at` change, when SignSealer records the payment.

| Field | Means |
| --- | --- |
| `month` | `YYYY-MM`. |
| `businesses` | How many businesses added something that month: one entry each in `lines`. |
| `gross_cents` | What they paid for and used. |
| `fees_cents` | The card fees on that, in proportion. |
| `sms_cost_cents` | The carrier's cost of their texts, in proportion. |
| `revenue_cents` | `gross_cents` less the fees and the texts' cost: what your share is of. |
| `share_percent` | Your share at the rate in force when the month closed. |
| `share_cents` | That share of `revenue_cents`, truncated to the cent once, on the month's total. |
| `carried_in_cents` | A shortfall from your previous statement: 0 or negative. |
| `payable_cents` | What you are owed for the month: 0 or more. |
| `carried_out_cents` | A shortfall carried into the next month: 0 or negative. |
| `paid`, `paid_at` | Whether SignSealer has recorded the payment, and when. |
| `lines` | One per business that added something: `tenant_id`, `name`, `gross_cents`, `fees_cents`, `sms_cost_cents` and `revenue_cents`. A refund can make a line negative, and it is kept. |

The sums always meet: `payable_cents` plus `carried_out_cents` is `share_cents` plus `carried_in_cents`. A month that comes to less than nothing is carried into the next rather than invoiced.

### Errors

The body is the API's usual `{ "error": { "code": …, "message": … } }`, and every answer says `Cache-Control: no-store`.

| Status | Code | When |
| --- | --- | --- |
| 401 | `unauthorised` | No Basic credentials, or ones that do not open a partner account. |
| 400 | `invalid_limit` | `limit` on `/v1/partner/businesses` is not a whole number from 1 to 200. |
| 400 | `invalid_offset` | `offset` is not a whole number, 0 or more. |
| 404 | `not_found` | A path under `/v1/partner` that is not one of the three. |
| 405 | `method_not_allowed` | Anything but `GET` (or `HEAD`), with `Allow: GET`. |

### From the Node client

`SignSealerPartner` in [@signsealer/sdk](https://signsealer.com/docs/sdk), from version 1.8.0, which reached npm in 1.10.0. It takes your client id and secret and refuses a business's API key (anything starting `mk_`) when it is built. Every call only reads, so a network failure, a `429` or a `5xx` is tried again as it is, up to `maxAttempts` (3, the first included); anything else throws a `SignSealerError` at once. Keep the secret on a server.

```
import { SignSealerPartner } from "@signsealer/sdk";

const partner = new SignSealerPartner({
  clientId: process.env.SIGNSEALER_CLIENT_ID!,
  clientSecret: process.env.SIGNSEALER_CLIENT_SECRET!,
});

const me = await partner.profile();              // GET /v1/partner
if (!me.earning) console.log("under review:", me.review);

for (let offset = 0; ; offset += 200) {          // GET /v1/partner/businesses
  const page = await partner.businesses({ limit: 200, offset });
  for (const b of page.data) console.log(b.name, b.source, b.month_to_date_cents);
  if (!page.has_more) break;
}

const months = await partner.statements();       // GET /v1/partner/statements: the data array

SignSealerPartner.signupUrl(me.referral_code);   // me.signup_url, built without a call
```

### In the OpenAPI description

The three routes are in `/openapi.json` under the `Partners` tag, with a security scheme of their own, `partnerAuth` (HTTP Basic), in place of the API key the document declares by default. The [API reference](https://signsealer.com/docs/api#partner) draws them from the same declarations.

---

Source: https://signsealer.com/docs/texting (Texting and consent)

# Texting and consent

SignSealer sends texts on your behalf, from your business's own toll-free or local number, registered with the carriers under your name, and every text names your business. Texting from your own number is coming soon. The carriers hold *you* to what the person agreed to, and they ask for the exact wording. This page is what to collect and how to hand it over.

Watch it done: [Text the link instead](https://signsealer.com/guides/text-the-link-instead) (2:43)

## Why a text goes nowhere without this

The engine will not text a number it has no consent for. That is not a policy on a page — it is a check in the database, and a send to a number with no consent is recorded `suppressed`, not queued.

If you collect phone numbers on your own booking form, order page or at a counter, SignSealer never saw the person tick the box. Until you tell it, it assumes nothing, and every text you expect to go will not go. Send the consent once, when you take the number.

## The seven things the wording has to say

Send the exact words that were in front of the person — not a summary, not a description. It is kept verbatim, because it is what a carrier asks for when they audit your traffic. It must carry all seven of these, and a disclosure missing any is refused with `422` naming which:

| What | Why |
| --- | --- |
| **STOP** opts out | The one instruction every recipient must have. |
| **HELP** gets help | Required alongside it, and as often forgotten. |
| Message and data **rates** may apply | The cost is theirs, and they have to know. |
| Message **frequency** | "Frequency varies", or a number — "up to 4 msgs/month". |
| Consent is not a **condition of purchase** | Nobody may be made to agree to texts to buy something. |
| Their number is **not shared or sold** for marketing | Said as a promise: "we will not share or sell", "never sold". |
| Where the **terms** and the **privacy** policy are | Both, because a disclosure that links one is the half a reviewer asks about. |

Wording that passes. It is not short, and that is the trade: every sentence in it is one a carrier checks for, and a disclosure missing any of them is refused when you try to record it (`00327`).

```
I agree to receive text messages from [Your business name] via Sign Sealer
about documents I need to read and sign: the signing link, at most one
reminder if I have not signed, and a confirmation when everyone has signed.
Message frequency may vary. Message and data rates may apply. Consent is not
a condition of purchase. We will not share or sell your mobile information
with third parties for promotional or marketing purposes. Reply HELP for
help. Reply STOP to opt out. Terms: https://signsealer.com/legal/terms
Privacy: https://signsealer.com/legal/privacy-policy
```

Name your own business where the placeholder is. The recipient has to be able to tell who is texting them, and "a platform they have never heard of" is not an answer a carrier accepts.

The tick box must be the person's own act. A pre-ticked box, a checkbox bundled with your terms of service, or consent as a condition of booking are all things a carrier will take your numbers away for.

## Recording it

```
POST /v1/sms-consents
{
  "phone": "(615) 555-0142",
  "obtained_via": "booking form, checkbox beside the phone field",
  "wording": "I agree to receive text messages from Harbour Rentals via Sign Sealer about documents I need to read and sign: the signing link, at most one reminder if I have not signed, and a confirmation when everyone has signed. Message frequency may vary. Message and data rates may apply. Consent is not a condition of purchase. We will not share or sell your mobile information with third parties for promotional or marketing purposes. Reply HELP for help. Reply STOP to opt out. Terms: https://signsealer.com/legal/terms Privacy: https://signsealer.com/legal/privacy-policy"
}
```

One call covers all three things we would text about — the signing link, a reminder, and the confirmation — because somebody who agreed to those agreed to all three. It answers with the number in E.164 and the purposes recorded:

```
{ "phone": "+16155550142",
  "purposes": ["signing.link", "signing.reminder", "signing.completed"] }
```

`obtained_via` is for you, later. "Booking form" is enough; "the checkbox beside the phone field on /book" is what you will want when somebody asks in eighteen months.

## Then send the link to it

A consent on its own sends nothing. Put the number on the signer, beside the address or instead of it:

```
POST /v1/documents/{id}/send
{ "signers": [
    { "full_name": "Dana Reyes", "email": "dana@example.signsealer.com", "phone": "+16155550142" },
    { "full_name": "Sam Ortiz", "phone": "+16155550188" }
  ] }
```

Dana gets the same link twice, by mail and by text, because a person who does not check one inbox checks the other. Sam gets it once, by text, and their `email` comes back `null` in the answer.

The text goes only where `may_text` is true for `signing.link`. Where it is not, the send is not refused: the email still goes, and the reason the text did not is on the document's evidence trail as `signing.link.not_texted`. A signer with no email and no textable number is a different matter and is refused by name, before anything is minted — there is nowhere for their link to go.

From then on the number carries: the reminder and the completion note follow the road the link took, each under its own consent. The wording promises at most one reminder, and the engine keeps it: a signer is texted one reminder over the life of their link, whoever asks for it and however often, and every reminder after that goes by email alone — or, for a signer with no email address, is refused with `422` saying why ([Limits and paging](https://signsealer.com/docs/limits)).

## Asking before you ask again

```
GET /v1/sms-consents?phone=%2B16155550142
```

```
{ "phone": "+16155550142", "may_text": true, "why_not": null,
  "obtained_via": "booking form, checkbox beside the phone field",
  "obtained_at": "2026-10-03T14:22:09Z" }
```

Use it to decide whether to put the tick box in front of a returning customer again. It answers for one number at a time and deliberately will not list every number you hold.

`may_text` is what the engine will actually do, not what one of its checks says. Consent has to be live *and* the number must not be suppressed — a disconnected phone keeps its consent and still cannot be reached. When it is false, `why_not` tells you which:

| `why_not` | What happened | What to do |
| --- | --- | --- |
| `no_consent` | Nobody ever recorded one. | Ask, and record it. |
| `revoked` | They replied STOP. | Nothing. It is theirs to undo. |
| `suppressed` | The number could not be reached — disconnected, or a landline. | Check the number with them; email in the meantime. |

## STOP is theirs, not yours

When somebody replies STOP, the consent is *revoked*, not merely suppressed — and you cannot re-consent them by calling this endpoint again. They have to opt in themselves. A door that let a business overwrite a withdrawal would make the whole record worthless, since the business is not who withdrew it.

A number is one person however it is written. `(615) 555-0142`, `615-555-0142` and `+1 615 555 0142` are the same consent and the same STOP, so you can send numbers in whatever shape your database holds them.

## What we never do

SignSealer does not send marketing texts. The only purposes that exist are the signing link, one reminder, and the confirmation; a request for anything else is refused by the engine rather than by a policy. That is worth saying to your own customers, because it is the reason this consent is narrow enough to be easy to collect.

---

Source: https://signsealer.com/docs/api (API reference)

# API reference

Generated from the router. If an endpoint takes a field, it is in this table, because the table and the validator read the same declaration.

> **Base URL** `https://api.signsealer.com`. Everything is JSON, and every response carries `x-request-id`. Every route takes `Authorization: Bearer mk_live_…` (a key, or a partner's OAuth token) except the signing and verifying routes, where the token or code in the path is the credential and a key is ignored; those also answer a browser on another site.

## Account

### GET /v1/account

Scope `signing:read`

**Show the account this key belongs to**

The first call any integration makes: prove the credential works and show the operator the name of the account they just connected. `frame_origins` lists the sites its signing pages may be framed on (see `POST /v1/documents/{id}/signers/{signer}/embed`). `mode` is `test` for a test key (`mk_test_`), whose account is the business's sandbox: nothing it sends reaches anybody and nothing it does is billed; `live` otherwise. `texting` says whether this business can text people (`available`; `why_not` is `plan` when its plan has no texting, `number` while it waits for its own verified texting number, `beta` while the business is in the beta, which does not text, and `test` for a sandbox), and `wording` is the opt-in sentence to put beside a "text me" box: record exactly those words with `POST /v1/sms-consents` when the box is ticked. Offer no such box when `available` is false -- the consent would be recorded and no text would follow. `number` is the business's own verified texting number, and `application` where its application for one has got to (`status`, `kind`, `phone` once verified, `reason` when the carriers asked for a change or it is held up, `since`), or null when it has not applied: send its owner a link to apply with `POST /v1/texting/number/invitations`, and hear each step as `texting.number_updated`.

Returns

```
{
  "tenant_id": "3a1f…",
  "name": "Fern Hollow Stables",
  "slug": "fern-hollow",
  "key_label": "Booking system",
  "scopes": [
    "signing:read",
    "signing:write"
  ],
  "frame_origins": [
    "https://*.fernhollow.com",
    "https://fernhollow.com"
  ],
  "mode": "live",
  "texting": {
    "available": true,
    "why_not": null,
    "number": "+18885550142",
    "application": {
      "status": "verified",
      "kind": "toll_free",
      "phone": "+18885550142",
      "area_code": null,
      "reason": null,
      "brought": false,
      "since": "2026-10-03T14:22:09Z"
    },
    "wording": "I agree to receive text messages from Fern Hollow Stables via Sign Sealer: the link, at most one reminder if I have not signed, and a confirmation when everyone has signed. … Reply STOP to opt out. Terms: https://signsealer.com/legal/terms Privacy: https://signsealer.com/legal/privacy-policy"
  }
}
```

## Branding

### GET /v1/branding

Scope `signing:read`

**The brand the account shows its signers**

The business's name, colors, whether it has logos on file (fetch them at /brand/{tenant_id}/logo.png and logo-dark.png) and the host its signing links use. Apply the name, the colors and the dark logo only when `whiteLabelEnabled` is true, as SignSealer's own tablet app does; see [Branding and domains](https://signsealer.com/docs/branding).

Returns

```
{
  "businessName": "Fern Hollow Stables",
  "whiteLabelEnabled": true,
  "primaryColor": "#2f5d3a",
  "accentColor": "#c98b2b",
  "backgroundColor": "#f6f4ee",
  "textColor": "#1f2a22",
  "buttonTextColor": "#ffffff",
  "hasLogo": true,
  "hasDarkLogo": true,
  "hasOpening": true,
  "openingType": "image/jpeg",
  "openingUpdatedAt": "2026-10-03T14:22:09Z",
  "signingHost": "fern-hollow.signsealer.com",
  "footerText": "Questions? Call the barn.",
  "tenantId": "3a1f…",
  "logoUrl": "https://api.signsealer.com/brand/3a1f…/logo.png",
  "logoDarkUrl": "https://api.signsealer.com/brand/3a1f…/logo-dark.png",
  "openingUrl": "https://api.signsealer.com/brand/3a1f…/opening.jpg?v=1789000000"
}
```

## Sms-consents

### POST /v1/sms-consents

Scope `signing:send` (or `signing:write`, which includes it) · answers `201` · takes an `Idempotency-Key` (`sms_consents.record`)

**Record consent to text a number**

For a number you took somewhere SignSealer is not: your booking form, an order, the counter. Send the exact wording that was in front of the person, because that is the record a carrier asks for and it is kept verbatim (`GET /v1/account` gives the sentence to show, under `texting.wording`). It has to say that replying STOP opts out, that HELP gets help, that message and data rates may apply, that message frequency varies, that consent is not a condition of purchase, that the number is not shared or sold, and link the terms and the privacy policy; a disclosure missing any of those is refused with 422 naming which, and nothing is recorded. One call covers the link, the reminder and the confirmation, because somebody who agreed to those agreed to all three. A number that has replied STOP cannot be consented again: the call is refused, and it is not texted for you again.

| Field | Type |  | Constraints |
| --- | --- | --- | --- |
| phone | string | required | 7–20 chars |
| obtained_via | string | required | 3–200 chars |
| wording | string | required | 20–2000 chars |

Returns

```
{
  "phone": "+15035550142",
  "purposes": [
    "signing.link",
    "signing.reminder",
    "signing.completed"
  ]
}
```

### GET /v1/sms-consents

Scope `signing:read`

**Whether a number may be texted**

Pass `phone`. Answers for that one number — so an integration can decide whether to put the tick box in front of somebody again. It deliberately does not list every number the account holds. `may_text` is what the engine will actually do rather than what one of its checks says: consent has to be live *and* the number must not be suppressed, because a number that hard-bounced keeps its consent and still cannot be reached. When it is false, `why_not` says which of `revoked`, `suppressed` or `no_consent`.

Query

| Parameter | Type |  | What it is |
| --- | --- | --- | --- |
| phone | string | required | The number, as a person would type it. |

Returns

```
{
  "phone": "+15035550142",
  "may_text": true,
  "why_not": null,
  "obtained_via": "booking form, checkbox beside the phone field",
  "obtained_at": "2026-10-03T14:22:09Z"
}
```

## Texting

### POST /v1/texting/number/invitations

Scope `signing:read` · answers `201`

**A link for the owner to apply for a texting number**

Every business that texts does so from a number of its own, applied for by its owner or an admin under the business's legal name (see `texting` on `GET /v1/account`). When `texting.why_not` is `number`, ask for a link and put it in front of the business's owner: it opens their texting-number application on SignSealer, after they sign in, on this business, with `prefill` filled in. Send what you know, in the application's own names (`legal_name`, `ein`, `website`, the address, the contact, `kind` of `toll_free`, `local` or `sole_proprietor`, `area_code`, `volume`, `vertical`, `mobile`, and the business's own `privacy_url`, `terms_url` and `opt_in_url`); everything is optional, and nothing you send is filed until the owner has read it, ticked that it is true and applied. The link opens only for somebody already in the business, and fills in the form only for an owner or an admin. It lasts 14 days and is used up when the business applies; ask again for a new one, up to 20 a day. A name the application has no field for, or an answer over 300 characters, is refused with 422 naming it. A test key is refused: a sandbox never texts. Watch `texting.application` on `GET /v1/account`, or subscribe to `texting.number_updated`, to see where the application has got to.

| Field | Type |  | Constraints |
| --- | --- | --- | --- |
| prefill | object | optional |  |
| prefill.kind | "toll_free" \| "local" \| "sole_proprietor" | optional |  |
| prefill.legal_name | string | optional | 0–300 chars |
| prefill.entity_type | string | optional | 0–300 chars |
| prefill.ein | string | optional | 0–300 chars |
| prefill.website | string | optional | 0–300 chars |
| prefill.address_line1 | string | optional | 0–300 chars |
| prefill.address_line2 | string | optional | 0–300 chars |
| prefill.city | string | optional | 0–300 chars |
| prefill.state | string | optional | 0–300 chars |
| prefill.postal_code | string | optional | 0–300 chars |
| prefill.contact_first_name | string | optional | 0–300 chars |
| prefill.contact_last_name | string | optional | 0–300 chars |
| prefill.contact_email | string | optional | 0–300 chars |
| prefill.contact_phone | string | optional | 0–300 chars |
| prefill.volume | string | optional | 0–300 chars |
| prefill.vertical | string | optional | 0–300 chars |
| prefill.area_code | string | optional | 0–300 chars |
| prefill.mobile | string | optional | 0–300 chars |
| prefill.privacy_url | string | optional | 0–300 chars |
| prefill.terms_url | string | optional | 0–300 chars |
| prefill.opt_in_url | string | optional | 0–300 chars |

Returns

```
{
  "url": "https://app.signsealer.com/texting/invite/9f3c…",
  "from": "DeckPOS",
  "kind": "toll_free",
  "fields": [
    "address_line1",
    "city",
    "contact_email",
    "kind",
    "legal_name",
    "postal_code",
    "state",
    "website"
  ],
  "expires_at": "2026-10-17T14:22:09Z"
}
```

## Templates

### GET /v1/templates

Scope `signing:read`

**List templates**

Every version of every template, newest first, with whether each is published and how many documents were prepared from it. Without the text: `GET /v1/templates/{id}` has that. Pass `code` for one template's versions.

Query

| Parameter | Type |  | What it is |
| --- | --- | --- | --- |
| code | string | optional | Only this template's versions. |

Returns

```
{
  "templates": [
    {
      "template_id": "8c2e…",
      "code": "liability-waiver",
      "name": "Liability waiver",
      "kind": "waiver",
      "version": 2,
      "is_published": true,
      "published_at": "2026-10-03T14:22:09Z",
      "variables": [
        "participant_name",
        "date",
        "emergency_contact"
      ],
      "grants": {},
      "documents": "412",
      "is_latest": true,
      "one_time": false,
      "show_address": false,
      "valid_months": 12,
      "remind_days": 14,
      "resign_from_version": null
    }
  ]
}
```

### POST /v1/templates

Scope `signing:templates` · answers `201` · takes an `Idempotency-Key` (`templates.create`)

**Create a template**

Creates version 1, as a draft. A template is not usable until it is published, and publishing is what freezes the text people will have signed. `fields` says what the document asks for besides a signature — a date of birth, an address, one of a list — each `required` unless it says otherwise, and each checked when a signer supplies it. Marking one `sensitive` masks the answer wherever staff read it back; it is not masked on the sealed PDF, because the PDF is the document that was signed. A question can be asked only when earlier answers say so (`show_if: {"field": "injured", "ticked": true}`, or `equals` a list of choices, or `answered`; or `not_equals`, `contains`, `not_contains`, `gt`/`lt` for a number and `age_under`/`age_at_least` for a date of birth; or several such rules as `{"match": "all" | "any", "rules": [...]}`, any of them a group of two or more with its own `match`, up to ten rules in all; and `"action": "hide"` beside `rules` to hide the question when it holds); flagged for a person to read (`flag_when`, the same rules); grouped with others under a heading (`block`, with `block_label` and `block_intro` given once, and `block_step: true` for a page of its own); or placed on an uploaded PDF (`place`). The engine checks all of it and refuses by name -- a condition on a question below it, a block with two headings -- and a refused list leaves no template behind.

| Field | Type |  | Constraints |
| --- | --- | --- | --- |
| code | string | required | matches `^[a-z][a-z0-9_-]*$` |
| name | string | required | 1–200 chars |
| kind | "nda" \| "waiver" \| "contract" \| "consent" \| "policy" \| "other" | required |  |
| body | string | required | 1–∞ chars |
| variables | string[] | optional |  |
| grants | object | optional |  |
| consent_text | string \| null | optional |  |
| fields | object[] | optional | 0–50 items |
| fields[].key | string | required | matches `^[a-z][a-z0-9_]{0,58}$` |
| fields[].label | string | optional | 1–200 chars |
| fields[].kind | string | required | 1–20 chars |
| fields[].required | boolean | optional |  |
| fields[].sensitive | boolean | optional |  |
| fields[].supplied_by | "adult" \| "per_child" \| "staff" \| "business" | optional |  |
| fields[].options | string[] | optional | 0–30 items |
| fields[].hint | string | optional | 0–200 chars |
| fields[].show_if | object \| null | optional |  |
| fields[].flag_when | object \| null | optional |  |
| fields[].block | string \| null | optional | 0–59 chars |
| fields[].block_label | string \| null | optional | 0–200 chars |
| fields[].block_intro | string \| null | optional | 0–2000 chars |
| fields[].block_step | boolean \| null | optional |  |
| fields[].place | object \| null | optional |  |

Returns

```
{
  "template_id": "8c2e…"
}
```

### GET /v1/templates/{id}

Scope `signing:read`

**Show one template version**

The version's text (`body`, and `body_format`: `text` or `markdown`), its declared `variables`, the consent wording, the questions it asks (`fields`, in the shape `POST /v1/templates` takes them), whether it is published and whether it is the newest version of its code. `settings` belong to the code rather than the version: `one_time`, `show_address`, `photos_in_copy`, `valid_months`, `remind_days` and `resign_from_version`. `versions` lists every version of the code, newest first, so a caller can walk the history -- a published version is never changed or removed, and each document names the exact version it was sent on.

Returns

```
{
  "template_id": "8c2e…",
  "code": "liability-waiver",
  "name": "Liability waiver",
  "kind": "waiver",
  "version": 2,
  "is_published": true,
  "published_at": "2026-10-03T14:22:09Z",
  "is_latest": true,
  "created_at": "2026-10-03T14:22:09Z",
  "body": "# Liability waiver\\n\\nI, {{participant}}, understand that riding carries risk…",
  "body_format": "markdown",
  "variables": [
    "participant"
  ],
  "grants": {},
  "consent_text": "I agree to sign this electronically.",
  "fields": [
    {
      "key": "emergency_contact",
      "label": "Emergency contact",
      "kind": "text",
      "required": true
    }
  ],
  "has_pdf": false,
  "documents": 118,
  "change_note": "Names the e-bike and asks for an emergency contact.",
  "settings": {
    "one_time": false,
    "show_address": true,
    "photos_in_copy": true,
    "valid_months": 12,
    "remind_days": 14,
    "resign_from_version": null
  },
  "versions": [
    {
      "template_id": "8c2e…",
      "version": 2,
      "is_published": true,
      "published_at": "2026-10-03T14:22:09Z",
      "name": "Liability waiver",
      "created_at": "2026-10-03T14:22:09Z",
      "change_note": "Names the e-bike and asks for an emergency contact.",
      "has_pdf": false,
      "documents": 118
    },
    {
      "template_id": "51d7…",
      "version": 1,
      "is_published": true,
      "published_at": "2025-04-02T09:10:00Z",
      "name": "Liability waiver",
      "created_at": "2025-04-02T09:02:00Z",
      "change_note": null,
      "has_pdf": false,
      "documents": 342
    }
  ]
}
```

### PATCH /v1/templates/{id}

Scope `signing:templates`

**Change a draft**

A draft is changed in place until it is published. Any of `name`, `body`, `body_format`, `variables`, `fields` (the whole list, replacing the one it had) and `change_note` (what changed in this version, up to 500 characters, frozen with it when it is published). A published version refuses with 422: what people signed does not change, so make the next version with `POST /v1/templates/{id}/revise`. Answers with the template as `GET /v1/templates/{id}` does.

| Field | Type |  | Constraints |
| --- | --- | --- | --- |
| name | string | optional | 1–200 chars |
| body | string | optional | 1–∞ chars |
| body_format | "text" \| "markdown" | optional |  |
| variables | string[] | optional |  |
| fields | object[] | optional | 0–50 items |
| fields[].key | string | required | matches `^[a-z][a-z0-9_]{0,58}$` |
| fields[].label | string | optional | 1–200 chars |
| fields[].kind | string | required | 1–20 chars |
| fields[].required | boolean | optional |  |
| fields[].sensitive | boolean | optional |  |
| fields[].supplied_by | "adult" \| "per_child" \| "staff" \| "business" | optional |  |
| fields[].options | string[] | optional | 0–30 items |
| fields[].hint | string | optional | 0–200 chars |
| fields[].show_if | object \| null | optional |  |
| fields[].flag_when | object \| null | optional |  |
| fields[].block | string \| null | optional | 0–59 chars |
| fields[].block_label | string \| null | optional | 0–200 chars |
| fields[].block_intro | string \| null | optional | 0–2000 chars |
| fields[].block_step | boolean \| null | optional |  |
| fields[].place | object \| null | optional |  |
| change_note | string \| null | optional | 0–500 chars |

Returns

```
{
  "template_id": "93aa…",
  "code": "liability-waiver",
  "name": "Liability waiver",
  "kind": "waiver",
  "version": 3,
  "is_published": false,
  "published_at": null,
  "is_latest": true,
  "created_at": "2026-10-03T14:22:09Z",
  "body": "# Liability waiver\\n\\nI, {{participant}}, understand that riding carries risk…",
  "body_format": "markdown",
  "variables": [
    "participant"
  ],
  "grants": {},
  "consent_text": "I agree to sign this electronically.",
  "fields": [
    {
      "key": "emergency_contact",
      "label": "Emergency contact",
      "kind": "text",
      "required": true
    }
  ],
  "has_pdf": false,
  "documents": 0,
  "change_note": "Asks for an emergency contact.",
  "settings": {
    "one_time": false,
    "show_address": true,
    "photos_in_copy": true,
    "valid_months": 12,
    "remind_days": 14,
    "resign_from_version": null
  },
  "versions": [
    {
      "template_id": "93aa…",
      "version": 3,
      "is_published": false,
      "published_at": null,
      "name": "Liability waiver",
      "created_at": "2026-10-03T14:22:09Z",
      "change_note": "Asks for an emergency contact.",
      "has_pdf": false,
      "documents": 0
    },
    {
      "template_id": "8c2e…",
      "version": 2,
      "is_published": true,
      "published_at": "2026-10-03T14:22:09Z",
      "name": "Liability waiver",
      "created_at": "2026-10-03T14:22:09Z",
      "change_note": "Names the e-bike and asks for an emergency contact.",
      "has_pdf": false,
      "documents": 118
    },
    {
      "template_id": "51d7…",
      "version": 1,
      "is_published": true,
      "published_at": "2025-04-02T09:10:00Z",
      "name": "Liability waiver",
      "created_at": "2025-04-02T09:02:00Z",
      "change_note": null,
      "has_pdf": false,
      "documents": 342
    }
  ]
}
```

### POST /v1/templates/{id}/publish

Scope `signing:templates` · takes an `Idempotency-Key` (`templates.publish`)

**Publish a draft**

From now on documents made from this template's code use this version, and its text can no longer change. Refused with 422, naming what is wrong, when the body uses a placeholder the template does not declare, while its text still has a note for your attorney (`[Attorney: …]`, as the starters, the library and the drafter write them: settle it and take it out first; 00600), when an uploaded PDF has pages SignSealer has not yet drawn from the file, or when it is already published. Answers with the template.

Returns

```
{
  "template_id": "8c2e…",
  "code": "liability-waiver",
  "name": "Liability waiver",
  "kind": "waiver",
  "version": 2,
  "is_published": true,
  "published_at": "2026-10-03T14:22:09Z",
  "is_latest": true,
  "created_at": "2026-10-03T14:22:09Z",
  "body": "# Liability waiver\\n\\nI, {{participant}}, understand that riding carries risk…",
  "body_format": "markdown",
  "variables": [
    "participant"
  ],
  "grants": {},
  "consent_text": "I agree to sign this electronically.",
  "fields": [
    {
      "key": "emergency_contact",
      "label": "Emergency contact",
      "kind": "text",
      "required": true
    }
  ],
  "has_pdf": false,
  "documents": 118,
  "change_note": "Names the e-bike and asks for an emergency contact.",
  "settings": {
    "one_time": false,
    "show_address": true,
    "photos_in_copy": true,
    "valid_months": 12,
    "remind_days": 14,
    "resign_from_version": null
  },
  "versions": [
    {
      "template_id": "8c2e…",
      "version": 2,
      "is_published": true,
      "published_at": "2026-10-03T14:22:09Z",
      "name": "Liability waiver",
      "created_at": "2026-10-03T14:22:09Z",
      "change_note": "Names the e-bike and asks for an emergency contact.",
      "has_pdf": false,
      "documents": 118
    },
    {
      "template_id": "51d7…",
      "version": 1,
      "is_published": true,
      "published_at": "2025-04-02T09:10:00Z",
      "name": "Liability waiver",
      "created_at": "2025-04-02T09:02:00Z",
      "change_note": null,
      "has_pdf": false,
      "documents": 342
    }
  ]
}
```

### POST /v1/templates/{id}/revise

Scope `signing:templates` · answers `201` · takes an `Idempotency-Key` (`templates.revise`)

**Make the next version of a template**

Copies the newest version of this template's code into a new draft, one version higher, with any of `name`, `body`, `variables`, `fields` and `change_note` (what changed, kept in its history) changed; publish it to put it into use. Documents already sent keep the version they were sent on. The id must be the newest version: revising an older one answers 409 with the newest version's id in the hint. A draft is refused too -- change it with `PATCH` instead. Text on an uploaded PDF cannot change; its name and questions can.

| Field | Type |  | Constraints |
| --- | --- | --- | --- |
| name | string | optional | 1–200 chars |
| body | string | optional | 1–∞ chars |
| variables | string[] | optional |  |
| fields | object[] | optional | 0–50 items |
| fields[].key | string | required | matches `^[a-z][a-z0-9_]{0,58}$` |
| fields[].label | string | optional | 1–200 chars |
| fields[].kind | string | required | 1–20 chars |
| fields[].required | boolean | optional |  |
| fields[].sensitive | boolean | optional |  |
| fields[].supplied_by | "adult" \| "per_child" \| "staff" \| "business" | optional |  |
| fields[].options | string[] | optional | 0–30 items |
| fields[].hint | string | optional | 0–200 chars |
| fields[].show_if | object \| null | optional |  |
| fields[].flag_when | object \| null | optional |  |
| fields[].block | string \| null | optional | 0–59 chars |
| fields[].block_label | string \| null | optional | 0–200 chars |
| fields[].block_intro | string \| null | optional | 0–2000 chars |
| fields[].block_step | boolean \| null | optional |  |
| fields[].place | object \| null | optional |  |
| change_note | string | optional | 0–500 chars |

Returns

```
{
  "template_id": "93aa…",
  "code": "liability-waiver",
  "name": "Liability waiver",
  "kind": "waiver",
  "version": 3,
  "is_published": false,
  "published_at": null,
  "is_latest": true,
  "created_at": "2026-10-03T14:22:09Z",
  "body": "# Liability waiver\\n\\nI, {{participant}}, understand that riding carries risk…",
  "body_format": "markdown",
  "variables": [
    "participant"
  ],
  "grants": {},
  "consent_text": "I agree to sign this electronically.",
  "fields": [
    {
      "key": "emergency_contact",
      "label": "Emergency contact",
      "kind": "text",
      "required": true
    }
  ],
  "has_pdf": false,
  "documents": 0,
  "change_note": "Asks for an emergency contact.",
  "settings": {
    "one_time": false,
    "show_address": true,
    "photos_in_copy": true,
    "valid_months": 12,
    "remind_days": 14,
    "resign_from_version": null
  },
  "versions": [
    {
      "template_id": "93aa…",
      "version": 3,
      "is_published": false,
      "published_at": null,
      "name": "Liability waiver",
      "created_at": "2026-10-03T14:22:09Z",
      "change_note": "Asks for an emergency contact.",
      "has_pdf": false,
      "documents": 0
    },
    {
      "template_id": "8c2e…",
      "version": 2,
      "is_published": true,
      "published_at": "2026-10-03T14:22:09Z",
      "name": "Liability waiver",
      "created_at": "2026-10-03T14:22:09Z",
      "change_note": "Names the e-bike and asks for an emergency contact.",
      "has_pdf": false,
      "documents": 118
    },
    {
      "template_id": "51d7…",
      "version": 1,
      "is_published": true,
      "published_at": "2025-04-02T09:10:00Z",
      "name": "Liability waiver",
      "created_at": "2025-04-02T09:02:00Z",
      "change_note": null,
      "has_pdf": false,
      "documents": 342
    }
  ]
}
```

### POST /v1/templates/{id}/restore

Scope `signing:templates` · answers `201` · takes an `Idempotency-Key` (`templates.restore`)

**Bring an older version back as a new draft**

Makes a new draft, one version above the newest, carrying this version's text, questions, consent wording, format and uploaded file; its `change_note` says `Restored from version N`, followed by yours if you give one. Publish it to put it into use. The older version keeps its number and its signatures, and so does every version since. Refused with 422 for the newest version (revise it instead), for a draft, and while the template has an open draft (publish or discard it first).

| Field | Type |  | Constraints |
| --- | --- | --- | --- |
| change_note | string | optional | 0–450 chars |

Returns

```
{
  "template_id": "c4f0…",
  "code": "liability-waiver",
  "name": "Liability waiver",
  "kind": "waiver",
  "version": 3,
  "is_published": false,
  "published_at": null,
  "is_latest": true,
  "created_at": "2026-10-03T14:22:09Z",
  "body": "I, {{participant}}, understand that riding carries risk…",
  "body_format": "text",
  "variables": [
    "participant"
  ],
  "grants": {},
  "consent_text": "I agree to sign this electronically.",
  "fields": [],
  "has_pdf": false,
  "documents": 0,
  "change_note": "Restored from version 1: the shorter wording tested better at the counter.",
  "settings": {
    "one_time": false,
    "show_address": true,
    "photos_in_copy": true,
    "valid_months": 12,
    "remind_days": 14,
    "resign_from_version": null
  },
  "versions": [
    {
      "template_id": "c4f0…",
      "version": 3,
      "is_published": false,
      "published_at": null,
      "name": "Liability waiver",
      "created_at": "2026-10-03T14:22:09Z",
      "change_note": "Restored from version 1: the shorter wording tested better at the counter.",
      "has_pdf": false,
      "documents": 0
    },
    {
      "template_id": "8c2e…",
      "version": 2,
      "is_published": true,
      "published_at": "2026-10-03T14:22:09Z",
      "name": "Liability waiver",
      "created_at": "2026-10-03T14:22:09Z",
      "change_note": "Names the e-bike and asks for an emergency contact.",
      "has_pdf": false,
      "documents": 118
    },
    {
      "template_id": "51d7…",
      "version": 1,
      "is_published": true,
      "published_at": "2025-04-02T09:10:00Z",
      "name": "Liability waiver",
      "created_at": "2025-04-02T09:02:00Z",
      "change_note": null,
      "has_pdf": false,
      "documents": 342
    }
  ]
}
```

### DELETE /v1/templates/{id}

Scope `signing:templates`

**Discard a draft**

Only a draft with no documents made from it. A published version is kept for as long as anything signed on it is, so it answers 422; to stop using a template, revise it or stop starting it. Discarding the only version of a code frees the code.

Returns

```
{
  "template_id": "93aa…",
  "code": "liability-waiver",
  "version": 3,
  "discarded": true
}
```

### PATCH /v1/templates/{id}/settings

Scope `signing:templates`

**Change a template's settings**

Settings belong to the template's code, not one version, so they carry over to every version after: `one_time` (made to send once, not reused), `show_address` (the business's address printed under it), `photos_in_copy` (the photographs a signer takes as answers are printed, each with its SHA-256, on pages after the certificate in the signed PDF; on unless turned off, and the certificate keeps every hash either way), `valid_months` (how long a signature stays good; null for never), `remind_days` (days before the end each signer is sent a link to sign again; needs `valid_months`) and `resign: true` (everybody who signed an older version must sign the newest published one; false lifts that). Answers with the template.

| Field | Type |  | Constraints |
| --- | --- | --- | --- |
| one_time | boolean | optional |  |
| show_address | boolean | optional |  |
| photos_in_copy | boolean | optional |  |
| valid_months | integer \| null | optional | 1–120 |
| remind_days | integer \| null | optional | 1–90 |
| resign | boolean | optional |  |

Returns

```
{
  "template_id": "8c2e…",
  "code": "liability-waiver",
  "name": "Liability waiver",
  "kind": "waiver",
  "version": 2,
  "is_published": true,
  "published_at": "2026-10-03T14:22:09Z",
  "is_latest": true,
  "created_at": "2026-10-03T14:22:09Z",
  "body": "# Liability waiver\\n\\nI, {{participant}}, understand that riding carries risk…",
  "body_format": "markdown",
  "variables": [
    "participant"
  ],
  "grants": {},
  "consent_text": "I agree to sign this electronically.",
  "fields": [
    {
      "key": "emergency_contact",
      "label": "Emergency contact",
      "kind": "text",
      "required": true
    }
  ],
  "has_pdf": false,
  "documents": 118,
  "change_note": "Names the e-bike and asks for an emergency contact.",
  "settings": {
    "one_time": false,
    "show_address": true,
    "photos_in_copy": true,
    "valid_months": 12,
    "remind_days": 14,
    "resign_from_version": null
  },
  "versions": [
    {
      "template_id": "8c2e…",
      "version": 2,
      "is_published": true,
      "published_at": "2026-10-03T14:22:09Z",
      "name": "Liability waiver",
      "created_at": "2026-10-03T14:22:09Z",
      "change_note": "Names the e-bike and asks for an emergency contact.",
      "has_pdf": false,
      "documents": 118
    },
    {
      "template_id": "51d7…",
      "version": 1,
      "is_published": true,
      "published_at": "2025-04-02T09:10:00Z",
      "name": "Liability waiver",
      "created_at": "2025-04-02T09:02:00Z",
      "change_note": null,
      "has_pdf": false,
      "documents": 342
    }
  ]
}
```

### GET /v1/templates/{id}/pdf

Scope `signing:read`

**Whether a template is an uploaded PDF**

`has_pdf` says whether the template is a PDF signed where it is rather than text. If it is: `page_count` is what the file has, `drawn` is how many pages SignSealer has drawn a picture of from the file itself (only those are shown to a signer), and `ready` is whether those agree — a PDF template cannot be published until they do. The pages are drawn on our side as the file is uploaded, and any that missed it within a minute; `drawing_failed` says why, when the file could not be drawn. `sha256` is the fingerprint of the file itself, which is the fingerprint the template's body names and the certificate commits to. Uploading the file is a dashboard step; see /docs/pdf.

Returns

```
{
  "has_pdf": true,
  "page_count": 4,
  "drawn": 4,
  "ready": true,
  "drawing_failed": null,
  "pages": [
    {
      "n": 1,
      "width": 612,
      "height": 792,
      "rotation": 0
    }
  ],
  "bytes": 284113,
  "sha256": "e362cc76dae17bbe2a9fc551d9b795fa4e0f77fb488eb748378a125b11f36324",
  "original_name": "tenancy.pdf",
  "uploaded_at": "2026-10-03T14:22:09Z"
}
```

## Standing

### GET /v1/standing

Scope `signing:read`

**Whether somebody's signature on a template is still good**

Pass `template` (the template's code) and `email` or `phone`. Answers with that person's newest completed signature on any version of the template: `standing` is `current` (inside the template's period), `expired` (past it), `resign` (signed on a version the business has since asked everybody to sign again), or `on_file` (signed, and the template has no period); `valid_until` is the day it runs out. `found: false` means they have never signed it, which is the answer "send them the form", not an error. The period is set per template in the dashboard, to match what the document's wording says.

Query

| Parameter | Type |  | What it is |
| --- | --- | --- | --- |
| template | string | required | The template's code. |
| email | string (email) | optional | Whose standing, by email address. This or `phone`. |
| phone | string | optional | Whose standing, by mobile number. This or `email`. |

Returns

```
{
  "template": "liability-waiver",
  "found": true,
  "document_id": "c30b…",
  "signed_at": "2026-10-03T14:22:09Z",
  "template_version": 2,
  "standing": "current",
  "valid_until": "2027-10-03T14:22:09Z"
}
```

## Documents

### GET /v1/documents

Scope `signing:read`

**List documents**

Newest first. Filter with `status` (a state, or `open` for draft and sent), `q` (title, subject or signer) and `external_ref` (your own reference, exactly). Page with `limit` (1–200, 50 by default; more than 200 gets 200) and `offset` (0 by default); `total` is how many match, and `has_more` whether another page follows. Either paging value that is not a whole number is a 400 saying which. A signed document carries `standing` and `valid_until` (00406): whether it is still good, by the period set on its template -- `current`, `expired`, `resign`, `renewed` or `on_file`.

Query

| Parameter | Type |  | What it is |
| --- | --- | --- | --- |
| status | string | optional | A state -- `draft`, `sent`, `completed`, `declined`, `expired`, `void` -- or `open` for draft and sent. |
| q | string | optional | Part of a title, a subject's name, or a signer's name, email or number. |
| external_ref | string | optional | Your own reference, as you gave it when you made the document. Exact. |
| limit | integer | optional | 1 to 200; 50 when absent. |
| offset | integer | optional | How many to skip; 0 when absent. |

Returns

```
{
  "documents": [
    {
      "document_id": "d41c…",
      "title": "Liability waiver — Dana Reyes",
      "status": "sent",
      "template_code": "liability-waiver",
      "template_version": 2,
      "subject_name": null,
      "subject_party_id": null,
      "signers": 2,
      "signed": 1,
      "waiting_on": "Sam Manager",
      "sequential": true,
      "expires_at": "2026-10-17T00:00:00Z",
      "sent_at": "2026-10-03T14:22:09Z",
      "completed_at": null,
      "void_reason": null,
      "integrity_ok": true,
      "standing": null,
      "valid_until": null,
      "external_ref": null,
      "total": "2"
    },
    {
      "document_id": "c30b…",
      "title": "Liability waiver — Sam Lee",
      "status": "completed",
      "template_code": "liability-waiver",
      "template_version": 2,
      "subject_name": null,
      "subject_party_id": null,
      "signers": 1,
      "signed": 1,
      "waiting_on": null,
      "sequential": false,
      "expires_at": null,
      "sent_at": "2026-10-03T14:22:09Z",
      "completed_at": "2026-10-03T14:22:09Z",
      "void_reason": null,
      "integrity_ok": true,
      "standing": "current",
      "valid_until": "2027-10-03T14:22:09Z",
      "external_ref": "booking-20931",
      "total": "2"
    }
  ],
  "total": 2,
  "has_more": false,
  "limit": 50,
  "offset": 0
}
```

### GET /v1/documents/{id}

Scope `signing:read`

**Show one document**

The document with its text and `body_sha256_hex`, its signers (each with the `assurance` their signature carries), the whole event trail -- each event with `matches_current_text`, false when it was made against different text than the document holds now -- and every answer the signers gave. `external_ref`, `metadata` and `return_url` are what you set when you made it. `answers` lists each question in the order the form asks it, with the signer it belongs to. `asked` says whether the question was on that signer's page -- a question hidden by its condition is `asked: false`, has no value, and is never flagged. `flagged` on an answer means the template's flag rule says a person should read it; `flagged` on the document counts them. A question marked sensitive has its value masked, as it is for the business's own staff; a redacted document keeps its questions and gives up every value. Answers are here and not in webhooks on purpose: a webhook goes to whatever address was typed, and some answers are about somebody's health.

Returns

```
{
  "document_id": "d41c…",
  "title": "Liability waiver — Dana Reyes",
  "status": "completed",
  "body": "I, Dana Reyes, …",
  "body_format": "text",
  "body_sha256_hex": "e362cc76dae17bbe2a9fc551d9b795fa4e0f77fb488eb748378a125b11f36324",
  "template_code": "liability-waiver",
  "template_version": 2,
  "template_kind": "waiver",
  "grants": {},
  "subject_name": null,
  "subject_party_id": null,
  "sequential": false,
  "expires_at": null,
  "sent_at": "2026-10-03T14:22:09Z",
  "completed_at": "2026-10-03T14:22:09Z",
  "voided_at": null,
  "void_reason": null,
  "integrity_ok": true,
  "redacted_at": null,
  "redaction_reason": null,
  "standing": "current",
  "valid_until": "2027-10-03T14:22:09Z",
  "renewed_by": null,
  "signers": [
    {
      "signer_id": "5f0a…",
      "email": "dana@example.signsealer.com",
      "phone": null,
      "full_name": "Dana Reyes",
      "role": "signer",
      "sign_order": 1,
      "status": "signed",
      "party_id": null,
      "grants": false,
      "consent_ref": "consent/1",
      "consented_at": "2026-10-03T14:22:09Z",
      "assurance": "email_link",
      "verified_at": null,
      "signed_at": "2026-10-03T14:22:09Z",
      "declined_at": null,
      "decline_reason": null,
      "token_expires_at": "2026-10-17T00:00:00Z",
      "for_business": false
    }
  ],
  "events": [
    {
      "event_id": "e1…",
      "kind": "sent",
      "occurred_at": "2026-10-03T14:22:09Z",
      "signer_email": null,
      "ip": null,
      "user_agent": null,
      "signature_method": null,
      "signature_value": null,
      "matches_current_text": true,
      "detail": {}
    },
    {
      "event_id": "e2…",
      "kind": "consented",
      "occurred_at": "2026-10-03T14:22:09Z",
      "signer_email": "dana@example.signsealer.com",
      "ip": "203.0.113.9/32",
      "user_agent": "Mozilla/5.0 …",
      "signature_method": null,
      "signature_value": null,
      "matches_current_text": true,
      "detail": {
        "consent": {
          "ref": "consent/1",
          "text": "By continuing you agree to sign this document electronically …",
          "sha256": "5ae7…"
        }
      }
    },
    {
      "event_id": "e3…",
      "kind": "signed",
      "occurred_at": "2026-10-03T14:22:09Z",
      "signer_email": "dana@example.signsealer.com",
      "ip": "203.0.113.9/32",
      "user_agent": "Mozilla/5.0 …",
      "signature_method": "typed",
      "signature_value": "Dana Reyes",
      "matches_current_text": true,
      "detail": {
        "assurance": "email_link",
        "intent": {
          "ref": "intent/1",
          "text": "By signing below I confirm …",
          "sha256": "ccf3…"
        }
      }
    }
  ],
  "answers": [
    {
      "signer_id": "5f0a…",
      "key": "rode_before",
      "label": "Have you ridden before?",
      "kind": "choice",
      "block": {
        "key": "experience",
        "label": "Your riding"
      },
      "about": null,
      "required": true,
      "sensitive": false,
      "asked": true,
      "value": "No",
      "supplied_at": "2026-10-03T14:22:09Z",
      "flagged": true
    },
    {
      "signer_id": "5f0a…",
      "key": "lessons",
      "label": "How many lessons have you had?",
      "kind": "number",
      "block": {
        "key": "experience",
        "label": "Your riding"
      },
      "about": null,
      "required": true,
      "sensitive": false,
      "asked": false,
      "value": null,
      "supplied_at": null,
      "flagged": false
    },
    {
      "signer_id": "5f0a…",
      "key": "medical",
      "label": "Anything we should know medically?",
      "kind": "paragraph",
      "block": null,
      "about": null,
      "required": false,
      "sensitive": true,
      "asked": true,
      "value": "••••••••••ergy",
      "supplied_at": "2026-10-03T14:22:09Z",
      "flagged": false
    }
  ],
  "flagged": 1,
  "external_ref": "booking-20931",
  "metadata": {
    "lesson": "Saturday 10am"
  },
  "return_url": null
}
```

### GET /v1/documents/{id}/signers

Scope `signing:read`

**Who has signed one document**

The gate's question (00340): each signer's name, role and state, and nothing else -- no text, no addresses, no event trail. The route a paired tablet reads; the full document is `GET /v1/documents/:id`. Once it is signed, `standing` says whether it is still good (00406): `current`, `expired`, `resign` (the terms changed since), `renewed` (the same person has signed it again since) or `on_file` (no period), with `valid_until`. `link_allowed` says whether this caller may mint a fresh link for it (00409): always for a key, and for a paired tablet only on a document it or its form started, unless the business let that tablet show links for every open document.

Returns

```
{
  "document_id": "d41c…",
  "title": "Liability waiver — Dana Reyes",
  "status": "sent",
  "sent_at": "2026-10-03T14:22:09Z",
  "completed_at": null,
  "standing": null,
  "valid_until": null,
  "link_allowed": true,
  "signers": [
    {
      "signer_id": "5f0a…",
      "full_name": "Dana Reyes",
      "role": "signer",
      "sign_order": 1,
      "status": "signed",
      "signed_at": "2026-10-03T14:22:09Z",
      "declined_at": null
    },
    {
      "signer_id": "6a1b…",
      "full_name": "Sam Manager",
      "role": "signer",
      "sign_order": 2,
      "status": "pending",
      "signed_at": null,
      "declined_at": null
    }
  ]
}
```

### POST /v1/documents/{id}/signers/{signer}/link

Scope `signing:links` (or `signing:write`, which includes it) or `signing:workflows` · answers `201`

**A fresh signing link for a signer who has not signed, as a QR code**

The last check at the gate (00340). Mints a new link for the signer -- the one they were sent stops working -- and returns it with an SVG QR code to hold up, so a customer who never signed at the counter scans it and signs on their own phone. Recorded on the trail as `link_shown`. Refused for a signer who has signed or declined, a copied recipient, or a document that is not open; ten a minute per document.

Returns

```
{
  "document_id": "d41c…",
  "signer_id": "5f0a…",
  "url": "https://api.signsealer.com/s/9k3…",
  "qr_svg": "<svg xmlns=\"http://www.w3.org/2000/svg\" …>…</svg>"
}
```

### POST /v1/documents/{id}/signers/{signer}/remind

Scope `signing:remind` (or `signing:write`, which includes it) · takes an `Idempotency-Key` (`documents.remind`)

**Send a signer a reminder with a fresh link**

Emails (or texts, where they agreed to texts) a new link to one signer who has not signed, and the link they had stops working. Works for an `embedded` signer too, because you asked by name. Refused with 422 inside an hour of their last reminder, past three reminders to one signer in a day or twenty-five for one document in a day (the automatic reminders and the dashboard's Remind count too), for a signer who has signed or declined, a copied recipient, a document that is not out for signature, somebody there is no way to reach, or a signer held for their turn on a document signed in order (00609: their link is sent when the people before them have signed) -- and in every one of those cases their link is left as it was. A signer is texted at most one reminder over the life of their link, because the words they agreed to before we texted them say "at most one reminder": after that one, counting the dashboard's, the automatic one and a party's link sent again, a reminder goes by email alone (`by: "email"`), and for a signer with no email address we may use it is refused with 422, saying so. `reminded: true` means the reminder was queued, not that it arrived: like every message to somebody outside the business it is screened before it leaves and may be held for review (see `POST /v1/documents/{id}/send`).

Returns

```
{
  "document_id": "d41c…",
  "signer_id": "5f0a…",
  "reminded": true,
  "by": "email"
}
```

### POST /v1/documents/{id}/signers/{signer}/embed

Scope `signing:links` (or `signing:write`, which includes it) · answers `201`

**A fresh signing link to show in a frame**

Mints a new link for a signer who has not signed -- the one they had stops working -- and answers with its `url` and `frame_origins`: the sites the signing page may be framed on, which are the ones the business has proven (a verified signing domain, a proven company sign-in domain, or the site of an app it connected, other than an AI assistant). Put the url in an `<iframe>` on one of them; anywhere else the browser refuses to show it, and an empty list means nowhere yet. Inside a frame the page tells its parent what happened with `postMessage`: `{source: "signsealer", event, document_id, signer_id, height}`, where `event` is `ready` on every page, `signed` once they have signed, and `declined`. Recorded on the trail as `link_shown`; ten a minute per document.

Returns

```
{
  "document_id": "d41c…",
  "signer_id": "7b21…",
  "url": "https://sign.fernhollow.com/s/b91d…",
  "frame_origins": [
    "https://sign.fernhollow.com",
    "https://*.sign.fernhollow.com",
    "https://fernhollow.com",
    "https://*.fernhollow.com"
  ],
  "expires_at": "2026-11-02T14:22:09Z"
}
```

### POST /v1/documents

Scope `signing:send` (or `signing:write`, which includes it) · answers `201` · takes an `Idempotency-Key` (`documents.prepare`)

**Prepare a document from a template**

Renders the newest published version of the template with the values given and stores the result on the document, as a draft. Every declared variable needs a value: a contract that ships with a placeholder still in it is worse than one that failed to send. Nor is a document made whose text still has a note for your attorney (`[Attorney: …]`), from a template published before such notes were refused at publishing: 422, quoting the note (00600). The exception is the signing date -- `date` and its synonyms (`today`, `todays_date`, `date_signed`, `signed_date`, `signed_on`, `signing_date`, `sign_date`): it is never supplied, a value sent for it is ignored, and the text keeps `{{date}}` until the first signature writes in that day, in the business's timezone. On an uploaded PDF, a question marked `staff` and placed on the page is filled in by whoever sends the document: give it under `values`, keyed as the question is (a date as YYYY-MM-DD). It is checked like an answer, stored as every signer's answer before they sign, shown on their page and not theirs to change, and drawn on the sealed PDF; a required one that is missing is refused with 422, naming it. `external_ref` is your own reference (an order number, a booking id), up to 200 characters: every webhook about the document carries it back as `document.metadata.external_ref`, and `GET /v1/documents?external_ref=` finds it. `metadata` is up to 20 names of your own with text values; it comes back as `document.metadata.custom`. `return_url` is where the signed page offers to take the signer next -- https, on a host the business has proven. `time_zone` is the zone the document's times are in, as a zone name (`America/Denver`): a value for a time blank (`start_time`, `rental_starts`) given as `14:30` or `2026-10-03T09:00` is written into the text in words with the zone named ("October 3, 2026 at 9:00 am MDT"), and a time a signer gives later is shown the same way. A zone the engine does not know is refused. Without it, values go into the text exactly as sent.

| Field | Type |  | Constraints |
| --- | --- | --- | --- |
| template_code | string | required |  |
| title | string | optional | 0–200 chars |
| values | object | optional |  |
| expires_at | string (date-time) \| null | optional |  |
| sequential | boolean | optional |  |
| external_ref | string | optional | 1–200 chars |
| metadata | object | optional |  |
| return_url | string (uri) | optional | 0–2000 chars |
| time_zone | string | optional | 1–64 chars |

Returns

```
{
  "document_id": "d41c…"
}
```

### POST /v1/documents/{id}/send

Scope `signing:send` (or `signing:write`, which includes it) · takes an `Idempotency-Key` (`documents.send`)

**Send a document for signature**

Returns one signing link per signer, once: `token`, and `url`, the page to send them to. The tokens are not stored, only their hashes, so a lost link is replaced rather than looked up -- by `POST /v1/documents/{id}/signers/{signer}/remind`, which sends a new one, or `.../embed`, which hands you one. Each signer is emailed or texted their link unless you send them with `delivery: "embedded"`: then nothing is sent to them, and the automatic reminders leave them alone, because you are showing them the page yourself -- in a frame on your site, or in your app. They still need an email address or a mobile number: the certificate records how they could be reached, and the completed copy goes to them. On a document prepared with `sequential: true`, only the first step is sent its links now. A later step's signer is held: their `token` and `url` are null and `held` is true, and their link is made and sent to them when every signer before them has signed (00609). An `embedded` signer is not held, and nor is anybody when the business sends its own links. Every link that goes out by email or text counts against the business's sending allowance for the hour and the day, which grows with how far the business is trusted (/docs/limits). A send that would cross it is refused whole with 429 `rate_limited` and `Retry-After`, and nobody on it is sent anything. A 200 here says the links were made and the messages queued, not that they arrived. Every message to somebody outside the business is screened before it leaves: it may be held for review -- usually a few hours -- or, rarely, not sent at all, and the business is told on the document's page in the dashboard. Nothing in this answer, and nothing else in the API yet, changes when that happens: `signing.delivered` says the email carrying a signer's link reached their mail server, `signing.viewed` is the first sign that somebody opened it, and the evidence bundle, once the document completes, lists every message and whether it arrived.

| Field | Type |  | Constraints |
| --- | --- | --- | --- |
| signers | object[] | required | 1–50 items |
| signers[].email | string (email) | optional |  |
| signers[].phone | string | optional | 7–40 chars |
| signers[].full_name | string | required | 1–200 chars |
| signers[].role | "signer" \| "approver" \| "witness" \| "cc" | optional |  |
| signers[].sign_order | integer | optional | 1–50 |
| signers[].party_id | string (uuid) \| null | optional |  |
| signers[].delivery | "send" \| "embedded" | optional |  |
| signers[].for_business | boolean | optional |  |

Returns

```
{
  "links": [
    {
      "signer_id": "5f0a…",
      "email": "dana@example.signsealer.com",
      "phone": "+16155550142",
      "delivery": "send",
      "for_business": false,
      "token": "3f9c…44 base64 characters",
      "url": "https://sign.fernhollow.com/s/3f9c…"
    },
    {
      "signer_id": "7b21…",
      "email": "sam@example.signsealer.com",
      "phone": null,
      "delivery": "embedded",
      "for_business": false,
      "token": "a08e…44 base64 characters",
      "url": "https://sign.fernhollow.com/s/a08e…"
    },
    {
      "signer_id": "9c42…",
      "email": "sam@example.signsealer.com",
      "phone": null,
      "delivery": "send",
      "for_business": true,
      "token": null,
      "url": null,
      "held": true
    }
  ]
}
```

### POST /v1/documents/{id}/void

Scope `signing:void` (or `signing:write`, which includes it) · takes an `Idempotency-Key` (`documents.void`)

**Void a document**

Needs a reason, which goes on the audit trail. An executed agreement cannot be voided: it is terminated by agreement, not by deletion.

| Field | Type |  | Constraints |
| --- | --- | --- | --- |
| reason | string | required | 1–500 chars |

Returns

```
{
  "voided": true
}
```

### GET /v1/documents/{id}/certificate

Scope `signing:read`

**Fetch the certificate of completion**

Issued when the document completes, frozen at issue and hashed. `still_matches_record` re-derives it from the live record and reports any divergence rather than correcting it.

Returns

```
{
  "certificate_id": "c7d0…",
  "verification_code": "K7QP3MTV9XBD2FHR",
  "issued_at": "2026-10-03T14:22:09Z",
  "document_sha256_hex": "e362cc76dae17bbe2a9fc551d9b795fa4e0f77fb488eb748378a125b11f36324",
  "certificate_sha256_hex": "592f…",
  "still_matches_record": true,
  "payload": {
    "issuer": {
      "tenant": "Fern Hollow Stables",
      "tenant_id": "3a1f…"
    },
    "document": {
      "id": "d41c…",
      "title": "Liability waiver — Dana Reyes",
      "sha256": "e362cc76dae17bbe2a9fc551d9b795fa4e0f77fb488eb748378a125b11f36324",
      "completed_at": "2026-10-03T14:22:09Z",
      "template": {
        "code": "liability-waiver",
        "version": 2
      }
    },
    "signers": [
      {
        "full_name": "Dana Reyes",
        "email": "dana@example.signsealer.com",
        "role": "signer",
        "sign_order": 1,
        "status": "signed",
        "consented_at": "2026-10-03T14:22:09Z",
        "signed_at": "2026-10-03T14:22:09Z",
        "signature": {
          "method": "typed",
          "value_sha256": "017a…",
          "signed_against_sha256": "e362cc76dae17bbe2a9fc551d9b795fa4e0f77fb488eb748378a125b11f36324",
          "ip": "203.0.113.9/32"
        }
      }
    ],
    "events": [
      {
        "kind": "signed",
        "occurred_at": "2026-10-03T14:22:09Z",
        "signer": "dana@example.signsealer.com",
        "ip": "203.0.113.9/32",
        "against_sha256": "e362cc76dae17bbe2a9fc551d9b795fa4e0f77fb488eb748378a125b11f36324"
      }
    ]
  }
}
```

### GET /v1/documents/{id}/pdf

Scope `signing:read`

**Download the sealed PDF**

The certificate as a PAdES-sealed PDF, with an RFC 3161 timestamp over the signature. Sealed once, when the document completed, and kept: every call returns the same bytes, and their SHA-256 is what `GET /v1/verify/:code?sha256=` matches. Returns base64 bytes and the filename to save them under. `kept` is false in the rare case the copy could not be kept: that file is recorded and still verifies, and a later call may return a different one, which is kept.

Returns

```
{
  "filename": "certificate-K7QP3MTV9XBD2FHR.pdf",
  "content_type": "application/pdf",
  "seal": {
    "commonName": "SignSealer",
    "selfIssued": true,
    "trust": "unverified",
    "timestamped": true
  },
  "kept": true,
  "bytes_base64": "JVBERi0xLjcK…"
}
```

### GET /v1/documents/{id}/bundle

Scope `signing:read`

**Download the evidence bundle**

The sealed PDF with the evidence package printed after the audit trail: every message sent about the document, every webhook delivered, and the record's state when the file was made, with the package's SHA-256 on the last page. One PAdES-sealed file. Returns base64 bytes and the filename to save them under.

Returns

```
{
  "filename": "evidence-bundle-K7QP3MTV9XBD2FHR.pdf",
  "content_type": "application/pdf",
  "seal": {
    "commonName": "SignSealer",
    "selfIssued": true,
    "trust": "unverified",
    "timestamped": true
  },
  "bytes_base64": "JVBERi0xLjcK…"
}
```

## Workflows

### GET /v1/workflows

Scope `signing:read`

**List workflows**

A workflow is a published template plus the rules for running it: who signs in what order, how long a link lives, and whether it has a public address.

Returns

```
{
  "workflows": [
    {
      "id": "w9b1…",
      "code": "waiver",
      "name": "Kayak rental waiver",
      "kind": "waiver",
      "template_code": "liability-waiver",
      "template_published": true,
      "signer_roles": [
        {
          "label": "Participant",
          "role": "signer",
          "order": 1,
          "participant": true
        }
      ],
      "sequential": false,
      "countersign": false,
      "expires_days": 7,
      "remind_after_days": 3,
      "public_slug": "waiver",
      "intro": "Read it, answer two questions, sign.",
      "form_fields": [
        {
          "key": "emergency_contact",
          "label": "Emergency contact",
          "required": true
        }
      ],
      "asked_fields": [
        {
          "key": "emergency_contact",
          "label": "Emergency contact",
          "required": true
        }
      ],
      "sender_fields": [],
      "document_after_questions": false,
      "time_zone": "America/Denver",
      "each_person_signs": false,
      "party_ages": "tick",
      "majority_age": 18,
      "minors_also_sign": false,
      "party_confirm_code": false,
      "party_documents": "one",
      "email_check": true,
      "stop_after_signed": null,
      "closes_on": "2026-12-31",
      "once_within_days": null,
      "closed": null,
      "needs_attention": null,
      "active": true,
      "drafted_by_run": null,
      "created_at": "2026-10-03T14:22:09Z",
      "updated_at": "2026-10-03T14:22:09Z",
      "started": 412,
      "completed": 398
    }
  ]
}
```

### GET /v1/workflows/{id}/qr

Scope `signing:read`

**The QR code for a workflow's public form**

The public address of a workflow, drawn as a QR code: an SVG to put on a page and a PNG (1024px, base64) to print. Anybody who scans it opens the form on their own phone and signs there. 404 for a workflow with no public address.

Returns

```
{
  "workflow_id": "w9b1…",
  "name": "Kayak rental waiver",
  "url": "https://signsealer.com/f/harbour-rentals/waiver",
  "svg": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 33 33\" …>…</svg>",
  "png_base64": "iVBORw0KGgo…"
}
```

### POST /v1/workflows/{id}/start

Scope `signing:workflows` · answers `201` · takes an `Idempotency-Key` (`workflows.start`)

**Start a workflow for one participant**

Prepares the document, sends it to every fixed role, and returns the tokens once: the participant's link comes back to the caller, to hand the person on. On a workflow signed in order, a fixed role whose turn has not come is held: their `token` is null and `held` is true, and they are sent their link when the people before them have signed (00609). Nobody is held when the business sends its own links (sending turned off in the dashboard): every token comes back now, and handing each one over in its turn is yours. With `send_link: true` SignSealer sends the participant their link too, by email and by text where it may text the number, and the answer says whether it went (`link_sent`, false when the business delivers its own links); for a start made for somebody who is not there (00601). A fixed role with a `show_if` (00541) is on the document only when the form's answers in `fields` meet it; the roles they did not need are listed under `not_needed`. An answer to a form question with a `kind` is checked as a template's answer is, and one that is not what its question is (a date of birth that is not a date) is refused with 422, naming the question. A tablet reconciling a start it ran with no network names `expected_template_version` (refused with 409 `template_changed` if the published form has moved on, so nothing is sealed against words nobody read) and `captured` (its own clock, kept as a claim with the skew computed); it sends the `date` it showed under `values` so the frozen text carries the day the customer was there, kept only when it is a day in words within a day of the tablet's clock and not after today. `captured` from anything but a paired tablet is refused with 422. A start the business cannot take (Free's signings for the month used, a balance that does not cover the next, its own spending limit reached, or a stopped subscription) is refused with 402 `quota_exceeded` and nothing is made; a tablet's start made with no network is answered 429 `allowance_reached` with `Retry-After` instead, to keep and send again, because the person has already signed (00681). From any other caller a `date` (or a synonym) under `values` is ignored: the text keeps `{{date}}` and the first signature writes in its day. On an uploaded PDF, a box filled in when it is sent (a question marked `staff` and placed on the page) is taken from `fields` or `values` under its key; a required one that is missing is refused, naming it. `return_url` is where the signed page sends the person afterwards: https, on a domain this business has proven (a verified signing domain, a proven company sign-in domain, or the site of a connected app), else 422.

| Field | Type |  | Constraints |
| --- | --- | --- | --- |
| email | string (email) | required |  |
| full_name | string | required | 1–200 chars |
| phone | string | optional | 0–40 chars |
| fields | object | optional |  |
| values | object | optional |  |
| external_ref | string | optional | 0–200 chars |
| send_link | boolean | optional |  |
| expected_template_version | integer | optional | 0–∞ |
| captured | object | optional |  |
| captured.offline | boolean | required |  |
| captured.at | string (date-time) | required |  |
| captured.device | string | required | 0–120 chars |
| return_url | string (uri) | optional | 0–2000 chars |

Returns

```
{
  "document_id": "d41c…",
  "title": "Kayak rental waiver — Dana Reyes",
  "expires_at": "2026-10-10T14:22:09Z",
  "template_version": 3,
  "party_size": null,
  "signers": [
    {
      "signer_id": "5f0a…",
      "email": "dana@example.signsealer.com",
      "phone": null,
      "full_name": "Dana Reyes",
      "role": "signer",
      "participant": true,
      "for_business": false,
      "token": "3f9c…"
    },
    {
      "signer_id": "5f0b…",
      "email": "manager@fernhollow.example",
      "phone": null,
      "full_name": "Sam Manager",
      "role": "signer",
      "participant": false,
      "for_business": true,
      "token": "7a21…"
    }
  ]
}
```

### GET /v1/workflows/{id}/bundle

Scope `signing:workflows`

**Everything needed to run a workflow offline**

The workflow's fields and roles, the published template's text, variables and version, the consent and intent wording a signer is shown with their versions, the business's name, and the pages of an uploaded PDF (fetch each at `/v1/workflows/{id}/pages/{n}`). A tablet keeps this so it can start a signing with no network, then reconciles the start naming the version it rendered. `condition_zone` is the zone whose calendar day a document started from it reads its conditions on (an age, for one).

Returns

```
{
  "workflow": {
    "id": "w9b1…",
    "code": "waiver",
    "name": "Kayak rental waiver",
    "kind": "waiver",
    "intro": "Please read and sign before launch.",
    "form_fields": [
      {
        "key": "boat",
        "label": "Boat",
        "required": true,
        "derived": true
      }
    ],
    "signer_roles": [
      {
        "role": "signer",
        "label": "Participant",
        "participant": true,
        "order": 1
      }
    ],
    "sequential": false,
    "countersign": false
  },
  "template": {
    "id": "t7d2…",
    "code": "kayak-waiver",
    "name": "Kayak rental waiver",
    "kind": "waiver",
    "version": 3,
    "variables": [
      "participant_name",
      "date",
      "boat"
    ],
    "body": "Between {{business_name}} and {{participant_name}}, on {{date}}. Boat: {{boat}}. …",
    "body_format": "text",
    "body_sha256": "9c1e…"
  },
  "consent": {
    "text": "By continuing you agree to sign this document electronically …",
    "version": "consent/1"
  },
  "intent": {
    "text": "By signing below I confirm that I have read this document, …",
    "version": "intent/1"
  },
  "id_evidence": {
    "offered": "off",
    "id_disclosure": null,
    "selfie_disclosure": null
  },
  "location": {
    "offered": "off",
    "disclosure": null
  },
  "photos": [],
  "questions": [
    {
      "key": "helmet",
      "label": "Will you wear the helmet provided?",
      "kind": "checkbox",
      "required": true,
      "hint": null,
      "options": null,
      "show_if": null,
      "show_if_rules": null,
      "block": null,
      "block_label": null,
      "block_intro": null,
      "block_step": null,
      "placed": false
    }
  ],
  "document_after_questions": false,
  "condition_zone": "America/Denver",
  "business_name": "Harbour Rentals",
  "pages": [],
  "fetched_at": "2026-09-16T09:48:15Z"
}
```

### GET /v1/workflows/{id}/pages/{n}

Scope `signing:workflows`

**One page of a workflow's PDF template, as an image**

The published template's page `n` as a PNG, for a tablet keeping the form on the device: base64 bytes and the content type, like the PDF routes. 404 for a text template or a page it does not have. A published template's pages do not change, so the tablet may keep the file.

Returns

```
{
  "page": 1,
  "content_type": "image/png",
  "bytes_base64": "iVBORw0KGgo…"
}
```

## Devices

### POST /v1/devices/pair

No key: the token in the path is the credential

**Trade a pairing code for a device credential**

The code is shown once on the fleet screen, lives fifteen minutes and is spent on first use. What comes back is an API key scoped to this device alone and the workflow it has been given, if it has one. Every refusal answers identically — a code that is wrong, expired, spent or belongs to a stopped device all read the same, because telling them apart tells a guesser whether they are warm.

| Field | Type |  | Constraints |
| --- | --- | --- | --- |
| code | string | required | 8–32 chars |
| platform | "ios" \| "android" \| "other" | optional |  |
| app_version | string | optional | 0–40 chars |
| os_version | string | optional | 0–40 chars |

Returns

```
{
  "device_id": "de91…",
  "name": "Front counter iPad",
  "key": "mk_live_9f2a…",
  "workflow_id": "wf3c…",
  "workflow_name": "River float waiver"
}
```

### POST /v1/devices/heartbeat

Scope `signing:device`

**Say the device is still here, and read back what it should be running**

The device does not say which device it is — the credential it called with does. So a tablet cannot report on another's behalf, and a heartbeat from a revoked credential resolves to no device at all. The answer carries the device's name and assigned workflow — and, from 00420, `workflows`: every form it runs, in the order its kiosk lists them — so a change made on the fleet screen reaches the tablet without re-pairing; and `update`: the newest Android build available with where to get it, and where this tablet stands against the version rules set in Ops (`required` below the minimum, `recommended_now` below the recommended version). A business on the preview list is offered the preview build, when one newer than the shipped build exists, and `channel` says `preview`.

| Field | Type |  | Constraints |
| --- | --- | --- | --- |
| app_version | string | optional | 0–40 chars |
| os_version | string | optional | 0–40 chars |
| queue_waiting | integer | optional | 0–100000 |
| queue_refused | integer | optional | 0–100000 |
| synced | boolean | optional |  |

Returns

```
{
  "device_id": "de91…",
  "name": "Front counter iPad",
  "platform": "android",
  "workflow_id": "wf3c…",
  "workflow_name": "River float waiver",
  "hand_off": "separate",
  "waiting": [
    {
      "packet_id": "p6c9…",
      "code": "ABCD234567",
      "since": "2026-10-03T14:22:09Z",
      "outstanding": 2,
      "who": [
        "Dana R.",
        "Sam L."
      ]
    }
  ],
  "workflows": [
    {
      "id": "wf3c…",
      "name": "River float waiver",
      "kind": "waiver",
      "active": true
    },
    {
      "id": "wf7a…",
      "name": "Campsite rules",
      "kind": "policy",
      "active": true
    }
  ],
  "latest_android_version": "1.2.0",
  "download_url": "https://app.signsealer.com/devices",
  "update": {
    "latest": "1.2.0",
    "channel": "stable",
    "download_url": "https://app.signsealer.com/devices",
    "minimum": "1.1.0",
    "recommended": "1.2.0",
    "required": false,
    "recommended_now": true,
    "announce": true,
    "preview": false
  }
}
```

### POST /v1/devices/report

Scope `signing:device`

**Report a problem from a tablet**

Names and numbers, never text (00341): a `code` such as `bundle_page_missing`, the `screen` and `step` the tablet was on, whether it was `online`, how many items were waiting to send, and the HTTP status if a request was refused. There is no field for a message. Kept against the tablet for ninety days, shown on the fleet screens, and forwarded to error reporting with the same fields and no others. Thirty an hour per tablet.

| Field | Type |  | Constraints |
| --- | --- | --- | --- |
| code | string | required | matches `^[a-z][a-z0-9_]{1,39}$` |
| screen | string | optional | matches `^[a-z][a-z0-9_/-]{0,39}$` |
| step | string | optional | matches `^[a-z][a-z0-9_]{0,39}$` |
| online | boolean | optional |  |
| queue_waiting | integer | optional | 0–100000 |
| http_status | integer | optional | 100–599 |
| app_version | string | optional | 0–40 chars |
| os_version | string | optional | 0–40 chars |

Returns

```
{
  "report_id": "r7a1…",
  "device_id": "de91…"
}
```

### GET /v1/devices

Scope `signing:devices`

**List tablets**

Every tablet of the account: paired or waiting, what it runs (`workflows`, in the order its kiosk lists them), when it was last seen, and whether a pairing code is outstanding. Never the code itself, which is shown once when it is made.

Returns

```
{
  "devices": [
    {
      "id": "de91…",
      "name": "Front counter iPad",
      "workflow_id": "wf3c…",
      "workflow_name": "River float waiver",
      "paired": true,
      "paired_at": "2026-09-02T15:04:11Z",
      "platform": "android",
      "app_version": "1.0.3",
      "os_version": "14",
      "last_seen_at": "2026-09-16T09:40:02Z",
      "revoked_at": null,
      "revoke_reason": null,
      "pairing_open": false,
      "pair_expires_at": null,
      "review": false,
      "hand_off": "walk_up",
      "gate": "own",
      "below_minimum": false,
      "below_recommended": false,
      "queue_waiting": 0,
      "queue_refused": 0,
      "last_synced_at": "2026-09-16T09:40:02Z",
      "last_problem_code": null,
      "last_problem_at": null,
      "workflows": [
        {
          "id": "wf3c…",
          "name": "River float waiver",
          "kind": "waiver",
          "active": true
        },
        {
          "id": "wf7a…",
          "name": "Campsite rules",
          "kind": "policy",
          "active": true
        }
      ]
    }
  ]
}
```

### POST /v1/devices

Scope `signing:devices` · answers `201`

**Add a tablet and get its pairing code**

Returns the pairing code once and never again: eight characters, fifteen minutes, one use. Type it into the SignSealer app on the tablet, which trades it for a credential of its own. `workflow_id` locks the tablet to one form (a kiosk); leave it out for a staff tablet that chooses. `for_review` makes a code that lasts thirty days, for an app store reviewer.

| Field | Type |  | Constraints |
| --- | --- | --- | --- |
| name | string | required | 1–60 chars |
| workflow_id | string (uuid) \| null | optional |  |
| for_review | boolean | optional |  |

Returns

```
{
  "id": "de92…",
  "code": "K7PQ2M9D",
  "expires_at": "2026-09-16T10:03:15Z",
  "review": false
}
```

### POST /v1/devices/{id}/code

Scope `signing:devices`

**A new pairing code for a tablet**

For a tablet that never paired, or one being set up again on new hardware. Any tablet paired to this one stops working the moment the new code is made, so a lost tablet is one call here rather than a new key for everything else.

Returns

```
{
  "id": "de92…",
  "code": "R4WX8NHB",
  "expires_at": "2026-09-16T10:05:40Z",
  "review": false
}
```

### PATCH /v1/devices/{id}

Scope `signing:devices`

**Rename a tablet, change what it runs, how it is handed a customer, or whose links it may show**

Any of the fields. A change reaches a paired tablet on its next heartbeat, without re-pairing. `workflow_id: null` makes it a staff tablet that chooses. `workflow_ids` (00420) gives it several forms, in the order its kiosk lists them — a campground's site waiver and its kayak waiver on one tablet — and `workflow_id` becomes the first; `[]` makes it a staff tablet. `hand_off` (00321, 00343) is `walk_up` (a person types their name), `same_device` (your till app hands the signing code to ours on the same tablet) or `separate` (a separate till; the tablet lists who is waiting). `gate` (00409) is `own` (the default for a tablet added from 24 September 2026: the Gate screen shows a signing link only for a document this tablet or its form started, and its search matches names, not addresses) or `account` (for every open document, for a tablet at the gate that checks people you emailed; tablets paired earlier were left here). A link a tablet shows is one whoever holds it could open, so open it only on the tablet that needs it.

| Field | Type |  | Constraints |
| --- | --- | --- | --- |
| name | string | optional | 1–60 chars |
| workflow_id | string (uuid) \| null | optional |  |
| workflow_ids | string (uuid)[] | optional | 0–12 items |
| hand_off | "walk_up" \| "same_device" \| "separate" | optional |  |
| gate | "own" \| "account" | optional |  |

Returns

```
{
  "updated": true
}
```

### DELETE /v1/devices/{id}

Scope `signing:devices`

**Stop a tablet**

Its credential stops in the same breath. Needs `?reason=`, which goes on the audit trail beside who stopped it and when.

Query

| Parameter | Type |  | What it is |
| --- | --- | --- | --- |
| reason | string | required | Why, for the audit trail. |

Returns

```
{
  "revoked": true
}
```

## Subjects

### PUT /v1/subjects

Scope `signing:subjects`

**Import a reservation or activity, and build its packet**

Keyed on (provider, external_id), so importing the same reservation twice is one reservation, which is why this needs no idempotency key. Participants and the packet are built in the same call, because a caller who imported a reservation always wants to know what is now required. What is required is decided by the documents chosen for bookings from the API, in the dashboard under Integrations; a reservation none of them fits has an empty packet, with `required` 0.

| Field | Type |  | Constraints |
| --- | --- | --- | --- |
| kind | "reservation" \| "activity" | optional |  |
| provider | string | optional | matches `^[a-z][a-z0-9_-]*$` |
| external_id | string | required | 1–200 chars |
| label | string | optional | 0–200 chars |
| starts_on | string | required | matches `^\d{4}-\d{2}-\d{2}$` |
| ends_on | string \| null | optional | matches `^\d{4}-\d{2}-\d{2}$` |
| facts | object | optional |  |
| participants | object[] | optional | 0–60 items |
| participants[].ref | string | optional | 0–64 chars |
| participants[].full_name | string | required | 1–200 chars |
| participants[].email | string (email) | optional |  |
| participants[].phone | string | optional | 0–40 chars |
| participants[].date_of_birth | string | optional | matches `^\d{4}-\d{2}-\d{2}$` |
| participants[].is_primary | boolean | optional |  |
| participants[].guardian_ref | string | optional | 0–64 chars |

Returns

```
{
  "subject_id": "s2e4…",
  "packet": {
    "packet_id": "p6c9…",
    "code": "ABCD234567",
    "added": 2,
    "dropped": 0,
    "state": "open",
    "required": 2,
    "completed": 0,
    "outstanding": 2,
    "not_started": 2
  }
}
```

## Packets

### GET /v1/packets/code/{code}

Scope `signing:read`

**Resolve a signing code, from a tablet**

The last few feet of a sale made in your own software (00321): the customer holds the signing code from the receipt, the tablet at the counter resolves it and sees what is still owed -- each item's first name and last initial, workflow and state -- and nothing else: no address, no full guest list. Only a paired tablet's credential may ask; a code from another business, a code nobody holds and a malformed code all answer `found: false` the same way. Rate limited per tablet.

Returns

```
{
  "found": true,
  "packet_id": "p6c9…",
  "code": "ABCD234567",
  "state": "open",
  "required": 2,
  "completed": 1,
  "outstanding": 1,
  "declined": 0,
  "expires_at": "2026-10-01T00:00:00Z",
  "items": [
    {
      "item_id": "i1a…",
      "who": "Dana R.",
      "workflow": "river-float",
      "required": true,
      "status": "completed"
    },
    {
      "item_id": "i2b…",
      "who": "Sam L.",
      "workflow": "river-float",
      "required": true,
      "status": "not_started"
    }
  ]
}
```

### GET /v1/packets/{id}

Scope `signing:read`

**Show a packet**

Who owes what, where each one has got to, and a readiness state a door lock can wait on.

Returns

```
{
  "packet_id": "p6c9…",
  "code": "ABCD234567",
  "status": "open",
  "ready_at": null,
  "subject": {
    "id": "s2e4…",
    "kind": "reservation",
    "label": "Reyes party, 4 Oct",
    "provider": "deckpos",
    "external_id": "RES-88213",
    "starts_on": "2026-10-04",
    "ends_on": "2026-10-04",
    "facts": {}
  },
  "readiness": {
    "state": "open",
    "required": 2,
    "completed": 1,
    "outstanding": 1,
    "not_started": 0,
    "declined": 0
  },
  "items": [
    {
      "item_id": "i1…",
      "requirement": "waiver",
      "workflow": "waiver",
      "required": true,
      "participant": {
        "id": "pa1…",
        "full_name": "Dana Reyes",
        "email": "dana@example.signsealer.com",
        "is_minor": false,
        "signs_for_them": null
      },
      "document_id": "d41c…",
      "status": "completed"
    }
  ]
}
```

### POST /v1/packets/items/{id}/start

Scope `signing:subjects` or `signing:workflows` · answers `201` · takes an `Idempotency-Key` (`packets.start_item`)

**Start one packet item**

Renders the item's workflow for the person who owes it. A minor's document is started for their guardian, because the guardian is who signs. A paired tablet may start an item it resolved from a signing code, the way it starts its own workflow. On a workflow signed in order, a fixed role whose turn has not come is held, as at `POST /v1/workflows/{id}/start`: their `token` is null and `held` is true, and they are sent their link when the people before them have signed (00609). Nobody is held when the business sends its own links (sending turned off in the dashboard): every token comes back now, and handing each one over in its turn is yours.

Returns

```
{
  "document_id": "d41d…",
  "title": "Kayak rental waiver — Dana Reyes",
  "expires_at": "2026-10-10T14:22:09Z",
  "template_version": 3,
  "party_size": null,
  "signers": [
    {
      "signer_id": "5f0c…",
      "email": "dana@example.signsealer.com",
      "phone": null,
      "full_name": "Dana Reyes",
      "role": "signer",
      "participant": true,
      "for_business": false,
      "token": "3f9c…"
    }
  ]
}
```

### POST /v1/packets/{id}/start

Scope `signing:subjects`

**Start everything a packet still owes**

Starts every item nobody has started yet, each for the person who owes it (a minor's for their guardian). Items already started are left alone, which makes this safe to call on every booking update. An item that cannot be started -- nobody with an email address, an archived workflow -- is listed under `skipped` with the reason, and the others still go. Refused on a voided packet.

Returns

```
{
  "packet_id": "p6c9…",
  "started": [
    {
      "item_id": "i2…",
      "requirement": "waiver",
      "participant": "Sam Reyes",
      "document_id": "d41e…"
    }
  ],
  "skipped": [
    {
      "item_id": "i3…",
      "requirement": "waiver",
      "participant": "Ana Reyes",
      "reason": "no address to send Ana Reyes's document to"
    }
  ]
}
```

### POST /v1/packets/{id}/void

Scope `signing:void` (or `signing:write`, which includes it)

**Void a packet: the booking was canceled**

Voids every document the packet started that nobody has finished, with the reason on each, and marks the packet void. A document somebody already signed is kept -- an executed waiver is evidence of what was agreed, and a cancellation afterwards does not unsign it -- and counted under `kept`.

| Field | Type |  | Constraints |
| --- | --- | --- | --- |
| reason | string | required | 1–500 chars |

Returns

```
{
  "packet_id": "p6c9…",
  "voided": 2,
  "kept": 1
}
```

## Integrations

### GET /v1/integrations

Scope `signing:read`

**List the booking systems this business can connect, and what it has connected**

Every provider with its status (`available`, `beta`, `pending_partner_access`, `planned`, `deprecated`, `disabled`), how it connects and what API version it is built against; and the business's connections with their state, why one is paused when the membership ended (`paused_reason`), when a booking last arrived, the last error and how many events are waiting or gave up. `needs_membership` is true when the business is on Free: connecting a booking system comes with the membership (00425), and a connection paused because the membership ended resumes by itself when it starts again. Credentials and the address a provider posts to are never included. Connecting is done in the dashboard, where the provider is asked to confirm the credentials.

Returns

```
{
  "providers": [
    {
      "key": "guesty",
      "label": "Guesty",
      "category": "vacation_rentals",
      "status": "beta",
      "connects": "webhook",
      "auth_type": "oauth_client_credentials",
      "verification": "svix",
      "connector_version": "1.0.0",
      "api_version": "Open API v1; reservations v3; webhooks v2",
      "deprecates_at": null,
      "sunsets_at": null
    }
  ],
  "connections": [
    {
      "id": "c7a1…",
      "provider": "guesty",
      "label": "Guesty (main)",
      "status": "active",
      "paused_reason": null,
      "config": {
        "send": "on_booking",
        "void_on_cancel": true,
        "kind": "reservation"
      },
      "created_at": "2026-10-03T14:22:09Z",
      "last_event_at": "2026-10-03T14:22:09Z",
      "last_success_at": "2026-10-03T14:22:09Z",
      "last_error": null,
      "last_error_at": null,
      "waiting": 0,
      "dead": 0
    }
  ],
  "needs_membership": false
}
```

### GET /v1/integrations/{id}/events

Scope `signing:read`

**What arrived from one connection, and what became of it**

The latest fifty deliveries, newest first: the provider's booking id, the event, its state (`queued`, `processing`, `done`, `ignored`, `superseded`, `failed`, `dead`), the error when there is one, what the provider's data said about consent to text (`consent_evidence`), the reservation it made and a summary of the packet (how many documents were required, started and skipped, and for each guest with a number whether the link was also texted and why not). What arrived is never returned.

Returns

```
{
  "events": [
    {
      "id": "e9b2…",
      "event_type": "reservation.updated.v2",
      "external_ref": "64f1c2…",
      "status": "done",
      "attempts": 1,
      "received_at": "2026-10-03T14:22:09Z",
      "processed_at": "2026-10-03T14:22:09Z",
      "next_attempt_at": "2026-10-03T14:22:09Z",
      "error": null,
      "verified_by": "svix",
      "consent_evidence": "INSUFFICIENT_EVIDENCE",
      "subject_id": "s2e4…",
      "result": {
        "packet_id": "p6c9…",
        "required": 2,
        "state": "open",
        "started": 2,
        "skipped": [],
        "sent": true,
        "texts": [
          {
            "guest": "Dana Reyes",
            "may_text": false,
            "why": "no consent on file; the link goes by email"
          }
        ]
      }
    }
  ]
}
```

## Webhooks

### GET /v1/webhooks

Scope `signing:webhooks`

**List webhook endpoints**

Each endpoint with its address, label and events, whether it is on, its consecutive `failures` and `paused_at` (twenty failures in a row pause it), how many deliveries are `queued` and `dead`, and `held_dropped`: deliveries not kept because ten thousand were already waiting while it was paused. `unknown_events` lists any of its `events` that are not events we send -- names stored before 3 October, when a change to an endpoint's events began to be checked -- which never arrive; change its events to drop them. Never the secret.

Returns

```
{
  "endpoints": [
    {
      "id": "h4a7…",
      "url": "https://pms.example.com/hooks/signsealer",
      "label": "Booking system",
      "events": [
        "signing.completed",
        "signing.declined"
      ],
      "active": true,
      "failures": 0,
      "paused_at": null,
      "last_delivered_at": "2026-10-03T14:22:09Z",
      "created_at": "2026-10-03T14:22:09Z",
      "queued": 0,
      "dead": 0,
      "held_dropped": 0,
      "unknown_events": []
    }
  ]
}
```

### POST /v1/webhooks

Scope `signing:webhooks` · answers `201` · takes an `Idempotency-Key` (`webhooks.add`)

**Add a webhook endpoint**

Returns the signing secret once and never again. It is sealed at rest; a caller who loses it rotates it (`POST /v1/webhooks/{id}/rotate`). `events` defaults to `["*"]`, which is every event but `signing.location_shared`: a signer's position goes only to an endpoint that names it. A name not on the list in /docs/webhooks is refused with 422. Twenty endpoints per business.

| Field | Type |  | Constraints |
| --- | --- | --- | --- |
| url | string (uri) | required | matches `^https://` |
| events | string[] | optional | 1–30 items |
| label | string | optional | 0–80 chars |

Returns

```
{
  "id": "h4a7…",
  "secret": "whsec_…48 hex characters, shown once"
}
```

### PATCH /v1/webhooks/{id}

Scope `signing:webhooks`

**Change a webhook endpoint**

Turning an endpoint back on forgives its failure count and releases what it held. A paused endpoint keeps receiving events — they wait rather than being lost (00289) — so the answer says how many are waiting to go out, and how many were dropped because the hold was full while it was paused. `events`, when it is sent, replaces the list and is checked as `POST /v1/webhooks` checks it: a name that is not an event is refused with 422 `invalid`, whose hint lists every event there is, and nothing is changed. A change that sends no `events` is not asked about the ones the endpoint already holds, even one that is not an event (see `unknown_events` on `GET /v1/webhooks`).

| Field | Type |  | Constraints |
| --- | --- | --- | --- |
| active | boolean | optional |  |
| events | string[] | optional | 1–30 items |
| label | string | optional | 0–80 chars |

Returns

```
{
  "updated": true,
  "resumed": true,
  "waiting": 14,
  "dropped_while_paused": 0
}
```

### POST /v1/webhooks/{id}/rotate

Scope `signing:webhooks`

**Rotate a webhook endpoint's secret**

A new secret, returned once. For 24 hours every delivery is signed with both — the signature header carries two comma-separated `v1=` values, the new secret's first — so a receiver can switch without dropping a delivery. After that the old secret is forgotten.

Returns

```
{
  "secret": "whsec_…shown once",
  "previous_valid_for_seconds": 86400
}
```

### GET /v1/webhooks/{id}/deliveries

Scope `signing:webhooks`

**List an endpoint's recent deliveries**

The last fifty, newest first: event, status, attempts, the next attempt, the last error and the document. A replay names the delivery it repeats in `replay_of`.

Returns

```
{
  "deliveries": [
    {
      "id": "dl1…",
      "endpoint_id": "h4a7…",
      "event": "signing.completed",
      "status": "delivered",
      "attempts": 1,
      "next_attempt_at": "2026-10-03T14:22:09Z",
      "last_error": null,
      "response_status": 200,
      "created_at": "2026-10-03T14:22:09Z",
      "delivered_at": "2026-10-03T14:22:09Z",
      "replay_of": null,
      "document_id": "d41c…",
      "document_title": "Liability waiver — Dana Reyes"
    }
  ]
}
```

### POST /v1/webhooks/deliveries/{id}/replay

Scope `signing:webhooks`

**Send a delivery again**

Queues a delivered, failed or dead delivery again as a new delivery with the same event and body, marked as a replay of the original. One still in the queue is refused; so is a second replay while the first is queued. A replay waits like any other if the endpoint is off or paused. The body is the one kept: once the document is redacted, or the business's message retention has passed (thirty days unless it set otherwise), the people have been taken out of it -- the title, the signer's name, address, number and reason, and `external_ref` -- and a replay sends it that way. A `signing.location_shared` delivery is not replayed to an endpoint that does not name that event now (422): a signer's position goes only where it is asked for by name.

Returns

```
{
  "delivery_id": "dl2…"
}
```

### DELETE /v1/webhooks/{id}

Scope `signing:webhooks`

**Remove a webhook endpoint**

Needs `?reason=`, which goes on the audit trail.

Query

| Parameter | Type |  | What it is |
| --- | --- | --- | --- |
| reason | string | required | Why, for the audit trail. |

Returns

```
{
  "deleted": true
}
```

## Sign

### GET /v1/sign/{token}

No key: the token in the path is the credential

**Read a document from a signing link**

Everything the signing page needs from one token: the text and its hash, who is being asked, who else is on it, whether it is this signer's turn, and — when it will not take a signature — why, in a sentence a person can read. When the template is an uploaded PDF, `pages` lists its pages and each field may carry a `place` saying where on one it belongs; fetch a page as an image from `/s/{token}/page?n=1`. Returns a body even for a token that matches nothing, so a bad link and an expired one fail identically. `body_format` is `text` or `markdown`; a `markdown` body uses headings, bold, italics and lists and should be drawn as such, not as the raw marks. Each field may carry a `block` -- a set of questions asked as one, with a heading and an introduction, and `step: true` when it gets a page of its own -- and a `show_if` condition on earlier answers: one rule, or several joined by all or any, any of them a group of its own, and with `action: "hide"` hiding the question rather than showing it. `visible` is the engine's own answer to that condition: draw only the visible questions. A hidden one is not required, and answering the question it depends on differently clears it. `rules_at_start` is its answer to each rule on its own, for a page that decides some rules itself and needs the others. A condition is read on the calendar day in `condition_zone`, so an age means the same to your page as to the engine. `document_after_questions` is true when the business asked for the questions first and the document after them, and while the first signer's answers still decide which paragraphs the text has. `paragraphs` (00540) is set when paragraphs of the text depend on the first signer's answers: `body` then has only the ones that apply as the link is read, `sections` says which (in order), `decided_by` whose answers decide them, and `settled` whether that signer has signed, which freezes them. While they are this signer's to decide, `source` is the text with its `[[show if ...]]` and `[[end]]` lines and `conditions` each paragraph's condition (with `rules_at_start`, each of its rules met or not so far), for a page that asks the questions itself; anybody else is `waiting`, and is refused a signature until then. Pass `sections` back as `paragraphs` when you sign; while they are undecided a signature without it is refused. `party` is set when everybody in a booking's party signs (a workflow with `each_person_signs`, started with `persons` above one): for the person it was started for, `lead` is true, `still_to_add` says how many people they must add before they can sign, and `others` lists those added; for somebody they added, `added_by` names them. A lead whose `may_add` is true adds the others with `POST /v1/sign/{token}/party`, or on the signing page at `/s/{token}`; either way the lead cannot sign until they have. `documents` is `one` when the party signs one document, or `each` when every person added has a document of their own (the workflow's `party_documents`); the party is read the same either way, from any of its documents.

Returns

```
{
  "ok": true,
  "reason": null,
  "document_id": "d41c…",
  "title": "Liability waiver — Dana Reyes",
  "body": "# Liability waiver\n\nI, **Dana Reyes**, …",
  "body_format": "markdown",
  "body_sha256_hex": "e362cc76dae17bbe2a9fc551d9b795fa4e0f77fb488eb748378a125b11f36324",
  "document_status": "sent",
  "sequential": false,
  "expires_at": "2026-10-17T00:00:00Z",
  "tenant_name": "Fern Hollow Stables",
  "signer_id": "5f0a…",
  "full_name": "Dana Reyes",
  "email": "dana@example.signsealer.com",
  "signer_role": "signer",
  "sign_order": 1,
  "signer_status": "pending",
  "consented_at": null,
  "signed_at": null,
  "template_kind": "waiver",
  "grants": {},
  "is_my_turn": true,
  "waiting_on": null,
  "consent_text": "By continuing you agree to sign this document electronically and to receive a copy by email. …",
  "consent_version": "consent/1",
  "intent_text": "By signing below I confirm that I have read this document, …",
  "intent_version": "intent/1",
  "signers": [
    {
      "full_name": "Dana Reyes",
      "role": "signer",
      "sign_order": 1,
      "status": "pending",
      "signed_at": null,
      "is_me": true
    }
  ],
  "verification_required": null,
  "verification_to": null,
  "verified_at": null,
  "code_sent_at": null,
  "powered_by": true,
  "theme": null,
  "mark": {
    "tenant_id": "3a1f…",
    "name": "Fern Hollow Stables",
    "logo": "png"
  },
  "footer": null,
  "document_after_questions": false,
  "time_zone": null,
  "condition_zone": "America/Chicago",
  "party": null,
  "pages": [],
  "fields": [
    {
      "key": "rode_before",
      "label": "Have you ridden before?",
      "kind": "choice",
      "required": true,
      "about": null,
      "hint": null,
      "options": [
        "Yes",
        "No"
      ],
      "sensitive": false,
      "place": null,
      "block": {
        "key": "experience",
        "label": "Your riding",
        "intro": "So we can match you to a horse.",
        "step": true
      },
      "show_if": null,
      "rules_at_start": null,
      "visible": true,
      "supplied": false,
      "passed": false,
      "at_signing": null,
      "placed_value": null,
      "placed_words": null,
      "from_sender": false
    },
    {
      "key": "lessons",
      "label": "How many lessons have you had?",
      "kind": "number",
      "required": true,
      "about": null,
      "hint": null,
      "options": [],
      "sensitive": false,
      "place": null,
      "block": {
        "key": "experience",
        "label": "Your riding",
        "intro": "So we can match you to a horse.",
        "step": true
      },
      "show_if": {
        "field": "rode_before",
        "equals": [
          "Yes"
        ]
      },
      "rules_at_start": [
        false
      ],
      "visible": false,
      "supplied": false,
      "passed": false,
      "at_signing": null,
      "placed_value": null,
      "placed_words": null,
      "from_sender": false
    },
    {
      "key": "initials",
      "label": "Initial here",
      "kind": "initials",
      "required": true,
      "about": null,
      "hint": null,
      "options": [],
      "sensitive": false,
      "place": null,
      "block": null,
      "show_if": null,
      "rules_at_start": null,
      "visible": true,
      "supplied": false,
      "passed": false,
      "at_signing": null,
      "placed_value": null,
      "placed_words": null,
      "from_sender": false
    }
  ]
}
```

### POST /v1/sign/{token}/consent

No key: the token in the path is the credential

**Record consent to sign electronically**

Must happen before the signature, and is its own event for that reason: ESIGN requires consent to precede the transaction, and a system that recorded both in the same instant could not show that it did.

| Field | Type |  | Constraints |
| --- | --- | --- | --- |
| captured | object | optional |  |
| captured.offline | boolean | optional |  |
| captured.at | string (date-time) | optional |  |
| captured.device | string | optional | 0–80 chars |

Returns

```
{
  "consented": true
}
```

### GET /v1/sign/{token}/id-evidence

No key: the token in the path is the credential

**What the signer is asked for by way of ID evidence**

The business's choice (00228, 00339): `mode` is what the signing page requires of a signer we delivered a link to; `offered` is what the counter offers a signer standing there, who may skip it; `required` says whether the signature will be refused without a photo. With what is captured so far, by hash, and the disclosure each capture is taken under. A token that matches nothing is answered 404 `not_found`.

Returns

```
{
  "mode": "off",
  "offered": "id_selfie",
  "required": false,
  "id": {
    "captured_at": "2026-10-03T14:22:09Z",
    "sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"
  },
  "selfie": null,
  "id_disclosure": {
    "ref": "id_capture/1",
    "text": "Photograph the front of a government-issued ID. …",
    "sha256": "e3b0…"
  },
  "selfie_disclosure": {
    "ref": "selfie_capture/1",
    "text": "If you wish, take a photo of yourself. …",
    "sha256": "e3b0…"
  }
}
```

### POST /v1/sign/{token}/id-evidence

No key: the token in the path is the credential · answers `201`

**Keep a photo of the ID, or of the person**

The tablet app's camera step (00339). The bytes are shrunk here as the signing page's are, hashed, encrypted under the business's key and kept for thirty days; the capture goes on the trail with its hash and the disclosure shown. Refused when the business did not ask (`offered` is `off`), when a selfie is sent to a business that asked only for the ID, or when the link is closed -- all before the image is read. The image is never logged. A JPEG or a PNG of at most 52 megapixels, as base64 in a body of at most a megabyte -- about 740 KB of image, which is why the tablet app shrinks a photo before it sends one. Two refusals are about timing rather than the photo: another photo from this link is still being read, or the photos waiting to be read are queueing (each business holds at most two of the places). Both answer 429 `busy` with `Retry-After` in seconds (thirty): nothing was kept, so send the same photo again after that long. A refusal of the photo itself, or of a link that is closed, is 422 `invalid`, and sending the same photo again will not change it.

| Field | Type |  | Constraints |
| --- | --- | --- | --- |
| kind | "id" \| "selfie" | required |  |
| content_type | string | required | 0–80 chars |
| bytes_base64 | string | required | 1–1000000 chars |
| captured | object | optional |  |
| captured.offline | boolean | optional |  |
| captured.at | string (date-time) | optional |  |
| captured.device | string | optional | 0–80 chars |

Returns

```
{
  "captured": true,
  "kind": "id",
  "sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"
}
```

### GET /v1/sign/{token}/location

No key: the token in the path is the credential

**Whether the signer is asked where they are**

The business's choice (00231): `mode` is `off`, `ask` or `require`, and `require` means the signature is refused until a position is on the record — for a signer we sent a link to. `offered` is what a counter tablet does with the same choice (00363): `ask` when the business asks anybody, and never more, because a signature at the counter is never refused for the want of a position. `position` is the answer already given, and `disclosure` is the wording the capture is taken under, which the client must show before it asks. `{ "shared": false }` answers `ask`; under `require` only a shared position lets the signature through. For a token that matches nothing, `mode` and `offered` are `off`.

Returns

```
{
  "mode": "require",
  "offered": "ask",
  "position": null,
  "disclosure": {
    "ref": "location_capture/2",
    "sha256": "10f0…",
    "text": "You will be asked whether to share where you are. If you allow it, the latitude and longitude your device reports are recorded on this signature …"
  }
}
```

### POST /v1/sign/{token}/location

No key: the token in the path is the credential

**Record where the signer is, or that they would not say**

Send `{ "shared": true, "lat": …, "lon": …, "accuracy_m": … }` when the person allowed it, and `{ "shared": false }` when they refused or the device could not get a fix — both go on the trail. Under `ask` either is an answer; under `require` a refusal is recorded and the signature is still refused, so take the person back to the step. Ask for the position only after showing the `disclosure` from the GET. Refused when the business does not ask for a location at all, and when the document is already signed.

| Field | Type |  | Constraints |
| --- | --- | --- | --- |
| shared | boolean | required |  |
| lat | number | optional | -90–90 |
| lon | number | optional | -180–180 |
| accuracy_m | number | optional | 0–100000 |
| captured | object | optional |  |
| captured.offline | boolean | optional |  |
| captured.at | string (date-time) | optional |  |
| captured.device | string | optional | 0–80 chars |

Returns

```
{
  "shared": true,
  "lat": 45.523064,
  "lon": -122.676483,
  "accuracy_m": 12.5,
  "disclosure": "location_capture/2"
}
```

### POST /v1/sign/{token}/fields/{key}/photo

No key: the token in the path is the credential · answers `201`

**Answer a photo field with a photograph**

A template field of kind `photo` (00342) takes a photograph, not text: a JPEG or PNG, shrunk here as the signing page's are, hashed, encrypted under the business's key and kept with the document for as long as the document is kept. The field's value becomes `sha256:<hex>` and the capture goes on the trail as `photo_supplied`. A second photograph replaces the first. `about` names the covered person for a per-child field. Refused for a field that is not a photo, a link that is closed, or an image that is not one. Sizes, and the two 429 `busy` refusals worth sending again after `Retry-After`, are as for `POST /v1/sign/{token}/id-evidence`.

| Field | Type |  | Constraints |
| --- | --- | --- | --- |
| content_type | string | required | 0–80 chars |
| bytes_base64 | string | required | 1–1000000 chars |
| about | string | optional | 0–200 chars |
| captured | object | optional |  |
| captured.offline | boolean | optional |  |
| captured.at | string (date-time) | optional |  |
| captured.device | string | optional | 0–80 chars |

Returns

```
{
  "supplied": true,
  "key": "boat_condition",
  "sha256": "e362cc76dae17bbe2a9fc551d9b795fa4e0f77fb488eb748378a125b11f36324"
}
```

### POST /v1/sign/{token}/code

No key: the token in the path is the credential

**Send the signer a one-time code**

Only when the business asks signers for a code (Settings → Signing) and a link was delivered to this signer. The code goes to the address or number the link went to; the answer says where, masked. One a minute, five an hour for one signer; and a business's signers are sent at most three hundred codes by text an hour between them, past which the answer is 429 `rate_limited` with `Retry-After`. Not an identity check: it proves control of that inbox or phone at the moment of signing.

Returns

```
{
  "channel": "email",
  "sent_to": "d•••@example.signsealer.com",
  "resend_after": "2026-10-03T14:22:09Z"
}
```

### POST /v1/sign/{token}/verify

No key: the token in the path is the credential

**Confirm the one-time code**

A wrong code is answered with ok false and the tries left rather than an error; after five wrong tries the code is dead and a new one must be sent. A confirmed code is a verified event on the trail and the certificate says email_otp or sms_otp.

| Field | Type |  | Constraints |
| --- | --- | --- | --- |
| code | string | required | 4–12 chars |

Returns

```
{
  "ok": true
}
```

### POST /v1/sign/{token}/fields

No key: the token in the path is the credential

**Supply a required field**

Initials, a checkbox, a date. A signature is refused while anything required is unsupplied, and that refusal is in the database rather than in the form — so a second interface cannot go around it. Refused, as a signature is, once the document is voided, declined or expired or the link is past its date; and six hundred answers an hour per link.

| Field | Type |  | Constraints |
| --- | --- | --- | --- |
| key | string | required | matches `^[a-z][a-z0-9_]{0,58}$` |
| value | string | required | 0–20000 chars |
| about | string \| null | optional | 0–200 chars |

Returns

```
{
  "supplied": true
}
```

### POST /v1/sign/{token}

No key: the token in the path is the credential · answers `201`

**Sign**

Typed or drawn, both equally valid: what matters is intent. `captured` is for a signature taken where there was no network — the server records when it received it and keeps the device's claim beside it, with the clock skew computed rather than accepted. It is kept only from a paired tablet of the business the link belongs to, which sends its device credential as the bearer on this one call (the token still authorizes it); from anybody else -- no bearer, an API key, another business's tablet -- it is left out without an error and the signature is dated when it arrives. `paragraphs` says which of the document's conditional paragraphs (00540) your page drew, in the order of `paragraphs.sections` on the link. While the first signer's answers still decide them, it is required: a signature without it is refused with 422, and one whose answers now call for different paragraphs with 409 `paragraphs_changed`, so nobody signs a paragraph they were not shown. It is kept with the signature.

| Field | Type |  | Constraints |
| --- | --- | --- | --- |
| method | "typed" \| "drawn" \| "clicked" \| "uploaded" | required |  |
| value | string | required | 1–400000 chars |
| captured | object | optional |  |
| captured.offline | boolean | optional |  |
| captured.at | string (date-time) | optional |  |
| captured.device | string | optional | 0–80 chars |
| paragraphs | boolean[] | optional | 0–500 items |

Returns

```
{
  "event_id": "e3…"
}
```

### POST /v1/sign/{token}/decline

No key: the token in the path is the credential

**Decline to sign**

With a reason. A decline is a person saying no, which is not the same as still waiting — a packet containing one is blocked rather than outstanding, so nobody chases somebody who already answered.

| Field | Type |  | Constraints |
| --- | --- | --- | --- |
| reason | string | required | 1–500 chars |

Returns

```
{
  "declined": true
}
```

### POST /v1/sign/{token}/party

No key: the token in the path is the credential · answers `201`

**Add the others in the party, as the person who booked**

For a lead whose `party.may_add` is true on `GET /v1/sign/{token}`: `people` is everybody else in the booking, exactly `party.still_to_add` of them, and the lead cannot sign until they are added. Each adult is `full_name` with an `email` or a `phone`, or with neither: then theirs is a place kept open, which they take from the party link by choosing their name and giving an address (a name left empty is a place for anybody in the party). A child is `minor: true` -- or, where the business asks for dates of birth (`party.ages` is `dob`), `date_of_birth` as YYYY-MM-DD and the age decides -- with `guardian`: `me` for the lead, `p<n>` for the n-th adult in `people`, or `other` with `guardian_name` and a `guardian_email` or `guardian_phone`. `over_13` marks a child old enough to sign beside the adult, where the business asks minors to sign too. Each person given an address is sent their own link, by email or by text where the business may text the number, and comes back with `sent: true` and no link: theirs alone. Anybody it could not be sent to comes back with `sent: false` and their `token` and `url`, shown once, for you to hand over -- that showing is on the trail. `party_link` is the link the open places are taken from: share it with the party (a text, a QR code). Refused in words: 422 for the wrong number of people, an address that is not one, a child with no adult to sign for them, and once the party is added or the lead has signed; 409 for an address already on the agreement (each person signs with their own); 403 for anybody but the lead.

| Field | Type |  | Constraints |
| --- | --- | --- | --- |
| people | object[] | required | 1–19 items |
| people[].full_name | string | optional | 0–200 chars |
| people[].email | string \| null | optional | 0–320 chars |
| people[].phone | string \| null | optional | 0–40 chars |
| people[].minor | boolean | optional |  |
| people[].date_of_birth | string \| null | optional | matches `^\d{4}-\d{2}-\d{2}$` |
| people[].over_13 | boolean | optional |  |
| people[].guardian | string | optional | matches `^(me\|other\|p([1-9]\|1[0-9]))$` |
| people[].guardian_name | string \| null | optional | 0–200 chars |
| people[].guardian_email | string \| null | optional | 0–320 chars |
| people[].guardian_phone | string \| null | optional | 0–40 chars |

Returns

```
{
  "people": [
    {
      "signer_id": "7c2d…",
      "full_name": "Riley Hart",
      "email": "riley@example.signsealer.com",
      "phone": null,
      "sent": true,
      "token": null,
      "url": null
    }
  ],
  "party_link": "https://sign.fernhollow.example/p/3f9a…"
}
```

### POST /v1/sign/{token}/party/share

No key: the token in the path is the credential · answers `201`

**The party link again, for the person who booked**

A new party link for the lead to share, and the last one stops working: for a link shared with the wrong people, or lost. The places already taken stay taken. Only the lead's token, once the party is added, while the agreement is waiting for signatures.

Returns

```
{
  "party_link": "https://sign.fernhollow.example/p/8b41…"
}
```

### POST /v1/sign/{token}/party/link

No key: the token in the path is the credential · answers `201`

**One person's link again, for the person who booked**

A new link for `signer_id`, somebody the lead added, and the one they had stops working. Sent to them where it can be, and then `sent` is true and no link comes back; otherwise `token` and `url`, shown once, for you to hand over. `address`, an email address or a mobile number different from the one on file, corrects where it goes -- only before they have opened their link, and a link that went by email only to another email address. Refused for somebody who has signed or declined, somebody who took their own place from the party link (their link is theirs alone), and anybody not in the lead's party. Thirty an hour from one lead's link, and three links sent to one address in a day.

| Field | Type |  | Constraints |
| --- | --- | --- | --- |
| signer_id | string (uuid) | required |  |
| address | string | optional | 0–320 chars |

Returns

```
{
  "signer_id": "7c2d…",
  "sent": false,
  "token": "c1e0…",
  "url": "https://sign.fernhollow.example/s/c1e0…"
}
```

## Verify

### GET /v1/verify/{code}

No key: the token in the path is the credential

**Check a certificate by its printed code**

Anonymous, because the point is that somebody holding the document can check it. Answers three separate questions: whether the certificate exists, whether a document you hold matches it, and whether it still matches the record behind it. The third is a finding, never a correction. With the code alone you get the issuer, title, dates and how many signed; pass `?sha256=` of the document you hold and, when it matches, the signers (never their email addresses) and the trail. The file itself is checked first: the SHA-256 of the sealed PDF we issued (`copy_matches`), then that of the document's text. `document_matches` is true for either.

Query

| Parameter | Type |  | What it is |
| --- | --- | --- | --- |
| sha256 | string | optional | The SHA-256 of the sealed PDF you were sent (or of the document's text), in hex. When it matches, the signers and the trail come back too. |

Returns

```
{
  "certificate_found": true,
  "verification_code": "K7QP3MTV9XBD2FHR",
  "issued_at": "2026-10-03T14:22:09Z",
  "issuer": "Fern Hollow Stables",
  "title": "Liability waiver — Dana Reyes",
  "document_sha256_hex": "e362cc76dae17bbe2a9fc551d9b795fa4e0f77fb488eb748378a125b11f36324",
  "certificate_sha256_hex": "592f…",
  "document_matches": true,
  "still_matches_record": true,
  "divergence": null,
  "completed_at": "2026-10-03T14:22:09Z",
  "redacted_at": null,
  "signer_count": 1,
  "signers": [
    {
      "full_name": "Dana Reyes",
      "role": "signer",
      "sign_order": 1,
      "status": "signed",
      "party_id": null,
      "consented_at": "2026-10-03T14:22:09Z",
      "signed_at": "2026-10-03T14:22:09Z",
      "declined_at": null,
      "signature": {
        "method": "typed",
        "value": "Dana Reyes",
        "value_sha256": null,
        "signed_against_sha256": "e362cc76dae17bbe2a9fc551d9b795fa4e0f77fb488eb748378a125b11f36324",
        "ip": "203.0.113.9",
        "user_agent": "Mozilla/5.0 …"
      }
    }
  ],
  "events": [
    {
      "kind": "signed",
      "occurred_at": "2026-10-03T14:22:09Z",
      "signer": "Dana Reyes",
      "against_sha256": "e362cc76dae17bbe2a9fc551d9b795fa4e0f77fb488eb748378a125b11f36324",
      "detail": null
    }
  ],
  "copy_matches": false,
  "copy_sha256_hex": null
}
```

## OAuth

How an app is connected to a business: the browser redirect, the token exchange, and the WordPress plugin registering its own client. Served at `https://api.signsealer.com`, beside the API rather than under `/v1`. See [Authentication](https://signsealer.com/docs/authentication) for the flow, and [AI assistants](https://signsealer.com/docs/mcp) for an assistant connecting itself.

### GET /oauth/authorize

No key

**Send a business to approve your app**

A browser redirect, not an API call: send the person here and they are shown SignSealer's consent screen, signed in to their own account. Query: `response_type=code`, `client_id`, `redirect_uri` (exactly as registered), `scope` (space-separated, within what your app may ask for), `state`, `code_challenge` and `code_challenge_method=S256`. They come back to `redirect_uri` with `code` and your `state`, or with `error`.

### POST /oauth/token

No key

**Exchange a code, or refresh a token**

RFC 6749, as a form body (JSON is accepted too). The client authenticates with `client_id` and `client_secret` in the body or by HTTP Basic. `grant_type=authorization_code` with `code`, `redirect_uri` and `code_verifier`; or `grant_type=refresh_token` with `refresh_token`. Answers `access_token` (good for an hour), `token_type: Bearer`, `expires_in`, `scope` and, to a client that has refresh tokens, `refresh_token` (good once, for thirty days; the answer carries the next), with `Cache-Control: no-store`; or an RFC 6749 error object with status 400 or 401. A `resource` (RFC 8707) names the API the token is for; one on another origin is refused with `invalid_target`. `invalid_grant` on a refresh also means the connection is over: the business ended it, a refresh token was presented twice (which revokes the whole connection), or the person who connected your app was removed or can no longer grant what it holds. Send the business through `/oauth/authorize` again.

| Field | Type |  | Constraints |
| --- | --- | --- | --- |
| grant_type | "authorization_code" \| "refresh_token" | required |  |
| code | string | optional |  |
| redirect_uri | string (uri) | optional |  |
| code_verifier | string | optional |  |
| refresh_token | string | optional |  |
| client_id | string | optional |  |
| client_secret | string | optional |  |
| resource | string (uri) | optional |  |

### POST /oauth/register

No key · answers `201`

**Register a client: a WordPress site, or an app by RFC 7591**

Two kinds of registration, told apart by the body. **A WordPress site**, which the plugin does itself when a site connects: a form body with `kind=wordpress`, `redirect_uri`, `manifest_url` and `token`, all on one https host. SignSealer fetches the manifest and registers the client only when the page shows that token's SHA-256, base64url, as `token_sha256` (a plugin before 1.16.2 shows the token itself). Ten an hour per address. **An app or AI assistant** (RFC 7591 dynamic registration, as an MCP client does it): a JSON body with `redirect_uris` and no `kind`. Each address is https, or http on localhost, 127.0.0.1 or [::1], with a path; `token_endpoint_auth_method` `none` registers a public client, which uses PKCE alone. It is given reading and the four parts of signing:write, whatever it asks for; a `scope` sent is ignored. It gets refresh tokens only when `grant_types` lists `refresh_token`. Thirty an hour per address, and a client nobody connects within a day is removed. Either way the secret, when there is one, is in the answer once.

| Field | Type |  | Constraints |
| --- | --- | --- | --- |
| kind | "wordpress" | required |  |
| redirect_uri | string (uri) | required |  |
| manifest_url | string (uri) | required |  |
| token | string | required | 16–128 chars |

## Partner

What a partner reads about the businesses it brought. Read only. See [Platforms and partners](https://signsealer.com/docs/partners).

### GET /v1/partner

Your app's `client_id` and `client_secret` as HTTP Basic

**Your program, this month so far, and your signup link**

The share you earn, whether your custom branding is on (it is free), how many businesses you have brought, and this month so far: what they paid for, the card fees and texts' cost taken off, and your share. `signup_url` is the link to hand a business: signing up through it makes the business yours. So does installing your app in its first thirty days. `review` is `pending` until a person at SignSealer has approved your account: businesses are recorded as yours meanwhile, and `earning` turns true, with your share counted from `earning_since`, once it is approved.

Returns

```
{
  "partner": "DeckPOS",
  "client_id": "ss_client_0123456789abcdef0123456789abcdef",
  "referral_code": "deckpos",
  "share_percent": 20,
  "active": true,
  "custom_branding": true,
  "review": "approved",
  "earning": true,
  "earning_since": "2026-09-02T15:04:05Z",
  "businesses": 12,
  "month_to_date": {
    "month": "2026-09-01",
    "businesses": 9,
    "gross_cents": 43100,
    "fees_cents": 1250,
    "sms_cost_cents": 600,
    "revenue_cents": 41250,
    "share_bp": 2000,
    "share_cents": 8250
  },
  "signup_url": "https://app.signsealer.com/signup?partner=deckpos"
}
```

### GET /v1/partner/businesses

Your app's `client_id` and `client_secret` as HTTP Basic

**The businesses you brought**

Newest first, with how each came to you (`referral_link`, `oauth_install`, `promotion` or `ops`), when, and what its paid use has added this month. `month_to_date_cents` is what it used of what it paid for, after card fees and the carrier's cost of its texts: credit SignSealer gave away earns nothing.

Query

| Parameter | Type |  | What it is |
| --- | --- | --- | --- |
| limit | integer (1–200) | optional | At most this many; 50 when left out. |
| offset | integer (0–∞) | optional | Skip this many. |

Returns

```
{
  "data": [
    {
      "tenant_id": "7d9c1c1e-7a57-4f55-9a86-0f7f3f9c2b11",
      "name": "Harbour Rentals",
      "status": "active",
      "source": "referral_link",
      "attributed_at": "2026-08-02T15:04:05Z",
      "month_to_date_cents": 1840
    }
  ],
  "has_more": false
}
```

### GET /v1/partner/statements

Your app's `client_id` and `client_secret` as HTTP Basic

**Every closed month**

Newest first. A month is closed on the 1st of the next and never changes after: the businesses and what each added, the share at the rate then in force, the card fees and the carrier's cost of texts taken off before the share, anything carried in, and what is owed. A month that comes to less than nothing is carried into the next rather than invoiced. `paid` turns true when SignSealer records the payment.

Returns

```
{
  "data": [
    {
      "month": "2026-08",
      "businesses": 8,
      "gross_cents": 39900,
      "fees_cents": 1250,
      "sms_cost_cents": 650,
      "revenue_cents": 38000,
      "share_percent": 19,
      "share_cents": 7220,
      "carried_in_cents": 0,
      "payable_cents": 7220,
      "carried_out_cents": 0,
      "paid": true,
      "paid_at": "2026-09-03T10:00:00Z",
      "lines": [
        {
          "tenant_id": "7d9c1c1e-7a57-4f55-9a86-0f7f3f9c2b11",
          "name": "Harbour Rentals",
          "gross_cents": 5400,
          "fees_cents": 160,
          "sms_cost_cents": 40,
          "revenue_cents": 5200
        }
      ]
    }
  ]
}
```

---

Source: https://signsealer.com/docs/webhooks (Webhooks)

# Webhooks

Every event in the trail, delivered to an HTTPS endpoint you control, signed with a secret you were handed once.

Watch it done: [Webhooks that you can debug](https://signsealer.com/guides/webhooks-you-can-debug) (1:44)

## Events

| Event | When |
| --- | --- |
| signing.created | A document was prepared. |
| signing.sent | It went out, with one link per signer. |
| signing.delivered | The message carrying a signer's link reached them, and detail.channel says how. email: our email service was told by the server that receives their mail that it took the message. sms, only when the business turns it on (below): the phone network said the text reached the phone. Neither means anybody read it — signing.viewed says that. Once per signer per channel, for the first such message (the invitation, a reminder or a party's link), and only while the document waits for them. |
| signing.viewed | A signer opened it. The first view only — a trail that grows on every refresh buries the events that matter. |
| signing.verified | A signer confirmed the one-time code sent to the address or number their link went to. detail says the channel (email or sms) and where it went, masked. |
| signing.location_shared | A signer shared where they were, when the business asks for it. detail carries lat, lon and accuracy_m. Sent only to an endpoint that names it, never to "*". |
| signing.location_declined | A signer was asked where they were and said no, or their device could not tell. No position. |
| signing.id_captured | A photo of the signer's ID, or of the signer, was kept. detail says which (id or selfie) and carries its SHA-256, never the image. |
| signing.photo_supplied | A photograph answered a question. detail names the field, and the person a per-child field is about, and carries the photo's SHA-256, never the image. |
| signing.link_shown | A fresh link was shown rather than sent: at the gate, put in a frame, or handed over by a party's booker. |
| signing.consented | A signer agreed to do business electronically. Always before the signature. |
| signing.signed | A signer signed. |
| signing.completed | Everyone who had to sign has. This is the one most integrations want. |
| signing.declined | A signer said no, with a reason. |
| signing.voided | Withdrawn, with a reason. |
| signing.expired | The link ran out. |
| signing.reminded | A reminder went out, with a fresh link. |
| packet.ready | Every required document about one subject is complete. |
| packet.blocked | Something in a packet was declined. |
| billing.quota_approaching | Four fifths of the month's included agreements are used, on a plan that stops at the line. Once a period. |
| billing.quota_exhausted | They are all used, and sends are refused with a 402 until the plan changes or the period turns. Once a period. |
| texting.number_updated | The business's application for its own texting number moved a step: sent to the carriers, a change asked for, verified, paused, released. One event per step, so keep the last one; GET /v1/account says the same under texting.application. |
| signing.ping | A test delivery you asked for. |

Subscribe to `"*"` for all of them but one, or name the ones you want. An event that is not on this list is refused when you add the endpoint or change its events (`PATCH /v1/webhooks/{id}`), with `422` and a hint that lists every one, rather than silently never arriving. A change that sends no `events` is not asked about the ones already stored; a name stored before changes were checked (3 October) is listed in the endpoint's `unknown_events`, and marked on its page in the dashboard. A business has at most twenty endpoints.

**A texted link reaching the phone.** `signing.delivered` is sent for the email that carried a signer's link. A business may also have it sent when the link went by text and the phone network says the text reached the phone: *Tell my webhooks when a texted link reaches the phone*, under Integrations, Webhooks in the dashboard, which only an owner or an admin of the business can turn on, and which is off until they do. Then the event says `detail.channel` `sms`, once per signer, beside the email's `email`: two facts, two deliveries. A carrier's "delivered" means the phone network accepted the text for the handset, not that anybody read it. Every change to the setting is on the business's audit trail. It is not in the API.

**A signer's position goes only where it is named.** `signing.location_shared` carries the latitude and longitude a signer shared, and a webhook goes to whatever address was typed into a form, so it is sent only to an endpoint that lists `signing.location_shared` by name; `"*"` is not sent it, and no event reaches `"*"` with a position in its `detail`. An endpoint on `"*"` since before 3 October was sent it until then, and a replay of one of those is refused. The network region on a signature (`detail.client.geo`, a country, region and city read from an address) is not a position and is not held back.

## The payload

Enough to act on without a second call — and never the token. A webhook body lands in somebody's logs.

`tenant_id` is the business the event belongs to. It is there so one endpoint can serve many businesses and route on the body alone: the document id cannot do that job, because looking it up needs you to already know which business to look in.

```
{
  "event": "signing.completed",
  "tenant_id": "8f14e45f-ceea-467a-9f6b-1c2d3e4f5a6b",
  "occurred_at": "2026-10-03T14:22:09Z",
  "document": {
    "id": "…", "title": "Rental agreement — Dana Reyes", "status": "completed",
    "workflow_id": null, "template_id": "…",
    "body_sha256": "…", "completed_at": "2026-10-03T14:22:09Z", "expires_at": null,
    "metadata": { "external_ref": "RES-88213", "custom": { "unit": "River Bend" } }
  },
  "signer": {
    "id": "…", "email": "dana@example.signsealer.com", "phone": null, "full_name": "Dana Reyes",
    "role": "signer", "sign_order": 1, "status": "signed",
    "signed_at": "2026-10-03T14:22:09Z", "declined_at": null, "decline_reason": null
  },
  "signature_method": "typed",
  "detail": null
}
```

### Every event, by its shape

| Events | Carries |
| --- | --- |
| signing.* | `document` as above, and `signer` when the event is one person's (null for `sent`, `completed`, `voided`, `expired`). `signature_method` on `signed`; `detail` is what the trail recorded beside the event, when anything. `document.metadata` carries your `external_ref` and, under `custom`, the `metadata` you gave when you made it. |
| packet.ready · packet.blocked | `packet`: `id`, `code`, `required`, `completed`; `subject`: `id`, `kind`, `provider`, `external_id`, `label`, `starts_on`. |
| billing.quota_approaching · billing.quota_exhausted | `allowance`: `included`, `used`, `remaining`, `state`, `reason`, `balance_cents`, `prepaid`. |
| texting.number_updated | `number`: `status`, `kind` (`toll_free`, `local` or `sole_proprietor`), `phone` once it is the business's (verified or paused; null before), `area_code`, `reason` when the carriers asked for a change or it is held up (null otherwise), and `brought`, true for a number the business already had. |
| signing.ping | A test sent with *Send a test* on the endpoint's page in the portal (sixty an hour per endpoint; there is no API route for it yet): nothing to act on, and proof the endpoint and its secret work. |

Every body has `event`, `tenant_id` and `occurred_at`. Fields are added over time and never removed or renamed inside `v1`, so ignore a key you do not know rather than refusing the body ([Changelog and versioning](https://signsealer.com/docs/changelog)).

We keep each delivery's body, for the deliveries list and for a replay, and not for ever. Once the document is redacted, or the business's message retention has passed (thirty days; see [Retention and redaction](https://signsealer.com/docs/retention)) for a delivery that is finished, the people are taken out of it: the title reads `Redacted document`, the signer's name, address, number and reason for declining go, and so does `external_ref`. What happened, to which document, and when, stays.

## What counts as delivered

- **A `2xx` within ten seconds.** Anything else is a failure and goes on the retry ladder below: another status, a timeout, a refused connection.
- **A redirect is a failure, not a hop.** We deliver to the address you registered and nowhere it forwards to — a redirect is how a delivery would be walked to an address nobody checked.
- **HTTPS only, and never to a private address.** The endpoint must resolve to a public address at the moment we call it.
- **Answer first, work after.** Record the event and answer `200`; do the slow part afterwards. A receiver that does the work inside the ten seconds is one that times out on a busy day and is sent the event again.

## Retries

A delivery is tried six times by default: the first, then again 1 minute, 5, 30, 2 hours and 12 hours after each failure (daily after that, for a business that allows more tries). After the last the delivery is `dead` and stays readable, so you can see what was missed rather than guessing. A try our own worker stopped in the middle of counts as one of the six, so a delivery that keeps stopping the worker ends dead, with a sentence saying why, rather than being tried for ever.

Twenty consecutive failures across deliveries pause the endpoint. Pausing stops us calling it; it does not throw your events away. They keep being written down and wait — up to ten thousand of them — and turning the endpoint back on forgives the failure count and sends what is waiting. The answer to that call tells you how many were released.

Past ten thousand held deliveries we stop keeping them, and count what we did not keep. That number is on the endpoint's page in the portal and in `held_dropped` on the endpoint, and it does not reset: it is the record of what the outage cost, so you know a gap exists rather than finding out later. The documents themselves are unaffected and readable through the API — it is the notifications about them that were missed.

About ten thousand, rather than exactly: two events arriving at once can each find room, so the queue can pass the mark by a few. It is a safety valve on a queue nobody is draining, not a number to count on. While an endpoint is at that mark, sending a test or replaying a delivery answers `422` and says why, instead of reporting a delivery that was not made — resume the endpoint and both work again.

> **Deliveries are at-least-once.** A network can drop our side of a successful call, so make your handler idempotent — the event carries enough to recognize a repeat.

## Verifying a delivery

Three headers come with every delivery.

| Header | What |
| --- | --- |
| SignSealer-Event-Id | The delivery's id. The same on every retry, so it is what you deduplicate on. |
| SignSealer-Timestamp | Unix seconds when it was signed. Refuse anything more than five minutes from your clock, either way. |
| SignSealer-Signature | `v1=<hex>`: HMAC-SHA256 of `timestamp.body` with your secret. During a rotation it carries two, comma-separated; either verifies. |

The bytes that are signed are the exact bytes that are sent, so verify the raw body *before* parsing it. Parsing and re-serialising checks your own formatter rather than ours, and two JSON serialisers disagree about key order and unicode escapes eventually — the day they do, every delivery fails at once.

The SDK does this for you, and it is the recommended way:

```
import { verifyWebhookRequest } from "@signsealer/sdk";

app.post("/hooks/signsealer",
  express.raw({ type: "application/json" }),        // the bytes, not the object
  async (req, res) => {
    const { ok, reason, eventId } = await verifyWebhookRequest({
      secret: process.env.SIGNSEALER_WEBHOOK_SECRET,
      body: req.body.toString("utf8"),
      headers: req.headers,
    });
    if (!ok) return res.status(400).send(reason);
    if (await alreadyHandled(eventId)) return res.sendStatus(200);  // at-least-once
    // ... act on it, then record eventId
    res.sendStatus(200);
  });
```

**The event id is stable across retries** — a delivery attempted six times carries the same id all six — which is what makes it the thing to deduplicate on.

What it is not is authenticated. The signature covers the timestamp and the body; the id travels beside them in a header, outside the signature. So somebody holding one valid delivery can send those same signed bytes again inside the tolerance window with a different id on them, and a receiver keyed on the id will treat the replay as new. We say so rather than implying otherwise: if a replay inside a five-minute window would be harmful to your system, check the event's own contents against your records before acting. Bringing the id inside the signature is a change we will make under a `v2=` scheme.

Or deduplicate on a SHA-256 of the raw body, which is what our WordPress plugin does. That is covered by the signature, and it is the same on every retry, because a delivery's body is built once and sent unchanged each time. The one thing it cannot tell apart is a replay somebody asked for (below), which sends the same body again under a new event id — so a receiver keyed on the body treats that as a repeat too.

It works in Node, in an edge runtime and in the browser, because it is built on WebCrypto rather than `node:crypto` — which is why it is `await`ed.

### If you are not using the SDK

Verify in constant time, and mind the three things that are easy to miss: the timestamp is *inside* the MAC, so check the window in *both* directions; a rotation sends two signatures and either must verify; and compare every part rather than stopping at the first that matches.

```
import { createHmac, timingSafeEqual } from "node:crypto";

function verify(secret, body, headers) {
  const sig = headers["signsealer-signature"];
  const ts = Number(headers["signsealer-timestamp"]);
  if (!sig || !Number.isFinite(ts)) return false;
  if (Math.abs(Date.now() / 1000 - ts) > 300) return false;        // both directions

  const expected = Buffer.from(
    createHmac("sha256", secret).update(ts + "." + body).digest("hex"), "hex");

  let matched = false;
  for (const part of sig.split(",")) {
    const given = /^v1=([0-9a-f]{64})$/.exec(part.trim())?.[1];
    if (given === undefined) return false;                         // no junk in the header
    const b = Buffer.from(given, "hex");
    // Every part, not the first that matches: the time taken then says
    // nothing about which one was right.
    if (b.length === expected.length && timingSafeEqual(expected, b)) matched = true;
  }
  return matched;
}
```

## Rotating the secret

`POST /v1/webhooks/{id}/rotate`, or the button on the endpoint's page, returns a new secret once. For the next 24 hours every delivery is signed with both secrets — the header carries two `v1=` values, the new one first — so you can switch your receiver at your own pace without dropping a delivery. Then the old secret is forgotten. Both checks above handle the pair, and it is the part a hand-written one usually gets wrong: a receiver that only looks at the first signature works perfectly until the first rotation and then refuses every delivery.

## Sending a delivery again

`GET /v1/webhooks/{id}/deliveries` lists the last fifty. A delivery that was delivered, failed or died can be queued again with `POST /v1/webhooks/deliveries/{id}/replay`, or "Send again" beside it in the portal: a new delivery with the same event and the same body, with `replay_of` naming the original. It gets a new event id, on purpose — a receiver that already acted on the original can tell this repeat was asked for by a person. One replay of a delivery may be in the queue at a time, and a replay waits like any other if the endpoint is off or paused.

---

Source: https://signsealer.com/docs/errors (Errors)

# Errors

One shape, always.

```
{
  "error": {
    "code": "invalid",
    "message": "no value for guest_name",
    "hint": "A contract that ships with a placeholder still in it is worse than one that failed to send."
  }
}
```

The `message` is frequently the database's own sentence, passed through rather than replaced. It is more specific than anything this layer could write, and the layer that knows why something was refused is the layer that refused it.

| Status | Code | Means |
| --- | --- | --- |
| 400 | bad_request | The request could not be read at all. |
| 401 | unauthorized | No key, or a key that is not live. Unknown, revoked and expired all answer the same way — a caller who could tell them apart could enumerate. |
| 403 | forbidden | The key is live and its scopes do not carry this. |
| 403 | terms_not_accepted | The business was asked to agree to SignSealer's updated terms and thirty days have passed without it, so nothing new can be sent until an owner or admin agrees to them in the dashboard. Documents already sent can still be signed and everything can still be read. Retrying will not help until then. |
| 404 | not_found | No such thing, in this account. A thing in another account answers the same way, and deliberately: confirming it exists would be the leak. |
| 405 | method_not_allowed | That path exists under another method. Said separately from 404 because it saves an hour. |
| 402 | quota_exceeded | The account's credit is used up and could not be reloaded, or it reached the spending limit it set itself. Nothing is wrong with the request. |
| 409 | conflict | An idempotency key reused for a different body, or the first attempt still running; or the thing named has moved on, such as a template revised from a version that is no longer the newest. The message says which, and the hint names the current one. |
| 409 | template_changed | A start named the template version it showed (expected_template_version), and a newer one has been published since. Nothing was made: show the person the current wording. |
| 409 | paragraphs_changed | A signature named the conditional paragraphs its page drew (paragraphs), and the first signer's answers now call for different ones. Nothing was signed: fetch the link again and show the paragraphs it has now. |
| 413 | too_large | Larger than a signing request ever is. |
| 422 | invalid | The body did not validate, or the engine refused it. The message is the engine's own sentence. |
| 429 | rate_limited | Too many attempts, or a business past the signing links its standing allows in an hour or a day (Limits and paging). The message names the budget, the hint says when, and the Retry-After header says how many seconds. |
| 429 | busy | A photo on a signing link was not read because others are being read just now. Nothing was kept: send the same photo again after the Retry-After header's seconds. |
| 429 | allowance_reached | A tablet's start made with no network, synced when the business cannot take another signing (its free signings for the month used, a balance that does not cover the next, its own spending limit, or a stopped subscription). Nothing was made: keep it and send it again; the Retry-After header says when. Any other start is answered 402 quota_exceeded. |
| 500 | internal | Ours. Quote the x-request-id. |

## Retrying

Retry `429` and `500`, with backoff. Do not retry `422` — the request will be refused the same way every time, and the message says why. Retrying anything that creates something means sending an [idempotency key](https://signsealer.com/docs/idempotency); our own SDK mints one for you.

## 402 is not 429

A `402` means the account needs money or the membership, not a pause: Free's 10 signings are used, the prepaid credit has run out, or the business's own spending limit is reached. It is the one refusal that a retry cannot fix: credit has to be added (automatic reload usually does it first), the membership started, or the month has to turn. Treat it as you would a declined card — surface it to the person who can act on it, and stop. The response carries the same shape as any other error, and the `hint` names the way out.

One start is answered otherwise: a counter tablet's, made with no network and sent when it synced. The person has already signed at the counter, so the answer is `429 allowance_reached`, for the tablet to keep it and send it again. Nothing is made until the business can take another signing, and then it counts like any other.

Every successful send carries `x-agreements-remaining` when the account has a fixed number of signings left to count down: how many more documents it can send before it needs credit. A document out for signature holds its place, so the number goes down with the send that sent it, and comes back if that document is voided, declined or expires unsigned; one that is never signed costs nothing. It is on the send's answer because that is the call an integration already makes. It is absent when there is nothing to count down. Watch it and you will never meet a `402` unprepared — or subscribe to `billing.quota_approaching` and do not watch at all.

A `429` carries `Retry-After`, in seconds. Wait that long rather than backing off by a guess: the rate-limit window is a minute, so three quick retries all land inside the same window, fail identically, and spend the next window's budget as well. The Node client honors the header — it sleeps through a short wait and hands a long one back to you as `error.retryAfter` rather than blocking your call for a minute.

---

Source: https://signsealer.com/docs/limits (Limits and paging)

# Limits and paging

What the API will take, and how to walk a long list.

## Rate limits

Each key may make **300 requests a minute**. Every answer to a request made with a key says where it stands:

| Header | Means |
| --- | --- |
| X-RateLimit-Limit | Requests this key may make in the window. |
| X-RateLimit-Remaining | How many are left in it. |
| X-RateLimit-Reset | When the window turns over, in seconds since the epoch. |

Past the limit the answer is `429 rate_limited` with `Retry-After` in seconds. Wait that long rather than guessing: three quick retries land in the same window, fail the same way, and spend the next window's budget as well. Some actions have smaller budgets of their own, named in the refusal: a fresh signing link is ten a minute per document, and three hundred one-time codes by text an hour across a business's signers. The routes a signing link opens have theirs [below](#signing-links).

A signer's own one-time code is paced rather than budgeted, and refused with `422 invalid`, not `429`: one a minute and five an hour for each signer, and none after fifteen wrong guesses in a day; six an hour and twenty a day to one email address or number, whichever signer and business asks; and none to an address after fifteen wrong guesses in a day at one form's documents, however many were started. The answer to asking for one says when the next may be asked for, as `resend_after` ([Your own signing page](https://signsealer.com/docs/signing-page)).

### Reminders

A reminder is refused with `422`, naming why and leaving the signer's link as it was, inside an hour of the last one to that signer, past three to one signer in a day, or past twenty-five for one document in a day. The dashboard's Remind button, the API and the automatic reminders all count.

**One by text.** A signer is texted at most one reminder over the life of their link, because that is what the words they agreed to before we texted them say. The dashboard's, the API's, the automatic one and a party's link sent again by the person who booked all count toward it. After that one, a reminder goes by email alone, and `by` in the answer says `email`; for a signer with no email address we may use, it is refused with `422`, saying they have had the one reminder by text they agreed to, and their link is left as it was.

### Photos on a signing link

Photos are read one at a time, with a few waiting, and one business holds at most two of the places to wait. A photo that arrives while the places are full, or while another photo from the same link is still being read, is refused with `429 busy` and `Retry-After` (thirty seconds): nothing was kept, so send the same photo again after that long.

### How many people a business sends to

The people a business sends signing links to are counted across every send, workflow, form and party, by email and text alike (an address and a number for one signer are two; reminders are not counted), against a ceiling an hour and a day that grows with how far the business is trusted so far:

| Standing | When | An hour | A day |
| --- | --- | --- | --- |
| New | Where everybody starts. | 3 | 10 |
| Normal | A day old, its owner's address verified, three documents signed, and its mail arriving without bounces or complaints. | 20 | 60 |
| Paying | The membership with a payment that went through (or billed through a partner), and clean mail. | 200 | 1,000 |
| Established | Paying, clean mail, and thirty days old. | 1,000 | 10,000 |

A send that would cross the line is refused whole with `429
rate_limited` and `Retry-After`, so nobody on it was sent anything. Reports from people who did not expect the mail, bounces and complaints can hold a business below the standing the table gives it for a while, and we can set one by hand; ask us from Help if your business needs more. A test key's sandbox sends nothing and counts nothing.

While a business is New or Normal, Send and Bulk send in the dashboard say how many more people it can send to and when the hour and the day turn over, in the business's timezone; the day turns at midnight UTC. A list longer than that is said before it goes: each row is its own send, so the rows that fit go and the rest are refused and listed with their line numbers.

### Screening

Every message a business sends to somebody outside it — the link, a reminder, a party's link, the completed copy, a code — is read before it leaves. Most go at once. Some are held for a person to look at, usually for a few hours, and a few are not sent, with the reason on the document's page in the dashboard. The API's answer does not change either way: a send's `200` says the links were made and the messages queued, not that they arrived, and nothing in the API says a message is held yet.

### Keys and endpoints

A business holds ten live API keys until it is paying, and fifty from then; past that, issuing one is refused until one is revoked. A tablet's credential, a partner's access token and a connected booking system's key are not counted. It has at most twenty webhook endpoints.

## Paging

`GET /v1/documents` pages with `limit` (1 to 200, 50 when absent) and `offset`, newest first, and answers beside the page:

```
{ "documents": [ … ], "total": 312, "has_more": true, "limit": 50, "offset": 0 }
```

Ask for the next page with `offset` plus `limit` until `has_more` is false. A document made while you walk appears at the front and moves everything after it along by one, so an integration that must see every document once should also find them by what it knows: its own reference (`?external_ref=`), or the webhook that told it about them.

The other lists are short enough to answer whole: templates (every version), workflows, webhook endpoints, tablets. An endpoint's deliveries are its last fifty.

## Sizes

- A request body is at most a megabyte; larger is `413 too_large`.
- A document has at most fifty signers; a template at most fifty questions.
- `external_ref` is up to 200 characters; `metadata` up to twenty names of up to 40 characters, each with text of up to 500.
- An idempotency key is 8 to 255 characters and is remembered for 24 hours.

## Limits on signing links and public forms

The routes that take no key — a signing link, a certificate check, a public form, a party link — have budgets of their own. Most are counted against the thing being used rather than against whoever is using it. A signing link's budget is the link's: the signer's browser and your own server share it, and asking from another address does not start a fresh one.

| Limit | What it counts | How many |
| --- | --- | --- |
| `signing.token_lookup` | Reading a signing link (`GET /v1/sign/{token}`, or the signing page) and each step taken on it: consent, a one-time code asked for or confirmed, a photo, where the signer is, the signature, a refusal to sign. | 20 a minute for each link |
| `signing.supply_field` | Answering a question on a signing link (`POST /v1/sign/{token}/fields`). | 600 an hour for each link |
| `signing.certificate_lookup` | Checking a certificate (`GET /v1/verify/{code}`, or the verify page). | 30 a minute for each code |
| `signing.workflow_start` | Starting a document from a public form (`/f/{business}/{form}`). | 10 a minute for each caller's IP address, at each business |
| `public_form.mail_to` | A start on a public form, or a place taken on a party link, that carries an email address; a party member's link sent by email. | 5 an hour for each inbox, across every business |
| `public_form.mails` | The same. | 1,000 an hour for each business |
| `public_form.text_to` | A start on a public form that asks for the link by text, or a place taken on a party link with texts ticked; a party member's link sent by text. | 3 an hour for each mobile number, across every business |
| `public_form.text_to_day` | The same as `public_form.text_to`. | 5 a day for each mobile number, across every business |
| `public_form.texts` | The same. | 60 an hour for each business |
| `signing.add_party` | The person who booked adding the others in their party, from their own signing link. | 6 an hour for each link |
| `signing.party_link` | The person who booked making the party link, or one person's link, again. Each one made retires the one before it. | 30 an hour for each link |
| `signing.party_open` | Opening a party link (`/p/{link}`). | 240 an hour for each party link |
| `signing.party_claim` | Taking a place from a party link. | 60 an hour for each party link |
| `signing.party_link_to` | A party member's link sent to them, the first time and each time again. | 3 a day for each email address or mobile number, across every business |
| `outbound.report` | Reporting a message nobody expected, from the foot of a signing email or a signing page. | 5 an hour for each link |
| `outbound.report_from` | The same. | 30 an hour for each caller's IP address |

A mobile number typed on a public form or a party link with texts ticked is confirmed before anything else is texted to it: it is sent a six-digit code, and only when the code is typed back on the page is the consent recorded and, on a form, the link texted. A code works for ten minutes and five tries. To one number, across every business, we text a code a minute, five an hour and ten a day, and none after fifteen wrong tries in a day.

A code a signer types on their own signing page, by email or by text, is limited for the link (one a minute, five an hour, none after fifteen wrong tries in a day) and for the address it goes to, across every link and every business: six an hour and twenty a day, and none after fifteen wrong tries in a day at one form's documents. They are refused in words on the page rather than counted here.

An inbox is counted however it is typed: case, a `+tag` and Gmail's dots make no difference. Windows are fixed rather than rolling: a minute starts on the minute, an hour on the hour, and a day at midnight UTC.

Over a limit, the API's keyless routes (`/v1/sign/{token}` and the routes under it, and `/v1/verify/{code}`) answer `429
rate_limited`. The message names the limit and its budget (`rate limit reached for signing.token_lookup: 20 per 60 seconds`), the hint says when to try again, and `Retry-After` says the same in seconds. There are no `X-RateLimit-*` headers on these routes: those describe a key's budget, and there is no key. The public form and the party page are pages, not API routes: a start or a place refused there is drawn again with the reason in words, and nothing is made.

---

Source: https://signsealer.com/docs/changelog (Changelog and versioning)

# Changelog and versioning

What `v1` promises, and what has changed inside it.

## What v1 promises

- **Nothing is removed or renamed inside `v1`.** A route, a field in an answer, a value of a field that is an enumeration, an error code: once published, it stays.
- **Things are added.** New routes, new optional request fields, new fields in answers and webhook bodies, new values of a field that is an enumeration (a status, an event type, an error code), new webhook events (sent only to endpoints that subscribe to them or to `*`). Write your client to ignore what it does not know, and to treat a value it has not seen as something it does not handle rather than as an error.
- **A refusal may become more specific** — a `422` whose message names more precisely what was wrong — but not a success into a refusal, except under the security exception below.
- **A change that would break a client gets a new version**, and `v1` keeps working beside it for at least twelve months after the new one is published, with the date announced here and to every account's owner by email.
- **The one exception is security.** If keeping something working would leave a business's data or its signers exposed, we close it without a new version. The change is kept as narrow as we can make it and announced here, marked *security*; where possible whatever already worked is left working, and where something an account relied on does stop, its owner is told by email first.

Outages and incidents are on the [status page](https://status.signsealer.com), with ninety days of history. The Node client keeps its own changelog, in the package.

## Changes

### 22 October 2026

- **A document each for a party.** `party_documents` on `GET /v1/workflows`: `one`, the document the whole party signs, as before; or `each`, a document for every adult the person who booked adds, made from the first, with their own name in it. Each completes on its own and each is a signing. The links that come back from `POST /v1/sign/{token}/party`, the party link and `party` on a signing link work across them all. [Signers, roles and order](https://signsealer.com/docs/signers).
- **`persons` under `fields`** starts a party as it does under `values`, so a start that fills in `asked_fields` can add it beside them.

### 15 October 2026

- **The business signs its own line.** A signer sent with `for_business: true` on `POST /v1/documents/{id}/send` (or by an assistant, with `signsealer_send_document`), or a workflow's fixed role with `business: true`, signs for the business. The template's questions with `supplied_by: "business"` are theirs and nobody else's, and they are asked nobody else's. On an uploaded PDF, the business's own signature line, its date and its name are found at upload and made such questions, so each box on the page has one person's answer. Each link answers `for_business`. [Signers, roles and order](https://signsealer.com/docs/signers).
- **An uploaded PDF’s boxes are placed for it.** A PDF uploaded in the dashboard has its signature and date put where the file asks for them, and every other line, box to tick, box to write in and fillable field added as a question on its own box, named by the words beside it, for the business to check before it publishes. Text in square brackets is never a box: every piece is highlighted on its page and listed, to replace before the file is sent or, where it is meant to be there, to keep as part of the document. `GET /v1/templates/{id}` shows them as any placed question, with a `place`. [Signing a PDF where it is](https://signsealer.com/docs/pdf).
- **The party over the API.** The person who booked adds the others in their party with `POST /v1/sign/{token}/party`, as the signing page lets them: each person with an address is sent their own link, anybody we could not send it to comes back with theirs for you to hand over, and `party_link` is where a place kept open is taken from. `POST /v1/sign/{token}/party/share` makes the party link again and `POST /v1/sign/{token}/party/link` one person’s link. [Your own signing page](https://signsealer.com/docs/signing-page).
- **A link goes when it is its signer’s turn.** On a document prepared with `sequential: true`, or a workflow signed in order, only the first step is sent its links. A later step’s signer is held, and is sent a new link of their own when everybody before them has signed. `POST /v1/documents/{id}/send` and `POST /v1/workflows/{id}/start` answer `token: null` and `url: null` with `held: true` for a held signer, where they answered a link that the signer could open only to be told to wait; and `POST /v1/documents/{id}/signers/{signer}/remind` refuses one with `422` until their turn. An `embedded` signer is not held, nor is anybody when the business sends its own links. [Signers, roles and order](https://signsealer.com/docs/signers).

### 7 October 2026

- **The reference shows more.** Each route's query parameters, the fields inside a list (`signers[].email`, `participants[].full_name`), and the OAuth and partner endpoints, drawn from the same declarations as `/openapi.json`. Nothing about the API changed. [API reference](https://signsealer.com/docs/api).
- **New guides:** [Signers, roles and order](https://signsealer.com/docs/signers), [Your own signing page](https://signsealer.com/docs/signing-page), [Teams, roles and sign-in](https://signsealer.com/docs/teams), [Retention and redaction](https://signsealer.com/docs/retention), [Branding and domains](https://signsealer.com/docs/branding) and the [WordPress plugin](https://signsealer.com/docs/wordpress); and sections on [questions and fields](https://signsealer.com/docs/templates#fields), [the partner API](https://signsealer.com/docs/partners#partner-api), [which version of the Node client added what](https://signsealer.com/docs/sdk#versions), [limits on signing links](https://signsealer.com/docs/limits#signing-links), [getting the tablet app](https://signsealer.com/docs/kiosk#get-the-app) and [what is done in the dashboard](https://signsealer.com/docs#dashboard).
- **A copied recipient is sent the signed copy.** A signer with `role: "cc"` and an email address is emailed the sealed PDF when everybody else has signed, as the send screen always said and as nobody was. They are still sent no link, no reminder and no text, and asked nothing. [Signers, roles and order](https://signsealer.com/docs/signers).
- **The Node client on Node 18.** Before `@signsealer/sdk` 1.11.1, every write not given its own idempotency key threw on Node 18 unless it was started with `--experimental-global-webcrypto`. [Node client](https://signsealer.com/docs/sdk#versions).
- **A redacted document names nobody, and reads as intact on the list.** `GET /v1/documents` answered `integrity_ok: false` for every redacted document with a signature, where `GET /v1/documents/{id}` answered `true`; both now check its signatures against the fingerprint it kept. A redaction now also takes out the name of each child an answer was about (`answers[].about` reads *Redacted child 1* and so on, and so does a parent or guardian's statement), the dates of birth a party gave, and the document's link to the person on file it was about (`subject_party_id` and `subject_name` read null), on documents redacted before today too. And a redacted document's certificate now verifies (`still_matches_record: true`) in two cases where it could say the record had changed: when signers shared a place in the order, as a party's do, and when a question had been shown or hidden by an earlier answer. [Retention and redaction](https://signsealer.com/docs/retention).
- **Corrections.** These pages said otherwise, and the API has always done this: under a location `require`, a signer who declines is recorded and the signature is still refused; a signer's one-time code is paced with `422 invalid`, not `429`; the four parts of `signing:write` are held by a connected app's tokens, and a dashboard key takes `signing:write` whole; a workflow role with `"self": true` cannot be set through the API; a staff field can be placed on a PDF's page, filled by the sender.

### 6 October 2026

- **An MCP server.** `POST https://api.signsealer.com/mcp` is a remote Model Context Protocol server that Claude, ChatGPT, Codex and the coding editors connect to with OAuth: ten tools, each the same check and the same work as the `/v1` route that does the same thing. It answers protocol version `2026-07-28`, which has no handshake, and `2025-11-25`, `2025-06-18`, `2025-03-26` and `2024-11-05`, opened with `initialize`. [AI assistants (MCP)](https://signsealer.com/docs/mcp).
- **An app can register itself.** `POST /oauth/register` takes an RFC 7591 registration naming `redirect_uris`, as an MCP client sends the first time it meets SignSealer; the server describes itself at `/.well-known/oauth-protected-resource/mcp` (RFC 9728) and `/.well-known/oauth-authorization-server` (RFC 8414). Such an app may be given reading and the four parts of sending below, no more, and is removed if nobody connects it within a day. [OAuth](https://signsealer.com/docs/api#oauth).
- **Four scopes inside `signing:write`.** `signing:send`, `signing:remind`, `signing:links` and `signing:void` each allow one part of what `signing:write` allows, so a person connecting an app can let it send without letting it void. `signing:write` still allows all four, and every route that takes one says so. [Authentication](https://signsealer.com/docs/authentication).
- **Connecting again with less ticked takes it away now** (security). Leaving a box clear when an app is connected again narrows the access tokens it already holds at that moment, where a token issued before kept its scopes until its hour ran out; a token left with nothing is revoked. Moving a connection to `signing:write`, which holds the four parts, takes nothing away. [Authentication](https://signsealer.com/docs/authentication).
- **Refresh tokens only for an app that asks.** An app that registers itself without naming `refresh_token` in `grant_types` is given no refresh token, where it was given a thirty-day one anyway. WordPress sites, partners and apps already registered keep what they had.
- **The docs as Markdown.** Every docs page is also served as Markdown at its own address with `.md` (`/docs/quickstart.md`), and all of them together at `/llms-full.txt`, for a coding assistant to read whole.

### 3 October 2026

- **A signer's position goes only where it is named** (security). `signing.location_shared`, which carries the latitude and longitude a signer shared, is sent only to an endpoint that names it; an endpoint on `"*"` is no longer sent it, and no event reaches `"*"` with a position in its `detail`. That is a delivery `"*"` used to receive and now does not, made under the security exception: a webhook goes to whatever address was typed, often somebody else's tool, and where a person stood is not something to send there unasked. Endpoints are unchanged and nothing is deleted; a position already waiting in such an endpoint's queue is not sent, and replaying one it was sent before is refused with `422`. Add `signing.location_shared` to an endpoint's events to keep receiving it. [Webhooks](https://signsealer.com/docs/webhooks).
- **Six more events can be named.** `signing.verified`, `signing.id_captured`, `signing.photo_supplied`, `signing.link_shown`, `signing.location_shared` and `signing.location_declined` are taken by `POST /v1/webhooks`, where they were refused; `"*"` was already sent all of them but the position. [Webhooks](https://signsealer.com/docs/webhooks).
- **`signing.delivered` is sent.** When the email carrying a signer's link reaches their mail server, with `detail.channel` `email`, and, for a business that turns it on, when the phone network says a texted link reached the phone, with `sms`: once per signer per channel, and only while the document waits for them. It was listed and never sent. Neither means the message was read; `signing.viewed` still says it was opened. [Webhooks](https://signsealer.com/docs/webhooks).
- **A change to an endpoint's events is checked.** `PATCH /v1/webhooks/{id}` refuses an `events` name that is not an event with `422`, as `POST /v1/webhooks` always has, and the hint lists every event. It once stored the name, which then never arrived, so this turns a success that did nothing into a refusal that says so. A change that sends no `events` goes through as before, and a name stored earlier is kept and listed in `unknown_events` on `GET /v1/webhooks`. [Webhooks](https://signsealer.com/docs/webhooks).
- **One reminder by text** (security). A signer is texted at most one reminder over the life of their link, because the words they agreed to say "at most one reminder"; the dashboard's, the API's, the automatic one and a party's link sent again all count. After it, `POST /v1/documents/{id}/signers/{signer}/remind` sends the reminder by email alone (`by: "email"`), and for a signer with no email address it is refused with `422`, where it once texted them again. [Limits and paging](https://signsealer.com/docs/limits).
- **A busy photo is a 429.** The two photo routes on a signing link answer `429 busy` with `Retry-After` when the photo was not read because others were being read, where they answered `422 invalid`. Nothing was kept; send the same photo again after that long. [Errors](https://signsealer.com/docs/errors).

### 2 October 2026

- **How many people a business sends to** (security). Signing links are counted against a ceiling an hour and a day that grows with how far the business is trusted, and a send, a workflow start or a public form past it is refused whole with `429 rate_limited` and `Retry-After`, where it once went through. A business's signers are sent at most three hundred codes by text an hour between them. [Limits and paging](https://signsealer.com/docs/limits).
- **Reminders** (security). `POST /v1/documents/{id}/signers/{signer}/remind` is refused with `422` past three reminders to one signer in a day, or twenty-five for one document, counting the dashboard's and the automatic ones.
- **Every message is screened before it leaves** (security). A message to somebody outside the business may be held for review or not sent; the API's answers are unchanged, and nothing in the API says so yet. [Limits and paging](https://signsealer.com/docs/limits).
- **A partner's connection is the person's who made it** (security). It ends when that person is removed, leaves, or can no longer give what it holds, and a refresh is refused with `invalid_grant` from then. [Authentication](https://signsealer.com/docs/authentication).
- **The signing day a tablet keeps** (security). `captured` on `POST /v1/sign/{token}` is kept only when a paired tablet of the link's business sends its own credential with it; from anybody else it is left out, and the signature is dated when it arrives. The certificate's network region is read only from requests that crossed our edge. [Node client](https://signsealer.com/docs/sdk).
- **An answer after the end** (security). `POST /v1/sign/{token}/fields` is refused once the document is voided, declined or expired or the link is past its date, as a signature is; six hundred answers an hour per link.
- **Photos are checked before they are read.** The two photo routes on a signing link refuse a link that would not keep a photo before decoding it, read one photo per link at a time, and answer `422` asking to send again when the photos waiting to be read are queueing.
- **A webhook's body is let go.** Once a document is redacted, or a finished delivery is older than the business's message retention, the people are taken out of its stored body, and a replay sends it that way. [Webhooks](https://signsealer.com/docs/webhooks).
- **Everyone in the party signs.** A workflow can have each person in a booking's party sign (`each_person_signs` on `GET /v1/workflows`); its start answers `party_size`, and the signing link carries `party`: who is still to be added, and who was. The person who booked adds them on the signing page. Each person with an address we may write to is sent their own link, a link the booker handed over is assured as `party_link`, and party links are made on the business's own signing host. [Evidence and certificates](https://signsealer.com/docs/evidence).

### 1 October 2026

- **The pages a signer reads are drawn from the file they sign.** SignSealer draws an uploaded PDF's pages itself; `drawn` on `GET /v1/templates/{id}/pdf` counts only those, and a signing link shows no other. [Signing a PDF where it is](https://signsealer.com/docs/pdf).
- **Times say which clock they are on.** `POST /v1/documents` takes `time_zone`; a time blank is written in words with the zone named, and the signing link says `time_zone`.

### 29 September 2026

- **Whether a business can text.** `GET /v1/account` says `texting`: `available`, `why_not` (`plan` when its plan has no texting, `number` while it waits for its own verified texting number, `beta` while the business is in the beta, which does not text, `test` for a sandbox) and `wording`, the opt-in sentence to put beside a "text me" box and record with `POST /v1/sms-consents` when it is ticked. [Texting and consent](https://signsealer.com/docs/texting).

### 28 September 2026

- **The signed copy is sealed once.** `GET /v1/documents/{id}/pdf` returns the copy sealed when the document completed, the same bytes on every call. `GET /v1/verify/{code}?sha256=` takes the SHA-256 of that file as well as of the document's text: `copy_matches` says it was the file, and `document_matches` is true for either. [Evidence and certificates](https://signsealer.com/docs/evidence).
- **A partner is reviewed before it earns.** `GET /v1/partner` says `review` (`pending`, `approved` or `declined`), `earning` and `earning_since`. [Platforms and partners](https://signsealer.com/docs/partners).
- **Reminders.** `POST /v1/documents/{id}/signers/{signer}/remind` is refused with `422` when nothing could be sent — an address we may not write to, and a number that cannot be texted a reminder — and the link the signer holds keeps working; `by` in its answer is the channel the reminder went by.

### 27 September 2026

- **A name is only a name** (security). `POST /v1/workflows/{id}/start` refuses a `full_name` with a web address in it with `422`, where it once accepted one: the name is printed in the signing email, and a web address there is a link somebody else chose.

### 26 September 2026

- **The signing date is the day it was signed.** `{{date}}` and its synonyms (`today`, `signed_on`, `date_signed` and the rest) are never supplied: a value sent for one on `POST /v1/documents` is ignored, and the first signature writes that day in, in the business's timezone. [Signing a PDF where it is](https://signsealer.com/docs/pdf).
- **The signing day is nobody's to choose** (security). `captured` on `POST /v1/workflows/{id}/start` is refused with `422` from anything but a paired tablet, where it was once accepted from any key and let the caller choose the day a document says it was signed. A tablet's date is kept only when it is within a day of the tablet's own clock and not after today. [Tablets and kiosks](https://signsealer.com/docs/kiosk).
- **Times and periods.** A question can be a `time` or a `datetime`; what is picked is written into the document in words, and a period whose end comes before its start is refused.
- **Boxes the sender fills in.** A question marked `staff` and placed on an uploaded PDF is given when the document is sent, under `values` on `POST /v1/documents`, or `fields` or `values` on a workflow start; a required one that is missing refuses the send. The signing link's fields say `from_sender`, and `placed_words` gives a placed date or time as it is printed on the sealed copy. [Signing a PDF where it is](https://signsealer.com/docs/pdf).

### 25 September 2026

- **Boxes signing fills.** A signature box or signing-date box placed on an uploaded PDF is filled by signing itself; the signing link's fields say `at_signing` and `placed_value`, and signing no longer refuses for those boxes. [Signing a PDF where it is](https://signsealer.com/docs/pdf).
- **The photographs in the signed copy.** The sealed PDF and the bundle print each photograph taken as an answer after the certificate, with its SHA-256. `settings.photos_in_copy` on a template, and on `PATCH /v1/templates/{id}/settings`, turns it off. [Evidence and certificates](https://signsealer.com/docs/evidence).

### 24 September 2026

- **Templates, all the way through.** `GET /v1/templates/{id}` (the version whole, with every version of its code), `PATCH /v1/templates/{id}` (change a draft), `POST /v1/templates/{id}/publish`, `POST /v1/templates/{id}/revise`, `DELETE /v1/templates/{id}` (a draft) and `PATCH /v1/templates/{id}/settings`. `GET /v1/templates` takes `code`. [Templates and versions](https://signsealer.com/docs/templates).
- **Signing inside your product.** A signer sent with `delivery: "embedded"` is sent nothing; `POST /v1/documents/{id}/signers/{signer}/embed` mints a link to frame; the signing page and public forms may be framed on the business's proven sites and post what happened to the page around them. `GET /v1/account` says `frame_origins`. [Signing inside your product](https://signsealer.com/docs/embedding).
- **Your own reference.** `POST /v1/documents` takes `external_ref`, `metadata` and `return_url`; webhooks carry them back; `GET /v1/documents?external_ref=` finds them; the list and the document say them.
- **Reminders.** `POST /v1/documents/{id}/signers/{signer}/remind`.
- **Paging.** `GET /v1/documents` answers `total`, `has_more`, `limit` and `offset`.
- **Rate-limit headers** on every keyed answer. [Limits and paging](https://signsealer.com/docs/limits).
- **The signing and verifying routes answer a browser on another site** (CORS), so a signing page of your own can call them directly.
- **The send's answer** carries each link's `url` and `delivery`.
- **The OpenAPI description** types each path parameter (a signing token is not a UUID), declares query parameters, says `201` where a route makes something, documents `409 template_changed` and the OAuth endpoints, and files every operation under a declared tag.
- **Test keys.** `mk_test_` keys act on the business's sandbox, where nothing is sent to anybody and nothing is billed; `GET /v1/account` says `mode`. [Testing](https://signsealer.com/docs/authentication).
- **A template's history.** `POST /v1/templates/{id}/restore` brings an older version back as a new draft; `change_note` on `PATCH` and `revise`, and on each of `versions` with its name, date, file and documents. [Templates and versions](https://signsealer.com/docs/templates).
- **Tablets** (security). A tablet paired from now on starts at `gate: "own"`: it shows a signing link only for a document it started itself, and asking it for one it did not start is refused with `403`, which it would once have answered. That is a success becoming a refusal, made under the security exception above: a tablet's key could otherwise open a signing link for any unsigned customer in the account, and the certificate would still have called it an emailed link. Tablets paired earlier were left at `account`, so nothing that worked stopped working, and an owner can set either under Apps & tablets or with `PATCH /v1/devices/{id}`, which takes `gate`; `GET /v1/devices` says it, and `GET /v1/documents/{id}/signers` answers `link_allowed`.
- **A WordPress site's own connection** (security). The OAuth client the plugin registers for its site no longer carries `signing:templates`, which the plugin never used; asking for it grants the rest, and the token's `scope` says what was granted. Connections already made keep what they were given. A client we registered for a partner is unchanged.

### Before

Earlier changes were recorded by the migration that made them rather than here; each is named in the [reference](https://signsealer.com/docs/api) beside what it added, and the Node client's changelog lists every one it exposed.

---

Source: https://signsealer.com/docs/kiosk (Tablet and kiosk signing)

# Tablet and kiosk signing

Kiosk mode is for controlled in-person signing at a front desk, rental counter, check-in area or service counter.

Watch it done: [A signing tablet on your counter](https://signsealer.com/guides/a-signing-tablet-on-your-counter) (4:49)

## Getting the app

The SignSealer app is one app for iPhone, iPad and Android phones and tablets. Until it is listed in the App Store and on Google Play, it is installed like this:

- **Android.** In the dashboard, [Apps & tablets](https://app.signsealer.com/devices) has a *Download for Android* button for anybody signed in to the business. Open the file on the tablet and allow installs from that source when Android asks. It needs Android 7 or later on an ARM processor, 32-bit or 64-bit; it does not install on an x86 emulator.
- **iPhone and iPad.** An iOS app cannot be installed outside the App Store. During our beta, a business taking part is offered Apple's TestFlight instead: once we have set the link, Apps & tablets shows *Join on TestFlight*. Open it on the device, install TestFlight if it asks, then install SignSealer from it. Without it, an iPad can still run a counter from the form's own page in Safari ([Waivers and workflows](https://signsealer.com/docs/waivers)).

The site's [App Store](https://signsealer.com/go/ios) and [Google Play](https://signsealer.com/go/android) links send you to each listing from the day it exists, and say so until then.

### Updates

A store install is updated by its store. A tablet running the download from Apps & tablets is told on its Home screen when a newer build is offered to your business, with a button back to that page. On Android the download and the Google Play build are signed with different keys, so a tablet moving from one to the other is uninstalled first, which loses its pairing and anything still waiting to send: let the queue empty before you switch.

We can also set the lowest version we support. A tablet below it shows the update card and nothing else, and its kiosk will not start, until it is updated.

### Pairing it

The app does nothing until it is paired. In [Apps & tablets](https://app.signsealer.com/devices), *Add a tablet*: name it and tick the forms it runs, and the page shows an eight-character code, good for fifteen minutes and for one use. Type it on the app's first screen. The tablet trades it for a credential of its own and never holds your API key. Then, on the tablet, set a staff PIN of four to eight digits under Settings: the kiosk will not start without one. A platform pairing tablets for the businesses it runs does the same with `POST /v1/devices`, under *Tablets from your own software* on this page.

The PIN guards the app's own screens; the tablet guards the rest. On a counter, lock the tablet to the app with Guided Access on an iPad or screen pinning on Android, and turn off the keyboard's predictive text and suggestions, so it does not offer one customer's name to the next.

## Operator model

- **Staff setup.** Connect the device, choose the workflow and set the staff PIN before entering kiosk mode.
- **Signer session.** The signer gets one focused form. The device resets between people, and an idle timeout clears abandoned work.
- **Offline capture.** The device holds the consent and the signature through a connection drop and sends them when service returns.
- **Or a QR.** If the customer would rather use their own phone, show a QR code at the same counter instead of handing the tablet over.

## Device acceptance test

- Enter and exit kiosk with the staff PIN.
- Verify lockout after repeated wrong PIN attempts.
- Leave a form idle and confirm it clears.
- Complete 10–20 signers consecutively and confirm no prior data remains.
- Drop connectivity during signing and verify synchronization behavior.
- Rotate the device and test supported orientations.

## Starting with no network

A connection that is down when the customer is already at the counter must not stop the signing. The SignSealer app keeps everything it needs to run its workflow on the device — the published form and its version, the consent and intent wording a signer is shown, the pages of an uploaded PDF — and refreshes it on every heartbeat. With no network on start-up it renders the form itself, takes consent and the signature, and queues the whole signing: the start first, then the consent and signature behind it, each tied to the one before.

When service returns the queue drains in order. The start names the version of the form the customer read (`expected_template_version`), the date the tablet showed, and the device’s own clock as a claim (`captured`); the server computes the skew rather than believing it and puts both on the audit trail. If the form was revised in the meantime the start is refused with `409 template_changed`, nothing is sealed against words nobody read, and the tablet tells staff which customer needs to sign again on the current form. Your own tablet software does the same with `GET /v1/workflows/{id}/bundle`, `GET /v1/workflows/{id}/pages/{n}` and the same two fields on the start, once it is paired as a device (`POST /v1/devices/pair`): `captured` is refused with `422` from anything that is not a paired tablet, because it is what lets the tablet keep the date it showed, and the day a document is signed is nobody else’s to choose (00435). The date is kept only when it is a day within a day of the tablet’s own clock and not after today; otherwise the first signature writes the day in.

## A signing code at the counter

When the sale is made in your own software (00321), `PUT /v1/subjects` builds the packet and the receipt carries a ten-character signing code. Set the tablet’s hand-off on Apps & tablets: **same device** hands the code to the app on the same tablet (`signsealer://kiosk?code=…`); **separate till** makes the tablet list who is waiting, by first name and last initial, refreshed on its heartbeat. Either way the customer’s screen shows what the packet owes, each item is signed in turn on the ordinary road — read, consent, photographs, signature — and the list ends complete. A tablet resolves a code with `GET /v1/packets/code/{code}` and starts an item with `POST /v1/packets/items/{id}/start`; it never reads a packet’s full detail. A code from another business, a code nobody holds and a malformed one answer the same way.

## A photograph as an answer

A template field of kind **photo** (00342) — the boat before it leaves, the fishing license, the vaccination card — takes a photograph, not text. On the signing page it is a camera button; at the counter the tablet asks for it after consent, with the template’s own label and hint, and with no network keeps it sealed behind the start and sends it in its turn. A required one is needed before the signature. The image is encrypted under the business’s key and kept with the document for as long as the document is kept; the field carries its SHA-256, the trail records `photo_supplied`, and Documents shows it beside the signer. It is an answer to a question in the agreement, not an identity check of any kind. Over the API: `POST /v1/sign/{token}/fields/{key}/photo`. The signed PDF prints each photograph after the certificate unless the business turns that off for the template ([the sealed PDF](https://signsealer.com/docs/evidence)).

## The last check at the gate

The person who hands over the kayak, opens the gate or drives the bus is the last to see the customer, and the one with the least time. **Gate check** in the app (from Home, the menu, or the kiosk’s menu behind the PIN) answers one question over the open documents: has everybody on this waiver signed? Search by name or title (a tablet kept to its own documents does not search addresses or numbers); open one and each signer is listed with a tick or a circle. For anyone who has not signed, *Show QR to sign* mints a fresh signing link on the server — the one they were sent stops working, and the trail records that a link was shown at the gate — and draws it as a QR code the customer scans with their own phone. The screen asks again every few seconds and turns green when the signature lands. It works online only, and says so: the point of the check is what the server knows now.

A link the tablet shows is one whoever holds the tablet could open too, so a tablet shows links only for documents it started, or that its own form started. A tablet at the gate that checks people your booking system emailed needs more: in the portal, under **Apps & tablets**, set *Show links for* to *every open document* for that tablet (or `PATCH /v1/devices/{id}` with `"gate": "account"`). The change is on the audit trail; a tablet paired before 24 September 2026 was left at every open document, so nothing that worked stopped working, and can be narrowed the same way. `GET /v1/documents/{id}/signers` answers `link_allowed`, so the button is only offered where it will work. A signature made through a link shown this way is assured as `link`, not by the email that went out before it.

Your own software asks the same way: `GET /v1/documents/{id}/signers` is each signer’s name and state and nothing else, and `POST /v1/documents/{id}/signers/{signer}/link` answers a fresh link with its QR code as SVG. A paired tablet’s credential may call both; the whole document, with its text and every address, stays with an API key.

## How the tablets are doing

Every heartbeat carries the queue’s shape: how many signatures are waiting on the tablet to be sent, how many the server refused for good, and whether everything captured has been delivered. **Apps & tablets** shows it beside each tablet as one word — synced, waiting, needs attention, update, or not heard from — so nobody has to walk over to the counter to know. A problem on the tablet (an item the server refused, a screen that failed) is reported as a code, the screen and the step it was on, whether it was online and how deep the queue was: names and numbers, never a message, so never a customer. Your own tablet software can say the same with `queue_waiting`, `queue_refused` and `synced` on the heartbeat and `POST /v1/devices/report`.

## Tablets from your own software

One business pairs its tablets from **Apps & tablets** in the portal. A platform that runs many businesses does the same over the API, with a key that carries `signing:devices`, so a tablet goes on each counter from your own back office:

| Call | What it does |
| --- | --- |
| POST /v1/devices | Add a tablet. Answers its pairing code *once*: eight characters, fifteen minutes, one use. `workflow_id` locks it to one form; `for_review` makes a thirty-day code for a store reviewer. |
| GET /v1/devices | Every tablet: paired or waiting, what it runs, last seen. Never the code. |
| POST /v1/devices/{id}/code | A new code. Any tablet paired to this one stops the moment it is made. |
| PATCH /v1/devices/{id} | Rename it, change the forms it runs (`workflow_ids`), how it is handed a customer (`hand_off`) or whose links it may show (`gate`); a paired tablet picks it up on its next heartbeat. |
| DELETE /v1/devices/{id}?reason= | Stop it. Its credential stops with it. |

The tablet itself trades the code for its own credential with `POST /v1/devices/pair`, which takes no key at all: the code is the credential, and what comes back is scoped to that tablet alone. A tablet belongs to one business; a platform with many pairs each business's tablets under that business.

---

Source: https://signsealer.com/docs/teams (Teams, roles and sign-in)

# Teams, roles and sign-in

Everybody who signs in to a business holds one role there. It decides what they can do in the dashboard, whether they can make API keys, and what they can let a connected app do.

How a key or a token is sent, and what each scope allows on the API, is [Authentication](https://signsealer.com/docs/authentication). This page is the people side.

## More than one business

One sign-in can belong to several businesses, each with its own templates, documents, team, plan and bill. *Add a business*, in the account menu, starts another that you own and switches you to it; an invitation from another business to your address adds that one. The business menu at the top moves between them. A sign-in can start up to ten; ask us if you need more.

## Roles

A business has one owner, the person who made it. Ownership is transferred, never given: only the owner can hand it over, and becomes an admin in doing so. Everybody else is an admin, a manager, staff or a viewer. Each role starts with these permissions, and the owner's cannot be changed.

| Permission | Owner | Admin | Manager | Staff | Viewer |
| --- | --- | --- | --- | --- | --- |
| View documents and signatures (`signing.read`) | Yes | Yes | Yes | Yes | Yes |
| Send a document for signature (`signing.send`) | Yes | Yes | Yes | Yes | No |
| Manage bookings and guests (`signing.subject`) | Yes | Yes | Yes | Yes | No |
| Prepare a document for signature (`signing.prepare`) | Yes | Yes | Yes | No | No |
| Void a sent document (`signing.void`) | Yes | Yes | Yes | No | No |
| Use AI to draft templates and forms (`signing.draft`) | Yes | Yes | Yes | No | No |
| Create and edit templates (`signing.template`) | Yes | Yes | No | No | No |
| Countersign on behalf of the business (`signing.sign_internal`) | Yes | Yes | No | No | No |
| Take back the access a signed NDA gave (`signing.revoke_grant`) | Yes | Yes | No | No | No |
| Change how signing looks to your customers (`signing.branding`) | Yes | Yes | No | No | No |
| Set up forms, tablets, integrations and API keys (`signing.api`) | Yes | Yes | No | No | No |
| Invite people, change their roles, remove them (`team.manage`) | Yes | Yes | No | No | No |
| See the activity log (`audit.read`) | Yes | Yes | No | No | No |

Some things go by role and cannot be given to anybody else: only the owner closes the business, and only the owner or an admin changes its details or its billing, or exports its records.

## Managing the team

Whoever holds `team.manage` invites people, changes their roles and removes them. Under **Team**, *Permissions* on a member's row also grants or withholds any one permission for that person, whatever their role says; changing their role clears those. Three rules hold throughout:

- **Nobody reaches above themselves.** Nobody invites somebody as, or gives them, a role above their own, or changes, removes or edits the permissions of somebody above them. An admin is made by the owner or an admin.
- **Nobody gives what they do not hold.** A permission you lack cannot be granted, even by clearing a refusal the role would answer yes to.
- **Nobody acts on themselves or the owner.** You cannot change your own role or permissions, or remove yourself: you leave. The owner can neither leave nor be removed until they hand the business over.

An invitation names an address and a role. Its link works for seven days, and only for somebody signed in as that address. Inviting the address again replaces it.

## API keys

Making and revoking keys, test keys included, needs `signing.api`: the permission behind webhooks, tablets, booking-system connections and connected apps too. **Integrations → API keys** is in the menu for owners and admins; anybody else given the permission finds it at `https://app.signsealer.com/keys`.

A key is the business's, not the person's, and its scopes are not limited to what its maker may do: whoever holds `signing.api` can make a key with any scope on the form. Give that permission only to somebody you would trust with all of them.

The form offers `signing:read`, `signing:write`, `signing:templates`, `signing:workflows`, `signing:subjects`, `signing:webhooks` and `signing:devices`, and an expiry of never, 30 days, 90 days or a year. The four parts of `signing:write` (`signing:send`, `signing:remind`, `signing:links`, `signing:void`) are not on it: only a connected app's tokens hold them.

## Connected apps

The person pressing **Connect** on the consent screen must hold `signing.api`, so a manager, staff member or viewer is refused unless it was given to them. Each scope asked for is then checked against that person, and one they could not give is left out of the grant. If none is left, the connection is refused.

| Scope | The person connecting must hold |
| --- | --- |
| `signing:read` | `signing.read` |
| `signing:write` | `signing.read`, `signing.prepare`, `signing.send`, `signing.void` |
| `signing:send` | `signing.read`, `signing.prepare`, `signing.send` |
| `signing:remind`, `signing:links`, `signing:workflows` | `signing.read`, `signing.send` |
| `signing:void` | `signing.read`, `signing.void` |
| `signing:templates` | `signing.read`, `signing.template` |
| `signing:subjects` | `signing.read`, `signing.subject`, `signing.send` |
| `signing:webhooks` | `signing.read`, `signing.api` |

With the defaults this matters only once somebody's permissions change: a manager given `signing.api` can give an app everything but `signing:templates`, and an admin whose voiding is withheld cannot give `signing:write` or `signing:void`.

An app holds one grant per business. Connecting it again replaces the grant, which becomes the grant of whoever connected it this time. Giving less cuts the access tokens it already holds down at once, and revokes any left with nothing; giving more changes no token already issued. An [AI assistant](https://signsealer.com/docs/mcp) whose registration or metadata document does not list `refresh_token` in `grant_types` is given no refresh token. Each access token shows under **Integrations → API keys**, under the app's name.

## When somebody leaves

| What they made | Removed, or left | Role or permissions narrowed |
| --- | --- | --- |
| Apps they connected | Disconnected, with every token | Disconnected if they can no longer give all it holds |
| Invitations not yet accepted | Withdrawn | Withdrawn if they can no longer invite, or it is above their new role |
| Tablet pairing codes not yet used | Voided | Voided if they can no longer add a tablet |
| API keys | Keep working, and are named | Keep working; named if they can do more than the person now may |
| Tablets they paired, systems they connected | Keep working, and are named | Keep working |

Keys are left alone on purpose: one is what the booking form or the till runs on. But the person saw its secret, so after a removal the Team page says how many keys they made that still work, and after a role or permission change how many can now do more than the person may. Revoke any they should not keep under **Integrations → API keys**. A removal also says how many tablets they set up and systems they connected still work, which they may still have in hand. A pairing code is only good while whoever made it could add a tablet, so one nobody has typed in yet stops when they go.

## Single sign-on with SAML

A business can make its own identity provider, anything that speaks SAML 2.0, the only way in for everybody at its email domain. Whoever holds `team.manage` sets it up at `https://app.signsealer.com/settings/sso`.

| Give your provider | Value |
| --- | --- |
| Entity ID (audience) | `https://app.signsealer.com/sso` |
| Reply URL (ACS), HTTP-POST | `https://app.signsealer.com/sso/acs` |
| Name ID format | EmailAddress |

There is no metadata file: type these in. The assertion itself must be signed, must name that entity ID as its audience, and must carry an email address, as the Name ID or an `email`, `mail` or `emailaddress` attribute.

1. **Prove the domain.** Publish the TXT record the screen shows at `_signsealer.<domain>`. Its value is the token alone, with no `signsealer-verify=` in front as a signing domain's has. We look for it every five minutes, and until a look finds it the screen says what the last one saw. A proven domain is not looked at again. Claiming the domain again before then gives it a new token, and only the new one counts. A domain belongs to one business, and only that exact domain counts: `acme.com` does not cover an address at `uk.acme.com`.
2. **Connect the provider:** its entity ID, https sign-in URL and signing certificate. Assertions are checked against this certificate and no other. To rotate it, save the connection again with the same entity ID.
3. **Require it.** This is refused until a domain is proven, a connection is on, and the owner is named as the one person who keeps the ordinary way in, so an outage at your provider cannot lock the business out.

### Once it is required

- Somebody at a proven domain who types their address on the sign-in page is sent to your provider. The emailed link, Google, Apple, passkeys and texted codes are refused for them, and a session opened another way ends on its next request. The named owner is the exception.
- It follows the address, not the business: somebody at your domain signs in through your provider for every SignSealer business they belong to. Other domains sign in as before.
- It works only while required, so it cannot be tried first. Try it the moment you switch it on, while the owner can still sign in and switch it off.
- The sign-in must start at SignSealer and finish in the same browser within ten minutes. One started from your provider's own list of apps is refused.
- API keys and connected apps are not sign-ins, and carry on.

Somebody new is given a **viewer**'s seat, joined to any account they already had at that address: your provider says who somebody is, never what they may do. To start somebody higher, invite them before their first sign-in; accepting sets the role. A member who was removed, or left, is refused and told to ask for an invitation. Removing somebody from your provider stops their next sign-in but not a session already open, which ends after twelve hours idle or thirty days; and nothing tells SignSealer, so they stay a member, with whatever they connected, until you remove them under **Team**.

## What the activity log records

**Activity** needs `audit.read`. Each line shows when, who, what, about which record, any reason given, and the network it came from. The other details below are kept in the record and the business's export. It can be searched by action name.

| Action | Recorded when |
| --- | --- |
| `team.invited`, `team.joined`, `team.invitation_revoked` | An invitation is sent (address and role), accepted, or withdrawn: by hand, or because its sender can no longer send it. |
| `team.role_changed`, `team.grant_set` | A role changes, or one permission is set for one person: what was taken back, and the keys they made that can now do more than they may. |
| `team.removed`, `team.left` | Somebody is removed, with the reason, or leaves: what was taken back, and the keys they made that still work. A removal also names the tablets and systems they set up. |
| `device.pairing_voided` | A tablet's pairing code nobody had used is voided, because whoever made it can no longer add a tablet. |
| `team.ownership_transferred` | The business is handed over. |
| `signing.api_key_issued`, `signing.api_key.revoke` | A key is made (label, prefix, scopes, expiry, addresses) or revoked, with the reason. |
| `signing.oauth.authorized`, `signing.oauth.token_issued`, `signing.oauth.revoked` | An app is connected with its scopes, its code is exchanged (and whether a refresh token came with it), or it is disconnected, with the reason. |
| `settings.changed` | A sign-in domain is claimed, a provider connection saved, or single sign-on required or relaxed. |
| `settings.sso_domain_proven` | We find a sign-in domain's record, and the domain is proven. It is recorded as SignSealer's, not a person's. |
| `portal.signed_in` | Somebody signs in through your provider, and whether that made their account or their seat. |

---

Source: https://signsealer.com/docs/signers (Signers, roles and order)

# Signers, roles and order

Who a document goes to, what each of them does, and in what order. Said once, when it is sent.

## The request

Order is a property of the document, so it is set when the document is prepared: `sequential` on `POST /v1/documents`, false when absent. The people are set when it is sent, on `POST /v1/documents/{id}/send`, one to fifty of them.

```
POST /v1/documents
{ "template_code": "equipment-rental",
  "values": { "renter": "Dana Reyes", "boat": "Tandem kayak 4" },
  "sequential": true }

POST /v1/documents/{id}/send
{ "signers": [
    { "full_name": "Dana Reyes", "email": "dana@example.signsealer.com",
      "phone": "+16155550142", "role": "signer", "sign_order": 1 },
    { "full_name": "Lee Park", "email": "lee@example.signsealer.com",
      "role": "witness", "sign_order": 2 },
    { "full_name": "Priya Shah", "email": "priya@example.signsealer.com",
      "role": "approver", "sign_order": 3 },
    { "full_name": "Front desk", "email": "desk@example.signsealer.com", "role": "cc" }
  ] }
```

| Field | Takes | Means |
| --- | --- | --- |
| `full_name` | Required, 1 to 200 characters. | The name on the link, the page and the certificate. |
| `email` | An email address. | Where the link is emailed. |
| `phone` | 7 to 40 characters. | Where the link is texted, where the business holds consent ([Texting and consent](https://signsealer.com/docs/texting)). |
| `role` | `signer` (when absent), `approver`, `witness` or `cc`. | What they do: below. |
| `sign_order` | A whole number from 1 to 50; 1 when absent. | Their step, when the document is signed in order. |
| `delivery` | `send` (when absent) or `embedded`. | `embedded`: nothing is sent to them, because you show them the page yourself ([Signing inside your product](https://signsealer.com/docs/embedding)). |
| `for_business` | `true` or `false`; `false` when absent. At most one signer, never a `cc`. | They sign for the business: the template's questions with `supplied_by: "business"` are theirs, and nobody else's are ([Templates](https://signsealer.com/docs/templates)). |
| `party_id` | A UUID, or `null`. | A person or organization the business keeps on file, copied onto the signer and answered as `party_id` by `GET /v1/documents/{id}`. No route lists them. It has nothing to do with a booking's party, below. |

Everyone but a `cc` needs an `email`, a `phone`, or both; given both, the same link goes by each. The answer is one link per person, once, and only the hash of each is kept. A document takes its signers once: sending one that has already gone out is refused with `422`.

## Roles

| Role | Signs? | What happens |
| --- | --- | --- |
| `signer` | Yes | Sent a link, asked the template's questions, agrees to sign electronically, signs. The document is not complete without them. Reminded automatically. |
| `approver` | Yes | Exactly as a signer: the same link, questions and signature, and the document waits for them. The role is what the record calls them: somebody who authorized it rather than a party to it. Reminded automatically. |
| `witness` | Yes | As a signer, and the document waits for them too. Not sent the automatic reminder; the dashboard's Remind and the API's still work. |
| `cc` | No | On the document's record, and emailed the sealed PDF once everybody has signed. Nothing before that: sent no link and no reminder, and asked no questions. May have no email or number, and with no email is sent nothing at all. Opened anyway, their link says *You were copied on this document. There is nothing to sign.* Not counted in `signers` or `signed` on `GET /v1/documents`, and never named in `waiting_on`. |

> **A `cc` gets the signed copy and nothing else.** When everybody has signed, the sealed PDF, with its certificate, is emailed to each person who signed and to each `cc` with an email address: the same message, in their own name. A document declined, voided or expired before everybody signs never completes, and a `cc` on it is sent nothing. The confirmation text goes only to people who signed, never to a `cc`, whatever number they have. Somebody on a document twice, as a signer and as a `cc`, is sent one copy. To file a copy somewhere email cannot reach, fetch it from `GET /v1/documents/{id}/pdf` on `signing.completed`.

Every role that signs is asked every question on the template, each answering for themselves ([Questions and fields](https://signsealer.com/docs/templates#fields)), and every one of them has to sign before the document completes.

## Order

With `sequential` false, which is the default, everybody signs when they like and `sign_order` only orders the lists.

With `sequential` true, a link takes a signature only once everybody with a lower `sign_order` has signed, copied recipients aside. People with the same `sign_order` are one step and sign in any order between them; the step after waits for all of them. Opened too soon, the page says *It is not your turn yet. This document is signed in order, and somebody before you has not signed.*; `GET /v1/sign/{token}` answers `is_my_turn: false`; and `POST /v1/sign/{token}` is refused with `422`, *an earlier signer has not signed yet*.

> **A link goes when it is its signer's turn** (00609). With `sequential` true, only the first step is sent its links at the send. Each later step is sent theirs, by every road its people gave, when the step before it is fully signed. Until then they hold no working link: the send's answer, and a workflow start's, give them `token: null` and `url: null` with `held: true`, and a reminder for them is refused with `422`, because their turn has not come. An `embedded` signer is not held: their link is yours to show, and opened too soon it says so, as above. Nor is anybody held when the business sends its own links (sending turned off in the dashboard): then every link is in the send's answer, as before. The automatic reminder follows the order too: it goes to the people whose step it is.

One address, or one number, can be on a document once at each step. The same person twice at the same `sign_order` is refused with `409`; at two steps, they are two signers with a link each.

### Who it is waiting on

`waiting_on` on `GET /v1/documents` names everybody who signs and has not, in step order, separated by commas, and is `null` once nobody is left. It is who has not signed, not whose turn it is: in a sequential document it names the later steps too. The signing link answers the same list, leaving out the person reading it, and the page shows it to them under the Sign button (*After you, this still needs …*) and once they have signed. For each person's step and state, read `GET /v1/documents/{id}/signers`: each signer's name, `role`, `sign_order`, `status`, `signed_at` and `declined_at`, with no text and no addresses.

## Workflows: the person it is for, and the people every time

A workflow names its roles once, and each start fills them ([Waivers and workflows](https://signsealer.com/docs/waivers)). `GET /v1/workflows` lists them as `signer_roles`, each with a `label`, a `role` and an `order`:

- **The participant** (`participant: true`, one per workflow): whoever the start is for. Their link comes back in the start's answer and is not emailed, because they are at the form, the tablet or your own page already.
- **Fixed people**, with an `email` and a `full_name`: a manager who countersigns every waiver. Each is emailed their link the moment a document starts.

The workflow's own `sequential` decides the order, as on a document. Roles are set in the dashboard under **Forms & QR**, which offers the person it is for and up to two fixed people; the API reads a workflow and starts one, and has no route that changes one.

### Somebody who signs only after an answer

A fixed person can sign only when the form's answers say so: a guardian when the guest is under 18, a manager when the hire is over $10,000. Under **Questions to ask first**, add the question and choose what kind of answer it takes (a tick box, a date of birth, a number, one of a list). Under **Advanced: edit as text** the same questions are one per line:

```
under_18 | The guest is under 18 | checkbox
dob      | Date of birth | birthdate
total    | Hire total | number
craft    | Craft | choice: Kayak, Canoe, Paddleboard
```

and under the person, choose **They sign only if** the question, what about its answer, and the answer. In `signer_roles` it is the role's `show_if`, the same shape a question's condition has ([questions and fields](https://signsealer.com/docs/templates#fields)): one rule, or several joined by all or any, in groups if need be, each about one of the form's own questions. The dashboard offers **only if** and **unless** with one rule; a condition with more, written through the API, is kept as it is when the workflow is saved there.

It is decided when the document starts, from the answers as they were given, each checked first as a template's answer is: a date of birth that is not a date refuses the start, naming the question, rather than leaving a guardian off. A person whose condition is not met is not on the document at all: no link, no reminder, nobody waiting for them. The start's answer lists them under `not_needed`, and so does the document's `sent` event. The person the form is for always signs, so they cannot have a condition, and somebody other than those copied in has to sign whatever the answers; the dashboard says so when a workflow is saved.

### One person in two roles

A role with `"self": true` is the participant again: a sole proprietor signing for the business and again as personal guarantor. The start makes a second signer at the same address, named with the role's label after the person's name (*Dana Reyes (Guarantor)*), and emails it its own link; in a sequential workflow that link waits for the first signature.

> **No route or screen sets it today.** The editor under Forms & QR has no such option, and the API has no route that writes a workflow. To do the same over the API, send the person twice, at two steps, with `sequential` true on the document:

```
{ "signers": [
    { "full_name": "Dana Reyes", "email": "dana@example.signsealer.com", "sign_order": 1 },
    { "full_name": "Dana Reyes (Guarantor)", "email": "dana@example.signsealer.com", "sign_order": 2 }
  ] }
```

## When everybody in a booking's party signs

A booking for three is three people taking the risk, and the person who booked cannot accept it for the other two. A workflow with `each_person_signs` on `GET /v1/workflows`, started with `persons` above one in `values` or `fields` (the WordPress plugin's bookings send it), records the party on the document, and the start answers `party_size`, at most twenty. The form's own page asks *How many people are signing, including you?* when nothing on it asks for `persons` already, so a QR code or a website link starts a party too.

- **The person who booked describes the others first.** They cannot sign until they have, and it is done on the signing page, not over the API: send them to their link. On `GET /v1/sign/{token}`, `party` says `lead`, how many are `still_to_add`, the `others` added, and for somebody added, `added_by`.
- **Each adult signs their own link.** One added with an email address, or a number that has agreed to the business's texts, is sent their own link, and the person who booked never sees it. One we cannot reach is handed their link by the person who booked, which goes on the trail as `link_shown`; that signature is assured as `party_link` and the certificate says who handed it out ([Evidence and certificates](https://signsealer.com/docs/evidence)).
- **Or one link for the whole party.** The person who booked can share a single party link, under `/p/` on the business's signing host; each person opens it, picks their place, gives their own address or number and goes on to their own link. The workflow can ask them to confirm a code sent there first.
- **A child is not a signer.** An adult signs for them, answers the template's per-child questions about each child, and ticks that they are the child's parent or legal guardian.

The document cannot complete until every place in the party is taken and signed. A party's link is sent to one address at most three times a day ([Limits and paging](https://signsealer.com/docs/limits)).

**Or a document each.** With `party_documents` set to `each` (*What the party signs* under Forms & QR), every adult the person who booked adds gets a document of their own, made from the first: the same template version and answers, their own name in it, the same last day, and anybody else the form has sign it, such as the business's countersignature. A parent who is not in the party has one too, and signs for their child on it; a child goes on the document of whoever signs for them. Each document completes on its own, and each is a signing. The links, the party link and `party` on the signing link work as above, across all of them.

## Reminders

**The automatic one.** Each signer and approver who has not signed is sent one reminder, with a fresh link, once the document has been out for the workflow's *Remind after* days, or the business's own setting, which is three days unless it has been changed; *Never*, or zero, turns it off. It skips a witness, an `embedded` signer, a document that has expired, anybody it has no way to reach, and anybody who has already had a reminder of any kind. In a sequential document it goes only to the people whose step it is.

**On demand.** `POST /v1/documents/{id}/signers/{signer}/remind` sends a fresh link to one person who has not signed, and the link they had stops working. It is refused for a `cc`, somebody who has signed or declined, a document that is not out for signature, and past the limits in [Limits and paging](https://signsealer.com/docs/limits), and in every refusal their link is left as it was. `by` in the answer is the road it went by. Either kind is `signing.reminded`.

## Declining

A signer who will not sign says so: *I would rather not sign this* on the page, or `POST /v1/sign/{token}/decline` with a `reason` of 1 to 500 characters. One decline closes the whole document: its status is `declined`, every other link says *This document was declined and is closed.*, no more reminders go, and a packet holding it is blocked rather than waiting. `signing.declined` carries the reason as `signer.decline_reason`.

Somebody who has signed cannot decline, because a signature is withdrawn by agreement, not by declining; nor can a `cc`, who has nothing to decline. To try again, prepare and send a new document.

## Changing who signs

There is no route to change, replace or remove a signer once a document has gone out. A wrong address is fixed by voiding the document with a reason, `POST /v1/documents/{id}/void`, and sending a new one; a document everybody has signed cannot be voided. A lost link is not a wrong address: `.../remind` sends a fresh one, and `POST /v1/documents/{id}/signers/{signer}/embed` hands you one to show.

## Following it

Each of these is a webhook ([Webhooks](https://signsealer.com/docs/webhooks)), and every one about a person carries `signer` with their `role`, `sign_order` and `status`.

| Event | Says |
| --- | --- |
| `signing.sent` | The links were made and the messages queued. |
| `signing.delivered` | The message carrying one person's link reached them. |
| `signing.viewed` | One person opened their link, the first time. |
| `signing.signed` | One person signed. In order, the next step's links now work. |
| `signing.completed` | Everybody who signs has. |
| `signing.declined` | One person said no, and the document is closed. |
| `signing.reminded` | A reminder went, with a fresh link. |
| `signing.link_shown` | A fresh link was shown rather than sent: at a gate, in a frame, or by the person who booked. |
| `signing.expired` | The document's `expires_at` passed before everybody signed. |
| `signing.voided` | The business withdrew it. |

Between events, `GET /v1/documents` answers `signers`, `signed` and `waiting_on` for each document, and `GET /v1/documents/{id}/signers` each person's step and state.

A link sent with `POST /v1/documents/{id}/send` lasts until the document's `expires_at`, or thirty days when it has none. Only a document with an `expires_at` expires as a whole and sends `signing.expired`; a link running out of its thirty days sends nothing.

---

Source: https://signsealer.com/docs/signing-page (Your own signing page)

# Your own signing page

Every screen in your own app, on the routes a signing token opens. They call the same engine SignSealer’s own page does, so a page that skips a step is refused, not believed.

## Build it, frame it, or send them to ours

Send the signer to SignSealer’s page (the `url` the send answered) when you can. Frame it when the screen is on a site the business has proven ([Signing inside your product](https://signsealer.com/docs/embedding)). Build your own when neither fits: the signing routes take no key and answer a browser on any site. What you take on:

- Drawing the document as the engine holds it: `body` as text or Markdown (`body_format`), or a PDF’s `pages` ([Signing a PDF](https://signsealer.com/docs/pdf)).
- Showing `consent_text` before consent and `intent_text` above the signature, word for word. The engine records its own wording whatever your page showed.
- Every step the business switched on, below.
- The party, when everybody in a booking’s party signs: the person who booked says who else is in it before they can sign (below).

One line of the certificate is written only by SignSealer’s page: *How the document was shown*. A signature taken through the API has none, because we did not draw the page.

## The token

A signing token is one signer’s credential for one document, and the only one these routes take; an API key sent with it is ignored. The send (or a workflow start) answers it once, as `token`; only its hash is kept. `POST /v1/documents/{id}/signers/{signer}/embed` mints a fresh link, with its `expires_at`, and the one before it stops working: the token is the part of its `url` after `/s/`, URL-encoded.

Whoever holds it can read the document, the signer’s name and email and the names of the others on it, and answer, consent, sign and decline as that signer. So:

- **Never store or log it.** Mint it on your server, with your key, when the person opens the screen, and hand only the token to their browser.
- **Never sign with it for somebody.** Each step records the address and browser of the request that made it. Called from your server, the trail records your server as the signer.
- **Never give it to anyone but the signer.** The certificate can say only that the link was used.

## The order

The order SignSealer’s page takes. Each step’s state is on the view or on the step’s own `GET`, so a page reloaded half-way carries on. `…` is `https://api.signsealer.com/v1/sign/{token}`.

1. **Read the link.** `GET …`. When `ok` is false, show `reason`, a sentence written for the person, and stop. It answers `200` for a token that matches nothing too. The first read puts `viewed` on the trail.
2. **Where they are.** `GET …/location`. When `mode` is `ask` or `require` and there is no `position`, show `disclosure.text`, ask the device, then `POST …/location` with `{ "shared": true, "lat", "lon", "accuracy_m" }`, or `{ "shared": false }` when they said no or it could not tell. `offered` is for counter tablets.
3. **The code**, when `verification_required` is `email` or `sms`. `POST …/code` sends six digits, good for ten minutes, to where the link went, and answers `channel`, `sent_to` (masked) and `resend_after`. `POST …/verify` with `{ "code" }` answers `ok`; a wrong code is `ok: false` with `reason` and `attempts_left`, not an error, and `expired: true` means send a new one.
4. **Consent.** Show `consent_text`, then `POST …/consent` with `{}`, unless `consented_at` is set.
5. **The ID photo.** The view does not carry it: `GET …/id-evidence`. When `mode` is not `off` and `id` is null, show `id_disclosure.text` and `POST …/id-evidence` with `kind: "id"`, `content_type` and `bytes_base64`. Under `id_selfie` you may offer `kind: "selfie"` too.
6. **The questions.** Draw the `fields` whose `visible` is not false, in order: a `block` with `step: true` gets a page of its own, and the rest come after the steps. Answer with `POST …/fields` (`key`, `value`, `about` for a field about one person), a `photo` with `POST …/fields/{key}/photo`. An empty value passes an optional question (`passed`); a required one cannot be passed. Never ask for a field with `at_signing` or `from_sender`. Read the view after each page: an answer can show a question (`show_if`) or hide one, and a hidden one loses its answer. When `document_after_questions` is true, ask these before showing the document, except a box placed on a PDF’s page.
7. **The party**, when `party.may_add` is true and `party.still_to_add` is above nought. Ask the lead about exactly that many people, then `POST …/party` with `{ "people": [ … ] }`. Each adult is a `full_name` with an `email` or a `phone`, or with neither. A child is `minor: true` (or has a `date_of_birth` when `party.ages` is `dob`) with a `guardian`: `me`, `p1` for the first adult in the list, or `other` with `guardian_name` and an address. Everybody with an address is sent their own link and comes back with `sent: true`. Anybody we could not send it to comes back with a `url`, shown once, for the lead to hand over. An adult with no address is a place kept open: show the lead `party_link` to share with the party, and each person opens it, chooses their name and gives an address. `POST …/party/share` makes a new party link, and `POST …/party/link` with a `signer_id` makes a new link for one person.
8. **Sign.** Show the document whole, `intent_text` above the signature, then `POST …` with `method` (`typed`, `drawn`, `clicked` or `uploaded`) and `value`: the name typed, or a drawing as a data URI. `201` with `event_id` means it is recorded. A box with `at_signing: "signature"` takes the words typed, or the signer’s name for any other method; one with `"date"`, the day. Read the view again: `waiting_on` names anybody still to sign.

Before the signature, `POST …/decline` with a `reason` (up to 500 characters) closes the document for everybody on it, not only this signer.

## What the engine will not let through

| Step | Skipped or refused |
| --- | --- |
| Code | Consent is refused until a code is confirmed, so there is no signature either. |
| Location, `ask` | `{ "shared": false }` is recorded as a decline and they sign as usual. Send it: a decline is a fact on the record, and silence is not. |
| Location, `require` | Only a shared position lets the signature through. A decline is recorded and the signature is still refused, so take them back to the step. |
| ID photo | The signature is refused without the photo of the ID. The selfie is never required. |
| Questions | The signature is refused while a required, visible question is unanswered, photographs included. |
| Party | The lead’s signature is refused until they have said who else is in it. |

> **The code, the location and the ID photo are asked of a signer we delivered a link to** by email or text. For a signer sent with `delivery: "embedded"`, `verification_required` is null and both `mode`s are `off`, until a reminder sends them a link.

## Errors and limits

Refusals have the usual shape ([Errors](https://signsealer.com/docs/errors)); the message is usually the engine’s own sentence, worth showing the person.

| Answer | When | Do |
| --- | --- | --- |
| `403 forbidden` | `no such signing link`, `this signing link expired on …`, or a token since replaced | Stop; the view says why. |
| `422 invalid` | `a code sent to you must be confirmed before you consent`, `a code sent to you must be confirmed before you decline`, `consent to electronic records must be recorded before signing`, `sharing your location is required before you sign`, `a photo of your ID is required before you sign`, `still needed before signing: …` | Back to that step. |
| `422 invalid` | `an earlier signer has not signed yet` | Not their turn. |
| `422 invalid` | `a code was sent less than a minute ago`, `too many codes in the last hour`, `too many wrong codes today`, `too many codes have gone to that address in the last hour`, `too many codes have gone to that address today` | Wait; `resend_after` says when. |
| `404 not_found` | `this document does not ask for …` | Check the field’s `key`. |
| `413 too_large` | A body over a megabyte | Shrink the photo. |
| `429 rate_limited` | A budget below is spent | Wait `Retry-After` seconds. |
| `429 busy` | A photo arrived while others were being read | Nothing was kept: send it again after `Retry-After`. |

| Budget | Limit |
| --- | --- |
| Calls on one link: the view, consent, the code and its check, a location, each photo, the signature, the decline | 20 a minute |
| Answers on one link (`POST …/fields`) | 600 an hour |
| Codes for one signer (refused with `422`) | One a minute, five an hour, none after fifteen wrong guesses in a day |
| Codes to one email address or number, across every signer and business (refused with `422`) | Six an hour, twenty a day, and none after fifteen wrong guesses in a day at one form’s documents |
| Codes by text, across a business’s signers | 300 an hour |
| Photos read for one link | One at a time |

The twenty is per link, not per caller, so a page that reads the view on a timer spends the signer’s budget; hear about other signers on your server from [webhooks](https://signsealer.com/docs/webhooks). The location and ID-evidence `GET`s and the page pictures (`/s/{token}/page?n=1`) do not count. A photo is a JPEG or PNG of at most 52 megapixels, base64 in a body of at most a megabyte. [Limits and paging](https://signsealer.com/docs/limits) has the rest.

## What is recorded

Each step goes on the trail with the address and browser of the request ([Evidence and certificates](https://signsealer.com/docs/evidence)):

- `viewed`, on the first read.
- `verified`, with the channel and masked address; the assurance becomes `email_otp` or `sms_otp`.
- `location_shared`, to six decimal places with the accuracy, or `location_declined`.
- `consented`, with the consent wording, its reference and its SHA-256.
- `id_captured`, with the photo’s SHA-256; the image is kept encrypted for thirty days.
- `photo_supplied`; the field’s value becomes `sha256:<hex>` and the image is kept as long as the document.
- `signed`, with the method, the value, the SHA-256 of the text signed, the statement above the signature and the assurance.
- `declined`, with the reason.

A signer holding a link from `…/embed`, or sent with `delivery: "embedded"` and never sent a link, signs at assurance `link`, possession of the link, unless they confirm a code.

## With the Node client

`SignSealerSigning` in [@signsealer/sdk](https://signsealer.com/docs/sdk) takes no key, runs in the browser and never retries: a second signature is not a retry. An `image` is `{ contentType, bytes }`.

| Method | Calls |
| --- | --- |
| `link(token)` | `GET …` |
| `pageUrl(token, n)` | Nothing: answers the address of page `n` |
| `location(token)` · `recordLocation(token, position)` | `GET` · `POST …/location` |
| `requestCode(token)` · `confirmCode(token, code)` | `POST …/code` · `POST …/verify` |
| `consent(token)` | `POST …/consent` |
| `idEvidence(token)` · `captureIdEvidence(token, kind, image)` | `GET` · `POST …/id-evidence` |
| `supply(token, key, value, about?)` | `POST …/fields` |
| `supplyPhoto(token, key, image, { about })` | `POST …/fields/{key}/photo` |
| `sign(token, method, value)` · `decline(token, reason)` | `POST …` · `POST …/decline` |
| `verify(code, sha256?)` | `GET /v1/verify/{code}` |

The whole flow, with your own screens behind the functions it does not import:

```
import { SignSealerSigning, SignSealerError } from "@signsealer/sdk";

const signing = new SignSealerSigning();   // no key: the token is the credential

try {
  let link = await signing.link(token);
  if (!link.ok) return show(link.reason);

  const where = await signing.location(token);
  if (where.mode !== "off" && (!where.position || (where.mode === "require" && !where.position.shared))) {
    await show(where.disclosure.text);
    const fix = await askTheDevice();      // null when they said no
    await signing.recordLocation(token, fix
      ? { shared: true, lat: fix.latitude, lon: fix.longitude, accuracyM: fix.accuracy }
      : { shared: false });
  }

  if (link.verification_required) {
    const { sent_to } = await signing.requestCode(token);
    let checked = await signing.confirmCode(token, await ask("Code sent to " + sent_to));
    while (!checked.ok && !checked.expired) {
      checked = await signing.confirmCode(token, await ask(checked.reason));
    }
  }

  if (!link.consented_at) {
    await show(link.consent_text);
    await signing.consent(token);
  }

  const id = await signing.idEvidence(token);
  if (id.mode !== "off" && !id.id) {
    await show(id.id_disclosure.text);
    await signing.captureIdEvidence(token, "id", await takePhoto());
  }

  const owed = (l) => l.fields.filter((f) =>
    f.visible !== false && !f.passed && !f.at_signing && !f.from_sender);
  for (let open = owed(link); open.length; open = owed(link = await signing.link(token))) {
    for (const f of open) {
      if (f.kind === "photo") await signing.supplyPhoto(token, f.key, await takePhoto(), { about: f.about ?? undefined });
      else await signing.supply(token, f.key, await ask(f.label), f.about ?? undefined);
    }
  }

  if (link.party?.may_add && link.party.still_to_add > 0) {
    const added = await signing.addParty(token, await askWhoElse(link.party.still_to_add));
    await showToHandOver(added.people.filter((p) => p.url), added.party_link);
  }

  await show(link.body, link.intent_text);
  await signing.sign(token, "typed", await ask("Type your name to sign"));
} catch (e) {
  if (!(e instanceof SignSealerError)) throw e;
  show(e.status === 429 ? "Try again in " + e.retryAfter + " seconds." : e.message);
}
```

---

Source: https://signsealer.com/docs/retention (Retention and redaction)

# Retention and redaction

A signed agreement is evidence for years and somebody's personal data from the first day. SignSealer keeps both promises by redacting, not deleting: the text and the people go, the fingerprints, the trail and the certificate stay, and the certificate still verifies.

This page is what that means for your integration. The policy, including what redaction cannot reach, such as backups, is [Data retention and deletion](https://signsealer.com/security/data-retention).

## How long things are kept

| What | Kept for | Then |
| --- | --- | --- |
| A finished document: completed, declined, expired or void | 2,555 days (seven years) by default; never less than 365 or more than 7,300 | Redacted by the sweep |
| An email or text, once it is no longer waiting to go | 30 days by default; 1 to 365 | Its body and subject become `[redacted]`. Who it went to, when, and what became of it stay. |
| The stored body of a finished webhook delivery | The same period as messages | The people are taken out of it ([Webhooks](https://signsealer.com/docs/webhooks)) |
| ID evidence images | 30 days from capture | The image goes; its hash stays ([Evidence and certificates](https://signsealer.com/docs/evidence)) |
| The certificate, its code, the fingerprints and the event trail | For good | Scrubbed of the people when the document is redacted |

Both periods belong to the business, and neither can be changed from the dashboard or the API today. A document's clock starts at the first it has of: completed, voided, its expiry date, sent, created. A draft, or a document still out for signature, is never redacted, however old. The sweep runs every hour and takes at most two hundred documents per business a pass, oldest first.

## What redaction removes and keeps

### Goes

- The text, replaced by a dated notice, and the title, which becomes *Redacted document*.
- Each signer's name (*Redacted*), email address (one at `redacted.invalid`, which cannot receive mail), phone number, date of birth and reason for declining.
- The signatures themselves; the network address and browser on every event; a shared position's coordinates; and the names on a party's events (who handed a link out, whom a parent signed for).
- Every answer's value, the photographs taken as answers, and the sealed PDF kept since completion. ID evidence images go at the next hourly sweep.
- The name of each child an answer was about, which becomes *Redacted child 1*, *Redacted child 2* and so on: one number per child, the same on every question, in the parent or guardian's statement, and in the party's list of children, which loses their dates of birth. The certificate keeps the statement's words and drops the name and the statement's SHA-256.
- Its link to the person on file it was about, so `subject_party_id` and `subject_name` read null. That person stays on file, as they were, for your other documents.
- The body, subject and recipient of every message about it (one still queued is canceled), and the people in every webhook delivery about it (one still waiting goes without them).
- Your `external_ref`.

### Stays

- The document's id, status and dates, and the SHA-256 of its text, unchanged, as `body_sha256_hex`.
- Every event's kind, time and the fingerprint of the text it was made against; each signer's role, order, status and times; every question.
- The guests on a reservation you sent with `PUT /v1/subjects`, and the people on file: they are your records, shared by the other documents about them, and a redaction of one document leaves them as they are.
- The certificate's code, issue time and both hashes, and the SHA-256 of every sealed PDF issued for it.
- Your own `metadata` and `return_url`. Redaction leaves them, so keep personal data out of both.
- A line on the audit trail: who redacted it, when and why.

## What the API answers afterwards

No webhook event fires when a document is redacted. Your system finds out by reading the document, where `redacted_at` is set:

```
{
  "document_id": "d41c…",
  "title": "Redacted document",
  "status": "completed",
  "body": "[Redacted on 2033-10-01. The text is gone. Its SHA-256 fingerprint, the times, the event trail and the certificate are kept, and the certificate still verifies against them.]",
  "body_sha256_hex": "9f2c…",
  "integrity_ok": true,
  "redacted_at": "2033-10-01T15:04:12Z",
  "redaction_reason": "retention: past 2555 days",
  "signers": [{
    "full_name": "Redacted", "email": "redacted-5f0a8c21@redacted.invalid", "phone": null,
    "status": "signed", "signed_at": "2026-10-03T14:22:09Z", "decline_reason": null, …
  }],
  "events": [{
    "kind": "signed", "signer_email": "redacted-5f0a8c21@redacted.invalid",
    "ip": null, "user_agent": null, "signature_method": "typed",
    "signature_value": "[redacted]", "matches_current_text": true, …
  }],
  "answers": [{ "key": "medical", "label": "Anything we should know?", "asked": true, "value": null, "flagged": false, … }],
  "external_ref": null,
  "metadata": { "booking": "RES-88213" },
  …
}
```

| Call | After redaction |
| --- | --- |
| `GET /v1/documents/{id}` | As above. `integrity_ok` and each event's `matches_current_text` are checked against the kept fingerprint, so a redaction does not turn them false. |
| `GET /v1/documents` | Carries no `redacted_at`. `integrity_ok` is checked against the kept fingerprint, as on the document itself. Neither `external_ref` nor `q` finds it by your reference, the name of the person it was about, or the signer's name, address or number any more, so keep the `document_id`. |
| `GET /v1/documents/{id}/certificate` | The same `verification_code`, `issued_at`, `document_sha256_hex` and `certificate_sha256_hex`. The `payload` is scrubbed as the record is, and `still_matches_record` stays `true`. |
| `GET /v1/documents/{id}/pdf` | The copy kept at completion is gone. The next call draws one from the redacted record (no uploaded pages, no photographs, no names), keeps it, and returns it from then on, with a new SHA-256. |
| `GET /v1/documents/{id}/bundle` | Still made, and prints when the document was redacted and why. |
| `GET /v1/verify/{code}` | `redacted_at` is set, `still_matches_record` is `true`, and `divergence` says when it was redacted and that the text fingerprint, the times and the trail still match. The SHA-256 of a PDF sent before the redaction still answers `copy_matches: true`; the title and the signers read *Redacted*. |
| The signer's own link | No longer offers the signed copy. |

A webhook body is scrubbed where SignSealer keeps it, and a replay sends it scrubbed. What your receiver stored is out of our reach: redact your copy when `redacted_at` appears.

## Redacting a document yourself

This is how a signer's request to be forgotten is served, or how you act before the period ends. On the document's page in the dashboard, open **Redact the people from this document** and give a reason. Anyone on the team who can void a document can do it. There is no API route for it.

- **Only a finished document.** A draft, or one still out for signature, is refused: void it first.
- **The reason is kept.** It comes back as `redaction_reason` and goes on the audit trail, so name the request, not the person.
- **It cannot be undone.**

SignSealer is the processor here, so a signer who writes to us is pointed back to you.

## Legal holds

A hold takes one document, or every document a business has, out of the schedule while a matter is live. SignSealer places and lifts holds; there is no button or route for one. If you need one, write to [support@signsealer.com](mailto:support@signsealer.com).

- The sweep skips a held document, including after the account is closed, and redacting it by hand is refused.
- Nothing else stops. It can still be voided, expire and be read, and message bodies, webhook bodies and ID evidence images still go on their own clocks.
- Lifting a hold needs its own reason. A document already past its period is redacted at the next hourly sweep.

When SignSealer places or lifts a hold on your business, it is listed on [Activity](https://app.signsealer.com/activity), under *Who at SignSealer looked at your account*.

## Taking your records

An owner or admin can download everything the business holds as one JSON file, from [Settings](https://app.signsealer.com/settings#records) → **Download the records**: settings, team, templates, every document with its signers and evidence package, keys, webhooks and tablets by name (no secrets), every message sent (never its words) and the audit trail with its hash chain. Taking it goes on the trail. It does not carry the sealed PDFs: fetch those with `GET /v1/documents/{id}/pdf`.

## Closing the account

The owner closes a business from Settings by typing its name. It is refused while any document is still waiting for a signature, and a subscription is canceled at Stripe first. At once, every API key, tablet, webhook endpoint, invitation, connected app and workflow is revoked or switched off, and everybody but the owner loses access. Thirty days later the documents are redacted, with the closing date as the reason (one whose period ends sooner goes then), unless held. The certificates stay, and still verify for the people who signed.

> **Fetch the PDFs before you close.** From that moment the keys are revoked and the dashboard offers the owner the records download and nothing else. It is JSON; the sealed copies are not in it.

---

Source: https://signsealer.com/docs/branding (Branding and domains)

# Branding and domains

By default a signer opens SignSealer's page on signsealer.com, with the business's logo, when it has one, above the document. White label puts the business's name and colors on the page, and its own domains move the links and the mail onto hosts it owns. The host is the part that changes what the API hands you.

## What a business can set

All of it is set in [the dashboard](https://app.signsealer.com), under Settings → Brand, by an owner or an admin. The API reads it and has no route to change it.

| Setting | Shown with | Where it shows |
| --- | --- | --- |
| Logo for light backgrounds, PNG or SVG | Nothing | Above the document, at the head of the signed PDF, and at the top of mail (a PNG only: mail shows no SVG). |
| Sender name, reply address, a footer line | Nothing | Mail to signers. The footer line is on the signing page too with white label. |
| Name on the page, five colors, a logo for dark backgrounds, the tablet app's opening picture | White label | The signing page, public forms, the color of mail, and the tablet app. They can be set before white label is on, and are shown once it is. |
| An address on signsealer.com | White label | Signing links, at `yourbusiness.signsealer.com`; the business's slug unless it picks another. Chosen once white label is on, since choosing one claims the name. |
| Its own signing and sending domains | White label | Signing links, and the From address of mail. |

White label is an add-on to the membership, $25 a month drawn from credit, and not offered on Free ([pricing](https://signsealer.com/pricing)). A platform can put its own name on the businesses it brings, at no charge ([Platforms and partners](https://signsealer.com/docs/partners)).

## Where signing links point

Every link the engine sends for a business, by email or by text, and every `url` the API answers with, is on the first of these that applies:

1. A signing domain the business has verified: `https://sign.example.com/s/{token}`.
2. With white label on, its address on signsealer.com: `https://yourbusiness.signsealer.com/s/{token}`.
3. Otherwise `https://signsealer.com/s/{token}`.

A partner's branding does not change the host. `POST /v1/documents/{id}/send` answers a `url` per signer, as do the signer's `/embed` and `/link` routes: use it as given. `POST /v1/workflows/{id}/start` answers tokens only (with `send_link`, SignSealer sends the person theirs itself), so build the address from `signingHost`, and ask for it when you need it rather than storing it for good, because a newly verified domain moves it and white label starting or ending can:

```
const { signingHost } = await signsealer.branding();   // GET /v1/branding
const url = "https://" + signingHost + "/s/" + encodeURIComponent(token);
```

`GET /v1/workflows/{id}/qr` is the exception: it answers the form's address on signsealer.com, which keeps working; the same form also answers at `/f/…` on the business's own host.

A business's host serves only that business's signing links (`/s/`), party links (`/p/`), public forms (`/f/`), the certificate check (`/verify`), logos (`/brand/`) and a health check. Everything else is a 404 there, the API included: your calls, and the key-less signing routes a page of your own makes, go to `https://api.signsealer.com`. Another business's link on that host is a 404 too. A link on signsealer.com still opens after the business moves to its own host.

## Framing the page on your own site

The embed route's `url` ([Signing inside your product](https://signsealer.com/docs/embedding)) is on the signing host too, so check a message's origin against `new URL(url).origin`, never a fixed `https://signsealer.com`.

A verified signing domain lets the page be framed on that host and the hosts under it: `sign.example.com` adds `https://sign.example.com` and `https://*.sign.example.com` to `frame_origins`, not `www.example.com`. To frame it on your main site, prove `example.com` as a company sign-in domain or connect an app that lives there. An address on signsealer.com adds nothing. The same verified domain may take a `return_url` ([Waivers and workflows](https://signsealer.com/docs/waivers)).

## A signing domain of your own

With white label on, an owner or admin types a host under **Your own domains** (in Settings, and at the foot of Settings → Brand). Use a subdomain such as `sign.example.com`: a host that is a CNAME to us cannot also serve your own site. Then publish what the panel shows:

| Type | Name | Value |
| --- | --- | --- |
| TXT | `_signsealer.sign.example.com` | `signsealer-verify=` and the panel's token |
| CNAME | `sign.example.com` | The panel's target |

The checks run every few minutes, and the panel ticks off three stages:

| Stage | What it means |
| --- | --- |
| Proved | The TXT record carries the token. Nothing connects to your host before this. |
| Routed | We have added the host on our side, which is where its certificate comes from. |
| Serving | The host answered our health check over HTTPS. Signing links use it from now on. |

Under them the panel says what the last look found: no TXT record, one without the token, or a host that did not answer as us. A serving host is not checked again; leave the CNAME where it is.

A host is refused when it is signsealer.com or under it, when it is also the sending domain, or when another business has claimed it (write to us if it is yours). Changing it starts all three stages again, and until the new one serves, links go to the next host in the list above. An empty field withdraws it.

## Mail from your own domain

**Mail from**, in the same panel, takes a second subdomain such as `mail.example.com`, so its records leave your main domain's mail alone. We register it with our mail provider, and within a few minutes the panel lists the records to publish. It reads *checking* until the provider sees them, then *in use*; *records not found* means the provider reported a failure, and the panel gives the reason. A failed domain is asked about again hourly.

|  | Before | Once in use |
| --- | --- | --- |
| From | "Sender name via SignSealer" at SignSealer's address | "Sender name" <notifications@mail.example.com> |
| Reply-To | Your reply address, or ours | The same |

Only mail on the business's behalf changes; sign-in links, team invitations and billing mail stay SignSealer's. Inside the mail, the button goes to the signing host, and the logo and the certificate check (signsealer.com/verify) stay on SignSealer's.

## White label, and a partner's branding

|  | SignSealer's own | White label | A partner's branding |
| --- | --- | --- | --- |
| Bar of the signing page | SignSealer | Your dark logo, light logo or name | The partner's logo or name |
| Your light logo on the page | Above the document | In the bar, if there is no dark one | Not shown |
| Colours | SignSealer's | Yours | The partner's |
| Foot of the page | Signed with SignSealer | Your footer line | The partner's footer line, Powered by SignSealer |
| Last line of mail | Sent through SignSealer | None | Sent through the partner, powered by SignSealer |
| Signing links | signsealer.com | Your address on signsealer.com, or your own domain | signsealer.com |

A business's own white label wins over its partner's. Under all three, a business's texts go from its own toll-free or local number, registered under its own name, and that is coming soon ([Texting and consent](https://signsealer.com/docs/texting)); the certificate stays SignSealer's, checked at signsealer.com/verify: it is the evidence, not the branding.

## Reading the brand: GET /v1/branding

Scope `signing:read`; `signsealer.branding()` in the [Node client](https://signsealer.com/docs/sdk). It is what our tablet app themes itself with, and its keys are camelCase.

| Field | What it is |
| --- | --- |
| `businessName` | The name on the page while white label is on, else the business's name. |
| `whiteLabelEnabled` | Whether the add-on is on. |
| `primaryColor`, `accentColor`, `backgroundColor`, `textColor`, `buttonTextColor` | Hex, like `#124272`: the business's while white label is on, SignSealer's otherwise or where none is saved. |
| `hasLogo`, `hasDarkLogo`, `logoUrl`, `logoDarkUrl` | Whether a PNG of each is on file, and its address or null; the dark one only while white label is on. A logo uploaded only as an SVG reads false. |
| `hasOpening`, `openingType`, `openingUpdatedAt`, `openingUrl` | The tablet app's opening picture while white label is on; its address changes when it does. |
| `signingHost` | Where signing links point now. |
| `footerText`, `tenantId` | The footer line or null; the business. |

Without white label the answer is already SignSealer's look: the business's own name, our colours, no dark logo and no opening picture, even when the business has saved its own ready for the day it switches white label on. `whiteLabelEnabled` says which you have. Logos are public by address, `/brand/{tenantId}/logo.png` and `logo-dark.png` (or `.svg`), cached for an hour.

> **A partner's branding is not in it.** A business on its partner's branding answers `whiteLabelEnabled: false` and nothing of the partner's, though its signing page wears the partner's look.

## Webhooks

Nothing in a webhook changes with the brand or the host: a payload carries no link and never a token ([Webhooks](https://signsealer.com/docs/webhooks)). To put a signer in front of their page after an event, mint a link with the embed route, which answers it on the current host, or send a reminder, which carries a fresh one there.

---

Source: https://signsealer.com/docs/wordpress (WordPress plugin)

# WordPress plugin

One WordPress site, connected to one SignSealer business. The site's shop, forms and bookings start the signing; the signing happens on SignSealer, and the site keeps a document's id, its status and a link. Never the evidence.

This page is what happens underneath, as of version 1.17.1. For each integration's screens, step by step, follow the [WordPress guides](https://signsealer.com/wordpress), starting with [Getting started](https://signsealer.com/wordpress/getting-started).

## Requirements

- WordPress 6.4 or later (tested up to 7.1) and PHP 7.4 or later.
- The site on **https**: SignSealer registers only a site it can reach over https, and posts statuses back the same way.
- A WordPress administrator (`manage_options`) and a SignSealer account, which can be made while connecting.

Install it from [the WordPress.org directory](https://wordpress.org/plugins/signsealer/).

## Connecting

Under **SignSealer → Start here**, press **Connect to SignSealer**.

1. The plugin makes a one-time token, sends it to SignSealer to register the site (`POST /oauth/register`), and shows only its SHA-256 at `/wp-json/signsealer/v1/site`. SignSealer fetches that page over https and registers a client named *WordPress site* and your host only if the two match. That proves the site runs the plugin, not who runs the site, and the consent screen says **Not checked by SignSealer** for that reason.
2. You sign in to SignSealer and approve (OAuth with PKCE).
3. Back on Start here, the plugin reads the business's name and address (`GET /v1/account`), registers its own webhook endpoint, `/wp-json/signsealer/v1/webhook`, and keeps the secret SignSealer shows once. Start here says **Connected to** and the business's name. If either step fails, the plugin's screens try again, at most once a minute.

| Scope | Used for |
| --- | --- |
| `signing:read` | The business, its forms and templates, whether it can text, and whether somebody signed before an order or form goes through. |
| `signing:write` | Recording consent to be texted. |
| `signing:workflows` | Starting a workflow for an order, a submission or a booking. |
| `signing:webhooks` | Registering its endpoint, or a new secret for one already there. |

A scope the person approving does not hold is left out; **SignSealer → Settings** shows what was granted. In SignSealer the site is a row under [Integrations → Connected apps](https://app.signsealer.com/connections), and its endpoint, `WordPress:` and your host, subscribed to `"*"`, is under [Integrations → Webhooks](https://app.signsealer.com/webhooks).

The refresh token and the client's secret are in the `signsealer_connection` option, not autoloaded; the access token is a transient. SignSealer rotates the refresh token on each use and ends the connection if a used one comes back, so the plugin refreshes one request at a time. `SIGNSEALER_API_BASE` in `wp-config.php` points it at a partner's own host.

## The block and the shortcode

A button to sign a SignSealer form that has a public address. The block is **SignSealer agreement** (`signsealer/sign`), the shortcode `[signsealer_sign]`; both are drawn by the same code when the page is served.

| Attribute | In the block | What it is |
| --- | --- | --- |
| `workflow` | Form | Required. The form's public address, such as `kayak-waiver`, not its id. **SignSealer → Templates** lists the shortcode for each. |
| `label` | Button text | `Sign now` unless set. |
| `business` | Not offered | Another business's address, to link its form. The connected business's unless set. |

```
[signsealer_sign workflow="kayak-waiver" label="Sign the waiver"]
```

It is a link to `/f/{business}/{form}` on SignSealer, built without an API call. The visitor types their name and email there, and nothing is recorded in WordPress. Missing a `workflow` or a business address, it shows a visitor nothing and anyone who can edit posts a note. To style it yourself, choose **Your theme's buttons** under **SignSealer → Settings**; it carries the class `signsealer-button`.

Orders, form submissions and bookings each start a workflow instead (`POST /v1/workflows/{id}/start`); the guides cover their screens. Before payment, SignSealer's signing page is framed on a page of your site, which connecting the site allows ([Signing inside your product](https://signsealer.com/docs/embedding)).

## What it sends and keeps

| When | Sent to SignSealer |
| --- | --- |
| Every call | The access token, and `SignSealer-WordPress/{version}; {site address}` as the user agent. |
| A signing starts | The person's email, name and phone if known; the blanks the agreement asks, from the order, the form's fields, the booking or your answers; an `external_ref` such as `wc:{order}:{line item}`. |
| A box to be texted is ticked | The number, the words beside the box as shown, and which form or order on which site ([Texting and consent](https://signsealer.com/docs/texting)). |
| A document completes, and something here listens for its answers | A request for the document (`GET /v1/documents/{id}`), whose answers are handed on and not kept. If SignSealer cannot be reached it is tried again, five tries in about fifteen minutes. |
| An Uncanny Automator recipe uses SignSealer's trigger | Requests for your forms and, for the form chosen, the questions it asks, while the recipe is built and when it runs. |

It keeps, in options named `signsealer_…`, the connection, the webhook's secret, each integration's settings, and each document it started: its newest status and a map back to its order, entry or booking. An order keeps each line's document id, title, signing link and status (`_signsealer_documents`); a Gravity Forms, WPForms or Fluent Forms entry keeps its document. The wording of the questions an Automator recipe's form asks is kept in one transient, `signsealer_questions`: the newest twenty published template versions, until an hour passes without another being added.

## Hooks

| Hook | Arguments | Runs |
| --- | --- | --- |
| `signsealer_event` (action) | `$event`, `$payload` | After each verified webhook delivery. |
| `signsealer_document_completed` (action) | `$document`, with its answers | Once a document completes, from WP-Cron just after the delivery (1.17.0). |
| `signsealer_woocommerce_participant` | `$participant`, `$order`, `$item` | Before an order line's agreement starts. |
| `signsealer_woocommerce_presign_participant` | `$participant`, `$need`, `$key` (the cart line) | Before payment. A blank given a value here is not asked. |
| `signsealer_form_participant` | `$participant`, `$plugin`, `$form_id`, `$values` | Before a submission's agreement starts. `$plugin`: `gf`, `wpf`, `ff`, `cf7`, `frm`, `nf`, `srfm`, `fmn`, `mtf`, `evf`, `jfb`. |
| `signsealer_booking_participant` | `$participant`, `$plugin`, `$booking_id` | Before a booking's agreement starts. `$plugin`: `latepoint`, `amelia`, `ssa`, `tickets`, `em`, `wpbc`, `fb`, `mphb`, `bookly`. |
| `signsealer_starts_per_hour` | `$limit` (20) | Starts one visitor's address may make an hour; 0 for no limit. |
| `signsealer_visitor_ip` | `$ip` | The address that limit counts: `REMOTE_ADDR`, or empty from WP-CLI or cron. |
| `signsealer_admin_post`, `signsealer_admin_after_connection` (actions) | None | On SignSealer's admin screens, for your own settings. |

### A blank the plugin cannot fill

A participant is the workflow start's body: `email`, `full_name`, `external_ref`, `values` (text, keyed by blank), and `phone` and `return_url` when known. A filter can run more than once for one start, so only return the array. With WooCommerce Bookings, the plugin's own filter at priority 5 has already added `booking_date`, `booking_time`, `persons` and `resource`.

```
add_filter( 'signsealer_woocommerce_participant', function ( $participant, $order, $item ) {
    $vessel = (string) $order->get_meta( 'vessel_name' );
    if ( '' !== $vessel ) {
        $participant['values']['vessel_name'] = $vessel;
    }
    return $participant;
}, 10, 3 );
```

### Acting on an answer

A delivery never carries the answers to a form's questions; some are about somebody's health, and a webhook goes wherever it is pointed. When a document completes and something here is listening, the plugin asks SignSealer for them, just after the delivery has been answered, and fires `signsealer_document_completed`; if SignSealer cannot be reached it tries again, five tries in about fifteen minutes. The plugin keeps none of the answers. An Uncanny Automator recipe that runs on them is kept in Automator's own log, with its tokens, as every trigger's run is.

| Key | Holds |
| --- | --- |
| `answer` | One value per question, by its key. A tick box is `Yes` or `No`; a question several people answered (each person in a party) holds every different answer, sorted, joined with a comma; a sensitive answer is masked, as your staff see it. |
| `answers` | Each answer with its question, who gave it and who it is about. |
| `answers_text`, `flagged_text`, `flagged` | Every answer, one line each; the ones that want a person to read them; how many. |
| `document_id`, `workflow_id`, `title`, `external_ref` | Which document, from which form, and the reference it was sent with. |

```
add_action( 'signsealer_document_completed', function ( $document ) {
    if ( 'Yes' === ( $document['answer']['married'] ?? '' ) ) {
        // "Are you married?" was answered Yes.
    }
} );
```

`signsealer_get_answers( $document_id )` asks for a document's answers in the same shape. With **Uncanny Automator**, no code is needed: its trigger SignSealer → *A document from a form started anywhere is signed* takes a form or *Any form*, meaning any of your business's forms. With one form chosen, it can wait for one answer (“Are you married? → Yes”) and gives each question as a token; with *Any form*, it runs on whatever was answered and gives the answers together as *All answers (text)*. Left as *started anywhere*, it hears its form however the document was started; *started on this site* narrows it to the documents this site's own forms, orders and bookings started. It works in Automator's free edition; make one recipe per answer.

### Acting on a signature

The endpoint is subscribed to `"*"`, so the action also fires for documents this site did not start; `SignSealer_Webhook::ours( $doc_id )` says whether it did. Deliveries can arrive out of order: `SignSealer_Webhook::newest_status( $doc_id, $payload )` is the newest status known. `$payload` is the body as sent ([Webhooks](https://signsealer.com/docs/webhooks)); escape what you print from it.

```
add_action( 'signsealer_event', function ( $event, $payload ) {
    $doc = isset( $payload['document']['id'] ) ? (string) $payload['document']['id'] : '';
    if ( 'signing.completed' !== $event || '' === $doc || ! SignSealer_Webhook::ours( $doc ) ) {
        return;
    }
    wp_schedule_single_event( time(), 'mysite_agreement_signed', array( $doc ) );
}, 10, 2 );
```

> **A handler gets one chance.** The delivery is marked as seen before the action fires. If your handler fails, or the request outlasts the ten seconds SignSealer waits, the retry is answered as a repeat and your handler is not called again. Record what you need, and schedule the rest.

### The limit on visitors

Starts from the page before payment and from forms count against the visitor's address (IPv6 by its /64); orders, bookings and staff with `edit_others_posts` do not. Past the limit nothing is sent, and a form already sent keeps its entry with a note. Behind a proxy that hides visitors' addresses, return the one your proxy vouches for, never a header a visitor could write. A value that is not an IP address is not counted at all.

```
add_filter( 'signsealer_starts_per_hour', function () {
    return 50;
} );

// Your own proxy, at 10.0.0.5, sets X-Real-IP: trust it from there only.
add_filter( 'signsealer_visitor_ip', function ( $ip ) {
    if ( '10.0.0.5' === $ip && isset( $_SERVER['HTTP_X_REAL_IP'] ) ) {
        return sanitize_text_field( wp_unslash( $_SERVER['HTTP_X_REAL_IP'] ) );
    }
    return $ip;
} );
```

## How deliveries are checked

The endpoint is public, so everything rests on the check, made on the raw body in this order:

| Answer | Why |
| --- | --- |
| `503` `not configured` | The site holds no signing secret. |
| `400` `unsigned` | A `SignSealer-Event-Id`, `-Timestamp` or `-Signature` header is missing. |
| `400` `stale` | The timestamp is over five minutes from the site's clock. A server clock that far out fails every delivery. |
| `401` `bad signature` | No `v1=` value is the HMAC-SHA256 of `{timestamp}.{body}`. |
| `200`, `"repeat": true` | The same body within the hour: a retry, or a replay you asked for. Ignored. |
| `400` `not json` | The body is not JSON. |
| `200` | The status is kept and `signsealer_event` fires. |

A repeat is known by a SHA-256 of the body, which the signature covers. The status kept is the latest by `occurred_at`, so a late `signing.sent` cannot undo `signing.completed`.

## When something goes wrong

| It says | What happened |
| --- | --- |
| This site is not on https. | The site's address starts `http://`. Move it to https and connect again. |
| … did not show the token this attempt made | SignSealer could not read `/wp-json/signsealer/v1/site`; a firewall or security plugin blocking the REST API, say. Allow that address. |
| That connection attempt has expired. | More than thirty minutes between Connect and approving. Press Connect again. |
| Connected, but SignSealer did not answer when asked which business this is. | The business's address and the webhook are not set up yet, so the block shows nothing and no statuses arrive. Any SignSealer screen in WordPress asks again once a minute has passed: reload it then. Nothing needs forgetting. |
| Signed statuses will not arrive: … | The endpoint was not registered. If SignSealer already posts to this site, delete that endpoint under [Integrations → Webhooks](https://app.signsealer.com/webhooks), forget the connection and connect again. |
| SignSealer has ended this site's connection. | The refresh token was refused: ended under Connected apps, expired, or used twice. Nothing starts, and with Before payment the checkout stops. Connect again; settings stay. |
| Too many agreements have been started from your connection in the last hour. | The visitor passed `signsealer_starts_per_hour`. If every visitor shares one address, set `signsealer_visitor_ip`. |

When SignSealer refuses a start, its own sentence goes in the order's notes, the entry's notes where the form plugin keeps them, or on **SignSealer → Bookings** ([Errors](https://signsealer.com/docs/errors)).

## Deactivating, forgetting, deleting

| You | What happens |
| --- | --- |
| Deactivate | The connection is kept. The webhook address goes with the plugin, so deliveries fail meanwhile, and twenty in a row pause the endpoint. |
| **Forget the connection**, under Settings | The connection, the webhook's secret and the cached lists are forgotten, and deliveries refused. Every setting stays. |
| Delete | Every option and transient named `signsealer_` goes, on every site of a network. A product's agreement and what orders and entries carry stay. |

None of them ends the grant or removes the endpoint: do that under [Integrations → Connected apps](https://app.signsealer.com/connections) and [Integrations → Webhooks](https://app.signsealer.com/webhooks). The documents and their certificates were never in WordPress.

---

Source: https://signsealer.com/docs/integrations (Integrations)

# Integrations

A booking system sends SignSealer each reservation; the documents you chose for it decide what each guest signs; the guest is sent it. Nobody re-types a name, and nothing already sent is sent again.

| System | Kind | Status |
| --- | --- | --- |
| **[Guesty](https://signsealer.com/docs/integrations/guesty)** | Vacation rentals | Beta |
| **[Hostaway](https://signsealer.com/docs/integrations/hostaway)** | Vacation rentals | Beta |
| **[Hospitable](https://signsealer.com/docs/integrations/hospitable)** | Vacation rentals | Awaiting partner approval |
| **[Zapier](https://signsealer.com/docs/integrations/zapier)** | Automation | Beta |
| **[Make](https://signsealer.com/docs/integrations/make)** | Automation | Beta |
| **[Lodgify](https://signsealer.com/docs/integrations/lodgify)** | Vacation rentals | Beta |
| **[Hostfully](https://signsealer.com/docs/integrations/hostfully)** | Vacation rentals | Beta |
| **[HubSpot](https://signsealer.com/docs/integrations/hubspot)** | CRM | Planned |
| **[Zoho CRM](https://signsealer.com/docs/integrations/zoho-crm)** | CRM | Planned |
| **[Pipedrive](https://signsealer.com/docs/integrations/pipedrive)** | CRM | Planned |
| **[Salesforce](https://signsealer.com/docs/integrations/salesforce)** | CRM | Planned |
| **[Jobber](https://signsealer.com/docs/integrations/jobber)** | Field services | Planned |

**Beta** means a customer can connect it today, built against the provider's published API and tested against it on our side. **Awaiting partner approval** means it is built and the provider has to approve SignSealer before anyone can connect it. **Planned** means it cannot be connected yet. Most of those are built and wait on SignSealer's own app at the provider being approved and listed; each guide says where it has got to, and shows how to get the same result today with Zapier, Make or the API.

## The membership

Connecting a booking system comes with the membership, beside texting, passcodes, ID Evidence and white label ([pricing](https://signsealer.com/pricing)). The membership keeps the first 10 signings of each month free, however they arrive. On Free you still get 10 signings a month, sent from the dashboard. Zapier, Make and the API work on Free: they are the API, which every plan includes.

If the membership ends, each connection is paused rather than removed. It keeps recording what the provider sends, one waiting delivery per booking, and resumes by itself when the membership starts again, catching up on what changed meanwhile. A connection you paused yourself stays paused. From your own code, `GET
/v1/integrations` answers `needs_membership`, and a connection paused this way has `paused_reason: "membership"`.

## How a connection works

1. **You connect it** under [Integrations](https://app.signsealer.com/integrations) in the dashboard, with credentials you create in the provider. SignSealer checks them with the provider before keeping anything, then registers its webhook there when the provider allows that.
2. **The connection is a key.** Each connection owns an API key of its own, scoped to reservations and signing, whose secret nobody holds. Everything the integration does in your account is done as that key, through the same checks as the API, and the activity log names it. Disconnecting revokes it.
3. **The provider tells SignSealer.** Each connection has its own delivery address. A delivery is proven to be the provider's before anything in it is read — by signature where the provider signs, otherwise by the address's secret plus reading the booking back from the provider's API.
4. **The booking becomes a reservation.** A worker reads the booking as it is now, then writes the reservation, its guests and its packet, exactly as `PUT /v1/subjects` would.
5. **Its documents decide.** The documents chosen on the connection's page say what each guest owes, and the packet lists it. The connection sends it straight away or waits for you.

## What a document can print from the booking

A template sent for a booking can use these blanks, and SignSealer fills them from the record. An estimate, invoice, quote or deal that brings an amount can be accepted in so many words: *“I accept estimate {{document_number}} and agree to pay {{amount}}.”*

| Blank | What it prints | Example |
| --- | --- | --- |
| **`{{participant_name}}`** | The person signing, or the guest a guardian signs for | Dana Builder |
| **`{{activity_date}}`** | The booking's day, or the record's date | October 2, 2026 |
| **`{{amount}}`** | The total, as money | $4,250.00, or 980.00 EUR |
| **`{{amount_due}}`** | What is still owed, when the record says; otherwise the total | $450.00 |
| **`{{currency}}`** | The currency's code | USD |
| **`{{document_number}}`** | The estimate's, invoice's or quote's own number | 1042 |
| **`{{due_date}}`** | When an invoice is due | October 15, 2026 |
| **`{{expiry_date}}`** | When an estimate or quote runs out | November 1, 2026 |

A blank is filled only when the record has it. A template that prints `{{amount}}` is not sent for a record with no amount; the packet says which blank was missing. These are blanks, not the provider's own invoice: the signer reads your template's words with the record's figures in them.

## Secrets

A connection's credentials, the provider's webhook secret, the access token SignSealer was issued and the delivery address's token are sealed together with the same key that seals every other credential, and are never shown again after you enter them. The address token is kept as a hash for lookup; somebody who can manage the connection can read the address again, for when it has to be entered in the provider by hand.

## Texting and consent

Signing links go by email. They also go by text only when SignSealer holds that guest's consent to receive texts from your business, recorded with the exact words they agreed to — at your counter, on your booking form through `POST /v1/sms-consents`, or on SignSealer's own opt-in. That check runs when the link is queued (`app.may_text`), not in the integration.

No booking system can give SignSealer that consent, so none is treated as if it could. Each adapter records what the provider's data said — `VERIFIED_CONSENT`, `NO_CONSENT` or `INSUFFICIENT_EVIDENCE` — and only `NO_CONSENT` changes anything: the guest's number is not written at all. Every provider built so far can only ever say `INSUFFICIENT_EVIDENCE`. The connection's activity shows, for each guest with a number, whether the link was also texted and why not.

[How to record consent you took yourself](https://signsealer.com/docs/texting).

## Settings

| Setting | Choices | What it does |
| --- | --- | --- |
| **When a booking arrives** | Send straight away (default) · Build the list and wait | Straight away starts everything the packet owes as soon as the booking is worked. Waiting builds the reservation and its packet and sends nothing until somebody presses Send on the reservation, or your code calls `POST /v1/packets/{id}/start`. |
| **When a booking is canceled** | Void what nobody has signed (default) · Leave it | Voiding marks every unfinished document with the reason and the packet void. Anything already signed is kept: an executed waiver is evidence of what was agreed. |

What each guest is sent is decided by the connection's **documents for bookings**, chosen on its page: each says which document, who signs it — the person who booked, every adult, or a parent or guardian for each minor — and which bookings, read from the reservation's facts (dates, guest counts, property, channel). A default covers the bookings nothing else fits, and a booking that matched nothing says so in the connection's activity ([Reservations and packets](https://signsealer.com/docs/packets)).

## Duplicates, order and retries

- **Once.** A delivery is recorded once per connection and event id. A provider that redelivers the same event gets `200 {"duplicate": true}` and nothing happens twice.
- **Newest wins.** Each event means "read this booking as it is now". A newer event about a booking supersedes an older one still waiting, and one booking is never worked twice at once.
- **Nothing is sent twice.** Guests are recognized by their id in the provider (or by address and name), so an update keeps each guest's link to what they were already sent.
- **Retries.** A failure is retried after 1, 2, 4, 8 … minutes, up to six hours apart, and gives up after eight tries. It is then listed, with its reason, under the connection's activity, where it can be tried again once whatever refused it is fixed.
- **Refused credentials.** If the provider refuses SignSealer's credentials, the connection goes to *needs attention* and stops working events until new credentials are given. What arrives meanwhile is kept and worked afterwards.
- **Retention.** What arrived is cleared thirty days after it was worked; the outcome and the reservation it made are kept.

## Versions and deprecation

Each provider row records the version of SignSealer's connector and the provider API version it is built against, and each connection records what it last ran with. When a provider deprecates an API version we depend on, the provider's row carries the date it is deprecated and the date it goes away, the change is written to the activity log of every business connected to it, and it shows on the Integrations screen.

## Pausing and disconnecting

**Pause** keeps recording what arrives and works nothing until you resume. **New address** stops the old delivery address at once (and re-registers the webhook with the provider where SignSealer set it up). **Disconnect** revokes the connection's key, clears its credentials, removes the webhook from the provider where it can, and closes the address. The reservations and documents it made stay, with where they came from.

## From your own code

```
curl https://api.signsealer.com/v1/integrations -H "Authorization: Bearer $KEY"
curl https://api.signsealer.com/v1/integrations/$CONNECTION/events -H "Authorization: Bearer $KEY"
```

The first lists every provider with its status and your connections with their state; the second is what arrived from one connection and what became of it. Neither ever returns a credential, a delivery address or what arrived. Both need the `signing:read` scope. Connecting happens in the dashboard, where the provider confirms the credentials. See the [API reference](https://signsealer.com/docs/api).

## Zapier, Make and your own code

Every integration here is built on the public API. Anything these pages do, your code can do with `PUT /v1/subjects`, `POST /v1/packets/{id}/start`, `POST /v1/packets/{id}/void` and [webhooks](https://signsealer.com/docs/webhooks) — [Reservations and packets](https://signsealer.com/docs/packets) walks through it.

---

Source: https://signsealer.com/docs/integrations/guesty (Guesty)

# Guesty

A confirmed booking in Guesty sends the guest your rental agreement and the waivers that property needs, and you see who has signed before they reach the door.

> **Beta.** It is built against Guesty's published Open API and tested against it on our side; it has not yet run against a live Guesty account. It uses the Open API credentials you create yourself, which needs no partnership — the Guesty Marketplace listing is a separate program we have not joined yet. Links go by email. They go by text only to a guest whose consent to receive texts from you is on file in SignSealer: a booking system knowing a phone number is not that guest agreeing to be texted, and SignSealer never treats it as if it were. Texts go from your business's own number, which is coming soon.

## Before you start

- The membership: connecting a booking system comes with it ([how that works](https://signsealer.com/docs/integrations)). On Free, your 10 signings a month are sent from the dashboard.
- A SignSealer account, with the terms signed, and a published form for each document you want signed.
- Admin access to your Guesty account, to create an OAuth application.
- Once it is connected, documents chosen on its page for what each stay needs — a rental agreement for the person who booked at least.

## Connect Guesty

1. In Guesty, open **Integrations → Developer tools → OAuth applications** and create a new application named SignSealer. Copy the **client ID** and the **client secret** (Guesty shows the secret once).
2. In SignSealer, open [Integrations](https://app.signsealer.com/integrations), choose **Guesty → Connect**, and paste both.
3. Choose whether bookings send straight away and whether a cancellation voids what is unsigned, then press **Connect Guesty**.
4. SignSealer asks Guesty for a token with those credentials (proving them), registers its webhook for `reservation.created.v2` and `reservation.updated.v2`, and fetches the webhook's signing secret. You land on the connection's page.
5. Make or change a test reservation in Guesty and watch it arrive under the connection's activity.

## What SignSealer sets up in Guesty

One webhook subscription (`POST /v1/webhooks` in Guesty's Open API) pointing at this connection's delivery address, for the two v2 reservation events. Guesty's legacy reservation events are being phased out by the end of 2026, which is why only the v2 events are used. Disconnecting deletes the subscription; a new address re-registers it.

## What comes across

| Guesty | In SignSealer | Notes |
| --- | --- | --- |
| **_id** | Reservation external ID | Keys the reservation, so every update is the same reservation |
| **confirmationCode, listing.title** | Label | “Harbour Cottage · GY-100” |
| **checkInDateLocalized / checkOutDateLocalized** | Starts on / ends on | The property's own dates; minority is judged on check-in |
| **guest.firstName + lastName, email, phone** | Primary guest | Recognized on update by the Guesty guest ID |
| **guestsCount, numberOfGuests** | Facts: guests, adults, minors |  |
| **integration.platform or source** | Fact: channel | airbnb2, homeaway, manual … |
| **listingId** | Facts: property, property_name |  |
| **status** | What happens | confirmed / checked in: worked · inquiry, reserved: ignored · canceled, declined, expired: canceled |

## Documents that read it

The reservation carries these facts, which a document's *Only bookings where* can read: `guests`, `adults`, `minors`, `channel`, `property` and `property_name`. For example, a waiver for every adult on stays with more than six guests is *Each adult*, *Only bookings where* guests *is more than* 6.

Documents are chosen under **Documents for bookings** on the connection's page in [Integrations](https://app.signsealer.com/integrations) (there is no API route for them yet); see [Reservations and packets](https://signsealer.com/docs/packets).

## How a delivery is proven

Guesty signs each delivery with Svix: `svix-id`, `svix-timestamp` and `svix-signature`, an HMAC-SHA256 of the id, timestamp and exact body under the endpoint's own secret. SignSealer checks it in constant time, refuses a timestamp more than five minutes away, and only then reads the body. The reservation event carries no guest details, so SignSealer then reads the reservation and guest from Guesty's API. Guest events (`guest.*`) are accepted and ignored.

## Settings

| Setting | Choices | What it does |
| --- | --- | --- |
| **When a booking arrives** | Send straight away (default) · Build the list and wait | Straight away starts everything the packet owes as soon as the booking is worked. Waiting builds the reservation and its packet and sends nothing until somebody presses Send on the reservation, or your code calls `POST /v1/packets/{id}/start`. |
| **When a booking is canceled** | Void what nobody has signed (default) · Leave it | Voiding marks every unfinished document with the reason and the packet void. Anything already signed is kept: an executed waiver is evidence of what was agreed. |

What each guest is sent is decided by the connection's **documents for bookings**, chosen on its page: each says which document, who signs it — the person who booked, every adult, or a parent or guardian for each minor — and which bookings, read from the reservation's facts (dates, guest counts, property, channel). A default covers the bookings nothing else fits, and a booking that matched nothing says so in the connection's activity ([Reservations and packets](https://signsealer.com/docs/packets)).

## Texting and consent

Signing links go by email. They also go by text only when SignSealer holds that guest's consent to receive texts from your business, recorded with the exact words they agreed to — at your counter, on your booking form through `POST /v1/sms-consents`, or on SignSealer's own opt-in. That check runs when the link is queued (`app.may_text`), not in the integration.

No booking system can give SignSealer that consent, so none is treated as if it could. Each adapter records what the provider's data said — `VERIFIED_CONSENT`, `NO_CONSENT` or `INSUFFICIENT_EVIDENCE` — and only `NO_CONSENT` changes anything: the guest's number is not written at all. Every provider built so far can only ever say `INSUFFICIENT_EVIDENCE`. The connection's activity shows, for each guest with a number, whether the link was also texted and why not.

[How to record consent you took yourself](https://signsealer.com/docs/texting).

## Duplicates, order and retries

- **Once.** A delivery is recorded once per connection and event id. A provider that redelivers the same event gets `200 {"duplicate": true}` and nothing happens twice.
- **Newest wins.** Each event means "read this booking as it is now". A newer event about a booking supersedes an older one still waiting, and one booking is never worked twice at once.
- **Nothing is sent twice.** Guests are recognized by their id in the provider (or by address and name), so an update keeps each guest's link to what they were already sent.
- **Retries.** A failure is retried after 1, 2, 4, 8 … minutes, up to six hours apart, and gives up after eight tries. It is then listed, with its reason, under the connection's activity, where it can be tried again once whatever refused it is fixed.
- **Refused credentials.** If the provider refuses SignSealer's credentials, the connection goes to *needs attention* and stops working events until new credentials are given. What arrives meanwhile is kept and worked afterwards.
- **Retention.** What arrived is cleared thirty days after it was worked; the outcome and the reservation it made are kept.

## Troubleshooting

| What you see | Why | What to do |
| --- | --- | --- |
| **“Guesty refused our credentials” when connecting** | The client ID or secret is wrong, or the application was deleted | Create the application again in Guesty and paste the new pair |
| **Connection says needs attention** | Guesty stopped accepting the credentials (rotated or deleted) | Paste new credentials on the connection's page; waiting reservations are then worked |
| **An inquiry never arrives as a reservation** | Inquiries and holds are not bookings | It is worked when Guesty marks it confirmed |
| **Deliveries refused (401) in Guesty's webhook log** | The signing secret changed because the subscription was re-created outside SignSealer | Press New address on the connection; SignSealer re-registers and keeps the new secret |
| **A guest got nothing** | The guest has no email in Guesty, or no document fits the booking | The activity names the guest and the reason, or says nothing fitted; add the email in Guesty, or a document for the booking (a default catches the rest) |

## Guesty's limits

Guesty allows five tokens per OAuth application per day and a token lasts 24 hours, so SignSealer keeps its token sealed and reuses it until ten minutes before it runs out. Guesty rate-limits the Open API per account (15 per second, 120 per minute, 5,000 per hour, shared across every tool using your account); SignSealer makes one read per reservation change. Guesty retries a failed delivery on a schedule up to about a day and a half, and disables an endpoint after five days of failures.

## Guesty Marketplace

This connection uses Guesty's Open API with credentials you issue. Guesty asks Marketplace partners not to use Open API credentials (and Marketplace keys do not work with the Open API), so the Marketplace listing will be a separate connection when SignSealer joins it.

## Pausing and disconnecting

**Pause** keeps recording what arrives and works nothing until you resume. **New address** stops the old delivery address at once (and re-registers the webhook with the provider where SignSealer set it up). **Disconnect** revokes the connection's key, clears its credentials, removes the webhook from the provider where it can, and closes the address. The reservations and documents it made stay, with where they came from.

## From your own code

```
curl https://api.signsealer.com/v1/integrations -H "Authorization: Bearer $KEY"
curl https://api.signsealer.com/v1/integrations/$CONNECTION/events -H "Authorization: Bearer $KEY"
```

The first lists every provider with its status and your connections with their state; the second is what arrived from one connection and what became of it. Neither ever returns a credential, a delivery address or what arrived. Both need the `signing:read` scope. Connecting happens in the dashboard, where the provider confirms the credentials. See the [API reference](https://signsealer.com/docs/api).

---

Source: https://signsealer.com/docs/integrations/hostaway (Hostaway)

# Hostaway

Each new Hostaway reservation sends the guest the agreement and waivers that listing needs, re-read from Hostaway so what they sign matches the booking.

> **Beta.** Built against Hostaway's published Public API and tested against it on our side, not yet with a live Hostaway account. It needs no partnership: the key is one you create. Listing on the Hostaway Marketplace is a separate certification we have not started. Links go by email. They go by text only to a guest whose consent to receive texts from you is on file in SignSealer: a booking system knowing a phone number is not that guest agreeing to be texted, and SignSealer never treats it as if it were. Texts go from your business's own number, which is coming soon.

## Before you start

- The membership: connecting a booking system comes with it ([how that works](https://signsealer.com/docs/integrations)). On Free, your 10 signings a month are sent from the dashboard.
- A SignSealer account with the terms signed and a published form for each document.
- Access to Hostaway's settings, to create an API key.
- Once it is connected, documents chosen on its page for what each listing's bookings need.

## Connect Hostaway

1. In Hostaway, open **Settings → Hostaway API** and press **Create**. Choose **Hostaway Public API** as the partner. Copy your **account ID** and the **API key**.
2. In SignSealer, open [Integrations](https://app.signsealer.com/integrations), choose **Hostaway → Connect**, and paste both.
3. Choose the settings and press **Connect Hostaway**. SignSealer exchanges the key for a token (proving it) and registers a unified webhook with a login and password it made for this connection.
4. Make a test reservation in Hostaway and watch it arrive under the connection's activity.

## What SignSealer sets up in Hostaway

One unified webhook (`POST /v1/webhooks/unifiedWebhooks`) pointing at this connection's delivery address, with a Basic Auth login and password generated for it. Hostaway sends reservation created, reservation updated and new-message events to it; messages are accepted and ignored.

## What comes across

| Hostaway | In SignSealer | Notes |
| --- | --- | --- |
| **id** | Reservation external ID |  |
| **listingName, channelReservationId** | Label |  |
| **arrivalDate / departureDate** | Starts on / ends on |  |
| **guestFirstName + guestLastName, guestEmail, phone** | Primary guest | Recognized on update by the Hostaway guest ID |
| **numberOfGuests, adults, children, pets** | Facts: guests, adults, minors, pets |  |
| **channelName or source** | Fact: channel |  |
| **listingMapId** | Facts: property, property_name |  |
| **status** | What happens | new, modified: worked · inquiry, pending, owner stays: ignored · canceled, declined, expired: canceled |

## Documents that read it

The reservation carries these facts, which a document's *Only bookings where* can read: `guests`, `adults`, `minors`, `pets`, `channel`, `property` and `property_name`. For example, a waiver for every adult on stays with more than six guests is *Each adult*, *Only bookings where* guests *is more than* 6.

Documents are chosen under **Documents for bookings** on the connection's page in [Integrations](https://app.signsealer.com/integrations) (there is no API route for them yet); see [Reservations and packets](https://signsealer.com/docs/packets).

## How a delivery is proven

Hostaway does not sign its webhooks. SignSealer registers the webhook with a login and password of its own and refuses any delivery without them (compared in constant time), at an address whose 64-character token is itself a secret. Neither proves the delivery's contents, so the delivery is used only to learn which reservation changed, and the reservation is always read back from Hostaway's API. A forged delivery can at most make SignSealer re-read one of your own reservations. Hostaway also delivers from fixed addresses; SignSealer does not rely on them.

## Settings

| Setting | Choices | What it does |
| --- | --- | --- |
| **When a booking arrives** | Send straight away (default) · Build the list and wait | Straight away starts everything the packet owes as soon as the booking is worked. Waiting builds the reservation and its packet and sends nothing until somebody presses Send on the reservation, or your code calls `POST /v1/packets/{id}/start`. |
| **When a booking is canceled** | Void what nobody has signed (default) · Leave it | Voiding marks every unfinished document with the reason and the packet void. Anything already signed is kept: an executed waiver is evidence of what was agreed. |

What each guest is sent is decided by the connection's **documents for bookings**, chosen on its page: each says which document, who signs it — the person who booked, every adult, or a parent or guardian for each minor — and which bookings, read from the reservation's facts (dates, guest counts, property, channel). A default covers the bookings nothing else fits, and a booking that matched nothing says so in the connection's activity ([Reservations and packets](https://signsealer.com/docs/packets)).

## Texting and consent

Signing links go by email. They also go by text only when SignSealer holds that guest's consent to receive texts from your business, recorded with the exact words they agreed to — at your counter, on your booking form through `POST /v1/sms-consents`, or on SignSealer's own opt-in. That check runs when the link is queued (`app.may_text`), not in the integration.

No booking system can give SignSealer that consent, so none is treated as if it could. Each adapter records what the provider's data said — `VERIFIED_CONSENT`, `NO_CONSENT` or `INSUFFICIENT_EVIDENCE` — and only `NO_CONSENT` changes anything: the guest's number is not written at all. Every provider built so far can only ever say `INSUFFICIENT_EVIDENCE`. The connection's activity shows, for each guest with a number, whether the link was also texted and why not.

[How to record consent you took yourself](https://signsealer.com/docs/texting).

## Duplicates, order and retries

- **Once.** A delivery is recorded once per connection and event id. A provider that redelivers the same event gets `200 {"duplicate": true}` and nothing happens twice.
- **Newest wins.** Each event means "read this booking as it is now". A newer event about a booking supersedes an older one still waiting, and one booking is never worked twice at once.
- **Nothing is sent twice.** Guests are recognized by their id in the provider (or by address and name), so an update keeps each guest's link to what they were already sent.
- **Retries.** A failure is retried after 1, 2, 4, 8 … minutes, up to six hours apart, and gives up after eight tries. It is then listed, with its reason, under the connection's activity, where it can be tried again once whatever refused it is fixed.
- **Refused credentials.** If the provider refuses SignSealer's credentials, the connection goes to *needs attention* and stops working events until new credentials are given. What arrives meanwhile is kept and worked afterwards.
- **Retention.** What arrived is cleared thirty days after it was worked; the outcome and the reservation it made are kept.

## Troubleshooting

| What you see | Why | What to do |
| --- | --- | --- |
| **“Hostaway refused our credentials”** | The account ID or key is wrong, or the key was deleted | Create a new key for Hostaway Public API and paste it |
| **Needs attention after it worked** | The key was revoked in Hostaway | Paste a new key on the connection's page |
| **Deliveries show 401 in Hostaway** | The webhook was edited in Hostaway and lost SignSealer's login | Press New address; SignSealer registers a fresh webhook with a new login |
| **A guest got nothing** | No email on the reservation, or no document fits the booking | The activity names the guest and the reason, or says nothing fitted |

## Hostaway's limits

Hostaway allows 200 requests per 10 seconds per account; SignSealer makes one read per reservation change and keeps its token, which Hostaway issues for months, sealed. Hostaway retries a delivery up to three times within about an hour, only after a network error, a 5xx or a 429, and treats other 4xx answers as final; SignSealer answers 200 as soon as a delivery is recorded.

## Pausing and disconnecting

**Pause** keeps recording what arrives and works nothing until you resume. **New address** stops the old delivery address at once (and re-registers the webhook with the provider where SignSealer set it up). **Disconnect** revokes the connection's key, clears its credentials, removes the webhook from the provider where it can, and closes the address. The reservations and documents it made stay, with where they came from.

## From your own code

```
curl https://api.signsealer.com/v1/integrations -H "Authorization: Bearer $KEY"
curl https://api.signsealer.com/v1/integrations/$CONNECTION/events -H "Authorization: Bearer $KEY"
```

The first lists every provider with its status and your connections with their state; the second is what arrived from one connection and what became of it. Neither ever returns a credential, a delivery address or what arrived. Both need the `signing:read` scope. Connecting happens in the dashboard, where the provider confirms the credentials. See the [API reference](https://signsealer.com/docs/api).

---

Source: https://signsealer.com/docs/integrations/lodgify (Lodgify)

# Lodgify

A booked stay in Lodgify sends the guest the agreement and waivers that property needs, read back from Lodgify so what they sign matches the booking.

> **Beta.** Built against Lodgify's published API and webhook documentation and tested against stand-ins on our side, not yet run against a live Lodgify account, which is why it is beta. It needs no partnership: the key is one you copy from your own account. That key reads and writes all of Lodgify; SignSealer uses it only to read properties and bookings and to manage its own webhooks. Links go by email. They go by text only to a guest whose consent to receive texts from you is on file in SignSealer: a booking system knowing a phone number is not that guest agreeing to be texted, and SignSealer never treats it as if it were. Texts go from your business's own number, which is coming soon.

## Before you start

- The membership: connecting a booking system comes with it ([how that works](https://signsealer.com/docs/integrations)). On Free, your 10 signings a month are sent from the dashboard.
- A SignSealer account with the terms signed and a published form for each document.
- Access to your Lodgify account's settings, to copy its API key.
- Once it is connected, documents chosen on its page for what each property's bookings need.

## Connect Lodgify

1. In Lodgify, open **Settings → Public API** and copy the **API key** shown there. It opens your whole Lodgify account, so treat it like a password.
2. In SignSealer, open [Integrations](https://app.signsealer.com/integrations), choose **Lodgify → Connect**, and paste the key.
3. Choose the settings and press **Connect Lodgify**. SignSealer reads your properties with the key (proving it), then subscribes its webhooks in Lodgify for you.
4. Make a test booking in Lodgify, mark it Booked, and watch it arrive under the connection's activity.

## What SignSealer sets up in Lodgify

Four webhook subscriptions (`POST /webhooks/v1/subscribe`), one each for `booking_new_status_booked`, `booking_status_change_booked`, `booking_change` and `booking_status_change_declined`. Lodgify wants a different address for each subscription, so each is this connection's delivery address with `?event=` and the event's name after it. Lodgify gives each subscription its own signing secret, once, and SignSealer seals all four. Enquiries are not subscribed to. If one subscription is refused while connecting, the ones already made are removed again. Disconnecting unsubscribes all four; a new address subscribes them again.

## What comes across

| Lodgify | In SignSealer | Notes |
| --- | --- | --- |
| **id** | Reservation external ID | Keys the reservation, so every update is the same reservation |
| **property_id, and the property's name** | Label, and facts: property, property_name | “Fjord House · #880011”; the name is read from the property when the booking does not carry it |
| **arrival / departure** | Starts on / ends on |  |
| **guest name, email, phone** | Primary guest | Recognized on update by the Lodgify guest ID |
| **guest breakdown: adults, children, infants, pets; each room's people** | Facts: guests, adults, minors, pets | Children and infants are both minors; a booking of several rooms is added up |
| **source** | Fact: channel | Where it was booked, as Lodgify names it (AirbnbIntegration …) |
| **status** | What happens | Booked: worked · Open (an enquiry), Tentative: ignored · Declined: canceled |

## Documents that read it

The reservation carries these facts, which a document's *Only bookings where* can read: `guests`, `adults`, `minors`, `pets`, `channel`, `property` and `property_name`. For example, a waiver for every adult on stays with more than six guests is *Each adult*, *Only bookings where* guests *is more than* 6.

Documents are chosen under **Documents for bookings** on the connection's page in [Integrations](https://app.signsealer.com/integrations) (there is no API route for them yet); see [Reservations and packets](https://signsealer.com/docs/packets).

## How a delivery is proven

Lodgify signs each delivery with an `ms-signature` header: `sha256=` and the HMAC-SHA256 of the exact body under that subscription's secret, in upper-case hex. SignSealer checks it in constant time against each of the connection's secrets, and only then reads the body. It carries no timestamp and Lodgify gives a delivery no id, so the event is the booking and the exact bytes: a redelivery is a duplicate, and a replay can at most make SignSealer re-read one of your own bookings, because the booking is always read back from Lodgify's API (`GET /v2/reservations/bookings/{id}`) before anything is built from it. Signed events that are not about a booking are accepted and ignored.

## Settings

| Setting | Choices | What it does |
| --- | --- | --- |
| **When a booking arrives** | Send straight away (default) · Build the list and wait | Straight away starts everything the packet owes as soon as the booking is worked. Waiting builds the reservation and its packet and sends nothing until somebody presses Send on the reservation, or your code calls `POST /v1/packets/{id}/start`. |
| **When a booking is canceled** | Void what nobody has signed (default) · Leave it | Voiding marks every unfinished document with the reason and the packet void. Anything already signed is kept: an executed waiver is evidence of what was agreed. |

What each guest is sent is decided by the connection's **documents for bookings**, chosen on its page: each says which document, who signs it — the person who booked, every adult, or a parent or guardian for each minor — and which bookings, read from the reservation's facts (dates, guest counts, property, channel). A default covers the bookings nothing else fits, and a booking that matched nothing says so in the connection's activity ([Reservations and packets](https://signsealer.com/docs/packets)).

## Texting and consent

Signing links go by email. They also go by text only when SignSealer holds that guest's consent to receive texts from your business, recorded with the exact words they agreed to — at your counter, on your booking form through `POST /v1/sms-consents`, or on SignSealer's own opt-in. That check runs when the link is queued (`app.may_text`), not in the integration.

No booking system can give SignSealer that consent, so none is treated as if it could. Each adapter records what the provider's data said — `VERIFIED_CONSENT`, `NO_CONSENT` or `INSUFFICIENT_EVIDENCE` — and only `NO_CONSENT` changes anything: the guest's number is not written at all. Every provider built so far can only ever say `INSUFFICIENT_EVIDENCE`. The connection's activity shows, for each guest with a number, whether the link was also texted and why not.

[How to record consent you took yourself](https://signsealer.com/docs/texting).

## Duplicates, order and retries

- **Once.** A delivery is recorded once per connection and event id. A provider that redelivers the same event gets `200 {"duplicate": true}` and nothing happens twice.
- **Newest wins.** Each event means "read this booking as it is now". A newer event about a booking supersedes an older one still waiting, and one booking is never worked twice at once.
- **Nothing is sent twice.** Guests are recognized by their id in the provider (or by address and name), so an update keeps each guest's link to what they were already sent.
- **Retries.** A failure is retried after 1, 2, 4, 8 … minutes, up to six hours apart, and gives up after eight tries. It is then listed, with its reason, under the connection's activity, where it can be tried again once whatever refused it is fixed.
- **Refused credentials.** If the provider refuses SignSealer's credentials, the connection goes to *needs attention* and stops working events until new credentials are given. What arrives meanwhile is kept and worked afterwards.
- **Retention.** What arrived is cleared thirty days after it was worked; the outcome and the reservation it made are kept.

## Troubleshooting

| What you see | Why | What to do |
| --- | --- | --- |
| **“Lodgify refused our credentials” when connecting** | The key is wrong, or was replaced in Lodgify | Copy the key again from Settings → Public API and paste it |
| **Needs attention after it worked** | Lodgify stopped accepting the key | Paste the current key on the connection's page; waiting bookings are then worked |
| **An enquiry or a tentative booking never arrives as a reservation** | Only booked stays are bookings | It is worked when Lodgify marks it Booked |
| **Deliveries refused (401)** | The subscriptions were changed outside SignSealer, so their secrets are not the ones SignSealer holds | Press New address; SignSealer subscribes again and keeps the new secrets |
| **A guest got nothing** | No email on the booking, or no document fits the booking | The activity names the guest and the reason, or says nothing fitted |

## Lodgify's limits

Lodgify allows 750 requests a minute on its v2 API. SignSealer reads each booking once per change, and the property once more when the booking does not name it. Lodgify retries a delivery that is not answered 200, up to ten times, and may remove a subscription that keeps failing; SignSealer answers 200 as soon as a booking's delivery is recorded. Lodgify's API key reads and writes the whole account; SignSealer uses it only to read properties and bookings and to manage its own webhook subscriptions.

## Pausing and disconnecting

**Pause** keeps recording what arrives and works nothing until you resume. **New address** stops the old delivery address at once (and re-registers the webhook with the provider where SignSealer set it up). **Disconnect** revokes the connection's key, clears its credentials, removes the webhook from the provider where it can, and closes the address. The reservations and documents it made stay, with where they came from.

## From your own code

```
curl https://api.signsealer.com/v1/integrations -H "Authorization: Bearer $KEY"
curl https://api.signsealer.com/v1/integrations/$CONNECTION/events -H "Authorization: Bearer $KEY"
```

The first lists every provider with its status and your connections with their state; the second is what arrived from one connection and what became of it. Neither ever returns a credential, a delivery address or what arrived. Both need the `signing:read` scope. Connecting happens in the dashboard, where the provider confirms the credentials. See the [API reference](https://signsealer.com/docs/api).

---

Source: https://signsealer.com/docs/integrations/hostfully (Hostfully)

# Hostfully

Each booking in Hostfully sends the guest the agreement and waivers that property needs, read back from Hostfully so what they sign matches the booking.

> **Beta.** Built against Hostfully's published API documentation and tested against stand-ins on our side, which is what beta means here: it has not yet run against a live Hostfully account. It uses the API key from your own Agency Settings, which Hostfully shows on plans that include API access; a listing in Hostfully's Integration Zone is a separate program we have not joined. Links go by email. They go by text only to a guest whose consent to receive texts from you is on file in SignSealer: a booking system knowing a phone number is not that guest agreeing to be texted, and SignSealer never treats it as if it were. Texts go from your business's own number, which is coming soon.

## Before you start

- The membership: connecting a booking system comes with it ([how that works](https://signsealer.com/docs/integrations)). On Free, your 10 signings a month are sent from the dashboard.
- A SignSealer account with the terms signed and a published form for each document.
- A Hostfully plan that includes API access. Hostfully shows the API key under Agency Settings only then; its billing team adds it.
- Once it is connected, documents chosen on its page for what each property's bookings need.

## Connect Hostfully

1. In Hostfully, open **Agency Settings**. Copy the **API key**, under API, and the **agency UID**, at the bottom of the page.
2. In SignSealer, open [Integrations](https://app.signsealer.com/integrations), choose **Hostfully → Connect**, and paste both.
3. Choose the settings and press **Connect Hostfully**. SignSealer reads your agency from Hostfully with the key, which proves the key and the UID together, then registers its webhooks on the agency.
4. Make a test booking in Hostfully and watch it arrive under the connection's activity.

## What SignSealer sets up in Hostfully

Three webhooks (`POST /api/v3/webhooks`) on your agency, one each for `NEW_BOOKING`, `BOOKING_UPDATED` and `BOOKING_CANCELLED`, sending JSON to this connection's delivery address. If Hostfully refuses one, those already made are deleted again and nothing is connected. Disconnecting deletes all three; a new address deletes them and registers three more.

## What comes across

| Hostfully | In SignSealer | Notes |
| --- | --- | --- |
| **uid** | Reservation external ID | The lead's UID, so every update is the same reservation |
| **property name, externalBookingId** | Label | “Lighthouse Cabin · HA-77120”; the name is read from the property, and the start of the UID stands in for a missing booking ID |
| **checkInLocalDateTime / checkOutLocalDateTime** | Starts on / ends on | The property's own dates |
| **guestInformation: firstName + lastName, email, cellPhoneNumber or phoneNumber** | Primary guest | Hostfully gives a lead's guest no ID of their own; they are the lead's primary guest on every update |
| **adultCount, childrenCount, infantCount, petCount** | Facts: guests, adults, minors, pets | Guests counts adults, children and infants; minors counts children and infants |
| **channel, or source where there is no channel** | Fact: channel | Lower-cased: airbnb, vrbo, booking_com, hostfully … |
| **propertyUid** | Facts: property, property_name |  |
| **status** | What happens | BOOKED: worked · inquiries (NEW, ON_HOLD, CLOSED), booking requests (PENDING, DECLINED) and blocks: ignored · CANCELED: canceled |

## Documents that read it

The reservation carries these facts, which a document's *Only bookings where* can read: `guests`, `adults`, `minors`, `pets`, `channel`, `property` and `property_name`. For example, a waiver for every adult on stays with more than six guests is *Each adult*, *Only bookings where* guests *is more than* 6.

Documents are chosen under **Documents for bookings** on the connection's page in [Integrations](https://app.signsealer.com/integrations) (there is no API route for them yet); see [Reservations and packets](https://signsealer.com/docs/packets).

## How a delivery is proven

Hostfully does not sign its webhooks, and a delivery carries only the agency, the event, the lead's UID and its property's UID. The 64-character token in the delivery address is the secret; the delivery is used only to learn which lead changed, and the lead is always read back from Hostfully's API with your key before anything is built from it. A forged delivery can at most make SignSealer re-read one of your own bookings. Other events, such as messages, are accepted and ignored. Hostfully sends the same words for every change to a lead, so a delivery counts as a repeat only when it arrives in the same second as the one before; a later one is always read.

## Settings

| Setting | Choices | What it does |
| --- | --- | --- |
| **When a booking arrives** | Send straight away (default) · Build the list and wait | Straight away starts everything the packet owes as soon as the booking is worked. Waiting builds the reservation and its packet and sends nothing until somebody presses Send on the reservation, or your code calls `POST /v1/packets/{id}/start`. |
| **When a booking is canceled** | Void what nobody has signed (default) · Leave it | Voiding marks every unfinished document with the reason and the packet void. Anything already signed is kept: an executed waiver is evidence of what was agreed. |

What each guest is sent is decided by the connection's **documents for bookings**, chosen on its page: each says which document, who signs it — the person who booked, every adult, or a parent or guardian for each minor — and which bookings, read from the reservation's facts (dates, guest counts, property, channel). A default covers the bookings nothing else fits, and a booking that matched nothing says so in the connection's activity ([Reservations and packets](https://signsealer.com/docs/packets)).

## Texting and consent

Signing links go by email. They also go by text only when SignSealer holds that guest's consent to receive texts from your business, recorded with the exact words they agreed to — at your counter, on your booking form through `POST /v1/sms-consents`, or on SignSealer's own opt-in. That check runs when the link is queued (`app.may_text`), not in the integration.

No booking system can give SignSealer that consent, so none is treated as if it could. Each adapter records what the provider's data said — `VERIFIED_CONSENT`, `NO_CONSENT` or `INSUFFICIENT_EVIDENCE` — and only `NO_CONSENT` changes anything: the guest's number is not written at all. Every provider built so far can only ever say `INSUFFICIENT_EVIDENCE`. The connection's activity shows, for each guest with a number, whether the link was also texted and why not.

[How to record consent you took yourself](https://signsealer.com/docs/texting).

## Duplicates, order and retries

- **Once.** A delivery is recorded once per connection and event id. A provider that redelivers the same event gets `200 {"duplicate": true}` and nothing happens twice.
- **Newest wins.** Each event means "read this booking as it is now". A newer event about a booking supersedes an older one still waiting, and one booking is never worked twice at once.
- **Nothing is sent twice.** Guests are recognized by their id in the provider (or by address and name), so an update keeps each guest's link to what they were already sent.
- **Retries.** A failure is retried after 1, 2, 4, 8 … minutes, up to six hours apart, and gives up after eight tries. It is then listed, with its reason, under the connection's activity, where it can be tried again once whatever refused it is fixed.
- **Refused credentials.** If the provider refuses SignSealer's credentials, the connection goes to *needs attention* and stops working events until new credentials are given. What arrives meanwhile is kept and worked afterwards.
- **Retention.** What arrived is cleared thirty days after it was worked; the outcome and the reservation it made are kept.

## Troubleshooting

| What you see | Why | What to do |
| --- | --- | --- |
| **“Hostfully refused our credentials” when connecting** | The API key is wrong or was replaced, or it may not read that agency | Copy the key and the agency UID again from Agency Settings |
| **“Hostfully has no such record” when connecting** | The agency UID is not one the key can read | Copy the agency UID from the bottom of Agency Settings |
| **No API key in Agency Settings** | Your Hostfully plan does not include API access | Ask Hostfully's billing team to add it |
| **Needs attention after it worked** | Hostfully stopped accepting the key | Paste a new key on the connection's page |
| **An inquiry or a booking request never arrives as a reservation** | Only a booked lead is a booking | It is worked when it is booked in Hostfully |
| **The guest is named “Guest”, with no email** | Hostfully sent the guest's details as HIDDEN, which it does for a key that may not see them | Connect with the API key from your own Agency Settings |
| **A guest got nothing** | No email on the lead, or no document fits the booking | The activity names the guest and the reason, or says nothing fitted |

## Hostfully's limits

Hostfully limits calls per hour: its developer portal gives 10,000 an hour per caller, and its help center a default of 1,000. It blocks a caller that abuses them. SignSealer reads the lead once per delivery and, for a booking, its property once. Hostfully calls only HTTPS addresses, and does not document retrying a delivery that fails.

## Hostfully's Integration Zone

This connection uses the API key from your own Agency Settings. Partners listed in Hostfully's Integration Zone connect through Hostfully's OAuth flow instead, and Hostfully withholds guests' personal details from them. A listing there would be a separate connection.

## Pausing and disconnecting

**Pause** keeps recording what arrives and works nothing until you resume. **New address** stops the old delivery address at once (and re-registers the webhook with the provider where SignSealer set it up). **Disconnect** revokes the connection's key, clears its credentials, removes the webhook from the provider where it can, and closes the address. The reservations and documents it made stay, with where they came from.

## From your own code

```
curl https://api.signsealer.com/v1/integrations -H "Authorization: Bearer $KEY"
curl https://api.signsealer.com/v1/integrations/$CONNECTION/events -H "Authorization: Bearer $KEY"
```

The first lists every provider with its status and your connections with their state; the second is what arrived from one connection and what became of it. Neither ever returns a credential, a delivery address or what arrived. Both need the `signing:read` scope. Connecting happens in the dashboard, where the provider confirms the credentials. See the [API reference](https://signsealer.com/docs/api).

---

Source: https://signsealer.com/docs/integrations/hospitable (Hospitable)

# Hospitable

A reservation in Hospitable sends the guest the rental agreement for that property, and your automated messages stay exactly as you set them in Hospitable.

> **Awaiting partner approval.** Built, and not connectable yet. Hospitable connects vendors with OAuth and its partner portal, both of which follow Hospitable approving the vendor. We have applied; until then this is a design, not a product. Links go by email. They go by text only to a guest whose consent to receive texts from you is on file in SignSealer: a booking system knowing a phone number is not that guest agreeing to be texted, and SignSealer never treats it as if it were. Texts go from your business's own number, which is coming soon.

## Before you start

- The membership: connecting a booking system comes with it ([how that works](https://signsealer.com/docs/integrations)). On Free, your 10 signings a month are sent from the dashboard.
- **Not yet possible:** Hospitable must approve SignSealer as a vendor before OAuth and its partner webhooks exist for us.
- Until then, use the Zapier or Make route below.

## Connect Hospitable

1. Once approved: in SignSealer, Integrations → Hospitable → Connect sends you to Hospitable to approve SignSealer. No key changes hands.
2. Hospitable's partner webhooks then deliver your reservation events to SignSealer.

## What SignSealer sets up in Hospitable

Nothing in your account: a vendor's webhooks are configured once, in Hospitable's partner portal, for every customer.

## What comes across

| Hospitable | In SignSealer | Notes |
| --- | --- | --- |
| **id** | Reservation external ID |  |
| **property.name, code** | Label |  |
| **arrival_date / departure_date** | Starts on / ends on |  |
| **guest.first_name + last_name, email, phone_numbers[0]** | Primary guest |  |
| **guests.total, adult_count, child_count, pet_count** | Facts: guests, adults, minors, pets |  |
| **platform** | Fact: channel |  |
| **reservation status** | What happens | accepted: worked · request, inquiry: ignored · canceled: canceled |

## Documents that read it

The reservation carries these facts, which a document's *Only bookings where* can read: `guests`, `adults`, `minors`, `pets`, `channel` and `property`. For example, a waiver for every adult on stays with more than six guests is *Each adult*, *Only bookings where* guests *is more than* 6.

Documents are chosen under **Documents for bookings** on the connection's page in [Integrations](https://app.signsealer.com/integrations) (there is no API route for them yet); see [Reservations and packets](https://signsealer.com/docs/packets).

## How a delivery is proven

Hospitable signs each delivery with a `Signature` header: the hex HMAC-SHA256 of the exact body under the vendor's webhook secret, checked in constant time before the body is read. It carries no timestamp, so a captured delivery could be replayed; the event id makes a replay a duplicate, and the reservation is always read fresh from Hospitable's API.

## Settings

| Setting | Choices | What it does |
| --- | --- | --- |
| **When a booking arrives** | Send straight away (default) · Build the list and wait | Straight away starts everything the packet owes as soon as the booking is worked. Waiting builds the reservation and its packet and sends nothing until somebody presses Send on the reservation, or your code calls `POST /v1/packets/{id}/start`. |
| **When a booking is canceled** | Void what nobody has signed (default) · Leave it | Voiding marks every unfinished document with the reason and the packet void. Anything already signed is kept: an executed waiver is evidence of what was agreed. |

What each guest is sent is decided by the connection's **documents for bookings**, chosen on its page: each says which document, who signs it — the person who booked, every adult, or a parent or guardian for each minor — and which bookings, read from the reservation's facts (dates, guest counts, property, channel). A default covers the bookings nothing else fits, and a booking that matched nothing says so in the connection's activity ([Reservations and packets](https://signsealer.com/docs/packets)).

## Texting and consent

Signing links go by email. They also go by text only when SignSealer holds that guest's consent to receive texts from your business, recorded with the exact words they agreed to — at your counter, on your booking form through `POST /v1/sms-consents`, or on SignSealer's own opt-in. That check runs when the link is queued (`app.may_text`), not in the integration.

No booking system can give SignSealer that consent, so none is treated as if it could. Each adapter records what the provider's data said — `VERIFIED_CONSENT`, `NO_CONSENT` or `INSUFFICIENT_EVIDENCE` — and only `NO_CONSENT` changes anything: the guest's number is not written at all. Every provider built so far can only ever say `INSUFFICIENT_EVIDENCE`. The connection's activity shows, for each guest with a number, whether the link was also texted and why not.

[How to record consent you took yourself](https://signsealer.com/docs/texting).

## Duplicates, order and retries

- **Once.** A delivery is recorded once per connection and event id. A provider that redelivers the same event gets `200 {"duplicate": true}` and nothing happens twice.
- **Newest wins.** Each event means "read this booking as it is now". A newer event about a booking supersedes an older one still waiting, and one booking is never worked twice at once.
- **Nothing is sent twice.** Guests are recognized by their id in the provider (or by address and name), so an update keeps each guest's link to what they were already sent.
- **Retries.** A failure is retried after 1, 2, 4, 8 … minutes, up to six hours apart, and gives up after eight tries. It is then listed, with its reason, under the connection's activity, where it can be tried again once whatever refused it is fixed.
- **Refused credentials.** If the provider refuses SignSealer's credentials, the connection goes to *needs attention* and stops working events until new credentials are given. What arrives meanwhile is kept and worked afterwards.
- **Retention.** What arrived is cleared thirty days after it was worked; the outcome and the reservation it made are kept.

## Troubleshooting

| What you see | Why | What to do |
| --- | --- | --- |
| **“cannot be connected yet”** | Hospitable has not approved SignSealer as a vendor | Use Zapier or Make until then |

## Today, without vendor approval

Zapier and Make can pass a Hospitable reservation to SignSealer's **Add or Update a Reservation**. Or put your agreement form's link in a Hospitable automated message.

## Pausing and disconnecting

**Pause** keeps recording what arrives and works nothing until you resume. **New address** stops the old delivery address at once (and re-registers the webhook with the provider where SignSealer set it up). **Disconnect** revokes the connection's key, clears its credentials, removes the webhook from the provider where it can, and closes the address. The reservations and documents it made stay, with where they came from.

## From your own code

```
curl https://api.signsealer.com/v1/integrations -H "Authorization: Bearer $KEY"
curl https://api.signsealer.com/v1/integrations/$CONNECTION/events -H "Authorization: Bearer $KEY"
```

The first lists every provider with its status and your connections with their state; the second is what arrived from one connection and what became of it. Neither ever returns a credential, a delivery address or what arrived. Both need the `signing:read` scope. Connecting happens in the dashboard, where the provider confirms the credentials. See the [API reference](https://signsealer.com/docs/api).

---

Source: https://signsealer.com/docs/integrations/zapier (Zapier)

# Zapier

Send a SignSealer form from a new booking, order or lead in any app, and let a completed signature move the next step in the tools you already use.

> **Beta.** Built, and awaiting publication in Zapier's directory, which follows Zapier's own review. Until it is listed, we invite you to the app itself, which works on Zapier's Free plan; on a paid Zapier plan, Zapier's Webhooks step can also call SignSealer's API directly — the guide shows how. A phone number passed through a Zap is not consent to text. Links go by email. They go by text only to a guest whose consent to receive texts from you is on file in SignSealer: a booking system knowing a phone number is not that guest agreeing to be texted, and SignSealer never treats it as if it were. Texts go from your business's own number, which is coming soon.

**On Free too.** Zapier uses the SignSealer API, which every plan includes; each signing it starts counts toward your 10 free signings a month like any other.

## What the app does

| Step | Kind | Calls |
| --- | --- | --- |
| **Document Completed · Signer Signed · Document Sent · Declined · Expired · Voided** | Instant triggers (REST hooks) | Subscribes `POST /v1/webhooks` for the one event when the Zap is turned on; removes it with `DELETE /v1/webhooks/{id}?reason=` when it is turned off |
| **Send a Form to Sign** | Action | `POST /v1/workflows/{id}/start` with `send_link`: SignSealer emails the person their link (and texts it, where it may). Choose the form and each of its blanks is a box of its own, named as the form names it |
| **Add or Update a Reservation** | Action | `PUT /v1/subjects`, then `POST /v1/packets/{id}/start` when “Send now” is yes |
| **Find a Document** | Search | `GET /v1/documents` by your reference, title or signer |
| **Signed PDF** | File | On Document Completed, Find a Document and Find Form Answers once the document is complete: the sealed PDF (`GET /v1/documents/{id}/pdf`), fetched only when a later step uses it, to attach to an email or save to Drive |
| **Find Form Answers** | Search | `GET /v1/documents/{id}`: what the signer answered on the form, each question a field of its own for a Filter or a Path, sensitive answers masked as your staff see them. Choose the form and every question is listed in its own words (`GET /v1/workflows`, `GET /v1/templates/{id}`). Answers are never in a trigger's data, because a webhook goes wherever it is pointed; a Zap that needs them asks with this step, by the document ID a trigger gives it |

## Connecting

The app connects with OAuth 2.0 and PKCE. Zapier sends you to SignSealer's consent screen, where you choose the business and see what Zapier will be able to do; no key is copied anywhere. You can revoke it under **Integrations → Connected apps**.

## Until the app is listed

Ask us for an invitation to the app, which works on Zapier's Free plan. On a paid Zapier plan, Webhooks by Zapier (a paid feature of Zapier's) does the same job with an API key (Integrations → API keys):

```
POST https://api.signsealer.com/v1/workflows/{form id}/start
Authorization: Bearer mk_live_…
Content-Type: application/json

{ "full_name": "Dana Reyes", "email": "dana@example.signsealer.com", "external_ref": "RES-88213",
  "send_link": true }
```

`send_link` has SignSealer email Dana the signing link. Without it the link comes back in the answer, once, for a page that hands the person straight on to sign, and nobody is sent anything.

To trigger a Zap on a signature, create a **Catch Hook** in Zapier and add its URL as a webhook in SignSealer (Integrations → Webhooks) for `signing.completed`. Each delivery is the signed envelope described in [Webhooks](https://signsealer.com/docs/webhooks).

A delivery never carries the form's answers. With the document ID it does carry, the same key asks for what was answered (`GET /v1/documents/{id}`) and, once the document is complete, for the sealed PDF (`GET /v1/documents/{id}/pdf`).

## Recipes

- **CRM deal won → agreement:** trigger on the deal, Send a Form to Sign with the deal ID as your reference.
- **Booking tool → waivers:** trigger on the booking, Add or Update a Reservation with the booking ID; the documents for bookings from the API decide the rest.
- **Signed → spreadsheet:** Document Completed, then add a row with the title, reference and certificate.
- **Signed → the PDF in an email or a folder:** Document Completed, then Gmail's attachment or Google Drive's upload with *Signed PDF*. It is the sealed copy, the same file every time.
- **A different next step for each answer:** Document Completed, then Find Form Answers with its Document ID and the form chosen, then Paths, one per answer: “Are you married?” exactly matches “Yes” on one path and “No” on the other. A tick box is Yes or No, and one left alone is No once its signer has signed; a choice is the option exactly as the form lists it. A question several people answered, as each person in a party does, holds every different answer, sorted and joined with a comma: “exactly matches Yes” is everyone, “contains Yes” is anyone.
- **Answers to look at → a manager's inbox:** Document Completed, then Find Form Answers with its Document ID, then a filter on “Number of answers to look at” above 0, then an email with “Answers to look at (text)”. Send it as plain text, or the lines run together.

## For SignSealer: publishing

The app's source is `integrations/zapier` in SignSealer's repository (zapier-platform-core 19). Publishing needs an OAuth client registered in Ops with the redirect URI Zapier gives the app, `CLIENT_ID` and `CLIENT_SECRET` set with `zapier-platform env:set`, and Zapier's review.

## Texting and consent

Signing links go by email. They also go by text only when SignSealer holds that guest's consent to receive texts from your business, recorded with the exact words they agreed to — at your counter, on your booking form through `POST /v1/sms-consents`, or on SignSealer's own opt-in. That check runs when the link is queued (`app.may_text`), not in the integration.

No booking system can give SignSealer that consent, so none is treated as if it could. Each adapter records what the provider's data said — `VERIFIED_CONSENT`, `NO_CONSENT` or `INSUFFICIENT_EVIDENCE` — and only `NO_CONSENT` changes anything: the guest's number is not written at all. Every provider built so far can only ever say `INSUFFICIENT_EVIDENCE`. The connection's activity shows, for each guest with a number, whether the link was also texted and why not.

[How to record consent you took yourself](https://signsealer.com/docs/texting).

---

Source: https://signsealer.com/docs/integrations/make (Make)

# Make

Watch for a signature in Make and branch on it, or send a form from any module's data — with the same API, and the same evidence, as everything else in SignSealer.

> **Beta.** Built to what Make's review asks of an app, and awaiting publication as a Make app, which follows that review. Until it is listed, Make's HTTP module calls SignSealer's API with an API key and does the same job; the guide shows each call. Links go by email. They go by text only to a guest whose consent to receive texts from you is on file in SignSealer: a booking system knowing a phone number is not that guest agreeing to be texted, and SignSealer never treats it as if it were. Texts go from your business's own number, which is coming soon.

**On Free too.** Make uses the SignSealer API, which every plan includes; each signing it starts counts toward your 10 free signings a month like any other.

## What the app does

| Module | Kind | Calls |
| --- | --- | --- |
| **Watch signing events** | Instant trigger (dedicated webhook) | Attaches with `POST /v1/webhooks` for the event you choose (sent, signed, completed, declined, expired, voided, or every event); detaches with `DELETE /v1/webhooks/{id}?reason=` when you delete the webhook in Make. Each bundle is one delivery, the signed envelope described in [Webhooks](https://signsealer.com/docs/webhooks) |
| **Send a form to sign** | Action | `POST /v1/workflows/{id}/start` with `send_link`: SignSealer emails the person their link (and texts it, where it may). The link is the signer's, and never handed to the scenario |
| **Add or update a reservation** | Action | `PUT /v1/subjects`, keyed on your booking ID |
| **Send what a reservation owes** | Action | `POST /v1/packets/{id}/start`: safe to repeat |
| **Download a signed PDF** | Action | `GET /v1/documents/{id}/pdf`: a completed document's sealed PDF, as a file the next module can attach to an email or upload to a drive. The same bytes every time |
| **Search documents** | Search | `GET /v1/documents` by your reference, a title, a signer or a state, newest first. Pages through 200 at a time until your limit (10 unless you change it; empty for every one) |
| **Search form answers** | Search | `GET /v1/documents/{id}`: one bundle per answer, for a filter or a router. A ticked box is Yes, one left alone is No once its signer has signed, and a sensitive answer is masked as your staff see it. Choose the form, and then one of its questions in its own words, to get only that question's answers (`GET /v1/workflows/{id}/bundle`) |
| **Make an API call** | Universal | Any route in the [API reference](https://signsealer.com/docs/api), with the connection's key: a path such as `/v1/account` on `https://api.signsealer.com`, and only there |

Answers are never in a trigger's data, because a webhook goes wherever it is pointed and some answers are about somebody's health. A scenario that needs them asks with Search form answers, by the Document ID the trigger gives it.

## Connecting

Create an API key under **Integrations → API keys** with the Read, Write, Workflows, Subjects and Webhooks scopes, and paste it when Make asks. It is checked against `GET /v1/account`, whose business name labels the connection, and kept out of Make's logs. A test key (`mk_test_…`) connects your sandbox, where nothing is sent to anybody. A refusal is shown in SignSealer's words, with what to do about it; a key that has been revoked stops the scenario and says so.

## Recipes

- **Booking tool → waivers:** your booking tool's trigger, then Add or update a reservation with the booking ID, then Send what a reservation owes with its Packet ID.
- **Signed → the PDF in an email or a folder:** Watch signing events (Document completed), then Download a signed PDF with the document's ID, then an email attachment or a drive upload with its file.
- **A different next step for each answer:** Watch signing events (Document completed), then Search form answers with the document's ID, the form and the question chosen, then a router: a filter on Answer equal to “Yes” on one route and “No” on the other. A question several people answered, as each person in a party does, gives one bundle each, with who answered it.
- **Answers to look at → a manager's inbox:** Search form answers with the document's ID, a filter on To look at, then a text aggregator of Question and Answer into an email.

## Until the app is listed

Make's **HTTP → Make a request** module does the same job with that key. For a trigger, create a **Custom webhook** in Make and add its address as a webhook in SignSealer for the event you want.

```
PUT https://api.signsealer.com/v1/subjects
Authorization: Bearer mk_live_…

{ "provider": "make", "external_id": "BK-1042", "starts_on": "2026-10-10",
  "participants": [{ "ref": "g1", "full_name": "Sam Tan", "email": "sam@example.signsealer.com", "is_primary": true }] }
```

Then `POST /v1/packets/{packet_id}/start` sends what the reservation owes. Both are safe to repeat.

## For SignSealer: publishing

The app's source is `integrations/make` (Make's Apps SDK layout). Deploy it with the Make Apps Editor extension for VS Code, run the test scenarios Make's review asks for, then request the review; the folder's README lists each step.

## Texting and consent

Signing links go by email. They also go by text only when SignSealer holds that guest's consent to receive texts from your business, recorded with the exact words they agreed to — at your counter, on your booking form through `POST /v1/sms-consents`, or on SignSealer's own opt-in. That check runs when the link is queued (`app.may_text`), not in the integration.

No booking system can give SignSealer that consent, so none is treated as if it could. Each adapter records what the provider's data said — `VERIFIED_CONSENT`, `NO_CONSENT` or `INSUFFICIENT_EVIDENCE` — and only `NO_CONSENT` changes anything: the guest's number is not written at all. Every provider built so far can only ever say `INSUFFICIENT_EVIDENCE`. The connection's activity shows, for each guest with a number, whether the link was also texted and why not.

[How to record consent you took yourself](https://signsealer.com/docs/texting).

---

Source: https://signsealer.com/docs/integrations/hubspot (HubSpot)

# HubSpot

Choose the agreement for a HubSpot deal and its contacts are sent it; when they sign, the deal hears about it. Today through Zapier or Make.

> **Planned.** Built, and not yet connectable. The native connection is written and tested against stand-ins: you press Send for a deal and choose what goes, or name a stage that sends it, and a note goes on the deal when they have signed. It has not run against a live HubSpot account, and SignSealer's HubSpot app needs HubSpot's review and installs before listing. Until then Zapier and Make carry both directions, and the guide has the exact steps.

## Today, step by step

1. In Zapier: trigger on a HubSpot deal stage change, then SignSealer's Send a Form to Sign.
2. A second Zap: SignSealer's Document Completed, then update the HubSpot deal.
3. Use the deal ID as your reference so each document leads back to its deal.

## The signature coming back

A second Zap or scenario: SignSealer's Document Completed (or a SignSealer webhook) → update the HubSpot deal, using the reference you sent. A declined document carries the signer's reason.

## What the native connection does

It is built, and waits on SignSealer's HubSpot app. A deal goes when somebody sends it: on the connection's page in SignSealer, paste the deal's id or the address of its page, then choose what goes, any of your templates and forms, or what your rules say it needs, and whether to the deal's main contact or every contact on it. A deal sends at a stage only if you name that stage on the connection's page; a deal moved to Closed lost, or deleted, voids what nobody has signed. When everything is signed, or one is declined, a note goes on the deal; when everything is signed, each signed PDF, sealed with its certificate, is attached to that note and kept private in a SignSealer folder in your file manager (a switch on the connection turns that off). On the connection's page you can also name a stage a signed deal moves to, by its internal name such as `closedwon` (not one that sends or cancels), and a deal property of your own, such as a single-line text property `signsealer_status`, that says *Signed* when everything is signed or *Declined* when somebody declines; both are off until you fill them in, and a property HubSpot refuses is said in the connection's activity while the note still goes. Every delivery is checked against HubSpot's `X-HubSpot-Signature-v3`. A Send card inside HubSpot itself comes with the app.

Once it can be connected, connecting it comes with the membership, like every system SignSealer connects to; Zapier, Make and the API work on Free today.

## With the API directly

```
PUT https://api.signsealer.com/v1/subjects
Authorization: Bearer mk_live_…

{ "provider": "hubspot", "external_id": "…", "starts_on": "2026-10-10",
  "participants": [{ "ref": "…", "full_name": "…", "email": "…", "is_primary": true }] }

POST https://api.signsealer.com/v1/packets/{packet_id}/start
```

Keyed on the HubSpot ID, so sending the same record twice is one reservation, and starting again sends nothing already sent. See [Reservations and packets](https://signsealer.com/docs/packets) and [Webhooks](https://signsealer.com/docs/webhooks) for the signature coming back.

## Texting and consent

Signing links go by email. They also go by text only when SignSealer holds that guest's consent to receive texts from your business, recorded with the exact words they agreed to — at your counter, on your booking form through `POST /v1/sms-consents`, or on SignSealer's own opt-in. That check runs when the link is queued (`app.may_text`), not in the integration.

No booking system can give SignSealer that consent, so none is treated as if it could. Each adapter records what the provider's data said — `VERIFIED_CONSENT`, `NO_CONSENT` or `INSUFFICIENT_EVIDENCE` — and only `NO_CONSENT` changes anything: the guest's number is not written at all. Every provider built so far can only ever say `INSUFFICIENT_EVIDENCE`. The connection's activity shows, for each guest with a number, whether the link was also texted and why not.

[How to record consent you took yourself](https://signsealer.com/docs/texting).

---

Source: https://signsealer.com/docs/integrations/zoho-crm (Zoho CRM)

# Zoho CRM

A Zoho CRM deal at your stage, a contact you tick or a record in your own module sends your agreement, and a note says when it is signed. Zapier or Make today.

> **Planned.** Built, and not yet connectable. The native connection is written against Zoho CRM's documentation and tested against stand-ins: a button on the deal sends what you choose to its contacts, or a stage you name does, so does a contact, a lead or a custom module's record whose field you choose reaches a value you choose, a lost or deleted one voids what nobody signed, and a note goes on the record when they have signed. It has not run against a live Zoho CRM account, and it cannot be connected until SignSealer's Zoho app exists. Until then Zapier and Make carry both directions, and the guide has the steps.

## Today, step by step

1. In Zapier: Zoho CRM's Updated Module Entry on Deals, then SignSealer's Send a Form to Sign. In Make, Watch Objects does the same.
2. A second Zap or scenario: SignSealer's Document Completed, then Update Module Entry (Make: Update an Object) on the deal.
3. Use the deal's ID as your reference, so each document leads back to its deal.

## The signature coming back

A second Zap or scenario: SignSealer's Document Completed (or a SignSealer webhook) → Zoho CRM's Update Module Entry in Zapier, or Update an Object in Make, on the deal whose ID you sent as the reference. A declined document carries the signer's reason.

## What the native connection does, now that it is built

It is written against Zoho CRM's API v8 and tested against stand-ins, and it waits on SignSealer's Zoho app: nothing here can be switched on until that app exists.

- **Connecting.** Connect sends you to Zoho to sign in and approve SignSealer for one organization. Zoho sends you back naming your data center, and SignSealer only ever talks to that one: the United States, Europe, India, Australia, Japan, Canada, Saudi Arabia or the United Kingdom. It asks to read your organization, your modules' records and their fields, to add notes and attachments, to update records (only to make the two changes below, when you ask for them), and to keep a notification channel, and for nothing else.
- **Deals.** SignSealer opens a notification channel on your deals at the connection's own address. A notification is taken only with the channel's secret token and within an hour of Zoho sending it, and the deal is then read back from Zoho. A deal at a stage you name on the connection's page sends what its contact, and each contact with a role on the deal, owes (none does until you name one); one at a canceling stage (Closed Lost and Closed Lost to Competition), or deleted, voids what nobody has signed; any other stage changes nothing. Stage names are matched without regard to capitals, spaces or hyphens.
- **Sending from the deal.** The connection's page gives you an address for a button. In Zoho CRM's setup, add a button to the Deals module that opens a URL, with that address: pressing it on a deal opens SignSealer, signed in as you, to choose what goes, any of your templates and forms, or what your rules say it needs, and whether to the deal's contact or everyone on it. The deal is read from Zoho when you press Send, whatever its stage. A button on Contacts or Leads works the same way, with `Contacts:` or `Leads:` before the record's id.
- **Contacts, leads and your own modules.** On the connection's page, add up to ten modules besides deals, each by its API name (Zoho CRM shows them under Setup, Developer Hub, APIs and SDKs, API Names): a field on it, the values that send and those that cancel, and who signs. A *Send for signature* checkbox on Contacts sends when it is ticked (its value is `true`); a *Status* picklist on a custom module sends at *Ready to sign*. Who signs is the record itself (a contact or a lead, by its name, email and phone), or the record a lookup field on it names, such as a custom module's *Client* lookup to Contacts. The channel watches exactly the modules you list, and saving the page changes it at once.
- **The channel.** Zoho closes a channel after a week at most, so SignSealer opens it for six days and renews it a day before it ends, from the connection's own queue. A renewal that fails is retried and shows in the connection's activity like any delivery.
- **The signature coming back.** When every document is signed, or one is declined, a note goes on the deal, or on the record that sent, with each document, who signed it, when, and a link to it. When everything is signed, each signed PDF, sealed with its certificate, is added to the record's attachments too, unless you turn that off on the connection's page; one already there is not added twice.
- **Moving a signed deal on.** On the connection's page, name a stage a signed deal moves to, such as *Closed Won* (not one that sends or cancels), and a field by its API name, such as `Signing_Status`, that says *Signed* when everything is signed or *Declined* when somebody declines. The field is written on whatever record sent, a contact or your own module's as well as a deal, so add it to each; only a deal is moved. Both are off until you fill them in; one Zoho refuses is said in the connection's activity, and the note still goes. Nothing else on a record is ever changed.
- **Disconnecting.** Closes the channel and revokes SignSealer's access at Zoho.

Once it can be connected, connecting it comes with the membership, like every system SignSealer connects to; Zapier, Make and the API work on Free today.

## With the API directly

```
PUT https://api.signsealer.com/v1/subjects
Authorization: Bearer mk_live_…

{ "provider": "zoho-crm", "external_id": "…", "starts_on": "2026-10-10",
  "participants": [{ "ref": "…", "full_name": "…", "email": "…", "is_primary": true }] }

POST https://api.signsealer.com/v1/packets/{packet_id}/start
```

Keyed on the Zoho CRM ID, so sending the same record twice is one reservation, and starting again sends nothing already sent. See [Reservations and packets](https://signsealer.com/docs/packets) and [Webhooks](https://signsealer.com/docs/webhooks) for the signature coming back.

## Texting and consent

Signing links go by email. They also go by text only when SignSealer holds that guest's consent to receive texts from your business, recorded with the exact words they agreed to — at your counter, on your booking form through `POST /v1/sms-consents`, or on SignSealer's own opt-in. That check runs when the link is queued (`app.may_text`), not in the integration.

No booking system can give SignSealer that consent, so none is treated as if it could. Each adapter records what the provider's data said — `VERIFIED_CONSENT`, `NO_CONSENT` or `INSUFFICIENT_EVIDENCE` — and only `NO_CONSENT` changes anything: the guest's number is not written at all. Every provider built so far can only ever say `INSUFFICIENT_EVIDENCE`. The connection's activity shows, for each guest with a number, whether the link was also texted and why not.

[How to record consent you took yourself](https://signsealer.com/docs/texting).

---

Source: https://signsealer.com/docs/integrations/pipedrive (Pipedrive)

# Pipedrive

When a Pipedrive deal reaches your contract stage, its person is sent your agreement; when they sign, a note on the deal says so. Today through Zapier or Make.

> **Planned.** Built, and not yet connectable. The native connection is written against Pipedrive's documentation and tested against stand-ins: you press Send for a deal and choose what goes, or name a stage that sends it, to its person and participants, a lost or deleted deal voids what nobody signed, and a note goes on the deal when they have signed. It has not run against a live Pipedrive account, and it cannot be connected until SignSealer's Pipedrive app exists and passes Pipedrive's Marketplace review. Until then Zapier and Make carry both directions, and the guide has the exact steps.

## Today, step by step

1. In Zapier: trigger on Pipedrive's Updated Deal Stage, then SignSealer's Send a Form to Sign. In Make: Watch Deals, then Send a Form to Sign.
2. A second Zap or scenario: SignSealer's Document Completed, then Pipedrive's Create Note on the deal.
3. Use the deal ID as your reference so each document leads back to its deal.

## The signature coming back

A second Zap or scenario: SignSealer's Document Completed or Document Declined (or a SignSealer webhook) → Pipedrive's **Create Note** on the deal, found by the deal ID you sent as the reference. A declined document carries the signer's reason.

## What the native connection does

It is built, and waits on SignSealer's Pipedrive app. Connecting will be approving SignSealer in Pipedrive. SignSealer then registers a webhook of its own for your company's deals, which Pipedrive calls with a login and password only that connection holds, and reads each deal back from Pipedrive's API rather than trusting what the webhook said. A deal goes when somebody sends it: on the connection's page in SignSealer, paste the deal's id or the address of its page, then choose what goes, any of your templates and forms, or what your rules say it needs, and whether to the deal's person or everyone on it, won deals included. An open deal at one of the stages you name (by the name Pipedrive shows, or by number; none until you name one) sends what its person and its participants owe, the deal's person first. A lost or deleted deal voids what nobody has signed, unless you switch that off; a won deal is left alone. When every document is signed, or one is declined, a note goes on the deal listing each document, who signed it and a link to it, and when everything is signed each signed PDF is added to the deal's files (a switch on the connection turns that off). It never changes a deal's value. On the connection's page you can choose where a signed deal goes, `won` to mark it won or a stage by name or number (not one that sends or cancels), and a deal field of your own, a text field or a single option field with options called Signed and Declined, that says which; both are off until you fill them in, and one Pipedrive refuses is said in the connection's activity while the note still goes. Pipedrive tells SignSealer only about deals the person who connected it can see. Disconnecting takes the webhook down; SignSealer's app stays in Pipedrive until you uninstall it there.

Once it can be connected, connecting it comes with the membership, like every system SignSealer connects to; Zapier, Make and the API work on Free today.

## With the API directly

```
PUT https://api.signsealer.com/v1/subjects
Authorization: Bearer mk_live_…

{ "provider": "pipedrive", "external_id": "…", "starts_on": "2026-10-10",
  "participants": [{ "ref": "…", "full_name": "…", "email": "…", "is_primary": true }] }

POST https://api.signsealer.com/v1/packets/{packet_id}/start
```

Keyed on the Pipedrive ID, so sending the same record twice is one reservation, and starting again sends nothing already sent. See [Reservations and packets](https://signsealer.com/docs/packets) and [Webhooks](https://signsealer.com/docs/webhooks) for the signature coming back.

## Texting and consent

Signing links go by email. They also go by text only when SignSealer holds that guest's consent to receive texts from your business, recorded with the exact words they agreed to — at your counter, on your booking form through `POST /v1/sms-consents`, or on SignSealer's own opt-in. That check runs when the link is queued (`app.may_text`), not in the integration.

No booking system can give SignSealer that consent, so none is treated as if it could. Each adapter records what the provider's data said — `VERIFIED_CONSENT`, `NO_CONSENT` or `INSUFFICIENT_EVIDENCE` — and only `NO_CONSENT` changes anything: the guest's number is not written at all. Every provider built so far can only ever say `INSUFFICIENT_EVIDENCE`. The connection's activity shows, for each guest with a number, whether the link was also texted and why not.

[How to record consent you took yourself](https://signsealer.com/docs/texting).

---

Source: https://signsealer.com/docs/integrations/salesforce (Salesforce)

# Salesforce

When an opportunity reaches your contract stage, its contact roles are sent the agreement, and a task on it says when they sign. Zapier or Make until it is live.

> **Planned.** Built, and not yet connectable. The native connection is written against Salesforce's documentation and tested against stand-ins: a button on the opportunity sends what you choose to its contact roles, or a stage you name does, one that is lost or deleted voids what nobody signed, and a completed task goes on the opportunity when they have signed. It has not run against a live org, and it cannot be connected until SignSealer's Salesforce app exists, as a package your admin installs. It needs an edition with API access: Enterprise, Unlimited, Performance or Developer, or Professional with the API added. Until then Zapier and Make carry both directions, and the guide has the exact steps.

## Today, step by step

1. In Zapier: trigger on Salesforce's Updated Field on Record for Opportunity, watching Stage, then SignSealer's Send a Form to Sign. In Make: Watch Records, then Send a Form to Sign.
2. A second Zap or scenario: SignSealer's Document Completed, then a note or task created on the opportunity.
3. Use the opportunity ID as your reference so each document leads back to its opportunity.

## The signature coming back

A second Zap or scenario: SignSealer's Document Completed or Document Declined (or a SignSealer webhook) → a note or a task created on the opportunity, found by the opportunity ID you sent as the reference: **Create Record** in Zapier, **Create a Record** in Make. A declined document carries the signer's reason.

## What the native connection does

It is built, and waits on SignSealer's Salesforce app: an External Client App in a managed package, which your admin installs once, because Salesforce lets nobody in an org connect an app like ours until it is installed there. Connecting will then be logging in to your org and allowing SignSealer, as somebody who can see every opportunity that should send. Your admin then adds SignSealer's button to the opportunity: in Setup, Object Manager, Opportunity, Buttons, Links, and Actions, a new Detail Page Button that opens in a new window with the address the connection's page gives, added to the page layout. Pressing it opens SignSealer, signed in as you, to choose what goes, any of your templates and forms, or what your rules say it needs, and whether to the primary contact or every contact role. An opportunity also sends at a stage you name (by the name Salesforce shows; none until you name one), to its contact roles, the primary contact first and up to twenty of them; an opportunity with no contact roles sends nothing. One moved to Closed Lost, or deleted, voids what nobody has signed, unless you switch that off; a won opportunity is left alone. When every document is signed, or one is declined, a completed task goes in the opportunity's activity listing each document, who signed it, when, and a link to it, and when everything is signed each signed PDF is added to the opportunity's files (a switch on the connection turns that off). It never changes an opportunity's amount or close date. On the connection's page you can name a stage a signed opportunity moves to, such as *Closed Won* (not one that sends or cancels), and a field by its API name, such as `Signing_Status__c`, a text field your admin adds, that says *Signed* or *Declined*; both are off until you fill them in. A validation rule that refuses either, such as one that wants a close date first, is said in the connection's activity, and the task still goes. Disconnecting revokes SignSealer's access to the org.

## Telling SignSealer the moment a stage changes

Salesforce has no webhook an app can register for you, so your admin adds two things, once, in Setup. The address they need is shown when you connect, and again whenever you give the connection a new address.

1. **An Outbound Message.** In Setup, search for Outbound Messages and choose New. Object: Opportunity. Name it SignSealer. Endpoint URL: the connection's address. Send as a user who can see the opportunities that send. Fields to send: `Id` and `StageName`. Save.
2. **A record-triggered Flow.** In Setup, open Flows and choose New Flow, then Record-Triggered Flow. Object: Opportunity. Trigger it when a record is created or updated, with no condition (SignSealer reads each opportunity's stage itself and leaves alone any that does not send), and optimize it for actions and related records. Add an action, choose the SignSealer Outbound Message, then save and activate the Flow.

Each message is taken only at the connection's own address, and only when it names your org; every opportunity it names is read back from Salesforce's API rather than trusting the message. Until the Flow is active, and for anything it misses, SignSealer looks every hour for opportunities changed since it last looked whose stage sends or cancels, so an agreement goes within the hour rather than within the minute. A new address for the connection means changing the Outbound Message's endpoint to it.

## Which orgs

Any edition with API access: Enterprise, Unlimited, Performance and Developer include it, and Professional has it as an add-on. Professional has no outbound messages, so there SignSealer's hourly look is what finds a changed opportunity. Essentials and Professional without the add-on cannot be connected.

Once it can be connected, connecting it comes with the membership, like every system SignSealer connects to; Zapier, Make and the API work on Free today.

## With the API directly

```
PUT https://api.signsealer.com/v1/subjects
Authorization: Bearer mk_live_…

{ "provider": "salesforce", "external_id": "…", "starts_on": "2026-10-10",
  "participants": [{ "ref": "…", "full_name": "…", "email": "…", "is_primary": true }] }

POST https://api.signsealer.com/v1/packets/{packet_id}/start
```

Keyed on the Salesforce ID, so sending the same record twice is one reservation, and starting again sends nothing already sent. See [Reservations and packets](https://signsealer.com/docs/packets) and [Webhooks](https://signsealer.com/docs/webhooks) for the signature coming back.

## Texting and consent

Signing links go by email. They also go by text only when SignSealer holds that guest's consent to receive texts from your business, recorded with the exact words they agreed to — at your counter, on your booking form through `POST /v1/sms-consents`, or on SignSealer's own opt-in. That check runs when the link is queued (`app.may_text`), not in the integration.

No booking system can give SignSealer that consent, so none is treated as if it could. Each adapter records what the provider's data said — `VERIFIED_CONSENT`, `NO_CONSENT` or `INSUFFICIENT_EVIDENCE` — and only `NO_CONSENT` changes anything: the guest's number is not written at all. Every provider built so far can only ever say `INSUFFICIENT_EVIDENCE`. The connection's activity shows, for each guest with a number, whether the link was also texted and why not.

[How to record consent you took yourself](https://signsealer.com/docs/texting).

---

Source: https://signsealer.com/docs/integrations/jobber (Jobber)

# Jobber

When a quote goes out from Jobber, the client is sent the agreement that goes with it: your terms, a work authorization, a waiver for the job site. Today through Zapier.

> **Planned.** Built, and not yet connectable. The native connection is written against Jobber's developer documentation and tested against stand-ins, not a live Jobber account: a quote that reaches the status you choose sends what its client owes, and a note goes on the quote when everything is signed. It can be connected once SignSealer's Jobber app exists, and Jobber reviews an app before it connects more than five accounts or appears in its App Marketplace. Until then Zapier carries the quote across, and the guide has the exact steps.

## Today, step by step

1. In Zapier: trigger on Jobber's Quote Sent, then SignSealer's Send a Form to Sign, with the client's name and email from the quote.
2. Put the quote number in Your reference, so each document leads back to its quote.
3. A second Zap if you want one: SignSealer's Document Completed, then an email or a message to whoever books the work.

## The signature coming back

Jobber's Zapier app has no step that writes to a quote, so today the signed document stays in SignSealer, found by the quote number you sent as its reference. A second Zap on SignSealer's Document Completed (or a SignSealer webhook) can email or message whoever books the work; a declined document carries the signer's reason.

## What the native connection does

It is built, and waits on SignSealer's Jobber app. A quote that reaches a status you choose (by default `awaiting_response`, sent to the client) sends what its client owes, with the quote's number, status and total and the property's address for its documents to read. A quote archived or deleted is canceled, and at any other status a quote is left alone, so approving it or converting it to a job sends nothing again. Every delivery is checked against Jobber's `X-Jobber-Hmac-SHA256` signature, and the quote is read again from Jobber's API rather than taken from the delivery. When everything is signed, or a document is declined, a note goes on the quote listing each document, who signed it and a link to it; nothing else on the quote is changed. Disconnecting in SignSealer tells Jobber, which then shows SignSealer as disconnected; disconnecting inside Jobber leaves the connection in SignSealer waiting to be connected again.

Once it can be connected, connecting it comes with the membership, like every system SignSealer connects to; Zapier, Make and the API work on Free today.

## With the API directly

```
PUT https://api.signsealer.com/v1/subjects
Authorization: Bearer mk_live_…

{ "provider": "jobber", "external_id": "…", "starts_on": "2026-10-10",
  "participants": [{ "ref": "…", "full_name": "…", "email": "…", "is_primary": true }] }

POST https://api.signsealer.com/v1/packets/{packet_id}/start
```

Keyed on the Jobber ID, so sending the same record twice is one reservation, and starting again sends nothing already sent. See [Reservations and packets](https://signsealer.com/docs/packets) and [Webhooks](https://signsealer.com/docs/webhooks) for the signature coming back.

## Texting and consent

Signing links go by email. They also go by text only when SignSealer holds that guest's consent to receive texts from your business, recorded with the exact words they agreed to — at your counter, on your booking form through `POST /v1/sms-consents`, or on SignSealer's own opt-in. That check runs when the link is queued (`app.may_text`), not in the integration.

No booking system can give SignSealer that consent, so none is treated as if it could. Each adapter records what the provider's data said — `VERIFIED_CONSENT`, `NO_CONSENT` or `INSUFFICIENT_EVIDENCE` — and only `NO_CONSENT` changes anything: the guest's number is not written at all. Every provider built so far can only ever say `INSUFFICIENT_EVIDENCE`. The connection's activity shows, for each guest with a number, whether the link was also texted and why not.

[How to record consent you took yourself](https://signsealer.com/docs/texting).