{
"openapi": "3.1.0",
"info": {
"title": "SignSealer",
"version": "1.0.0",
"description": "Signatures with the evidence behind them.\n\nEvery write that creates something takes an optional `Idempotency-Key`, with Stripe's semantics — the same key and body replays, a different body is refused. Every response carries an `x-request-id`; quote it if you need us to look something up.",
"contact": {
"name": "SignSealer",
"url": "https://signsealer.com"
}
},
"servers": [
{
"url": "https://api.signsealer.com"
}
],
"security": [
{
"apiKey": []
}
],
"components": {
"securitySchemes": {
"apiKey": {
"type": "http",
"scheme": "bearer",
"description": "An API key, as `Authorization: Bearer mk_live_…`. Keys are shown once when issued and stored only as their hash. A key is a member of the account: its scopes are its capabilities, and revoking it ends its access in the same statement."
},
"oauth": {
"type": "oauth2",
"description": "For an app other businesses install. The business approves the scopes on SignSealer's consent screen; the access token is sent as `Authorization: Bearer …` like a key, and refreshed with the refresh token. PKCE (S256) is required.",
"flows": {
"authorizationCode": {
"authorizationUrl": "https://api.signsealer.com/oauth/authorize",
"tokenUrl": "https://api.signsealer.com/oauth/token",
"refreshUrl": "https://api.signsealer.com/oauth/token",
"scopes": {
"signing:read": "Read templates, documents, workflows and certificates.",
"signing:write": "Prepare, send, remind and void documents; hand out signing links.",
"signing:templates": "Create templates, change drafts, publish, revise and discard them, and change their settings.",
"signing:workflows": "Start workflows.",
"signing:webhooks": "Manage webhook endpoints.",
"signing:subjects": "Reservations and activities, and their packets."
}
}
}
},
"partnerAuth": {
"type": "http",
"scheme": "basic",
"description": "For a partner reading its own revenue share: your OAuth `client_id` and `client_secret` as HTTP Basic, the same pair `/oauth/token` takes. Only a confidential client that SignSealer has enrolled in the partner programme can use it; an API key or an access token is refused."
}
},
"schemas": {
"Error": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"hint": {
"type": "string"
}
}
}
}
}
}
},
"tags": [
{
"name": "Account",
"description": "Whose key this is, and the brand it signs under."
},
{
"name": "Templates",
"description": "The text people sign, and its versions: create, change a draft, publish, revise, discard."
},
{
"name": "Documents",
"description": "One agreement, its signers and its evidence."
},
{
"name": "Workflows",
"description": "A template plus the rules for running it."
},
{
"name": "Subjects",
"description": "Reservations and activities, and what each needs signed."
},
{
"name": "Packets",
"description": "Several documents about one subject, behind one link."
},
{
"name": "Webhooks",
"description": "Where completions are delivered."
},
{
"name": "Signing",
"description": "What a person holding a signing link can do. No API key: the token is the credential, and attaching a key would let any member of any tenant sign anything whose token they could guess."
},
{
"name": "Verify",
"description": "Checking a certificate from its printed code, without an account."
},
{
"name": "Standing",
"description": "Whether somebody's signature on a template is still good."
},
{
"name": "Texting consent",
"description": "Consent to text a number, taken somewhere SignSealer is not."
},
{
"name": "Devices",
"description": "Tablets: pairing, heartbeats, and managing a fleet from your own software."
},
{
"name": "Integrations",
"description": "The booking systems a business connects -- Guesty, Hostaway and others -- and what arrived from each. Read-only here: connecting asks the provider to confirm credentials, which is done in the dashboard."
},
{
"name": "OAuth",
"description": "Installing a partner's app on a business's account."
},
{
"name": "Partners",
"description": "A partner's own revenue share: the businesses it brought, what they have paid this month, and every closed month's statement. Read-only, with the partner's client credentials."
}
],
"paths": {
"/v1/account": {
"get": {
"operationId": "get-account",
"summary": "Show the account this key belongs to",
"description": "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 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.",
"tags": [
"Account"
],
"security": [
{
"apiKey": []
},
{
"oauth": [
"signing:read"
]
}
],
"x-scope": "signing:read",
"responses": {
"200": {
"description": "Done.",
"headers": {
"X-RateLimit-Limit": {
"description": "Requests this key may make in the window.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Remaining": {
"description": "Requests left in this window.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Reset": {
"description": "When the window turns over, in seconds since the epoch.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"example": {
"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"
}
}
}
},
"400": {
"description": "`bad_request`: The request could not be read.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "bad_request",
"message": "The request could not be read."
}
}
}
}
},
"401": {
"description": "`unauthorized`: No key, or a key that is not live. Unknown, revoked and expired all answer the same way.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "unauthorized",
"message": "No key, or a key that is not live. Unknown, revoked and expired all answer the same way."
}
}
}
}
},
"402": {
"description": "`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, and retrying will not help until credit is added.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "quota_exceeded",
"message": "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, and retrying will not help until credit is added."
}
}
}
}
},
"403": {
"description": "`forbidden`: The key is live but its scopes do not carry this.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "forbidden",
"message": "The key is live but its scopes do not carry this."
}
}
}
}
},
"404": {
"description": "`not_found`: No such thing, in this account.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "not_found",
"message": "No such thing, in this account."
}
}
}
}
},
"405": {
"description": "`method_not_allowed`: That path exists under another method.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "method_not_allowed",
"message": "That path exists under another method."
}
}
}
}
},
"409": {
"description": "`conflict`: The same idempotency key was used for a different request, or the work is still running; or the thing named has moved on -- a template revised from a version that is no longer the newest. The message says which. `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.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"conflict": {
"value": {
"error": {
"code": "conflict",
"message": "The same idempotency key was used for a different request, or the work is still running; or the thing named has moved on -- a template revised from a version that is no longer the newest. The message says which."
}
}
},
"template_changed": {
"value": {
"error": {
"code": "template_changed",
"message": "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."
}
}
}
}
}
}
},
"413": {
"description": "`too_large`: The body is larger than a signing request ever is.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "too_large",
"message": "The body is larger than a signing request ever is."
}
}
}
}
},
"422": {
"description": "`invalid`: The body did not validate, or the engine refused it. The message is the reason.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "invalid",
"message": "The body did not validate, or the engine refused it. The message is the reason."
}
}
}
}
},
"429": {
"description": "`rate_limited`: Too many attempts. The message says the budget.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "rate_limited",
"message": "Too many attempts. The message says the budget."
}
}
}
}
},
"500": {
"description": "`internal`: Something went wrong on our side. Quote the x-request-id.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "internal",
"message": "Something went wrong on our side. Quote the x-request-id."
}
}
}
}
}
}
}
},
"/v1/branding": {
"get": {
"operationId": "get-branding",
"summary": "The brand the account shows its signers",
"description": "The business's name, colours, 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. SignSealer's own until the business has the white-label add-on and has set its brand.",
"tags": [
"Account"
],
"security": [
{
"apiKey": []
},
{
"oauth": [
"signing:read"
]
}
],
"x-scope": "signing:read",
"responses": {
"200": {
"description": "Done.",
"headers": {
"X-RateLimit-Limit": {
"description": "Requests this key may make in the window.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Remaining": {
"description": "Requests left in this window.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Reset": {
"description": "When the window turns over, in seconds since the epoch.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"example": {
"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"
}
}
}
},
"400": {
"description": "`bad_request`: The request could not be read.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "bad_request",
"message": "The request could not be read."
}
}
}
}
},
"401": {
"description": "`unauthorized`: No key, or a key that is not live. Unknown, revoked and expired all answer the same way.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "unauthorized",
"message": "No key, or a key that is not live. Unknown, revoked and expired all answer the same way."
}
}
}
}
},
"402": {
"description": "`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, and retrying will not help until credit is added.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "quota_exceeded",
"message": "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, and retrying will not help until credit is added."
}
}
}
}
},
"403": {
"description": "`forbidden`: The key is live but its scopes do not carry this.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "forbidden",
"message": "The key is live but its scopes do not carry this."
}
}
}
}
},
"404": {
"description": "`not_found`: No such thing, in this account.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "not_found",
"message": "No such thing, in this account."
}
}
}
}
},
"405": {
"description": "`method_not_allowed`: That path exists under another method.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "method_not_allowed",
"message": "That path exists under another method."
}
}
}
}
},
"409": {
"description": "`conflict`: The same idempotency key was used for a different request, or the work is still running; or the thing named has moved on -- a template revised from a version that is no longer the newest. The message says which. `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.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"conflict": {
"value": {
"error": {
"code": "conflict",
"message": "The same idempotency key was used for a different request, or the work is still running; or the thing named has moved on -- a template revised from a version that is no longer the newest. The message says which."
}
}
},
"template_changed": {
"value": {
"error": {
"code": "template_changed",
"message": "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."
}
}
}
}
}
}
},
"413": {
"description": "`too_large`: The body is larger than a signing request ever is.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "too_large",
"message": "The body is larger than a signing request ever is."
}
}
}
}
},
"422": {
"description": "`invalid`: The body did not validate, or the engine refused it. The message is the reason.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "invalid",
"message": "The body did not validate, or the engine refused it. The message is the reason."
}
}
}
}
},
"429": {
"description": "`rate_limited`: Too many attempts. The message says the budget.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "rate_limited",
"message": "Too many attempts. The message says the budget."
}
}
}
}
},
"500": {
"description": "`internal`: Something went wrong on our side. Quote the x-request-id.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "internal",
"message": "Something went wrong on our side. Quote the x-request-id."
}
}
}
}
}
}
}
},
"/v1/sms-consents": {
"post": {
"operationId": "post-sms-consents",
"summary": "Record consent to text a number",
"description": "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 re-consented by you — they have to opt in again themselves.",
"tags": [
"Texting consent"
],
"security": [
{
"apiKey": []
},
{
"oauth": [
"signing:write"
]
}
],
"x-scope": "signing:write",
"parameters": [
{
"name": "Idempotency-Key",
"in": "header",
"required": false,
"description": "Your own key, 8–255 characters. The same key with the same body replays the first response without doing the work again; the same key with a different body is refused rather than absorbed.",
"schema": {
"type": "string",
"minLength": 8,
"maxLength": 255
}
}
],
"responses": {
"201": {
"description": "Made.",
"headers": {
"X-RateLimit-Limit": {
"description": "Requests this key may make in the window.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Remaining": {
"description": "Requests left in this window.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Reset": {
"description": "When the window turns over, in seconds since the epoch.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"example": {
"phone": "+15035550142",
"purposes": [
"signing.link",
"signing.reminder",
"signing.completed"
]
}
}
}
},
"400": {
"description": "`bad_request`: The request could not be read.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "bad_request",
"message": "The request could not be read."
}
}
}
}
},
"401": {
"description": "`unauthorized`: No key, or a key that is not live. Unknown, revoked and expired all answer the same way.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "unauthorized",
"message": "No key, or a key that is not live. Unknown, revoked and expired all answer the same way."
}
}
}
}
},
"402": {
"description": "`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, and retrying will not help until credit is added.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "quota_exceeded",
"message": "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, and retrying will not help until credit is added."
}
}
}
}
},
"403": {
"description": "`forbidden`: The key is live but its scopes do not carry this.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "forbidden",
"message": "The key is live but its scopes do not carry this."
}
}
}
}
},
"404": {
"description": "`not_found`: No such thing, in this account.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "not_found",
"message": "No such thing, in this account."
}
}
}
}
},
"405": {
"description": "`method_not_allowed`: That path exists under another method.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "method_not_allowed",
"message": "That path exists under another method."
}
}
}
}
},
"409": {
"description": "`conflict`: The same idempotency key was used for a different request, or the work is still running; or the thing named has moved on -- a template revised from a version that is no longer the newest. The message says which. `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.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"conflict": {
"value": {
"error": {
"code": "conflict",
"message": "The same idempotency key was used for a different request, or the work is still running; or the thing named has moved on -- a template revised from a version that is no longer the newest. The message says which."
}
}
},
"template_changed": {
"value": {
"error": {
"code": "template_changed",
"message": "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."
}
}
}
}
}
}
},
"413": {
"description": "`too_large`: The body is larger than a signing request ever is.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "too_large",
"message": "The body is larger than a signing request ever is."
}
}
}
}
},
"422": {
"description": "`invalid`: The body did not validate, or the engine refused it. The message is the reason.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "invalid",
"message": "The body did not validate, or the engine refused it. The message is the reason."
}
}
}
}
},
"429": {
"description": "`rate_limited`: Too many attempts. The message says the budget.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "rate_limited",
"message": "Too many attempts. The message says the budget."
}
}
}
}
},
"500": {
"description": "`internal`: Something went wrong on our side. Quote the x-request-id.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "internal",
"message": "Something went wrong on our side. Quote the x-request-id."
}
}
}
}
}
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"phone": {
"type": "string",
"minLength": 7,
"maxLength": 20
},
"obtained_via": {
"type": "string",
"minLength": 3,
"maxLength": 200
},
"wording": {
"type": "string",
"minLength": 20,
"maxLength": 2000
}
},
"required": [
"phone",
"obtained_via",
"wording"
],
"additionalProperties": false
}
}
}
}
},
"get": {
"operationId": "get-sms-consents",
"summary": "Whether a number may be texted",
"description": "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`.",
"tags": [
"Texting consent"
],
"security": [
{
"apiKey": []
},
{
"oauth": [
"signing:read"
]
}
],
"x-scope": "signing:read",
"parameters": [
{
"name": "phone",
"in": "query",
"required": true,
"description": "The number, as a person would type it.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Done.",
"headers": {
"X-RateLimit-Limit": {
"description": "Requests this key may make in the window.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Remaining": {
"description": "Requests left in this window.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Reset": {
"description": "When the window turns over, in seconds since the epoch.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"example": {
"phone": "+15035550142",
"may_text": true,
"why_not": null,
"obtained_via": "booking form, checkbox beside the phone field",
"obtained_at": "2026-10-03T14:22:09Z"
}
}
}
},
"400": {
"description": "`bad_request`: The request could not be read.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "bad_request",
"message": "The request could not be read."
}
}
}
}
},
"401": {
"description": "`unauthorized`: No key, or a key that is not live. Unknown, revoked and expired all answer the same way.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "unauthorized",
"message": "No key, or a key that is not live. Unknown, revoked and expired all answer the same way."
}
}
}
}
},
"402": {
"description": "`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, and retrying will not help until credit is added.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "quota_exceeded",
"message": "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, and retrying will not help until credit is added."
}
}
}
}
},
"403": {
"description": "`forbidden`: The key is live but its scopes do not carry this.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "forbidden",
"message": "The key is live but its scopes do not carry this."
}
}
}
}
},
"404": {
"description": "`not_found`: No such thing, in this account.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "not_found",
"message": "No such thing, in this account."
}
}
}
}
},
"405": {
"description": "`method_not_allowed`: That path exists under another method.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "method_not_allowed",
"message": "That path exists under another method."
}
}
}
}
},
"409": {
"description": "`conflict`: The same idempotency key was used for a different request, or the work is still running; or the thing named has moved on -- a template revised from a version that is no longer the newest. The message says which. `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.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"conflict": {
"value": {
"error": {
"code": "conflict",
"message": "The same idempotency key was used for a different request, or the work is still running; or the thing named has moved on -- a template revised from a version that is no longer the newest. The message says which."
}
}
},
"template_changed": {
"value": {
"error": {
"code": "template_changed",
"message": "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."
}
}
}
}
}
}
},
"413": {
"description": "`too_large`: The body is larger than a signing request ever is.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "too_large",
"message": "The body is larger than a signing request ever is."
}
}
}
}
},
"422": {
"description": "`invalid`: The body did not validate, or the engine refused it. The message is the reason.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "invalid",
"message": "The body did not validate, or the engine refused it. The message is the reason."
}
}
}
}
},
"429": {
"description": "`rate_limited`: Too many attempts. The message says the budget.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "rate_limited",
"message": "Too many attempts. The message says the budget."
}
}
}
}
},
"500": {
"description": "`internal`: Something went wrong on our side. Quote the x-request-id.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "internal",
"message": "Something went wrong on our side. Quote the x-request-id."
}
}
}
}
}
}
}
},
"/v1/templates": {
"get": {
"operationId": "get-templates",
"summary": "List templates",
"description": "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.",
"tags": [
"Templates"
],
"security": [
{
"apiKey": []
},
{
"oauth": [
"signing:read"
]
}
],
"x-scope": "signing:read",
"parameters": [
{
"name": "code",
"in": "query",
"required": false,
"description": "Only this template's versions.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Done.",
"headers": {
"X-RateLimit-Limit": {
"description": "Requests this key may make in the window.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Remaining": {
"description": "Requests left in this window.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Reset": {
"description": "When the window turns over, in seconds since the epoch.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"example": {
"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
}
]
}
}
}
},
"400": {
"description": "`bad_request`: The request could not be read.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "bad_request",
"message": "The request could not be read."
}
}
}
}
},
"401": {
"description": "`unauthorized`: No key, or a key that is not live. Unknown, revoked and expired all answer the same way.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "unauthorized",
"message": "No key, or a key that is not live. Unknown, revoked and expired all answer the same way."
}
}
}
}
},
"402": {
"description": "`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, and retrying will not help until credit is added.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "quota_exceeded",
"message": "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, and retrying will not help until credit is added."
}
}
}
}
},
"403": {
"description": "`forbidden`: The key is live but its scopes do not carry this.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "forbidden",
"message": "The key is live but its scopes do not carry this."
}
}
}
}
},
"404": {
"description": "`not_found`: No such thing, in this account.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "not_found",
"message": "No such thing, in this account."
}
}
}
}
},
"405": {
"description": "`method_not_allowed`: That path exists under another method.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "method_not_allowed",
"message": "That path exists under another method."
}
}
}
}
},
"409": {
"description": "`conflict`: The same idempotency key was used for a different request, or the work is still running; or the thing named has moved on -- a template revised from a version that is no longer the newest. The message says which. `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.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"conflict": {
"value": {
"error": {
"code": "conflict",
"message": "The same idempotency key was used for a different request, or the work is still running; or the thing named has moved on -- a template revised from a version that is no longer the newest. The message says which."
}
}
},
"template_changed": {
"value": {
"error": {
"code": "template_changed",
"message": "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."
}
}
}
}
}
}
},
"413": {
"description": "`too_large`: The body is larger than a signing request ever is.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "too_large",
"message": "The body is larger than a signing request ever is."
}
}
}
}
},
"422": {
"description": "`invalid`: The body did not validate, or the engine refused it. The message is the reason.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "invalid",
"message": "The body did not validate, or the engine refused it. The message is the reason."
}
}
}
}
},
"429": {
"description": "`rate_limited`: Too many attempts. The message says the budget.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "rate_limited",
"message": "Too many attempts. The message says the budget."
}
}
}
}
},
"500": {
"description": "`internal`: Something went wrong on our side. Quote the x-request-id.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "internal",
"message": "Something went wrong on our side. Quote the x-request-id."
}
}
}
}
}
}
},
"post": {
"operationId": "post-templates",
"summary": "Create a template",
"description": "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 an earlier answer says so (`show_if: {\"field\": \"injured\", \"ticked\": true}`, or `equals` a list of choices, or `answered`); 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.",
"tags": [
"Templates"
],
"security": [
{
"apiKey": []
},
{
"oauth": [
"signing:templates"
]
}
],
"x-scope": "signing:templates",
"parameters": [
{
"name": "Idempotency-Key",
"in": "header",
"required": false,
"description": "Your own key, 8–255 characters. The same key with the same body replays the first response without doing the work again; the same key with a different body is refused rather than absorbed.",
"schema": {
"type": "string",
"minLength": 8,
"maxLength": 255
}
}
],
"responses": {
"201": {
"description": "Made.",
"headers": {
"X-RateLimit-Limit": {
"description": "Requests this key may make in the window.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Remaining": {
"description": "Requests left in this window.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Reset": {
"description": "When the window turns over, in seconds since the epoch.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"example": {
"template_id": "8c2e…"
}
}
}
},
"400": {
"description": "`bad_request`: The request could not be read.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "bad_request",
"message": "The request could not be read."
}
}
}
}
},
"401": {
"description": "`unauthorized`: No key, or a key that is not live. Unknown, revoked and expired all answer the same way.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "unauthorized",
"message": "No key, or a key that is not live. Unknown, revoked and expired all answer the same way."
}
}
}
}
},
"402": {
"description": "`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, and retrying will not help until credit is added.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "quota_exceeded",
"message": "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, and retrying will not help until credit is added."
}
}
}
}
},
"403": {
"description": "`forbidden`: The key is live but its scopes do not carry this.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "forbidden",
"message": "The key is live but its scopes do not carry this."
}
}
}
}
},
"404": {
"description": "`not_found`: No such thing, in this account.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "not_found",
"message": "No such thing, in this account."
}
}
}
}
},
"405": {
"description": "`method_not_allowed`: That path exists under another method.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "method_not_allowed",
"message": "That path exists under another method."
}
}
}
}
},
"409": {
"description": "`conflict`: The same idempotency key was used for a different request, or the work is still running; or the thing named has moved on -- a template revised from a version that is no longer the newest. The message says which. `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.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"conflict": {
"value": {
"error": {
"code": "conflict",
"message": "The same idempotency key was used for a different request, or the work is still running; or the thing named has moved on -- a template revised from a version that is no longer the newest. The message says which."
}
}
},
"template_changed": {
"value": {
"error": {
"code": "template_changed",
"message": "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."
}
}
}
}
}
}
},
"413": {
"description": "`too_large`: The body is larger than a signing request ever is.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "too_large",
"message": "The body is larger than a signing request ever is."
}
}
}
}
},
"422": {
"description": "`invalid`: The body did not validate, or the engine refused it. The message is the reason.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "invalid",
"message": "The body did not validate, or the engine refused it. The message is the reason."
}
}
}
}
},
"429": {
"description": "`rate_limited`: Too many attempts. The message says the budget.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "rate_limited",
"message": "Too many attempts. The message says the budget."
}
}
}
}
},
"500": {
"description": "`internal`: Something went wrong on our side. Quote the x-request-id.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "internal",
"message": "Something went wrong on our side. Quote the x-request-id."
}
}
}
}
}
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"code": {
"type": "string",
"pattern": "^[a-z][a-z0-9_-]*$"
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"kind": {
"type": "string",
"enum": [
"nda",
"waiver",
"contract",
"consent",
"policy",
"other"
]
},
"body": {
"type": "string",
"minLength": 1
},
"variables": {
"type": "array",
"items": {
"type": "string"
}
},
"grants": {
"type": "object",
"additionalProperties": true
},
"consent_text": {
"nullable": true,
"type": "string"
},
"fields": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"pattern": "^[a-z][a-z0-9_]{0,58}$"
},
"label": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"kind": {
"type": "string",
"minLength": 1,
"maxLength": 20
},
"required": {
"type": "boolean"
},
"sensitive": {
"type": "boolean"
},
"supplied_by": {
"type": "string",
"enum": [
"adult",
"per_child",
"staff"
]
},
"options": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 80
},
"maxItems": 30
},
"hint": {
"type": "string",
"maxLength": 200
},
"show_if": {
"nullable": true,
"type": "object",
"additionalProperties": true
},
"flag_when": {
"nullable": true,
"type": "object",
"additionalProperties": true
},
"block": {
"nullable": true,
"type": "string",
"maxLength": 59
},
"block_label": {
"nullable": true,
"type": "string",
"maxLength": 200
},
"block_intro": {
"nullable": true,
"type": "string",
"maxLength": 2000
},
"block_step": {
"nullable": true,
"type": "boolean"
},
"place": {
"nullable": true,
"type": "object",
"additionalProperties": true
}
},
"required": [
"key",
"kind"
],
"additionalProperties": false
},
"maxItems": 50
}
},
"required": [
"code",
"name",
"kind",
"body"
],
"additionalProperties": false
}
}
}
}
}
},
"/v1/templates/{id}": {
"get": {
"operationId": "get-templates-by-id",
"summary": "Show one template version",
"description": "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.",
"tags": [
"Templates"
],
"security": [
{
"apiKey": []
},
{
"oauth": [
"signing:read"
]
}
],
"x-scope": "signing:read",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Done.",
"headers": {
"X-RateLimit-Limit": {
"description": "Requests this key may make in the window.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Remaining": {
"description": "Requests left in this window.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Reset": {
"description": "When the window turns over, in seconds since the epoch.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"example": {
"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
}
]
}
}
}
},
"400": {
"description": "`bad_request`: The request could not be read.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "bad_request",
"message": "The request could not be read."
}
}
}
}
},
"401": {
"description": "`unauthorized`: No key, or a key that is not live. Unknown, revoked and expired all answer the same way.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "unauthorized",
"message": "No key, or a key that is not live. Unknown, revoked and expired all answer the same way."
}
}
}
}
},
"402": {
"description": "`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, and retrying will not help until credit is added.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "quota_exceeded",
"message": "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, and retrying will not help until credit is added."
}
}
}
}
},
"403": {
"description": "`forbidden`: The key is live but its scopes do not carry this.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "forbidden",
"message": "The key is live but its scopes do not carry this."
}
}
}
}
},
"404": {
"description": "`not_found`: No such thing, in this account.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "not_found",
"message": "No such thing, in this account."
}
}
}
}
},
"405": {
"description": "`method_not_allowed`: That path exists under another method.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "method_not_allowed",
"message": "That path exists under another method."
}
}
}
}
},
"409": {
"description": "`conflict`: The same idempotency key was used for a different request, or the work is still running; or the thing named has moved on -- a template revised from a version that is no longer the newest. The message says which. `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.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"conflict": {
"value": {
"error": {
"code": "conflict",
"message": "The same idempotency key was used for a different request, or the work is still running; or the thing named has moved on -- a template revised from a version that is no longer the newest. The message says which."
}
}
},
"template_changed": {
"value": {
"error": {
"code": "template_changed",
"message": "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."
}
}
}
}
}
}
},
"413": {
"description": "`too_large`: The body is larger than a signing request ever is.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "too_large",
"message": "The body is larger than a signing request ever is."
}
}
}
}
},
"422": {
"description": "`invalid`: The body did not validate, or the engine refused it. The message is the reason.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "invalid",
"message": "The body did not validate, or the engine refused it. The message is the reason."
}
}
}
}
},
"429": {
"description": "`rate_limited`: Too many attempts. The message says the budget.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "rate_limited",
"message": "Too many attempts. The message says the budget."
}
}
}
}
},
"500": {
"description": "`internal`: Something went wrong on our side. Quote the x-request-id.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "internal",
"message": "Something went wrong on our side. Quote the x-request-id."
}
}
}
}
}
}
},
"patch": {
"operationId": "patch-templates-by-id",
"summary": "Change a draft",
"description": "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.",
"tags": [
"Templates"
],
"security": [
{
"apiKey": []
},
{
"oauth": [
"signing:templates"
]
}
],
"x-scope": "signing:templates",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Done.",
"headers": {
"X-RateLimit-Limit": {
"description": "Requests this key may make in the window.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Remaining": {
"description": "Requests left in this window.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Reset": {
"description": "When the window turns over, in seconds since the epoch.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"example": {
"template_id": "8c2e…",
"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": "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
}
]
}
}
}
},
"400": {
"description": "`bad_request`: The request could not be read.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "bad_request",
"message": "The request could not be read."
}
}
}
}
},
"401": {
"description": "`unauthorized`: No key, or a key that is not live. Unknown, revoked and expired all answer the same way.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "unauthorized",
"message": "No key, or a key that is not live. Unknown, revoked and expired all answer the same way."
}
}
}
}
},
"402": {
"description": "`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, and retrying will not help until credit is added.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "quota_exceeded",
"message": "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, and retrying will not help until credit is added."
}
}
}
}
},
"403": {
"description": "`forbidden`: The key is live but its scopes do not carry this.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "forbidden",
"message": "The key is live but its scopes do not carry this."
}
}
}
}
},
"404": {
"description": "`not_found`: No such thing, in this account.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "not_found",
"message": "No such thing, in this account."
}
}
}
}
},
"405": {
"description": "`method_not_allowed`: That path exists under another method.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "method_not_allowed",
"message": "That path exists under another method."
}
}
}
}
},
"409": {
"description": "`conflict`: The same idempotency key was used for a different request, or the work is still running; or the thing named has moved on -- a template revised from a version that is no longer the newest. The message says which. `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.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"conflict": {
"value": {
"error": {
"code": "conflict",
"message": "The same idempotency key was used for a different request, or the work is still running; or the thing named has moved on -- a template revised from a version that is no longer the newest. The message says which."
}
}
},
"template_changed": {
"value": {
"error": {
"code": "template_changed",
"message": "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."
}
}
}
}
}
}
},
"413": {
"description": "`too_large`: The body is larger than a signing request ever is.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "too_large",
"message": "The body is larger than a signing request ever is."
}
}
}
}
},
"422": {
"description": "`invalid`: The body did not validate, or the engine refused it. The message is the reason.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "invalid",
"message": "The body did not validate, or the engine refused it. The message is the reason."
}
}
}
}
},
"429": {
"description": "`rate_limited`: Too many attempts. The message says the budget.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "rate_limited",
"message": "Too many attempts. The message says the budget."
}
}
}
}
},
"500": {
"description": "`internal`: Something went wrong on our side. Quote the x-request-id.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "internal",
"message": "Something went wrong on our side. Quote the x-request-id."
}
}
}
}
}
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"body": {
"type": "string",
"minLength": 1
},
"body_format": {
"type": "string",
"enum": [
"text",
"markdown"
]
},
"variables": {
"type": "array",
"items": {
"type": "string"
}
},
"fields": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"pattern": "^[a-z][a-z0-9_]{0,58}$"
},
"label": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"kind": {
"type": "string",
"minLength": 1,
"maxLength": 20
},
"required": {
"type": "boolean"
},
"sensitive": {
"type": "boolean"
},
"supplied_by": {
"type": "string",
"enum": [
"adult",
"per_child",
"staff"
]
},
"options": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 80
},
"maxItems": 30
},
"hint": {
"type": "string",
"maxLength": 200
},
"show_if": {
"nullable": true,
"type": "object",
"additionalProperties": true
},
"flag_when": {
"nullable": true,
"type": "object",
"additionalProperties": true
},
"block": {
"nullable": true,
"type": "string",
"maxLength": 59
},
"block_label": {
"nullable": true,
"type": "string",
"maxLength": 200
},
"block_intro": {
"nullable": true,
"type": "string",
"maxLength": 2000
},
"block_step": {
"nullable": true,
"type": "boolean"
},
"place": {
"nullable": true,
"type": "object",
"additionalProperties": true
}
},
"required": [
"key",
"kind"
],
"additionalProperties": false
},
"maxItems": 50
},
"change_note": {
"nullable": true,
"type": "string",
"maxLength": 500
}
},
"additionalProperties": false
}
}
}
}
},
"delete": {
"operationId": "delete-templates-by-id",
"summary": "Discard a draft",
"description": "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.",
"tags": [
"Templates"
],
"security": [
{
"apiKey": []
},
{
"oauth": [
"signing:templates"
]
}
],
"x-scope": "signing:templates",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Done.",
"headers": {
"X-RateLimit-Limit": {
"description": "Requests this key may make in the window.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Remaining": {
"description": "Requests left in this window.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Reset": {
"description": "When the window turns over, in seconds since the epoch.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"example": {
"template_id": "93aa…",
"code": "liability-waiver",
"version": 3,
"discarded": true
}
}
}
},
"400": {
"description": "`bad_request`: The request could not be read.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "bad_request",
"message": "The request could not be read."
}
}
}
}
},
"401": {
"description": "`unauthorized`: No key, or a key that is not live. Unknown, revoked and expired all answer the same way.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "unauthorized",
"message": "No key, or a key that is not live. Unknown, revoked and expired all answer the same way."
}
}
}
}
},
"402": {
"description": "`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, and retrying will not help until credit is added.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "quota_exceeded",
"message": "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, and retrying will not help until credit is added."
}
}
}
}
},
"403": {
"description": "`forbidden`: The key is live but its scopes do not carry this.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "forbidden",
"message": "The key is live but its scopes do not carry this."
}
}
}
}
},
"404": {
"description": "`not_found`: No such thing, in this account.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "not_found",
"message": "No such thing, in this account."
}
}
}
}
},
"405": {
"description": "`method_not_allowed`: That path exists under another method.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "method_not_allowed",
"message": "That path exists under another method."
}
}
}
}
},
"409": {
"description": "`conflict`: The same idempotency key was used for a different request, or the work is still running; or the thing named has moved on -- a template revised from a version that is no longer the newest. The message says which. `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.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"conflict": {
"value": {
"error": {
"code": "conflict",
"message": "The same idempotency key was used for a different request, or the work is still running; or the thing named has moved on -- a template revised from a version that is no longer the newest. The message says which."
}
}
},
"template_changed": {
"value": {
"error": {
"code": "template_changed",
"message": "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."
}
}
}
}
}
}
},
"413": {
"description": "`too_large`: The body is larger than a signing request ever is.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "too_large",
"message": "The body is larger than a signing request ever is."
}
}
}
}
},
"422": {
"description": "`invalid`: The body did not validate, or the engine refused it. The message is the reason.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "invalid",
"message": "The body did not validate, or the engine refused it. The message is the reason."
}
}
}
}
},
"429": {
"description": "`rate_limited`: Too many attempts. The message says the budget.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "rate_limited",
"message": "Too many attempts. The message says the budget."
}
}
}
}
},
"500": {
"description": "`internal`: Something went wrong on our side. Quote the x-request-id.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "internal",
"message": "Something went wrong on our side. Quote the x-request-id."
}
}
}
}
}
}
}
},
"/v1/templates/{id}/publish": {
"post": {
"operationId": "post-templates-by-id-publish",
"summary": "Publish a draft",
"description": "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, when an uploaded PDF has pages nobody has drawn yet, or when it is already published. Answers with the template.",
"tags": [
"Templates"
],
"security": [
{
"apiKey": []
},
{
"oauth": [
"signing:templates"
]
}
],
"x-scope": "signing:templates",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": false,
"description": "Your own key, 8–255 characters. The same key with the same body replays the first response without doing the work again; the same key with a different body is refused rather than absorbed.",
"schema": {
"type": "string",
"minLength": 8,
"maxLength": 255
}
}
],
"responses": {
"200": {
"description": "Done.",
"headers": {
"X-RateLimit-Limit": {
"description": "Requests this key may make in the window.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Remaining": {
"description": "Requests left in this window.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Reset": {
"description": "When the window turns over, in seconds since the epoch.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"example": {
"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
}
]
}
}
}
},
"400": {
"description": "`bad_request`: The request could not be read.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "bad_request",
"message": "The request could not be read."
}
}
}
}
},
"401": {
"description": "`unauthorized`: No key, or a key that is not live. Unknown, revoked and expired all answer the same way.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "unauthorized",
"message": "No key, or a key that is not live. Unknown, revoked and expired all answer the same way."
}
}
}
}
},
"402": {
"description": "`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, and retrying will not help until credit is added.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "quota_exceeded",
"message": "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, and retrying will not help until credit is added."
}
}
}
}
},
"403": {
"description": "`forbidden`: The key is live but its scopes do not carry this.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "forbidden",
"message": "The key is live but its scopes do not carry this."
}
}
}
}
},
"404": {
"description": "`not_found`: No such thing, in this account.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "not_found",
"message": "No such thing, in this account."
}
}
}
}
},
"405": {
"description": "`method_not_allowed`: That path exists under another method.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "method_not_allowed",
"message": "That path exists under another method."
}
}
}
}
},
"409": {
"description": "`conflict`: The same idempotency key was used for a different request, or the work is still running; or the thing named has moved on -- a template revised from a version that is no longer the newest. The message says which. `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.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"conflict": {
"value": {
"error": {
"code": "conflict",
"message": "The same idempotency key was used for a different request, or the work is still running; or the thing named has moved on -- a template revised from a version that is no longer the newest. The message says which."
}
}
},
"template_changed": {
"value": {
"error": {
"code": "template_changed",
"message": "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."
}
}
}
}
}
}
},
"413": {
"description": "`too_large`: The body is larger than a signing request ever is.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "too_large",
"message": "The body is larger than a signing request ever is."
}
}
}
}
},
"422": {
"description": "`invalid`: The body did not validate, or the engine refused it. The message is the reason.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "invalid",
"message": "The body did not validate, or the engine refused it. The message is the reason."
}
}
}
}
},
"429": {
"description": "`rate_limited`: Too many attempts. The message says the budget.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "rate_limited",
"message": "Too many attempts. The message says the budget."
}
}
}
}
},
"500": {
"description": "`internal`: Something went wrong on our side. Quote the x-request-id.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "internal",
"message": "Something went wrong on our side. Quote the x-request-id."
}
}
}
}
}
}
}
},
"/v1/templates/{id}/revise": {
"post": {
"operationId": "post-templates-by-id-revise",
"summary": "Make the next version of a template",
"description": "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.",
"tags": [
"Templates"
],
"security": [
{
"apiKey": []
},
{
"oauth": [
"signing:templates"
]
}
],
"x-scope": "signing:templates",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": false,
"description": "Your own key, 8–255 characters. The same key with the same body replays the first response without doing the work again; the same key with a different body is refused rather than absorbed.",
"schema": {
"type": "string",
"minLength": 8,
"maxLength": 255
}
}
],
"responses": {
"201": {
"description": "Made.",
"headers": {
"X-RateLimit-Limit": {
"description": "Requests this key may make in the window.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Remaining": {
"description": "Requests left in this window.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Reset": {
"description": "When the window turns over, in seconds since the epoch.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"example": {
"template_id": "8c2e…",
"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": "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
}
]
}
}
}
},
"400": {
"description": "`bad_request`: The request could not be read.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "bad_request",
"message": "The request could not be read."
}
}
}
}
},
"401": {
"description": "`unauthorized`: No key, or a key that is not live. Unknown, revoked and expired all answer the same way.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "unauthorized",
"message": "No key, or a key that is not live. Unknown, revoked and expired all answer the same way."
}
}
}
}
},
"402": {
"description": "`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, and retrying will not help until credit is added.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "quota_exceeded",
"message": "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, and retrying will not help until credit is added."
}
}
}
}
},
"403": {
"description": "`forbidden`: The key is live but its scopes do not carry this.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "forbidden",
"message": "The key is live but its scopes do not carry this."
}
}
}
}
},
"404": {
"description": "`not_found`: No such thing, in this account.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "not_found",
"message": "No such thing, in this account."
}
}
}
}
},
"405": {
"description": "`method_not_allowed`: That path exists under another method.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "method_not_allowed",
"message": "That path exists under another method."
}
}
}
}
},
"409": {
"description": "`conflict`: The same idempotency key was used for a different request, or the work is still running; or the thing named has moved on -- a template revised from a version that is no longer the newest. The message says which. `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.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"conflict": {
"value": {
"error": {
"code": "conflict",
"message": "The same idempotency key was used for a different request, or the work is still running; or the thing named has moved on -- a template revised from a version that is no longer the newest. The message says which."
}
}
},
"template_changed": {
"value": {
"error": {
"code": "template_changed",
"message": "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."
}
}
}
}
}
}
},
"413": {
"description": "`too_large`: The body is larger than a signing request ever is.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "too_large",
"message": "The body is larger than a signing request ever is."
}
}
}
}
},
"422": {
"description": "`invalid`: The body did not validate, or the engine refused it. The message is the reason.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "invalid",
"message": "The body did not validate, or the engine refused it. The message is the reason."
}
}
}
}
},
"429": {
"description": "`rate_limited`: Too many attempts. The message says the budget.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "rate_limited",
"message": "Too many attempts. The message says the budget."
}
}
}
}
},
"500": {
"description": "`internal`: Something went wrong on our side. Quote the x-request-id.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "internal",
"message": "Something went wrong on our side. Quote the x-request-id."
}
}
}
}
}
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"body": {
"type": "string",
"minLength": 1
},
"variables": {
"type": "array",
"items": {
"type": "string"
}
},
"fields": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"pattern": "^[a-z][a-z0-9_]{0,58}$"
},
"label": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"kind": {
"type": "string",
"minLength": 1,
"maxLength": 20
},
"required": {
"type": "boolean"
},
"sensitive": {
"type": "boolean"
},
"supplied_by": {
"type": "string",
"enum": [
"adult",
"per_child",
"staff"
]
},
"options": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 80
},
"maxItems": 30
},
"hint": {
"type": "string",
"maxLength": 200
},
"show_if": {
"nullable": true,
"type": "object",
"additionalProperties": true
},
"flag_when": {
"nullable": true,
"type": "object",
"additionalProperties": true
},
"block": {
"nullable": true,
"type": "string",
"maxLength": 59
},
"block_label": {
"nullable": true,
"type": "string",
"maxLength": 200
},
"block_intro": {
"nullable": true,
"type": "string",
"maxLength": 2000
},
"block_step": {
"nullable": true,
"type": "boolean"
},
"place": {
"nullable": true,
"type": "object",
"additionalProperties": true
}
},
"required": [
"key",
"kind"
],
"additionalProperties": false
},
"maxItems": 50
},
"change_note": {
"type": "string",
"maxLength": 500
}
},
"additionalProperties": false
}
}
}
}
}
},
"/v1/templates/{id}/restore": {
"post": {
"operationId": "post-templates-by-id-restore",
"summary": "Bring an older version back as a new draft",
"description": "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).",
"tags": [
"Templates"
],
"security": [
{
"apiKey": []
},
{
"oauth": [
"signing:templates"
]
}
],
"x-scope": "signing:templates",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": false,
"description": "Your own key, 8–255 characters. The same key with the same body replays the first response without doing the work again; the same key with a different body is refused rather than absorbed.",
"schema": {
"type": "string",
"minLength": 8,
"maxLength": 255
}
}
],
"responses": {
"201": {
"description": "Made.",
"headers": {
"X-RateLimit-Limit": {
"description": "Requests this key may make in the window.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Remaining": {
"description": "Requests left in this window.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Reset": {
"description": "When the window turns over, in seconds since the epoch.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"example": {
"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
}
]
}
}
}
},
"400": {
"description": "`bad_request`: The request could not be read.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "bad_request",
"message": "The request could not be read."
}
}
}
}
},
"401": {
"description": "`unauthorized`: No key, or a key that is not live. Unknown, revoked and expired all answer the same way.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "unauthorized",
"message": "No key, or a key that is not live. Unknown, revoked and expired all answer the same way."
}
}
}
}
},
"402": {
"description": "`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, and retrying will not help until credit is added.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "quota_exceeded",
"message": "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, and retrying will not help until credit is added."
}
}
}
}
},
"403": {
"description": "`forbidden`: The key is live but its scopes do not carry this.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "forbidden",
"message": "The key is live but its scopes do not carry this."
}
}
}
}
},
"404": {
"description": "`not_found`: No such thing, in this account.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "not_found",
"message": "No such thing, in this account."
}
}
}
}
},
"405": {
"description": "`method_not_allowed`: That path exists under another method.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "method_not_allowed",
"message": "That path exists under another method."
}
}
}
}
},
"409": {
"description": "`conflict`: The same idempotency key was used for a different request, or the work is still running; or the thing named has moved on -- a template revised from a version that is no longer the newest. The message says which. `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.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"conflict": {
"value": {
"error": {
"code": "conflict",
"message": "The same idempotency key was used for a different request, or the work is still running; or the thing named has moved on -- a template revised from a version that is no longer the newest. The message says which."
}
}
},
"template_changed": {
"value": {
"error": {
"code": "template_changed",
"message": "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."
}
}
}
}
}
}
},
"413": {
"description": "`too_large`: The body is larger than a signing request ever is.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "too_large",
"message": "The body is larger than a signing request ever is."
}
}
}
}
},
"422": {
"description": "`invalid`: The body did not validate, or the engine refused it. The message is the reason.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "invalid",
"message": "The body did not validate, or the engine refused it. The message is the reason."
}
}
}
}
},
"429": {
"description": "`rate_limited`: Too many attempts. The message says the budget.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "rate_limited",
"message": "Too many attempts. The message says the budget."
}
}
}
}
},
"500": {
"description": "`internal`: Something went wrong on our side. Quote the x-request-id.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "internal",
"message": "Something went wrong on our side. Quote the x-request-id."
}
}
}
}
}
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"change_note": {
"type": "string",
"maxLength": 450
}
},
"additionalProperties": false
}
}
}
}
}
},
"/v1/templates/{id}/settings": {
"patch": {
"operationId": "patch-templates-by-id-settings",
"summary": "Change a template's settings",
"description": "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.",
"tags": [
"Templates"
],
"security": [
{
"apiKey": []
},
{
"oauth": [
"signing:templates"
]
}
],
"x-scope": "signing:templates",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Done.",
"headers": {
"X-RateLimit-Limit": {
"description": "Requests this key may make in the window.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Remaining": {
"description": "Requests left in this window.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Reset": {
"description": "When the window turns over, in seconds since the epoch.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"example": {
"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
}
]
}
}
}
},
"400": {
"description": "`bad_request`: The request could not be read.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "bad_request",
"message": "The request could not be read."
}
}
}
}
},
"401": {
"description": "`unauthorized`: No key, or a key that is not live. Unknown, revoked and expired all answer the same way.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "unauthorized",
"message": "No key, or a key that is not live. Unknown, revoked and expired all answer the same way."
}
}
}
}
},
"402": {
"description": "`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, and retrying will not help until credit is added.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "quota_exceeded",
"message": "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, and retrying will not help until credit is added."
}
}
}
}
},
"403": {
"description": "`forbidden`: The key is live but its scopes do not carry this.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "forbidden",
"message": "The key is live but its scopes do not carry this."
}
}
}
}
},
"404": {
"description": "`not_found`: No such thing, in this account.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "not_found",
"message": "No such thing, in this account."
}
}
}
}
},
"405": {
"description": "`method_not_allowed`: That path exists under another method.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "method_not_allowed",
"message": "That path exists under another method."
}
}
}
}
},
"409": {
"description": "`conflict`: The same idempotency key was used for a different request, or the work is still running; or the thing named has moved on -- a template revised from a version that is no longer the newest. The message says which. `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.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"conflict": {
"value": {
"error": {
"code": "conflict",
"message": "The same idempotency key was used for a different request, or the work is still running; or the thing named has moved on -- a template revised from a version that is no longer the newest. The message says which."
}
}
},
"template_changed": {
"value": {
"error": {
"code": "template_changed",
"message": "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."
}
}
}
}
}
}
},
"413": {
"description": "`too_large`: The body is larger than a signing request ever is.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "too_large",
"message": "The body is larger than a signing request ever is."
}
}
}
}
},
"422": {
"description": "`invalid`: The body did not validate, or the engine refused it. The message is the reason.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "invalid",
"message": "The body did not validate, or the engine refused it. The message is the reason."
}
}
}
}
},
"429": {
"description": "`rate_limited`: Too many attempts. The message says the budget.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "rate_limited",
"message": "Too many attempts. The message says the budget."
}
}
}
}
},
"500": {
"description": "`internal`: Something went wrong on our side. Quote the x-request-id.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "internal",
"message": "Something went wrong on our side. Quote the x-request-id."
}
}
}
}
}
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"one_time": {
"type": "boolean"
},
"show_address": {
"type": "boolean"
},
"photos_in_copy": {
"type": "boolean"
},
"valid_months": {
"nullable": true,
"type": "integer",
"minimum": 1,
"maximum": 120
},
"remind_days": {
"nullable": true,
"type": "integer",
"minimum": 1,
"maximum": 90
},
"resign": {
"type": "boolean"
}
},
"additionalProperties": false
}
}
}
}
}
},
"/v1/standing": {
"get": {
"operationId": "get-standing",
"summary": "Whether somebody's signature on a template is still good",
"description": "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.",
"tags": [
"Standing"
],
"security": [
{
"apiKey": []
},
{
"oauth": [
"signing:read"
]
}
],
"x-scope": "signing:read",
"parameters": [
{
"name": "template",
"in": "query",
"required": true,
"description": "The template's code.",
"schema": {
"type": "string"
}
},
{
"name": "email",
"in": "query",
"required": false,
"description": "Whose standing, by email address. This or `phone`.",
"schema": {
"type": "string",
"format": "email"
}
},
{
"name": "phone",
"in": "query",
"required": false,
"description": "Whose standing, by mobile number. This or `email`.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Done.",
"headers": {
"X-RateLimit-Limit": {
"description": "Requests this key may make in the window.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Remaining": {
"description": "Requests left in this window.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Reset": {
"description": "When the window turns over, in seconds since the epoch.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"example": {
"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"
}
}
}
},
"400": {
"description": "`bad_request`: The request could not be read.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "bad_request",
"message": "The request could not be read."
}
}
}
}
},
"401": {
"description": "`unauthorized`: No key, or a key that is not live. Unknown, revoked and expired all answer the same way.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "unauthorized",
"message": "No key, or a key that is not live. Unknown, revoked and expired all answer the same way."
}
}
}
}
},
"402": {
"description": "`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, and retrying will not help until credit is added.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "quota_exceeded",
"message": "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, and retrying will not help until credit is added."
}
}
}
}
},
"403": {
"description": "`forbidden`: The key is live but its scopes do not carry this.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "forbidden",
"message": "The key is live but its scopes do not carry this."
}
}
}
}
},
"404": {
"description": "`not_found`: No such thing, in this account.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "not_found",
"message": "No such thing, in this account."
}
}
}
}
},
"405": {
"description": "`method_not_allowed`: That path exists under another method.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "method_not_allowed",
"message": "That path exists under another method."
}
}
}
}
},
"409": {
"description": "`conflict`: The same idempotency key was used for a different request, or the work is still running; or the thing named has moved on -- a template revised from a version that is no longer the newest. The message says which. `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.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"conflict": {
"value": {
"error": {
"code": "conflict",
"message": "The same idempotency key was used for a different request, or the work is still running; or the thing named has moved on -- a template revised from a version that is no longer the newest. The message says which."
}
}
},
"template_changed": {
"value": {
"error": {
"code": "template_changed",
"message": "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."
}
}
}
}
}
}
},
"413": {
"description": "`too_large`: The body is larger than a signing request ever is.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "too_large",
"message": "The body is larger than a signing request ever is."
}
}
}
}
},
"422": {
"description": "`invalid`: The body did not validate, or the engine refused it. The message is the reason.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "invalid",
"message": "The body did not validate, or the engine refused it. The message is the reason."
}
}
}
}
},
"429": {
"description": "`rate_limited`: Too many attempts. The message says the budget.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "rate_limited",
"message": "Too many attempts. The message says the budget."
}
}
}
}
},
"500": {
"description": "`internal`: Something went wrong on our side. Quote the x-request-id.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "internal",
"message": "Something went wrong on our side. Quote the x-request-id."
}
}
}
}
}
}
}
},
"/v1/templates/{id}/pdf": {
"get": {
"operationId": "get-templates-by-id-pdf",
"summary": "Whether a template is an uploaded PDF",
"description": "`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 have a picture a signer can read, and `ready` is whether those agree — a PDF template cannot be published until they do. `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.",
"tags": [
"Templates"
],
"security": [
{
"apiKey": []
},
{
"oauth": [
"signing:read"
]
}
],
"x-scope": "signing:read",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Done.",
"headers": {
"X-RateLimit-Limit": {
"description": "Requests this key may make in the window.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Remaining": {
"description": "Requests left in this window.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Reset": {
"description": "When the window turns over, in seconds since the epoch.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"example": {
"has_pdf": true,
"page_count": 4,
"drawn": 4,
"ready": true,
"pages": [
{
"n": 1,
"width": 612,
"height": 792,
"rotation": 0
}
],
"bytes": 284113,
"sha256": "e362cc76dae17bbe2a9fc551d9b795fa4e0f77fb488eb748378a125b11f36324",
"original_name": "tenancy.pdf",
"uploaded_at": "2026-10-03T14:22:09Z"
}
}
}
},
"400": {
"description": "`bad_request`: The request could not be read.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "bad_request",
"message": "The request could not be read."
}
}
}
}
},
"401": {
"description": "`unauthorized`: No key, or a key that is not live. Unknown, revoked and expired all answer the same way.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "unauthorized",
"message": "No key, or a key that is not live. Unknown, revoked and expired all answer the same way."
}
}
}
}
},
"402": {
"description": "`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, and retrying will not help until credit is added.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "quota_exceeded",
"message": "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, and retrying will not help until credit is added."
}
}
}
}
},
"403": {
"description": "`forbidden`: The key is live but its scopes do not carry this.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "forbidden",
"message": "The key is live but its scopes do not carry this."
}
}
}
}
},
"404": {
"description": "`not_found`: No such thing, in this account.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "not_found",
"message": "No such thing, in this account."
}
}
}
}
},
"405": {
"description": "`method_not_allowed`: That path exists under another method.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "method_not_allowed",
"message": "That path exists under another method."
}
}
}
}
},
"409": {
"description": "`conflict`: The same idempotency key was used for a different request, or the work is still running; or the thing named has moved on -- a template revised from a version that is no longer the newest. The message says which. `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.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"conflict": {
"value": {
"error": {
"code": "conflict",
"message": "The same idempotency key was used for a different request, or the work is still running; or the thing named has moved on -- a template revised from a version that is no longer the newest. The message says which."
}
}
},
"template_changed": {
"value": {
"error": {
"code": "template_changed",
"message": "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."
}
}
}
}
}
}
},
"413": {
"description": "`too_large`: The body is larger than a signing request ever is.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "too_large",
"message": "The body is larger than a signing request ever is."
}
}
}
}
},
"422": {
"description": "`invalid`: The body did not validate, or the engine refused it. The message is the reason.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "invalid",
"message": "The body did not validate, or the engine refused it. The message is the reason."
}
}
}
}
},
"429": {
"description": "`rate_limited`: Too many attempts. The message says the budget.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "rate_limited",
"message": "Too many attempts. The message says the budget."
}
}
}
}
},
"500": {
"description": "`internal`: Something went wrong on our side. Quote the x-request-id.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "internal",
"message": "Something went wrong on our side. Quote the x-request-id."
}
}
}
}
}
}
}
},
"/v1/documents": {
"get": {
"operationId": "get-documents",
"summary": "List documents",
"description": "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`.",
"tags": [
"Documents"
],
"security": [
{
"apiKey": []
},
{
"oauth": [
"signing:read"
]
}
],
"x-scope": "signing:read",
"parameters": [
{
"name": "status",
"in": "query",
"required": false,
"description": "A state -- `draft`, `sent`, `completed`, `declined`, `expired`, `void` -- or `open` for draft and sent.",
"schema": {
"type": "string"
}
},
{
"name": "q",
"in": "query",
"required": false,
"description": "Part of a title, a subject's name, or a signer's name, email or number.",
"schema": {
"type": "string"
}
},
{
"name": "external_ref",
"in": "query",
"required": false,
"description": "Your own reference, as you gave it when you made the document. Exact.",
"schema": {
"type": "string"
}
},
{
"name": "limit",
"in": "query",
"required": false,
"description": "1 to 200; 50 when absent.",
"schema": {
"type": "integer"
}
},
{
"name": "offset",
"in": "query",
"required": false,
"description": "How many to skip; 0 when absent.",
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "Done.",
"headers": {
"X-RateLimit-Limit": {
"description": "Requests this key may make in the window.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Remaining": {
"description": "Requests left in this window.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Reset": {
"description": "When the window turns over, in seconds since the epoch.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"example": {
"documents": [
{
"document_id": "d41c…",
"title": "Liability waiver — Dana Reyes",
"status": "sent",
"template_code": "liability-waiver",
"template_version": 2,
"subject_name": 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,
"standing": null,
"valid_until": null,
"external_ref": null
},
{
"document_id": "c30b…",
"title": "Liability waiver — Sam Lee",
"status": "completed",
"template_code": "liability-waiver",
"template_version": 2,
"subject_name": 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,
"standing": "current",
"valid_until": "2027-10-03T14:22:09Z",
"external_ref": "booking-20931"
}
],
"total": 2,
"has_more": false,
"limit": 50,
"offset": 0
}
}
}
},
"400": {
"description": "`bad_request`: The request could not be read.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "bad_request",
"message": "The request could not be read."
}
}
}
}
},
"401": {
"description": "`unauthorized`: No key, or a key that is not live. Unknown, revoked and expired all answer the same way.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "unauthorized",
"message": "No key, or a key that is not live. Unknown, revoked and expired all answer the same way."
}
}
}
}
},
"402": {
"description": "`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, and retrying will not help until credit is added.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "quota_exceeded",
"message": "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, and retrying will not help until credit is added."
}
}
}
}
},
"403": {
"description": "`forbidden`: The key is live but its scopes do not carry this.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "forbidden",
"message": "The key is live but its scopes do not carry this."
}
}
}
}
},
"404": {
"description": "`not_found`: No such thing, in this account.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "not_found",
"message": "No such thing, in this account."
}
}
}
}
},
"405": {
"description": "`method_not_allowed`: That path exists under another method.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "method_not_allowed",
"message": "That path exists under another method."
}
}
}
}
},
"409": {
"description": "`conflict`: The same idempotency key was used for a different request, or the work is still running; or the thing named has moved on -- a template revised from a version that is no longer the newest. The message says which. `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.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"conflict": {
"value": {
"error": {
"code": "conflict",
"message": "The same idempotency key was used for a different request, or the work is still running; or the thing named has moved on -- a template revised from a version that is no longer the newest. The message says which."
}
}
},
"template_changed": {
"value": {
"error": {
"code": "template_changed",
"message": "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."
}
}
}
}
}
}
},
"413": {
"description": "`too_large`: The body is larger than a signing request ever is.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "too_large",
"message": "The body is larger than a signing request ever is."
}
}
}
}
},
"422": {
"description": "`invalid`: The body did not validate, or the engine refused it. The message is the reason.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "invalid",
"message": "The body did not validate, or the engine refused it. The message is the reason."
}
}
}
}
},
"429": {
"description": "`rate_limited`: Too many attempts. The message says the budget.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "rate_limited",
"message": "Too many attempts. The message says the budget."
}
}
}
}
},
"500": {
"description": "`internal`: Something went wrong on our side. Quote the x-request-id.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "internal",
"message": "Something went wrong on our side. Quote the x-request-id."
}
}
}
}
}
}
},
"post": {
"operationId": "post-documents",
"summary": "Prepare a document from a template",
"description": "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. 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.",
"tags": [
"Documents"
],
"security": [
{
"apiKey": []
},
{
"oauth": [
"signing:write"
]
}
],
"x-scope": "signing:write",
"parameters": [
{
"name": "Idempotency-Key",
"in": "header",
"required": false,
"description": "Your own key, 8–255 characters. The same key with the same body replays the first response without doing the work again; the same key with a different body is refused rather than absorbed.",
"schema": {
"type": "string",
"minLength": 8,
"maxLength": 255
}
}
],
"responses": {
"201": {
"description": "Made.",
"headers": {
"X-RateLimit-Limit": {
"description": "Requests this key may make in the window.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Remaining": {
"description": "Requests left in this window.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Reset": {
"description": "When the window turns over, in seconds since the epoch.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"example": {
"document_id": "d41c…"
}
}
}
},
"400": {
"description": "`bad_request`: The request could not be read.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "bad_request",
"message": "The request could not be read."
}
}
}
}
},
"401": {
"description": "`unauthorized`: No key, or a key that is not live. Unknown, revoked and expired all answer the same way.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "unauthorized",
"message": "No key, or a key that is not live. Unknown, revoked and expired all answer the same way."
}
}
}
}
},
"402": {
"description": "`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, and retrying will not help until credit is added.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "quota_exceeded",
"message": "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, and retrying will not help until credit is added."
}
}
}
}
},
"403": {
"description": "`forbidden`: The key is live but its scopes do not carry this.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "forbidden",
"message": "The key is live but its scopes do not carry this."
}
}
}
}
},
"404": {
"description": "`not_found`: No such thing, in this account.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "not_found",
"message": "No such thing, in this account."
}
}
}
}
},
"405": {
"description": "`method_not_allowed`: That path exists under another method.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "method_not_allowed",
"message": "That path exists under another method."
}
}
}
}
},
"409": {
"description": "`conflict`: The same idempotency key was used for a different request, or the work is still running; or the thing named has moved on -- a template revised from a version that is no longer the newest. The message says which. `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.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"conflict": {
"value": {
"error": {
"code": "conflict",
"message": "The same idempotency key was used for a different request, or the work is still running; or the thing named has moved on -- a template revised from a version that is no longer the newest. The message says which."
}
}
},
"template_changed": {
"value": {
"error": {
"code": "template_changed",
"message": "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."
}
}
}
}
}
}
},
"413": {
"description": "`too_large`: The body is larger than a signing request ever is.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "too_large",
"message": "The body is larger than a signing request ever is."
}
}
}
}
},
"422": {
"description": "`invalid`: The body did not validate, or the engine refused it. The message is the reason.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "invalid",
"message": "The body did not validate, or the engine refused it. The message is the reason."
}
}
}
}
},
"429": {
"description": "`rate_limited`: Too many attempts. The message says the budget.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "rate_limited",
"message": "Too many attempts. The message says the budget."
}
}
}
}
},
"500": {
"description": "`internal`: Something went wrong on our side. Quote the x-request-id.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "internal",
"message": "Something went wrong on our side. Quote the x-request-id."
}
}
}
}
}
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"template_code": {
"type": "string"
},
"title": {
"type": "string",
"maxLength": 200
},
"values": {
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"expires_at": {
"nullable": true,
"type": "string",
"format": "date-time"
},
"sequential": {
"type": "boolean"
},
"external_ref": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"metadata": {
"type": "object",
"additionalProperties": {
"type": "string",
"maxLength": 500
}
},
"return_url": {
"type": "string",
"format": "uri",
"maxLength": 2000
}
},
"required": [
"template_code"
],
"additionalProperties": false
}
}
}
}
}
},
"/v1/documents/{id}": {
"get": {
"operationId": "get-documents-by-id",
"summary": "Show one document",
"description": "The document, its signers, the whole event trail with the text hash each event was made against, 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.",
"tags": [
"Documents"
],
"security": [
{
"apiKey": []
},
{
"oauth": [
"signing:read"
]
}
],
"x-scope": "signing:read",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Done.",
"headers": {
"X-RateLimit-Limit": {
"description": "Requests this key may make in the window.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Remaining": {
"description": "Requests left in this window.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Reset": {
"description": "When the window turns over, in seconds since the epoch.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"example": {
"document_id": "d41c…",
"title": "Liability waiver — Dana Reyes",
"status": "completed",
"body": "I, Dana Reyes, …",
"body_sha256": "e362cc76dae17bbe2a9fc551d9b795fa4e0f77fb488eb748378a125b11f36324",
"template_code": "liability-waiver",
"template_version": 2,
"grants": {},
"sequential": false,
"sent_at": "2026-10-03T14:22:09Z",
"completed_at": "2026-10-03T14:22:09Z",
"voided_at": null,
"void_reason": null,
"integrity_ok": true,
"standing": "current",
"valid_until": "2027-10-03T14:22:09Z",
"renewed_by": null,
"signers": [
{
"signer_id": "5f0a…",
"email": "dana@example.com",
"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,
"decline_reason": null,
"token_expires_at": "2026-10-17T00:00:00Z"
}
],
"events": [
{
"event_id": "e1…",
"kind": "sent",
"occurred_at": "2026-10-03T14:22:09Z",
"signer_email": null,
"ip": null,
"user_agent": null,
"against_sha256": "e362cc76dae17bbe2a9fc551d9b795fa4e0f77fb488eb748378a125b11f36324",
"detail": null
},
{
"event_id": "e2…",
"kind": "consented",
"occurred_at": "2026-10-03T14:22:09Z",
"signer_email": "dana@example.com",
"ip": "203.0.113.9",
"user_agent": "Mozilla/5.0 …",
"against_sha256": "e362cc76dae17bbe2a9fc551d9b795fa4e0f77fb488eb748378a125b11f36324",
"detail": null
},
{
"event_id": "e3…",
"kind": "signed",
"occurred_at": "2026-10-03T14:22:09Z",
"signer_email": "dana@example.com",
"ip": "203.0.113.9",
"user_agent": "Mozilla/5.0 …",
"signature_method": "typed",
"against_sha256": "e362cc76dae17bbe2a9fc551d9b795fa4e0f77fb488eb748378a125b11f36324",
"detail": null
}
],
"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
}
}
}
},
"400": {
"description": "`bad_request`: The request could not be read.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "bad_request",
"message": "The request could not be read."
}
}
}
}
},
"401": {
"description": "`unauthorized`: No key, or a key that is not live. Unknown, revoked and expired all answer the same way.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "unauthorized",
"message": "No key, or a key that is not live. Unknown, revoked and expired all answer the same way."
}
}
}
}
},
"402": {
"description": "`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, and retrying will not help until credit is added.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "quota_exceeded",
"message": "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, and retrying will not help until credit is added."
}
}
}
}
},
"403": {
"description": "`forbidden`: The key is live but its scopes do not carry this.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "forbidden",
"message": "The key is live but its scopes do not carry this."
}
}
}
}
},
"404": {
"description": "`not_found`: No such thing, in this account.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "not_found",
"message": "No such thing, in this account."
}
}
}
}
},
"405": {
"description": "`method_not_allowed`: That path exists under another method.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "method_not_allowed",
"message": "That path exists under another method."
}
}
}
}
},
"409": {
"description": "`conflict`: The same idempotency key was used for a different request, or the work is still running; or the thing named has moved on -- a template revised from a version that is no longer the newest. The message says which. `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.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"conflict": {
"value": {
"error": {
"code": "conflict",
"message": "The same idempotency key was used for a different request, or the work is still running; or the thing named has moved on -- a template revised from a version that is no longer the newest. The message says which."
}
}
},
"template_changed": {
"value": {
"error": {
"code": "template_changed",
"message": "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."
}
}
}
}
}
}
},
"413": {
"description": "`too_large`: The body is larger than a signing request ever is.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "too_large",
"message": "The body is larger than a signing request ever is."
}
}
}
}
},
"422": {
"description": "`invalid`: The body did not validate, or the engine refused it. The message is the reason.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "invalid",
"message": "The body did not validate, or the engine refused it. The message is the reason."
}
}
}
}
},
"429": {
"description": "`rate_limited`: Too many attempts. The message says the budget.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "rate_limited",
"message": "Too many attempts. The message says the budget."
}
}
}
}
},
"500": {
"description": "`internal`: Something went wrong on our side. Quote the x-request-id.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "internal",
"message": "Something went wrong on our side. Quote the x-request-id."
}
}
}
}
}
}
}
},
"/v1/documents/{id}/signers": {
"get": {
"operationId": "get-documents-by-id-signers",
"summary": "Who has signed one document",
"description": "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.",
"tags": [
"Documents"
],
"security": [
{
"apiKey": []
},
{
"oauth": [
"signing:read"
]
}
],
"x-scope": "signing:read",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"200": {
"description": "Done.",
"headers": {
"X-RateLimit-Limit": {
"description": "Requests this key may make in the window.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Remaining": {
"description": "Requests left in this window.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Reset": {
"description": "When the window turns over, in seconds since the epoch.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"example": {
"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
}
]
}
}
}
},
"400": {
"description": "`bad_request`: The request could not be read.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "bad_request",
"message": "The request could not be read."
}
}
}
}
},
"401": {
"description": "`unauthorized`: No key, or a key that is not live. Unknown, revoked and expired all answer the same way.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "unauthorized",
"message": "No key, or a key that is not live. Unknown, revoked and expired all answer the same way."
}
}
}
}
},
"402": {
"description": "`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, and retrying will not help until credit is added.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "quota_exceeded",
"message": "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, and retrying will not help until credit is added."
}
}
}
}
},
"403": {
"description": "`forbidden`: The key is live but its scopes do not carry this.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "forbidden",
"message": "The key is live but its scopes do not carry this."
}
}
}
}
},
"404": {
"description": "`not_found`: No such thing, in this account.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "not_found",
"message": "No such thing, in this account."
}
}
}
}
},
"405": {
"description": "`method_not_allowed`: That path exists under another method.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "method_not_allowed",
"message": "That path exists under another method."
}
}
}
}
},
"409": {
"description": "`conflict`: The same idempotency key was used for a different request, or the work is still running; or the thing named has moved on -- a template revised from a version that is no longer the newest. The message says which. `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.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"conflict": {
"value": {
"error": {
"code": "conflict",
"message": "The same idempotency key was used for a different request, or the work is still running; or the thing named has moved on -- a template revised from a version that is no longer the newest. The message says which."
}
}
},
"template_changed": {
"value": {
"error": {
"code": "template_changed",
"message": "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."
}
}
}
}
}
}
},
"413": {
"description": "`too_large`: The body is larger than a signing request ever is.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "too_large",
"message": "The body is larger than a signing request ever is."
}
}
}
}
},
"422": {
"description": "`invalid`: The body did not validate, or the engine refused it. The message is the reason.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "invalid",
"message": "The body did not validate, or the engine refused it. The message is the reason."
}
}
}
}
},
"429": {
"description": "`rate_limited`: Too many attempts. The message says the budget.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "rate_limited",
"message": "Too many attempts. The message says the budget."
}
}
}
}
},
"500": {
"description": "`internal`: Something went wrong on our side. Quote the x-request-id.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "internal",
"message": "Something went wrong on our side. Quote the x-request-id."
}
}
}
}
}
}
}
},
"/v1/documents/{id}/signers/{signer}/link": {
"post": {
"operationId": "post-documents-by-id-signers-by-signer-link",
"summary": "A fresh signing link for a signer who has not signed, as a QR code",
"description": "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.",
"tags": [
"Documents"
],
"security": [
{
"apiKey": []
},
{
"oauth": [
"signing:write"
]
}
],
"x-scope": "signing:write",
"x-or-scope": "signing:workflows",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "signer",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
}
],
"responses": {
"201": {
"description": "Made.",
"headers": {
"X-RateLimit-Limit": {
"description": "Requests this key may make in the window.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Remaining": {
"description": "Requests left in this window.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Reset": {
"description": "When the window turns over, in seconds since the epoch.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"example": {
"document_id": "d41c…",
"signer_id": "5f0a…",
"url": "https://api.signsealer.com/s/9k3…",
"qr_svg": ""
}
}
}
},
"400": {
"description": "`bad_request`: The request could not be read.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "bad_request",
"message": "The request could not be read."
}
}
}
}
},
"401": {
"description": "`unauthorized`: No key, or a key that is not live. Unknown, revoked and expired all answer the same way.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "unauthorized",
"message": "No key, or a key that is not live. Unknown, revoked and expired all answer the same way."
}
}
}
}
},
"402": {
"description": "`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, and retrying will not help until credit is added.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "quota_exceeded",
"message": "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, and retrying will not help until credit is added."
}
}
}
}
},
"403": {
"description": "`forbidden`: The key is live but its scopes do not carry this.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "forbidden",
"message": "The key is live but its scopes do not carry this."
}
}
}
}
},
"404": {
"description": "`not_found`: No such thing, in this account.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "not_found",
"message": "No such thing, in this account."
}
}
}
}
},
"405": {
"description": "`method_not_allowed`: That path exists under another method.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "method_not_allowed",
"message": "That path exists under another method."
}
}
}
}
},
"409": {
"description": "`conflict`: The same idempotency key was used for a different request, or the work is still running; or the thing named has moved on -- a template revised from a version that is no longer the newest. The message says which. `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.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"conflict": {
"value": {
"error": {
"code": "conflict",
"message": "The same idempotency key was used for a different request, or the work is still running; or the thing named has moved on -- a template revised from a version that is no longer the newest. The message says which."
}
}
},
"template_changed": {
"value": {
"error": {
"code": "template_changed",
"message": "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."
}
}
}
}
}
}
},
"413": {
"description": "`too_large`: The body is larger than a signing request ever is.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "too_large",
"message": "The body is larger than a signing request ever is."
}
}
}
}
},
"422": {
"description": "`invalid`: The body did not validate, or the engine refused it. The message is the reason.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "invalid",
"message": "The body did not validate, or the engine refused it. The message is the reason."
}
}
}
}
},
"429": {
"description": "`rate_limited`: Too many attempts. The message says the budget.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "rate_limited",
"message": "Too many attempts. The message says the budget."
}
}
}
}
},
"500": {
"description": "`internal`: Something went wrong on our side. Quote the x-request-id.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "internal",
"message": "Something went wrong on our side. Quote the x-request-id."
}
}
}
}
}
}
}
},
"/v1/documents/{id}/signers/{signer}/remind": {
"post": {
"operationId": "post-documents-by-id-signers-by-signer-remind",
"summary": "Send a signer a reminder with a fresh link",
"description": "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, for a signer who has signed or declined, a copied recipient, a document that is not out for signature, or somebody there is no way to reach -- and in every one of those cases their link is left as it was.",
"tags": [
"Documents"
],
"security": [
{
"apiKey": []
},
{
"oauth": [
"signing:write"
]
}
],
"x-scope": "signing:write",
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "signer",
"in": "path",
"required": true,
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": false,
"description": "Your own key, 8–255 characters. The same key with the same body replays the first response without doing the work again; the same key with a different body is refused rather than absorbed.",
"schema": {
"type": "string",
"minLength": 8,
"maxLength": 255
}
}
],
"responses": {
"200": {
"description": "Done.",
"headers": {
"X-RateLimit-Limit": {
"description": "Requests this key may make in the window.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Remaining": {
"description": "Requests left in this window.",
"schema": {
"type": "integer"
}
},
"X-RateLimit-Reset": {
"description": "When the window turns over, in seconds since the epoch.",
"schema": {
"type": "integer"
}
}
},
"content": {
"application/json": {
"example": {
"document_id": "d41c…",
"signer_id": "5f0a…",
"reminded": true,
"by": "email"
}
}
}
},
"400": {
"description": "`bad_request`: The request could not be read.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "bad_request",
"message": "The request could not be read."
}
}
}
}
},
"401": {
"description": "`unauthorized`: No key, or a key that is not live. Unknown, revoked and expired all answer the same way.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "unauthorized",
"message": "No key, or a key that is not live. Unknown, revoked and expired all answer the same way."
}
}
}
}
},
"402": {
"description": "`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, and retrying will not help until credit is added.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "quota_exceeded",
"message": "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, and retrying will not help until credit is added."
}
}
}
}
},
"403": {
"description": "`forbidden`: The key is live but its scopes do not carry this.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "forbidden",
"message": "The key is live but its scopes do not carry this."
}
}
}
}
},
"404": {
"description": "`not_found`: No such thing, in this account.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "not_found",
"message": "No such thing, in this account."
}
}
}
}
},
"405": {
"description": "`method_not_allowed`: That path exists under another method.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "method_not_allowed",
"message": "That path exists under another method."
}
}
}
}
},
"409": {
"description": "`conflict`: The same idempotency key was used for a different request, or the work is still running; or the thing named has moved on -- a template revised from a version that is no longer the newest. The message says which. `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.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"conflict": {
"value": {
"error": {
"code": "conflict",
"message": "The same idempotency key was used for a different request, or the work is still running; or the thing named has moved on -- a template revised from a version that is no longer the newest. The message says which."
}
}
},
"template_changed": {
"value": {
"error": {
"code": "template_changed",
"message": "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."
}
}
}
}
}
}
},
"413": {
"description": "`too_large`: The body is larger than a signing request ever is.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "too_large",
"message": "The body is larger than a signing request ever is."
}
}
}
}
},
"422": {
"description": "`invalid`: The body did not validate, or the engine refused it. The message is the reason.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "invalid",
"message": "The body did not validate, or the engine refused it. The message is the reason."
}
}
}
}
},
"429": {
"description": "`rate_limited`: Too many attempts. The message says the budget.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "rate_limited",
"message": "Too many attempts. The message says the budget."
}
}
}
}
},
"500": {
"description": "`internal`: Something went wrong on our side. Quote the x-request-id.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"error": {
"code": "internal",
"message": "Something went wrong on our side. Quote the x-request-id."
}
}
}
}
}
}
}
},
"/v1/documents/{id}/signers/{signer}/embed": {
"post": {
"operationId": "post-documents-by-id-signers-by-signer-embed",
"summary": "A fresh signing link to show in a frame",
"description": "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). Put the url in an `