Create an envelope from a template, and optionally send it.
THE ENDPOINT THAT EMAILS REAL PEOPLE AND SPENDS REAL MONEY, and the reason Idempotency-Key is required rather than optional.
⚠️ A REPLAY RETURNS THE SAME ENVELOPE AND CREATES NOTHING. Send the identical body under the identical key and you receive the first attempt’s answer, byte for byte, with Idempotency-Replayed: true. No second envelope, no second invitation, no second billed envelope. Thatis what makes a timeout safe to retry — and none of the three products this API was designed against offers it.
A DIFFERENT BODY UNDER A USED KEY IS idempotency_key_reused, not a replay. A key identifies one request; answering a second one with the first one’s envelope is silent data loss wearing a 201.
KEYS ARE REMEMBERED FOR 1 DAY, per organisation and per environment (live and test never answer for one another). Past that the key is forgotten and the same string is a new request.
⚠️ values IS A LIST OF TRIPLES AND ONE OF THEM MAY FILL SEVERAL BOXES. Read GET /api/v1/templates/{templateId} first: it is where the (subject, data_key) pairs come from.
DOCUMENTS OF YOUR OWN MAY GO BESIDE THE TEMPLATE’S, in attachments. They follow the template’s documents in the order given, and their fields come from their own text tags, which may name a role the template does not. values fill only the template’s fields. Each recipient is shown the documents their role has fields on and those nobody has fields on, or every document when their role has none. See Attachments.
A REFUSAL CREATES NOTHING. Every 4xx below leaves no envelope behind — including a send refused after the draft was built, which is deleted again — and leaves the idempotency key free for a corrected retry.
POST
/
api
/
v1
/
envelopes
Create an envelope from a template, and optionally send it.
Authorization: Bearer vsk_live_…. Chosen over a bespoke X-API-KEY header because every client, proxy and log-redaction rule already knows this one. What a key may DO is its scopes — see x-scopes at the root of this document and x-required-scope on each operation. The scope list is not written here because OpenAPI reserves a requirement’s scope array for oauth2 and openIdConnect and requires it to be empty for an http scheme.
Headers
Idempotency-Key
string
required
Any string that identifies this request; a UUID is the usual choice, and at most 255 characters. ⚠️ REQUIRED. Without it a timeout is unresolvable: you cannot learn whether the envelope was created, and retrying makes a second one and emails everybody twice.
The caller’s own request identifier.
Example:
"01960000-0000-4000-8000-00000000ffff"
Body
application/json
The template, the people, the values, and whether to send.
The request.
template_id
string<uuid>
required
The template to instantiate. Layout is authored there, never here (§3).
Example:
"01960000-0000-4000-8000-0000000007e1"
recipients
object[]
required
⚠️ THE ORDER OF THIS ARRAY IS THE ORDER RECIPIENTS ARE LISTED IN, and without step it is also when they are asked: everyone together when the template’s roles that are not cc all share one step, otherwise one at a time in this order. Give step on every recipient to say when directly. Reordering it is a different request either way, and an idempotency key will not replay across the two.
One recipient: a person, or a role pre-signed under a standing authorisation (an entry carrying completion).
Option 1
Option 2
Show child attributes
values
object[]
Optional. Values to prefill, as triples. Omitted means none. ⚠️ A signature, a date_signed, a signer_name and a signer_email may not be prefilled — they are acts, or they are written by this system.
Show child attributes
subjects
object
Optional. WHO THIS ENVELOPE IS ABOUT, as a map from a subject key the template declares to true (on this envelope), false (not), or "ask": the signer who holds that person’s section is asked first, in a required question, and their answer decides. While it is open the person reads present: false and awaiting_signer: true on the envelope. Two cases are settled at send instead, with nobody asked: a person no recipient holds a box for is left out, and a person a recipient signs for in a role standing for the same person is included. A field addressed to a subject that is not on the envelope is hidden from the signer and not required.
A subject you do not name takes the template’s own rule: a required subject is on every envelope, and a conditional one is absent and the signer is never asked about them, whatever the template’s Ask, Include or Leave out says (that choice applies to envelopes sent from the dashboard). Omitting subjects altogether opens the same sections as naming nobody — but see the next paragraph, because the two are not the same request. A key the template does not declare is refused, and so are false and "ask" for a required subject — all invalid_request, and nothing is created.
⚠️ IT SETS WHAT THE DOCUMENT OPENS WITH, NOT WHAT IT MUST STAY. The signer can switch a conditional subject on or off on the signing page, in either direction, and every such change is recorded in the envelope’s audit history.
⚠️ NAME AS true OR "ask" EVERY conditional SUBJECT YOU PREFILL. A value for a subject you ask about is shown if the signer answers Yes, and cleared if they answer No. A value in values for a conditional subject you did not name as present or asked is handled in one of two ways, depending on whether subjects is in the request at all:
subjects sent (even {}): the subject is absent — by false, or by the template’s rule when unnamed — so the value contradicts the request and is refused with invalid_request. Nothing is created.
subjects omitted: the value is accepted and stored, but the subject is absent by the template’s rule when the envelope is sent, so the prefilled section opens HIDDEN until the signer switches it on.
Optional, default false. False creates a draft and emails nobody; true sends it, consuming the plan’s allowance and delivering an invitation to everyone whose turn it is.
expires_at
string<date-time> | null
Optional, default null — no deadline. When this envelope stops being signable, as an ISO 8601 instant. ⚠️ AN ABSOLUTE TIME RATHER THAN A DURATION, so a retried request carrying the same Idempotency-Key asks for the same deadline the first attempt did. At least 1 hour out and at most 365 days out; anything else is invalid_request. ⚠️ IT CANNOT BE CHANGED AFTERWARDS — there is no endpoint that extends a deadline yet, and an envelope that reaches one while partly signed can only be voided and started again, discarding the signatures already collected. It is enforced: every signing link is capped by it, no link can be reissued past it, and the envelope transitions to expired and emits envelope.expired once it passes.
brand_id
string<uuid> | null
Optional, default null — the organisation’s default brand. Which brand the envelope goes out under: the letterhead, the colours and the sending name a signer sees. ⚠️ THIS IS THE FIELD FOR SENDING ON BEHALF OF MANY CUSTOMER BRANDS FROM ONE ACCOUNT — change it between calls and the same integration sends Customer A’s paperwork under Customer A’s brand and Customer B’s under Customer B’s.
⚠️ AN ID THAT NAMES NO LIVE BRAND OF YOUR ORGANISATION IS REFUSED WITH brand_unknown, NOT IGNORED — including one that has been archived. The branding an envelope went out under is frozen the moment it is sent and cannot be corrected afterwards, so a wrong constant in your configuration would otherwise put somebody else’s letterhead on every envelope you ever send and nothing would say so.
It is recorded on the envelope, so a draft created with send: false still goes out under this brand when it is sent later.
Copy the id from Settings → Brands in the dashboard: brands are made and managed there, and no endpoint lists them. What a brand controls, and what it does not, is on Brands.
completion_delivery
enum<string>
Who tells the recipients the envelope is done and sends them the executed document. vumasign (the default for a send from the dashboard) means we email the sender and every recipient we are able to email, with the sealed PDF attached. integrator (the default for a send made with an API key) means we send nothing at completion and you do it. Omit it and the origin of the send decides — an envelope created with send: false and then sent from the dashboard is vumasign. It cannot be changed once the envelope has been sent.
⚠️ AN embedded RECIPIENT IS NEVER EMAILED, WHATEVER THIS SAYS. We issue one no signing link and send them no invitation, because their address may be an identifier of yours rather than a mailbox — so they are not sent the completed document either, even under vumasign. Delivering the executed document to an embedded recipient is yours on every envelope, and this field only decides who tells everybody else.
⚠️ IF YOU TAKE THIS ON, SUBSCRIBE TO envelope.sealed RATHER THAN envelope.completed. envelope.completed fires when the last person signs, which is about a minute before the executed document exists, and envelope.sealing_failed tells you it never will.
Available options:
vumasign,
integrator
reference
string | null
Optional, default null. Your own name for this envelope — an order number, a case id, the id of the row in your database that asked for it — opaque to us. Not blank, and at most 255 UTF-16 code units once composed to NFC, as JavaScript counts string length: most characters count as one, some (outside the Basic Multilingual Plane, such as most emoji) count as two. No maxLength is declared, because JSON Schema counts code points and would admit a value the server refuses. Stored and returned in Unicode NFC. GET /api/v1/envelopes?reference= finds every envelope carrying it, which is how you find out whether a request whose answer you lost created anything.
⚠️ IT IS NOT UNIQUE. We accept the same reference on any number of envelopes, and the list returns all of them, newest first. If you want one envelope per reference, make your references unique — derive it from the record that asked for the envelope, not from the attempt.
⚠️ IT CANNOT BE SET OR CHANGED AFTER CREATION. Not on a draft, not by a later request: a reference that could move would not identify anything.
Example:
"hire-2026-0917"
template_etag
string
Optional. The ETag of the template as you checked it — from GET /api/v1/templates/{templateId} or the template_etag of validate-values — with or without its quotes. When it is no longer current the request is refused with template_changed and nothing is created: the template has been renamed since, and a value could now fill a different box. ⚠️ SEND IT ON EVERY ENVELOPE. An unknown key fails loudly, but a SWAPPED one — two addresses exchanged — does not, and this is what catches it. Compared under the template’s lock, so nothing can change between the check and the copy.
Required string length: 1 - 200
attachments
object[]
Optional. Documents of your own sent beside the template’s, after them, in the order given — each a PDF or a Word .docx, base64-encoded, exactly as documents on POST /api/v1/envelopes/one-off. Their fields come from their own text tags, which name the roles in recipients: a template role, or a role only an attachment names, whose recipient then signs. A tag naming a role nobody holds, or using subject(...), is invalid_request, and values never fill an attachment. ⚠️ THE TEMPLATE’S DOCUMENTS AND THESE TOGETHER MAY BE AT MOST 10, and together these may hold at most 6 MB of document. Absent and [] are different requests under one Idempotency-Key; both make the template’s envelope alone.
Maximum array length: 9
Show child attributes
documents
object[]
Optional. The order the envelope’s documents are presented in: the signing page, the “Document N of M” above each page, the order fields are walked in, the completion email’s attachments, display_position on GET /api/v1/envelopes/{envelopeId}/documents, and the “document N of M” on each certificate. Absent: the template’s documents in its order, then attachments in the order given. Present: EVERY template document and EVERY attachment exactly once, each entry naming one of them — { "attachment": 0 } for the first of attachments, { "template_document": "<id>" } for a template document, by its id in GET /api/v1/templates/{templateId}’s documents. Allowed without attachments, to reorder a template of several documents. TO LEAVE A TEMPLATE DOCUMENT OFF THE ENVELOPE, name it with "include": false: it, its fields and any question wholly on it are not part of the envelope, and the rest close up. It is refused template_document_not_omittable when the envelope cannot do without it — the last signature box a required role is sure to sign, when no attachment gives another, a subject, a box that decides a kept box, part of a question a kept document also asks, every box of a role you name a recipient for — or when every template document is left out. ⚠️ A TEMPLATE DOCUMENT NOT NAMED AT ALL IS invalid_request, not left out, so a document is never dropped without your saying so; so is an attachment left out, a document named twice, "include": false on an attachment, or an index past attachments. An id the template does not hold is template_changed: read the template again. The first of the template’s documents you keep is position 1 of the envelope, whatever its place here. A different order is a different request under one Idempotency-Key. Not accepted on a batch.
Required array length: 1 - 19 elements
One document of the envelope, by exactly one key: attachment or template_document.
Option 1
Option 2
Show child attributes
Response
The envelope, as it stands. Idempotency-Replayed says whether this request created it (false) or is being shown an earlier one’s result (true); the status is 201 either way, deliberately, so that a client branching on it behaves identically on a retry.
The envelope.
id
string<uuid>
required
The envelope’s id. A bare uuid.
status
string
required
draft or sent from this endpoint. Later states arrive as people act.
template_id
string<uuid> | null
required
The template this was made from, or null when there was none — an envelope created by POST /api/v1/envelopes/one-off carries the document itself and never had a template. Branch on null, never on the empty string.
title
string
required
What the signers see naming the document. Defaults to the template’s name.
reference
string | null
required
The reference you set when you created it, in Unicode NFC, or null. Not unique, and never changed after creation.
Example:
"hire-2026-0917"
created_at
string<date-time>
required
ISO 8601, UTC.
sent_at
string<date-time> | null
required
ISO 8601, UTC. Null while it is a draft.
expires_at
string<date-time> | null
required
ISO 8601, UTC. Null when this envelope has no deadline, which is the default. Read back from the stored value rather than echoed, so an offset you sent comes back as the same instant in UTC.
recipients
object[]
required
In routing order.
Show child attributes
subjects
object[]
required
Who the envelope is about, such as a spouse or a dependant, in the order they were declared: the subject a value names. A one-off’s come from setting it up in the editor; an envelope made from a template has its template’s. Empty when the envelope is about nobody in particular.
Show child attributes
roles_left_out
object[]
required
The optional roles this envelope was sent without (Role.presence is optional on its template, and nobody was named for the role: no recipient in the request, or only an empty slot on a draft prepared in the dashboard). Each was left out when the envelope was sent, with every field it held, and the sealed certificate lists it as not on the envelope. Only a role that held fields is listed: one with none has nothing to leave out. Empty before the envelope is sent and for a one-off.
Show child attributes
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"Vumasign","description":"The Vumasign API: templates, envelopes, embedded signing and signed webhooks.","colors":{"primary":"#00827B","light":"#30B3AB","dark":"#00827B"},"logo":{"light":"https://mintcdn.com/vumasign/TFhwDypOVkWX-C3j/logo/vumasign.svg?fit=max\u0026auto=format\u0026n=TFhwDypOVkWX-C3j\u0026q=85\u0026s=f5e34bf1faf4c64eaa58dee0553702d6","dark":"https://mintcdn.com/vumasign/TFhwDypOVkWX-C3j/logo/vumasign-dark.svg?fit=max\u0026auto=format\u0026n=TFhwDypOVkWX-C3j\u0026q=85\u0026s=6288e3bd6e02af7f9ef27aa71b7df32c","href":"https://vumasign.com"},"favicon":"https://mintcdn.com/vumasign/TFhwDypOVkWX-C3j/logo/favicon.svg?fit=max\u0026auto=format\u0026n=TFhwDypOVkWX-C3j\u0026q=85\u0026s=ca1830bf11181e8ce259f0ca820ba7a9","api":{"openapi":"openapi.json","playground":{"display":"interactive"},"examples":{"defaults":"required","languages":["curl","python","javascript","go"],"prefill":true}},"background":{"color":{"light":"#F7F7F8","dark":"#0F1419"}},"navbar":{"primary":{"type":"button","label":"Get an API key","href":"https://app.vumasign.com/settings/api-keys"}},"fonts":{"family":"Inter"},"icons":{"library":"lucide"},"styling":{"latex":false},"navigation":{"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"vumasign","hasAudioNarration":false,"actualSubdomain":"vumasign","customDomains":["docs.vumasign.com"],"gitSource":{"type":"github","owner":"hellocrowd","repo":"vumasign","deployBranch":"main","contentDirectory":"docs-site","isPrivate":true,"mountPath":"","label":""},"entitlements":{"AI_CHAT":{"status":"DISABLED"},"WEB_MCP":{"status":"DISABLED"},"NARRATION":{"status":"DISABLED"}},"buildId":"6afa8fa53b9b1d7bae84e26b","clientVersion":"0.0.4160","searchFilterCounts":[{"language":"default","tag":"API reference","count":49},{"language":"default","tag":"Guides","count":34},{"language":"default","tag":"Concepts","count":17},{"language":"default","tag":"Templates","count":17},{"language":"default","tag":"Envelopes","count":12},{"language":"default","tag":"Standing authorisations","count":7},{"language":"default","tag":"Webhooks","count":6},{"language":"default","tag":"Get started","count":5},{"language":"default","tag":"Brands","count":4},{"language":"default","tag":"Documents","count":2}]},"assistantConfig":{"enableAskAiButton":false,"enableStarterQuestions":false,"enableContextualStarterQuestions":false,"enableAskAiSearchBar":true},"basePath":"","hasChatPermissions":false,"hasWebMcpPermissions":false,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-rbac-roles","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"rbac-expansion","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"full-page-search","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-sso-scim","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-signup","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-dual-write","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"approve-review-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-metadata","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"sso-setup-deadline-banner","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-serve","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"live-agents","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"googleFontsInlined":false},"customCss":[],"page":{"pagePath":"api-reference/create-envelope","slug":"/api-reference/create-envelope","pageMetadata":{"title":"Create an envelope from a template, and optionally send it.","description":"THE ENDPOINT THAT EMAILS REAL PEOPLE AND SPENDS REAL MONEY, and the reason `Idempotency-Key` is required rather than optional.\n\n⚠️ A REPLAY RETURNS THE SAME ENVELOPE AND CREATES NOTHING. Send the identical body under the identical key and you receive the first attempt’s answer, byte for byte, with `Idempotency-Replayed: true`. No second envelope, no second invitation, no second billed envelope. Thatis what makes a timeout safe to retry — and none of the three products this API was designed against offers it.\n\nA DIFFERENT BODY UNDER A USED KEY IS `idempotency_key_reused`, not a replay. A key identifies one request; answering a second one with the first one’s envelope is silent data loss wearing a 201.\n\nKEYS ARE REMEMBERED FOR 1 DAY, per organisation and per environment (live and test never answer for one another). Past that the key is forgotten and the same string is a new request.\n\n⚠️ `values` IS A LIST OF TRIPLES AND ONE OF THEM MAY FILL SEVERAL BOXES. Read `GET /api/v1/templates/{templateId}` first: it is where the `(subject, data_key)` pairs come from.\n\nDOCUMENTS OF YOUR OWN MAY GO BESIDE THE TEMPLATE’S, in `attachments`. They follow the template’s documents in the order given, and their fields come from their own text tags, which may name a role the template does not. `values` fill only the template’s fields. Each recipient is shown the documents their role has fields on and those nobody has fields on, or every document when their role has none. See [Attachments](https://docs.vumasign.com/concepts/templates-and-one-offs#attachments).\n\nA REFUSAL CREATES NOTHING. Every 4xx below leaves no envelope behind — including a send refused after the draft was built, which is deleted again — and leaves the idempotency key free for a corrected retry.","deprecated":null,"version":null,"sidebarTitle":"Create envelope","openapi":"/openapi.json post /api/v1/envelopes","href":"/api-reference/create-envelope","autogeneratedByOpenApi":true},"description":{"compiledSource":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n a: \"a\",\n code: \"code\",\n p: \"p\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsxs(_components.p, {\n children: [\"THE ENDPOINT THAT EMAILS REAL PEOPLE AND SPENDS REAL MONEY, and the reason \", _jsx(_components.code, {\n children: \"Idempotency-Key\"\n }), \" is required rather than optional.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"⚠️ A REPLAY RETURNS THE SAME ENVELOPE AND CREATES NOTHING. Send the identical body under the identical key and you receive the first attempt’s answer, byte for byte, with \", _jsx(_components.code, {\n children: \"Idempotency-Replayed: true\"\n }), \". No second envelope, no second invitation, no second billed envelope. Thatis what makes a timeout safe to retry — and none of the three products this API was designed against offers it.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"A DIFFERENT BODY UNDER A USED KEY IS \", _jsx(_components.code, {\n children: \"idempotency_key_reused\"\n }), \", not a replay. A key identifies one request; answering a second one with the first one’s envelope is silent data loss wearing a 201.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"KEYS ARE REMEMBERED FOR 1 DAY, per organisation and per environment (live and test never answer for one another). Past that the key is forgotten and the same string is a new request.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"⚠️ \", _jsx(_components.code, {\n children: \"values\"\n }), \" IS A LIST OF TRIPLES AND ONE OF THEM MAY FILL SEVERAL BOXES. Read \", _jsx(_components.code, {\n children: \"GET /api/v1/templates/{templateId}\"\n }), \" first: it is where the \", _jsx(_components.code, {\n children: \"(subject, data_key)\"\n }), \" pairs come from.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"DOCUMENTS OF YOUR OWN MAY GO BESIDE THE TEMPLATE’S, in \", _jsx(_components.code, {\n children: \"attachments\"\n }), \". They follow the template’s documents in the order given, and their fields come from their own text tags, which may name a role the template does not. \", _jsx(_components.code, {\n children: \"values\"\n }), \" fill only the template’s fields. Each recipient is shown the documents their role has fields on and those nobody has fields on, or every document when their role has none. See \", _jsx(_components.a, {\n href: \"https://docs.vumasign.com/concepts/templates-and-one-offs#attachments\",\n children: \"Attachments\"\n }), \".\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"A REFUSAL CREATES NOTHING. Every 4xx below leaves no envelope behind — including a send refused after the draft was built, which is deleted again — and leaves the idempotency key free for a corrected retry.\"\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){return _jsx(_Fragment,{})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent}","frontmatter":{},"scope":{"config":{},"pageMetadata":{"title":"Create an envelope from a template, and optionally send it.","description":"THE ENDPOINT THAT EMAILS REAL PEOPLE AND SPENDS REAL MONEY, and the reason `Idempotency-Key` is required rather than optional.\n\n⚠️ A REPLAY RETURNS THE SAME ENVELOPE AND CREATES NOTHING. Send the identical body under the identical key and you receive the first attempt’s answer, byte for byte, with `Idempotency-Replayed: true`. No second envelope, no second invitation, no second billed envelope. Thatis what makes a timeout safe to retry — and none of the three products this API was designed against offers it.\n\nA DIFFERENT BODY UNDER A USED KEY IS `idempotency_key_reused`, not a replay. A key identifies one request; answering a second one with the first one’s envelope is silent data loss wearing a 201.\n\nKEYS ARE REMEMBERED FOR 1 DAY, per organisation and per environment (live and test never answer for one another). Past that the key is forgotten and the same string is a new request.\n\n⚠️ `values` IS A LIST OF TRIPLES AND ONE OF THEM MAY FILL SEVERAL BOXES. Read `GET /api/v1/templates/{templateId}` first: it is where the `(subject, data_key)` pairs come from.\n\nDOCUMENTS OF YOUR OWN MAY GO BESIDE THE TEMPLATE’S, in `attachments`. They follow the template’s documents in the order given, and their fields come from their own text tags, which may name a role the template does not. `values` fill only the template’s fields. Each recipient is shown the documents their role has fields on and those nobody has fields on, or every document when their role has none. See [Attachments](https://docs.vumasign.com/concepts/templates-and-one-offs#attachments).\n\nA REFUSAL CREATES NOTHING. Every 4xx below leaves no envelope behind — including a send refused after the draft was built, which is deleted again — and leaves the idempotency key free for a corrected retry.","deprecated":null,"version":null,"sidebarTitle":"Create envelope","openapi":"/openapi.json post /api/v1/envelopes","href":"/api-reference/create-envelope","autogeneratedByOpenApi":true}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[],"codeExamples":{}},"jsLinks":[],"openApiReferenceData":{"operation":{"operationId":"createEnvelope","tags":["Envelopes"],"x-mint":{"href":"/api-reference/create-envelope"},"summary":"Create an envelope from a template, and optionally send it.","description":"THE ENDPOINT THAT EMAILS REAL PEOPLE AND SPENDS REAL MONEY, and the reason `Idempotency-Key` is required rather than optional.\n\n⚠️ A REPLAY RETURNS THE SAME ENVELOPE AND CREATES NOTHING. Send the identical body under the identical key and you receive the first attempt’s answer, byte for byte, with `Idempotency-Replayed: true`. No second envelope, no second invitation, no second billed envelope. Thatis what makes a timeout safe to retry — and none of the three products this API was designed against offers it.\n\nA DIFFERENT BODY UNDER A USED KEY IS `idempotency_key_reused`, not a replay. A key identifies one request; answering a second one with the first one’s envelope is silent data loss wearing a 201.\n\nKEYS ARE REMEMBERED FOR 1 DAY, per organisation and per environment (live and test never answer for one another). Past that the key is forgotten and the same string is a new request.\n\n⚠️ `values` IS A LIST OF TRIPLES AND ONE OF THEM MAY FILL SEVERAL BOXES. Read `GET /api/v1/templates/{templateId}` first: it is where the `(subject, data_key)` pairs come from.\n\nDOCUMENTS OF YOUR OWN MAY GO BESIDE THE TEMPLATE’S, in `attachments`. They follow the template’s documents in the order given, and their fields come from their own text tags, which may name a role the template does not. `values` fill only the template’s fields. Each recipient is shown the documents their role has fields on and those nobody has fields on, or every document when their role has none. See [Attachments](https://docs.vumasign.com/concepts/templates-and-one-offs#attachments).\n\nA REFUSAL CREATES NOTHING. Every 4xx below leaves no envelope behind — including a send refused after the draft was built, which is deleted again — and leaves the idempotency key free for a corrected retry.","security":["c67ebd9b-01c9-4e8b-b656-b871ff4a18fd"],"x-required-scope":"envelopes:write","parameters":["824ee3d4-9c96-495b-9972-f1bdbe7929be"],"requestBody":"be6ab201-d0a8-41f9-88fa-eb23dde6ce6f","responses":{"201":"9dfbb10c-04a1-490b-96ec-9fa12d0fbbde","400":"581b0274-13ef-4fbf-934b-348226a0a68f","401":"d253fab7-b7b5-492c-9173-4fc616fe004b","402":"fccf96d8-d500-4daa-bd2d-889db535294b","403":"efa5dc1a-2420-4161-8df5-f22d63dd2a17","404":"b1e75a45-8f19-49e8-8f02-f25b22adc626","409":"8e549848-2046-40b9-a79d-663db51fc6cc","412":"3b30130b-4193-480c-a7b7-d7d6324ab24b","422":"1ff42552-5f12-4a1c-9834-df663249ba7c","429":"bbdc509f-f9fb-4854-a393-2f5554cd9880","500":"a31ecc7d-a4c5-45e9-acfb-30adcf25cd48","503":"b5e831d4-93bb-4b4b-9ad0-bc8b41d12ebe"},"method":"post","type":"path","servers":["2ed67dbf-843b-4ce0-93c8-8c35248fcb3e"],"path":"/api/v1/envelopes","baseUrlOptions":["https://app.vumasign.com"],"title":"Create an envelope from a template, and optionally send it.","codeSamples":[],"requestExampleLanguages":["bash","python","javascript","go"],"requiredOnlyExamples":true,"requestExampleType":"generated","responseExampleType":"generated","prefillPlaygroundWithExample":true,"prefillPlaygroundExamples":[{"body.template_id":"01960000-0000-4000-8000-0000000007e1","body.recipients.items.0.oneOf.0.role":"Employee","body.recipients.items.0.oneOf.0.name":"Thandi Mokoena","body.recipients.items.0.oneOf.0.email":"thandi@example.test","body.recipients.items.0.oneOf.0.verification_method":"email_code","body.values.items.0.subject.oneOf.0":"employee","body.values.items.0.key":"staff.full_name","body.values.items.0.value.oneOf.0":"Thandi Mokoena","body.send":false,"body.reference.oneOf.0":"hire-2026-0917","body.documents.items.0.oneOf.1.template_document":"01960000-0000-4000-8000-00000000d0c5"}]},"dependencies":{"parameters":{"824ee3d4-9c96-495b-9972-f1bdbe7929be":{"name":"Idempotency-Key","in":"header","required":true,"description":"Any string that identifies this request; a UUID is the usual choice, and at most 255 characters. ⚠️ REQUIRED. Without it a timeout is unresolvable: you cannot learn whether the envelope was created, and retrying makes a second one and emails everybody twice.","schema":{"type":"string","examples":["01960000-0000-4000-8000-00000000ffff"],"description":"Any string that identifies this request; a UUID is the usual choice, and at most 255 characters. ⚠️ REQUIRED. Without it a timeout is unresolvable: you cannot learn whether the envelope was created, and retrying makes a second one and emails everybody twice.\nThe caller’s own request identifier.","isRequired":true,"uniqueKey":"","typeLabel":"string"}}},"requestBody":{"required":true,"description":"The template, the people, the values, and whether to send.","content":{"application/json":{"schema":{"type":"object","description":"The request.","properties":{"template_id":{"type":"string","format":"uuid","examples":["01960000-0000-4000-8000-0000000007e1"],"description":"The template to instantiate. Layout is authored there, never here (§3).","isRequired":true,"uniqueKey":"template_id","typeLabel":"string\u003cuuid>"},"recipients":{"type":"array","description":"⚠️ THE ORDER OF THIS ARRAY IS THE ORDER RECIPIENTS ARE LISTED IN, and without `step` it is also when they are asked: everyone together when the template’s roles that are not `cc` all share one step, otherwise one at a time in this order. Give `step` on every recipient to say when directly. Reordering it is a different request either way, and an idempotency key will not replay across the two.","items":{"oneOf":[{"type":"object","description":"One recipient: a person, or a role pre-signed under a standing authorisation (an entry carrying `completion`).","required":["role","name","email"],"properties":{"role":{"type":"string","examples":["Tenant"],"description":"A `name` from the template’s `roles`. ⚠️ NOT AN ORDINAL: §3 refuses BoldSign’s `roleIndex`, which breaks the moment somebody reorders a template. An unknown name is `recipient_role_unknown` and names itself. One person per role: two recipients naming the same role are refused as `recipient_role_duplicated`, unless the template routes that role as `cc`.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].oneOf.0.role","typeLabel":"string"},"name":{"type":"string","examples":["Thandi Mokoena"],"description":"What the invitation and the certificate will call them.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].oneOf.0.name","typeLabel":"string"},"email":{"type":"string","format":"email","examples":["thandi@example.test"],"description":"Where the invitation goes. ⚠️ STILL REQUIRED WHEN `embedded` IS TRUE, even though nothing is sent to it: the address is on the certificate of completion, in the audit chain, and in any `signer_email` field on the document. Embedded signing says your application authenticated this person; it does not say they have no identity. ⚠️ THE SHAPE IS CHECKED AND ONLY THE SHAPE: one `@`, a dotted domain, at most 254 characters. A malformed address is `invalid_request` naming the offending index — refused before anything is created, because a sent envelope cannot have its recipients corrected. Nothing here can tell whether the mailbox exists. A mailbox that does not exist surfaces later as a bounce, which is recorded in the envelope’s history in the app and is not a webhook event. This API reflects it only indirectly: that recipient’s `invitation_delivered` stays `false`. ⚠️ `false` IS NOT PROOF OF A BOUNCE — it also means \"not reported delivered yet\".","isRequired":true,"uniqueKey":"recipients.items.[INDEX].oneOf.0.email","typeLabel":"string\u003cemail>"},"job_title":{"oneOf":[{"type":"string","examples":["Group Executive"],"description":"Optional, default `null`. The job title you assert this person holds, at most 200 characters. ⚠️ IT IS SEEDED INTO A `signer_title` FIELD AT SEND AND THE SIGNER MAY THEN CORRECT IT — they are the authority on their own title, and stamping it would mean an executive whose title you got slightly wrong must sign a document that misstates their role or decline it. Your assertion is not lost: the seeded value is recorded with `source: \"prefill\"` and a correction with `source: \"signer\"`.\n\n⚠️ IT APPEARS NOWHERE IF THE DOCUMENT ASKS FOR IT NOWHERE. The template defines what is collected and what is shown, so a title supplied for a document that places no title field is on neither the pages nor the certificate of completion. ⚠️ AND IT IS NOT ECHOED BACK: it is read once, at send, and the certificate reports the FIELD VALUE rather than this. Blank is refused — send `null`.","uniqueKey":"recipients.items.[INDEX].oneOf.0.job_title.oneOf.0","typeLabel":"string"},{"type":"null","examples":["Group Executive"],"description":"Optional, default `null`. The job title you assert this person holds, at most 200 characters. ⚠️ IT IS SEEDED INTO A `signer_title` FIELD AT SEND AND THE SIGNER MAY THEN CORRECT IT — they are the authority on their own title, and stamping it would mean an executive whose title you got slightly wrong must sign a document that misstates their role or decline it. Your assertion is not lost: the seeded value is recorded with `source: \"prefill\"` and a correction with `source: \"signer\"`.\n\n⚠️ IT APPEARS NOWHERE IF THE DOCUMENT ASKS FOR IT NOWHERE. The template defines what is collected and what is shown, so a title supplied for a document that places no title field is on neither the pages nor the certificate of completion. ⚠️ AND IT IS NOT ECHOED BACK: it is read once, at send, and the certificate reports the FIELD VALUE rather than this. Blank is refused — send `null`.","uniqueKey":"recipients.items.[INDEX].oneOf.0.job_title.oneOf.1","typeLabel":"null"}],"uniqueKey":"recipients.items.[INDEX].oneOf.0.job_title","typeLabel":"string | null"},"company":{"oneOf":[{"type":"string","examples":["Vumasign (Pty) Ltd"],"description":"Optional, default `null`. The employer you assert this person has, at most 200 characters. Seeded into a `signer_company` field at send, editable by the signer, absent from the certificate unless the document asked, and not echoed back — all four for the same reasons as `job_title`. ⚠️ THIS REPLACES THE ADDRESS ROUTE FOR THE COMMON CASE: `values` with the address `company` still works and still takes precedence, but you no longer have to describe the same person twice.","uniqueKey":"recipients.items.[INDEX].oneOf.0.company.oneOf.0","typeLabel":"string"},{"type":"null","examples":["Vumasign (Pty) Ltd"],"description":"Optional, default `null`. The employer you assert this person has, at most 200 characters. Seeded into a `signer_company` field at send, editable by the signer, absent from the certificate unless the document asked, and not echoed back — all four for the same reasons as `job_title`. ⚠️ THIS REPLACES THE ADDRESS ROUTE FOR THE COMMON CASE: `values` with the address `company` still works and still takes precedence, but you no longer have to describe the same person twice.","uniqueKey":"recipients.items.[INDEX].oneOf.0.company.oneOf.1","typeLabel":"null"}],"uniqueKey":"recipients.items.[INDEX].oneOf.0.company","typeLabel":"string | null"},"embedded":{"type":"boolean","description":"Optional, default `false`. ⚠️ TRUE MEANS THIS PERSON IS NEVER EMAILED — no invitation, no reminder, no resend from the dashboard, no new link when theirs expires, no notice that the document changed or was voided, and no completed copy. You reach them by minting a URL with `POST /api/v1/envelopes/{envelopeId}/recipients/{recipientId}/signing-url` and framing it. An explicit mode rather than DocuSign’s inference from `clientUserId` being non-null, and it is returned on every recipient we describe, which theirs is not.\n\n⚠️ REFUSED IN TWO SITUATIONS, BOTH OF WHICH WOULD LEAVE THE PERSON UNREACHABLE: a role the template routes as `cc` (never issued a signing credential by any path), and an organisation whose default brand has no embedding origins registered.","uniqueKey":"recipients.items.[INDEX].oneOf.0.embedded","typeLabel":"boolean"},"delegates_stay_embedded":{"type":"boolean","examples":[false],"description":"Optional, default `false`, and only with `embedded: true`. Decides how the person an embedded signer DELEGATES to is reached. A signer can hand the document to somebody else from their signing session; your application has no seat for that person, so by default they are emailed a signing link like any other recipient. `true` keeps them embedded instead: nobody is emailed, `recipient.delegated` tells you who they are, and you seat them by minting their URL. Carried onto an embedded delegate, so their own delegate is treated the same way. Sent with `embedded: false`, the request is refused as `invalid_request`.","uniqueKey":"recipients.items.[INDEX].oneOf.0.delegates_stay_embedded","typeLabel":"boolean"},"step":{"type":"integer","minimum":1,"maximum":2147483647,"examples":[1],"description":"Optional. When this person is asked: everyone in the lowest step that still has something to do is asked together, and the next step opens when that one is finished. A `cc` never holds a step up. Gaps and ties are fine — `[2, 2, 5]` asks the first two together, then the third. ⚠️ ON EVERY RECIPIENT OR ON NONE: giving some and not others is refused as `recipient_step_partial`. Where the body also takes `signing_mode`, giving both is refused as `step_with_signing_mode`.\n\nWITHOUT `step`, THE ARRAY DECIDES, in one of two ways and never by the template’s own steps: everyone together (a one-off whose `signing_mode` is `parallel` or absent, or a template whose roles that are not `cc` all share one step), or one at a time in array order (a one-off whose `signing_mode` is `sequential`, or any other template). To send in a template’s own steps, read each role’s `step` from `GET /api/v1/templates/{templateId}` and pass them.","uniqueKey":"recipients.items.[INDEX].oneOf.0.step","typeLabel":"integer"},"verification_method":{"type":"string","enum":["none","email_code","mobile_code","identity_check","sms_code"],"examples":["email_code","mobile_code"],"description":"Optional, default `none`. What this person must prove before the document opens: nothing; (`email_code`) a 6-digit code emailed to `email`; or (`mobile_code`) a 6-digit code sent to their phone at `mobile` — on WhatsApp first, and the same code by SMS when WhatsApp cannot reach them within a few seconds or they ask for a text. A code is sent only when they open their link and ask for it — nothing is sent until they do — is valid for 10 minutes, and is asked for once per signing session. The certificate of completion states the code, and the route it took, only where the audit trail records it being entered.\n\n`identity_check` (Level 3) asks for a 6-digit code to `mobile` first, exactly as `mobile_code` does, and then, once per envelope, an identity check by VerifyNow on the signer’s phone: a photo of their South African ID (Smart ID card or green ID book) or their passport, and a live selfie. With an SA ID the selfie is matched to the Home Affairs photo for the number read from the ID; with a passport it is matched to the passport’s own photo, and the passport is checked for signs of tampering, but not against the issuing authority’s records. R 59 per signer, charged once they reach the face match (at most 2 tries, both included), and only on a paid plan: on Free it is refused as `identity_check_requires_paid_plan`. Never for a `cc` (`recipient_identity_check_not_allowed`), never on a row of a batch, and options go in `identity_check`. An embedded recipient may carry one: the check always runs on the signer’s phone (a QR code, or a link sent to the confirmed `mobile`), never inside the embedding iframe, so the iframe needs no camera permission. A test envelope runs VerifyNow’s sandbox, which returns sample results and costs nothing. A deployment where identity checks are not switched on for live envelopes refuses a live send that names one as `identity_check_not_live`.\n\n`sms_code` is a DEPRECATED alias of `mobile_code`: it is still accepted, means exactly the same, and is read back as `mobile_code`.\n\nMobile codes count against the plan’s monthly mobile-code allowance, once per code however it travelled; on a test envelope no message is sent and the code is shown on the signing screen instead.\n\n⚠️ NEVER `email_code` FOR AN EMBEDDED RECIPIENT — they are never emailed, so the code could not reach them; `mobile_code` is how to ask for a code for one — and nothing but `none` for a `cc`, who never opens a signing page. Both are refused as `recipient_verification_not_allowed`, naming the recipient, and nothing is created.","uniqueKey":"recipients.items.[INDEX].oneOf.0.verification_method","typeLabel":"enum\u003cstring>"},"mobile":{"oneOf":[{"type":"string","maxLength":64,"examples":["+27821234567"],"description":"Required with `verification_method: \"mobile_code\"`, and refused otherwise as `recipient_mobile_unused` rather than stored. A South African mobile, in any of `+27821234567`, `27821234567`, `082 123 4567` or `0821234567`; it is stored as E.164 (`+27821234567`). Missing with `mobile_code` is `recipient_mobile_required`; not a mobile is `recipient_mobile_invalid`; outside `+27` is `recipient_mobile_unsupported_country`. Used for nothing but this recipient’s code: never for notifications. It is passed to SMSPortal, and through it to WhatsApp (Meta), only to deliver that code.","uniqueKey":"recipients.items.[INDEX].oneOf.0.mobile.oneOf.0","typeLabel":"string"},{"type":"null","maxLength":64,"examples":["+27821234567"],"description":"Required with `verification_method: \"mobile_code\"`, and refused otherwise as `recipient_mobile_unused` rather than stored. A South African mobile, in any of `+27821234567`, `27821234567`, `082 123 4567` or `0821234567`; it is stored as E.164 (`+27821234567`). Missing with `mobile_code` is `recipient_mobile_required`; not a mobile is `recipient_mobile_invalid`; outside `+27` is `recipient_mobile_unsupported_country`. Used for nothing but this recipient’s code: never for notifications. It is passed to SMSPortal, and through it to WhatsApp (Meta), only to deliver that code.","uniqueKey":"recipients.items.[INDEX].oneOf.0.mobile.oneOf.1","typeLabel":"null"}],"uniqueKey":"recipients.items.[INDEX].oneOf.0.mobile","typeLabel":"string | null"},"identity_check":{"oneOf":[{"type":"object","examples":[{"routes":"either","expected_id":{"kind":"sa_id","number":"8001015009087"}}],"description":"Optional, and only with `verification_method: \"identity_check\"` (otherwise `recipient_identity_routes_invalid`). `routes` is which documents they may use: `either` (the default), `sa_id` or `passport`. `expected_id` is the ID you expect them to show: `{ \"kind\": \"sa_id\", \"number\": \"\u003c13 digits>\" }`, or `{ \"kind\": \"passport\", \"number\": \"...\", \"country\": \"\u003cISO 3166 alpha-3>\" }`. If the document shows a different number, the check stops, nothing is charged, and `recipient.identity_check_failed` is sent with `reason: \"id_mismatch\"`. With an expected number only the route of its kind is offered. An SA number is checked when the envelope is created (13 digits, the checksum, a real date of birth, and a citizenship digit of 0, 1 or 2); a number that fails, a malformed passport number or country, or a kind `routes` rules out is `recipient_expected_id_invalid`. ⚠️ THE NUMBER IS NEVER STORED OR RETURNED: it is kept as a keyed digest and its last digits, and a read returns `expected_id: { kind, masked, country }`.","properties":{"routes":{"type":"string","enum":["either","sa_id","passport"],"description":"Default `either`.","uniqueKey":"recipients.items.[INDEX].oneOf.0.identity_check.oneOf.0.routes","typeLabel":"enum\u003cstring>"},"expected_id":{"oneOf":[{"type":"object","description":"Optional: the ID you expect them to show.","properties":{"kind":{"type":"string","enum":["sa_id","passport"],"description":"An SA ID number, or a passport number.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].oneOf.0.identity_check.oneOf.0.expected_id.oneOf.0.kind","typeLabel":"enum\u003cstring>"},"number":{"type":"string","maxLength":64,"description":"The number. Never stored or returned whole.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].oneOf.0.identity_check.oneOf.0.expected_id.oneOf.0.number","typeLabel":"string"},"country":{"oneOf":[{"type":"string","description":"A passport’s issuing country, ISO 3166 alpha-3 (`ZAF`, `ZWE`, `GBR`).","uniqueKey":"recipients.items.[INDEX].oneOf.0.identity_check.oneOf.0.expected_id.oneOf.0.country.oneOf.0","typeLabel":"string"},{"type":"null","description":"A passport’s issuing country, ISO 3166 alpha-3 (`ZAF`, `ZWE`, `GBR`).","uniqueKey":"recipients.items.[INDEX].oneOf.0.identity_check.oneOf.0.expected_id.oneOf.0.country.oneOf.1","typeLabel":"null"}],"uniqueKey":"recipients.items.[INDEX].oneOf.0.identity_check.oneOf.0.expected_id.oneOf.0.country","typeLabel":"string | null"}},"required":["kind","number"],"uniqueKey":"recipients.items.[INDEX].oneOf.0.identity_check.oneOf.0.expected_id.oneOf.0","typeLabel":"object"},{"type":"null","description":"Optional: the ID you expect them to show.","properties":{"kind":{"type":"string","enum":["sa_id","passport"],"description":"An SA ID number, or a passport number."},"number":{"type":"string","maxLength":64,"description":"The number. Never stored or returned whole."},"country":{"oneOf":[{"type":"string","description":"A passport’s issuing country, ISO 3166 alpha-3 (`ZAF`, `ZWE`, `GBR`)."},{"type":"null","description":"A passport’s issuing country, ISO 3166 alpha-3 (`ZAF`, `ZWE`, `GBR`)."}]}},"required":["kind","number"],"uniqueKey":"recipients.items.[INDEX].oneOf.0.identity_check.oneOf.0.expected_id.oneOf.1","typeLabel":"null"}],"uniqueKey":"recipients.items.[INDEX].oneOf.0.identity_check.oneOf.0.expected_id","typeLabel":"object | null"}},"uniqueKey":"recipients.items.[INDEX].oneOf.0.identity_check.oneOf.0","typeLabel":"object"},{"type":"null","examples":[{"routes":"either","expected_id":{"kind":"sa_id","number":"8001015009087"}}],"description":"Optional, and only with `verification_method: \"identity_check\"` (otherwise `recipient_identity_routes_invalid`). `routes` is which documents they may use: `either` (the default), `sa_id` or `passport`. `expected_id` is the ID you expect them to show: `{ \"kind\": \"sa_id\", \"number\": \"\u003c13 digits>\" }`, or `{ \"kind\": \"passport\", \"number\": \"...\", \"country\": \"\u003cISO 3166 alpha-3>\" }`. If the document shows a different number, the check stops, nothing is charged, and `recipient.identity_check_failed` is sent with `reason: \"id_mismatch\"`. With an expected number only the route of its kind is offered. An SA number is checked when the envelope is created (13 digits, the checksum, a real date of birth, and a citizenship digit of 0, 1 or 2); a number that fails, a malformed passport number or country, or a kind `routes` rules out is `recipient_expected_id_invalid`. ⚠️ THE NUMBER IS NEVER STORED OR RETURNED: it is kept as a keyed digest and its last digits, and a read returns `expected_id: { kind, masked, country }`.","properties":{"routes":{"type":"string","enum":["either","sa_id","passport"],"description":"Default `either`."},"expected_id":{"oneOf":[{"type":"object","description":"Optional: the ID you expect them to show.","properties":{"kind":{"type":"string","enum":["sa_id","passport"],"description":"An SA ID number, or a passport number."},"number":{"type":"string","maxLength":64,"description":"The number. Never stored or returned whole."},"country":{"oneOf":[{"type":"string","description":"A passport’s issuing country, ISO 3166 alpha-3 (`ZAF`, `ZWE`, `GBR`)."},{"type":"null","description":"A passport’s issuing country, ISO 3166 alpha-3 (`ZAF`, `ZWE`, `GBR`)."}]}},"required":["kind","number"]},{"type":"null","description":"Optional: the ID you expect them to show.","properties":{"kind":{"type":"string","enum":["sa_id","passport"],"description":"An SA ID number, or a passport number."},"number":{"type":"string","maxLength":64,"description":"The number. Never stored or returned whole."},"country":{"oneOf":[{"type":"string","description":"A passport’s issuing country, ISO 3166 alpha-3 (`ZAF`, `ZWE`, `GBR`)."},{"type":"null","description":"A passport’s issuing country, ISO 3166 alpha-3 (`ZAF`, `ZWE`, `GBR`)."}]}},"required":["kind","number"]}]}},"uniqueKey":"recipients.items.[INDEX].oneOf.0.identity_check.oneOf.1","typeLabel":"null"}],"uniqueKey":"recipients.items.[INDEX].oneOf.0.identity_check","typeLabel":"object | null"},"external_ref":{"oneOf":[{"type":"string","description":"Optional, default `null`. Your own identifier for this human. Not blank, and at most 255 UTF-16 code units once composed to NFC, as JavaScript counts string length: most characters count as one, some (outside the Basic Multilingual Plane, such as most emoji) count as two. No `maxLength` is declared, because JSON Schema counts code points and would admit a value the server refuses. Stored and echoed back in Unicode NFC, so compare it in NFC, and used by us for nothing at all — it is deliberately separate from `embedded` because they answer different questions and this one is optional.","uniqueKey":"recipients.items.[INDEX].oneOf.0.external_ref.oneOf.0","typeLabel":"string"},{"type":"null","description":"Optional, default `null`. Your own identifier for this human. Not blank, and at most 255 UTF-16 code units once composed to NFC, as JavaScript counts string length: most characters count as one, some (outside the Basic Multilingual Plane, such as most emoji) count as two. No `maxLength` is declared, because JSON Schema counts code points and would admit a value the server refuses. Stored and echoed back in Unicode NFC, so compare it in NFC, and used by us for nothing at all — it is deliberately separate from `embedded` because they answer different questions and this one is optional.","uniqueKey":"recipients.items.[INDEX].oneOf.0.external_ref.oneOf.1","typeLabel":"null"}],"uniqueKey":"recipients.items.[INDEX].oneOf.0.external_ref","typeLabel":"string | null"}},"uniqueKey":"recipients.items.[INDEX].oneOf.0","typeLabel":"object"},{"type":"object","description":"One recipient: a person, or a role pre-signed under a standing authorisation (an entry carrying `completion`).","required":["role","completion"],"properties":{"role":{"type":"string","examples":["Employer"],"description":"A `name` from the template’s `roles`: a role that signs. A witness role only under an authorisation granted for witness use (`witness: true`), while witness use is enabled for your organisation.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].oneOf.1.role","typeLabel":"string"},"completion":{"type":"object","description":"How the role is completed.","required":["type","authorisation_id"],"properties":{"type":{"type":"string","enum":["standing_authorisation"],"description":"The only completion there is: under a standing authorisation.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].oneOf.1.completion.type","typeLabel":"enum\u003cstring>"},"authorisation_id":{"type":"string","format":"uuid","examples":["0b9a0000-0000-4000-8000-000000000012"],"description":"An `active` standing authorisation of this brand and environment. Vumasign never chooses one for you, and never applies one you did not name.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].oneOf.1.completion.authorisation_id","typeLabel":"string\u003cuuid>"}},"isRequired":true,"uniqueKey":"recipients.items.[INDEX].oneOf.1.completion","typeLabel":"object"},"external_ref":{"oneOf":[{"type":"string","description":"Optional, default `null`. Your own identifier for this role’s recipient. at most 255 UTF-16 code units once composed to NFC, as JavaScript counts string length: most characters count as one, some (outside the Basic Multilingual Plane, such as most emoji) count as two. No `maxLength` is declared, because JSON Schema counts code points and would admit a value the server refuses.","uniqueKey":"recipients.items.[INDEX].oneOf.1.external_ref.oneOf.0","typeLabel":"string"},{"type":"null","description":"Optional, default `null`. Your own identifier for this role’s recipient. at most 255 UTF-16 code units once composed to NFC, as JavaScript counts string length: most characters count as one, some (outside the Basic Multilingual Plane, such as most emoji) count as two. No `maxLength` is declared, because JSON Schema counts code points and would admit a value the server refuses.","uniqueKey":"recipients.items.[INDEX].oneOf.1.external_ref.oneOf.1","typeLabel":"null"}],"uniqueKey":"recipients.items.[INDEX].oneOf.1.external_ref","typeLabel":"string | null"},"step":{"type":"integer","minimum":1,"maximum":2147483647,"examples":[1],"description":"Optional. When this person is asked: everyone in the lowest step that still has something to do is asked together, and the next step opens when that one is finished. A `cc` never holds a step up. Gaps and ties are fine — `[2, 2, 5]` asks the first two together, then the third. ⚠️ ON EVERY RECIPIENT OR ON NONE: giving some and not others is refused as `recipient_step_partial`. Where the body also takes `signing_mode`, giving both is refused as `step_with_signing_mode`.\n\nWITHOUT `step`, THE ARRAY DECIDES, in one of two ways and never by the template’s own steps: everyone together (a one-off whose `signing_mode` is `parallel` or absent, or a template whose roles that are not `cc` all share one step), or one at a time in array order (a one-off whose `signing_mode` is `sequential`, or any other template). To send in a template’s own steps, read each role’s `step` from `GET /api/v1/templates/{templateId}` and pass them.","uniqueKey":"recipients.items.[INDEX].oneOf.1.step","typeLabel":"integer"}},"uniqueKey":"recipients.items.[INDEX].oneOf.1","typeLabel":"object"}],"uniqueKey":"recipients.items.[INDEX]","typeLabel":"object"},"isRequired":true,"uniqueKey":"recipients","typeLabel":"object[]"},"values":{"type":"array","description":"Optional. Values to prefill, as triples. Omitted means none. ⚠️ A signature, a `date_signed`, a `signer_name` and a `signer_email` may not be prefilled — they are acts, or they are written by this system.","items":{"type":"object","description":"One value at one address.","required":["subject","key","value"],"properties":{"subject":{"oneOf":[{"type":"string","examples":["tenant"],"description":"A `key` from the template’s `subjects` — WHOSE datum this is — or `null` for a field belonging to nobody in particular. Required as a property: `null` and \"I did not say\" must not be two spellings of one thing.","isRequired":true,"uniqueKey":"values.items.[INDEX].subject.oneOf.0","typeLabel":"string"},{"type":"null","examples":["tenant"],"description":"A `key` from the template’s `subjects` — WHOSE datum this is — or `null` for a field belonging to nobody in particular. Required as a property: `null` and \"I did not say\" must not be two spellings of one thing.","isRequired":true,"uniqueKey":"values.items.[INDEX].subject.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"values.items.[INDEX].subject","typeLabel":"string | null"},"key":{"type":"string","examples":["staff.full_name"],"description":"The field’s `data_key`, or a question’s, exactly as the template endpoint reports it. A box of a question has no address of its own: its question’s is the one to send.","isRequired":true,"uniqueKey":"values.items.[INDEX].key","typeLabel":"string"},"value":{"oneOf":[{"type":"string","description":"What to write. An address that matches nothing is refused rather than dropped. A string, or — for a question — an array of its option values (template field naming PR 6).","maxLength":10000,"example":"Thandi Mokoena","isRequired":true,"uniqueKey":"values.items.[INDEX].value.oneOf.0","typeLabel":"string"},{"type":"array","items":{"type":"string","maxLength":10000,"description":"One of the question’s option values.","uniqueKey":"values.items.[INDEX].value.oneOf.1.items.[INDEX]","typeLabel":"string"},"description":"What to write. An address that matches nothing is refused rather than dropped. A string, or — for a question — an array of its option values (template field naming PR 6).","maxItems":200,"example":["classic_saver","gap_cover"],"isRequired":true,"uniqueKey":"values.items.[INDEX].value.oneOf.1","typeLabel":"string[]"}],"isRequired":true,"uniqueKey":"values.items.[INDEX].value","typeLabel":"string | string[]"},"locked":{"type":"boolean","examples":[true],"description":"Optional. `true` fixes this answer: the signer reads it and cannot change it, and a submission that tries is refused. Use it when your own records are the authority and a signed form contradicting them would help nobody.\n\n⚠️ IT RIDES ON THE VALUE ON PURPOSE, so you cannot lock an address without saying in the same breath what it is locked TO. To hand a field back to the signer, send `{\"value\": \"\", \"locked\": false}`: the empty string already means *clear this*.\n\n⚠️ `{\"value\": \"\", \"locked\": true}` IS ACCEPTED, and it means \"this box stays empty and the signer may not fill it\". It is the spelling a grouped tickbox needs — five locked, empty options of a Race question, each saying *not this one* — so it is not refused. Earlier versions of this text said it could not be expressed at all; that was wrong.\n\n⚠️ A LOCKED ANSWER SURVIVES BEING HIDDEN AND SHOWN AGAIN. A signer can make a section disappear — by answering the question a condition reads, or by declaring that a `subject` is not on the document — and the answers under it are removed, so nothing unasked is printed. A locked answer is yours rather than theirs, so it is kept separately and comes back the moment the section does. You do not have to re-send it, and no gesture available to the signer can destroy it.\n\n⚠️ ON A TICKBOX, AN EMPTY VALUE IS RECORDED AS `false`. The two already mean the same thing to everything that reads or draws a tickbox; storing one spelling is what keeps *not this one* a single sentence. Every other type keeps exactly what you sent.\n\n⚠️ OMITTING IT LEAVES THE FIELD AS THE TEMPLATE HAD IT, which is not the same as sending `false`. A sender can lock a field in the editor; absence respects that, `false` overrides it.\n\n⚠️ AN ADDRESS MAY NAME SEVERAL BOXES AND THIS LOCKS ALL OF THEM — the same rule `value` follows. Two shapes of empty lock refuse the SEND with `locked_answer_missing`, because nobody left could supply the answer: a field that is locked, `required` and carries no value; and a QUESTION whose `min_selected` is out of reach because its options are locked and unticked. An optional, ungrouped box that is locked and empty is neither, and seals blank as it says.\n\n⚠️ AND NEITHER REFUSAL LOOKS AT A BOX ABOUT SOMEBODY THIS ENVELOPE IS NOT ABOUT. A field carrying a `subject` you declared absent in `subjects` — or one the template marks optional and nobody declared — is hidden from the signer and cannot block the document, so a lock on it moved no demand and there is nothing to refuse. This is what lets one template carry a locked spouse section and still send to somebody who has no spouse: `subjects` decides who the envelope is about, and these refusals are about the people it IS about.","uniqueKey":"values.items.[INDEX].locked","typeLabel":"boolean"}},"uniqueKey":"values.items.[INDEX]","typeLabel":"object"},"uniqueKey":"values","typeLabel":"object[]"},"subjects":{"type":"object","additionalProperties":{"oneOf":[{"type":"boolean","description":"What this envelope says about one subject.","uniqueKey":"subjects.additionalProperties.oneOf.0","typeLabel":"boolean"},{"type":"string","description":"What this envelope says about one subject.","enum":["ask"],"uniqueKey":"subjects.additionalProperties.oneOf.1","typeLabel":"enum\u003cstring>"}],"uniqueKey":"subjects.additionalProperties","typeLabel":"boolean | enum\u003cstring>"},"examples":[{"co_tenant":true,"surety":false},{"co_tenant":"ask"}],"description":"Optional. WHO THIS ENVELOPE IS ABOUT, as a map from a subject `key` the template declares to `true` (on this envelope), `false` (not), or `\"ask\"`: the signer who holds that person’s section is asked first, in a required question, and their answer decides. While it is open the person reads `present: false` and `awaiting_signer: true` on the envelope. Two cases are settled at send instead, with nobody asked: a person no recipient holds a box for is left out, and a person a recipient signs for in a role standing for the same person is included. A field addressed to a subject that is not on the envelope is hidden from the signer and not required.\n\nA subject you do not name takes the template’s own rule: a `required` subject is on every envelope, and a `conditional` one is absent and the signer is never asked about them, whatever the template’s Ask, Include or Leave out says (that choice applies to envelopes sent from the dashboard). Omitting `subjects` altogether opens the same sections as naming nobody — but see the next paragraph, because the two are not the same request. A key the template does not declare is refused, and so are `false` and `\"ask\"` for a `required` subject — all `invalid_request`, and nothing is created.\n\n⚠️ IT SETS WHAT THE DOCUMENT OPENS WITH, NOT WHAT IT MUST STAY. The signer can switch a `conditional` subject on or off on the signing page, in either direction, and every such change is recorded in the envelope’s audit history.\n\n⚠️ NAME AS `true` OR `\"ask\"` EVERY `conditional` SUBJECT YOU PREFILL. A value for a subject you ask about is shown if the signer answers Yes, and cleared if they answer No. A value in `values` for a `conditional` subject you did not name as present or asked is handled in one of two ways, depending on whether `subjects` is in the request at all:\n\n- **`subjects` sent** (even `{}`): the subject is absent — by `false`, or by the template’s rule when unnamed — so the value contradicts the request and is refused with `invalid_request`. Nothing is created.\n- **`subjects` omitted**: the value is accepted and stored, but the subject is absent by the template’s rule when the envelope is sent, so the prefilled section opens HIDDEN until the signer switches it on.\n\nSee [Subjects](https://docs.vumasign.com/concepts/subjects).","uniqueKey":"subjects","typeLabel":"object"},"send":{"type":"boolean","description":"Optional, default `false`. False creates a draft and emails nobody; true sends it, consuming the plan’s allowance and delivering an invitation to everyone whose turn it is.","uniqueKey":"send","typeLabel":"boolean"},"expires_at":{"oneOf":[{"type":"string","format":"date-time","description":"Optional, default `null` — no deadline. When this envelope stops being signable, as an ISO 8601 instant. ⚠️ AN ABSOLUTE TIME RATHER THAN A DURATION, so a retried request carrying the same `Idempotency-Key` asks for the same deadline the first attempt did. At least 1 hour out and at most 365 days out; anything else is `invalid_request`. ⚠️ IT CANNOT BE CHANGED AFTERWARDS — there is no endpoint that extends a deadline yet, and an envelope that reaches one while partly signed can only be voided and started again, discarding the signatures already collected. It is enforced: every signing link is capped by it, no link can be reissued past it, and the envelope transitions to `expired` and emits `envelope.expired` once it passes.","uniqueKey":"expires_at.oneOf.0","typeLabel":"string\u003cdate-time>"},{"type":"null","format":"date-time","description":"Optional, default `null` — no deadline. When this envelope stops being signable, as an ISO 8601 instant. ⚠️ AN ABSOLUTE TIME RATHER THAN A DURATION, so a retried request carrying the same `Idempotency-Key` asks for the same deadline the first attempt did. At least 1 hour out and at most 365 days out; anything else is `invalid_request`. ⚠️ IT CANNOT BE CHANGED AFTERWARDS — there is no endpoint that extends a deadline yet, and an envelope that reaches one while partly signed can only be voided and started again, discarding the signatures already collected. It is enforced: every signing link is capped by it, no link can be reissued past it, and the envelope transitions to `expired` and emits `envelope.expired` once it passes.","uniqueKey":"expires_at.oneOf.1","typeLabel":"null"}],"uniqueKey":"expires_at","typeLabel":"string\u003cdate-time> | null"},"brand_id":{"oneOf":[{"type":"string","format":"uuid","description":"Optional, default `null` — the organisation’s default brand. Which brand the envelope goes out under: the letterhead, the colours and the sending name a signer sees. ⚠️ THIS IS THE FIELD FOR SENDING ON BEHALF OF MANY CUSTOMER BRANDS FROM ONE ACCOUNT — change it between calls and the same integration sends Customer A’s paperwork under Customer A’s brand and Customer B’s under Customer B’s.\n\n⚠️ AN ID THAT NAMES NO LIVE BRAND OF YOUR ORGANISATION IS REFUSED WITH `brand_unknown`, NOT IGNORED — including one that has been archived. The branding an envelope went out under is frozen the moment it is sent and cannot be corrected afterwards, so a wrong constant in your configuration would otherwise put somebody else’s letterhead on every envelope you ever send and nothing would say so.\n\nIt is recorded on the envelope, so a draft created with `send: false` still goes out under this brand when it is sent later.\n\nCopy the id from Settings → Brands in the dashboard: brands are made and managed there, and no endpoint lists them. What a brand controls, and what it does not, is on [Brands](https://docs.vumasign.com/concepts/brands).","uniqueKey":"brand_id.oneOf.0","typeLabel":"string\u003cuuid>"},{"type":"null","format":"uuid","description":"Optional, default `null` — the organisation’s default brand. Which brand the envelope goes out under: the letterhead, the colours and the sending name a signer sees. ⚠️ THIS IS THE FIELD FOR SENDING ON BEHALF OF MANY CUSTOMER BRANDS FROM ONE ACCOUNT — change it between calls and the same integration sends Customer A’s paperwork under Customer A’s brand and Customer B’s under Customer B’s.\n\n⚠️ AN ID THAT NAMES NO LIVE BRAND OF YOUR ORGANISATION IS REFUSED WITH `brand_unknown`, NOT IGNORED — including one that has been archived. The branding an envelope went out under is frozen the moment it is sent and cannot be corrected afterwards, so a wrong constant in your configuration would otherwise put somebody else’s letterhead on every envelope you ever send and nothing would say so.\n\nIt is recorded on the envelope, so a draft created with `send: false` still goes out under this brand when it is sent later.\n\nCopy the id from Settings → Brands in the dashboard: brands are made and managed there, and no endpoint lists them. What a brand controls, and what it does not, is on [Brands](https://docs.vumasign.com/concepts/brands).","uniqueKey":"brand_id.oneOf.1","typeLabel":"null"}],"uniqueKey":"brand_id","typeLabel":"string\u003cuuid> | null"},"completion_delivery":{"type":"string","enum":["vumasign","integrator"],"description":"Who tells the recipients the envelope is done and sends them the executed document. `vumasign` (the default for a send from the dashboard) means we email the sender and every recipient we are able to email, with the sealed PDF attached. `integrator` (the default for a send made with an API key) means we send nothing at completion and you do it. Omit it and the origin of the **send** decides — an envelope created with `send: false` and then sent from the dashboard is `vumasign`. It cannot be changed once the envelope has been sent.\n\n⚠️ AN `embedded` RECIPIENT IS NEVER EMAILED, WHATEVER THIS SAYS. We issue one no signing link and send them no invitation, because their address may be an identifier of yours rather than a mailbox — so they are not sent the completed document either, even under `vumasign`. **Delivering the executed document to an embedded recipient is yours on every envelope**, and this field only decides who tells everybody else.\n\n⚠️ IF YOU TAKE THIS ON, SUBSCRIBE TO `envelope.sealed` RATHER THAN `envelope.completed`. `envelope.completed` fires when the last person signs, which is about a minute before the executed document exists, and `envelope.sealing_failed` tells you it never will.","uniqueKey":"completion_delivery","typeLabel":"enum\u003cstring>"},"reference":{"oneOf":[{"type":"string","examples":["hire-2026-0917"],"description":"Optional, default `null`. Your own name for this envelope — an order number, a case id, the id of the row in your database that asked for it — opaque to us. Not blank, and at most 255 UTF-16 code units once composed to NFC, as JavaScript counts string length: most characters count as one, some (outside the Basic Multilingual Plane, such as most emoji) count as two. No `maxLength` is declared, because JSON Schema counts code points and would admit a value the server refuses. Stored and returned in Unicode NFC. `GET /api/v1/envelopes?reference=` finds every envelope carrying it, which is how you find out whether a request whose answer you lost created anything.\n\n⚠️ IT IS NOT UNIQUE. We accept the same reference on any number of envelopes, and the list returns all of them, newest first. If you want one envelope per reference, make your references unique — derive it from the record that asked for the envelope, not from the attempt.\n\n⚠️ IT CANNOT BE SET OR CHANGED AFTER CREATION. Not on a draft, not by a later request: a reference that could move would not identify anything.","uniqueKey":"reference.oneOf.0","typeLabel":"string"},{"type":"null","examples":["hire-2026-0917"],"description":"Optional, default `null`. Your own name for this envelope — an order number, a case id, the id of the row in your database that asked for it — opaque to us. Not blank, and at most 255 UTF-16 code units once composed to NFC, as JavaScript counts string length: most characters count as one, some (outside the Basic Multilingual Plane, such as most emoji) count as two. No `maxLength` is declared, because JSON Schema counts code points and would admit a value the server refuses. Stored and returned in Unicode NFC. `GET /api/v1/envelopes?reference=` finds every envelope carrying it, which is how you find out whether a request whose answer you lost created anything.\n\n⚠️ IT IS NOT UNIQUE. We accept the same reference on any number of envelopes, and the list returns all of them, newest first. If you want one envelope per reference, make your references unique — derive it from the record that asked for the envelope, not from the attempt.\n\n⚠️ IT CANNOT BE SET OR CHANGED AFTER CREATION. Not on a draft, not by a later request: a reference that could move would not identify anything.","uniqueKey":"reference.oneOf.1","typeLabel":"null"}],"uniqueKey":"reference","typeLabel":"string | null"},"template_etag":{"type":"string","minLength":1,"maxLength":200,"description":"Optional. The `ETag` of the template as you checked it — from `GET /api/v1/templates/{templateId}` or the `template_etag` of `validate-values` — with or without its quotes. When it is no longer current the request is refused with `template_changed` and nothing is created: the template has been renamed since, and a value could now fill a different box. ⚠️ SEND IT ON EVERY ENVELOPE. An unknown key fails loudly, but a SWAPPED one — two addresses exchanged — does not, and this is what catches it. Compared under the template’s lock, so nothing can change between the check and the copy.","uniqueKey":"template_etag","typeLabel":"string"},"attachments":{"type":"array","maxItems":9,"description":"Optional. Documents of your own sent beside the template’s, after them, in the order given — each a PDF or a Word `.docx`, base64-encoded, exactly as `documents` on `POST /api/v1/envelopes/one-off`. Their fields come from their own text tags, which name the `role`s in `recipients`: a template role, or a role only an attachment names, whose recipient then signs. A tag naming a role nobody holds, or using `subject(...)`, is `invalid_request`, and `values` never fill an attachment. ⚠️ THE TEMPLATE’S DOCUMENTS AND THESE TOGETHER MAY BE AT MOST 10, and together these may hold at most 6 MB of document. Absent and `[]` are different requests under one `Idempotency-Key`; both make the template’s envelope alone.","items":{"type":"object","description":"One attachment.","properties":{"content":{"type":"string","examples":["JVBERi0xLjcKJc..."],"description":"The document’s bytes, base64-encoded with the standard alphabet — no `data:` prefix, no whitespace, no URL-safe `-` or `_`. ⚠️ ABOUT 6 MB OF DOCUMENT IN THE WHOLE REQUEST, SHARED BY EVERY ENTRY IN `documents` — not that much each — whichever format you send, because the whole JSON body is capped at 8 MB and base64 costs a third on top. That bound is on the REQUEST, so it is what refuses an over-large pack here — not the 20 MB the upload screen allows a PDF, and not the 10 MB it allows a `.docx`. Send it through the dashboard, or make it smaller.","isRequired":true,"uniqueKey":"attachments.items.[INDEX].content","typeLabel":"string"}},"required":["content"],"uniqueKey":"attachments.items.[INDEX]","typeLabel":"object"},"uniqueKey":"attachments","typeLabel":"object[]"},"documents":{"type":"array","minItems":1,"maxItems":19,"description":"Optional. The order the envelope’s documents are presented in: the signing page, the “Document N of M” above each page, the order fields are walked in, the completion email’s attachments, `display_position` on `GET /api/v1/envelopes/{envelopeId}/documents`, and the “document N of M” on each certificate. Absent: the template’s documents in its order, then `attachments` in the order given. Present: EVERY template document and EVERY attachment exactly once, each entry naming one of them — `{ \"attachment\": 0 }` for the first of `attachments`, `{ \"template_document\": \"\u003cid>\" }` for a template document, by its `id` in `GET /api/v1/templates/{templateId}`’s `documents`. Allowed without `attachments`, to reorder a template of several documents. TO LEAVE A TEMPLATE DOCUMENT OFF THE ENVELOPE, name it with `\"include\": false`: it, its fields and any question wholly on it are not part of the envelope, and the rest close up. It is refused `template_document_not_omittable` when the envelope cannot do without it — the last signature box a required role is sure to sign, when no attachment gives another, a subject, a box that decides a kept box, part of a question a kept document also asks, every box of a role you name a recipient for — or when every template document is left out. ⚠️ A TEMPLATE DOCUMENT NOT NAMED AT ALL IS `invalid_request`, not left out, so a document is never dropped without your saying so; so is an attachment left out, a document named twice, `\"include\": false` on an attachment, or an index past `attachments`. An id the template does not hold is `template_changed`: read the template again. The first of the template’s documents you keep is `position` 1 of the envelope, whatever its place here. A different order is a different request under one `Idempotency-Key`. Not accepted on a batch.","items":{"oneOf":[{"type":"object","description":"One document of the envelope, by exactly one key: `attachment` or `template_document`.","required":["attachment"],"properties":{"attachment":{"type":"integer","minimum":0,"maximum":8,"description":"Its index in `attachments`, from 0.","isRequired":true,"uniqueKey":"documents.items.[INDEX].oneOf.0.attachment","typeLabel":"integer"}},"uniqueKey":"documents.items.[INDEX].oneOf.0","typeLabel":"object"},{"type":"object","description":"One document of the envelope, by exactly one key: `attachment` or `template_document`.","required":["template_document"],"properties":{"template_document":{"type":"string","format":"uuid","description":"Its `id` in `GET /api/v1/templates/{templateId}`’s `documents`.","isRequired":true,"uniqueKey":"documents.items.[INDEX].oneOf.1.template_document","typeLabel":"string\u003cuuid>"},"include":{"type":"boolean","description":"Optional. `false` leaves this document off the envelope; absent or `true` keeps it. Refused `template_document_not_omittable` when the envelope cannot do without it.","uniqueKey":"documents.items.[INDEX].oneOf.1.include","typeLabel":"boolean"}},"uniqueKey":"documents.items.[INDEX].oneOf.1","typeLabel":"object"}],"uniqueKey":"documents.items.[INDEX]","typeLabel":"object"},"uniqueKey":"documents","typeLabel":"object[]"}},"required":["template_id","recipients"],"uniqueKey":"","typeLabel":"object"},"examples":{"example":{"title":"example","summary":"A draft with one prefilled value","value":{"template_id":"01960000-0000-4000-8000-0000000007e1","recipients":[{"role":"Employee","name":"Thandi Mokoena","email":"thandi@example.test","verification_method":"email_code"}],"values":[{"subject":"employee","key":"staff.full_name","value":"Thandi Mokoena"}],"send":false,"reference":"hire-2026-0917","documents":[{"template_document":"01960000-0000-4000-8000-00000000d0c5"}]}}},"exampleType":"examples"}},"exampleType":"examples"},"responses":{"9dfbb10c-04a1-490b-96ec-9fa12d0fbbde":{"description":"The envelope, as it stands. `Idempotency-Replayed` says whether this request created it (`false`) or is being shown an earlier one’s result (`true`); the status is 201 either way, deliberately, so that a client branching on it behaves identically on a retry.","content":{"application/json":{"schema":{"type":"object","description":"The envelope.","properties":{"id":{"type":"string","format":"uuid","description":"The envelope’s id. A bare uuid.","isRequired":true,"uniqueKey":"id","typeLabel":"string\u003cuuid>"},"status":{"type":"string","description":"`draft` or `sent` from this endpoint. Later states arrive as people act.","isRequired":true,"uniqueKey":"status","typeLabel":"string"},"template_id":{"oneOf":[{"type":"string","format":"uuid","description":"The template this was made from, or `null` when there was none — an envelope created by `POST /api/v1/envelopes/one-off` carries the document itself and never had a template. Branch on `null`, never on the empty string.","isRequired":true,"uniqueKey":"template_id.oneOf.0","typeLabel":"string\u003cuuid>"},{"type":"null","format":"uuid","description":"The template this was made from, or `null` when there was none — an envelope created by `POST /api/v1/envelopes/one-off` carries the document itself and never had a template. Branch on `null`, never on the empty string.","isRequired":true,"uniqueKey":"template_id.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"template_id","typeLabel":"string\u003cuuid> | null"},"title":{"type":"string","description":"What the signers see naming the document. Defaults to the template’s name.","isRequired":true,"uniqueKey":"title","typeLabel":"string"},"reference":{"oneOf":[{"type":"string","examples":["hire-2026-0917"],"description":"The `reference` you set when you created it, in Unicode NFC, or `null`. Not unique, and never changed after creation.","isRequired":true,"uniqueKey":"reference.oneOf.0","typeLabel":"string"},{"type":"null","examples":["hire-2026-0917"],"description":"The `reference` you set when you created it, in Unicode NFC, or `null`. Not unique, and never changed after creation.","isRequired":true,"uniqueKey":"reference.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"reference","typeLabel":"string | null"},"created_at":{"type":"string","format":"date-time","description":"ISO 8601, UTC.","isRequired":true,"uniqueKey":"created_at","typeLabel":"string\u003cdate-time>"},"sent_at":{"oneOf":[{"type":"string","format":"date-time","description":"ISO 8601, UTC. Null while it is a draft.","isRequired":true,"uniqueKey":"sent_at.oneOf.0","typeLabel":"string\u003cdate-time>"},{"type":"null","format":"date-time","description":"ISO 8601, UTC. Null while it is a draft.","isRequired":true,"uniqueKey":"sent_at.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"sent_at","typeLabel":"string\u003cdate-time> | null"},"expires_at":{"oneOf":[{"type":"string","format":"date-time","description":"ISO 8601, UTC. Null when this envelope has no deadline, which is the default. Read back from the stored value rather than echoed, so an offset you sent comes back as the same instant in UTC.","isRequired":true,"uniqueKey":"expires_at.oneOf.0","typeLabel":"string\u003cdate-time>"},{"type":"null","format":"date-time","description":"ISO 8601, UTC. Null when this envelope has no deadline, which is the default. Read back from the stored value rather than echoed, so an offset you sent comes back as the same instant in UTC.","isRequired":true,"uniqueKey":"expires_at.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"expires_at","typeLabel":"string\u003cdate-time> | null"},"recipients":{"type":"array","description":"In routing order.","items":{"type":"object","description":"One recipient.","properties":{"id":{"type":"string","format":"uuid","description":"This recipient. Published where a template ROLE’s id deliberately is not, because a recipient has no natural key — one person may hold two roles and two people may hold one.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].id","typeLabel":"string\u003cuuid>"},"role":{"type":"string","description":"The template role they were given.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].role","typeLabel":"string"},"name":{"oneOf":[{"type":"string","description":"As stored, after normalisation. `null` only while the envelope is a `draft` and nobody has been named for this role yet (a draft prepared in the dashboard); every sent recipient has a name.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].name.oneOf.0","typeLabel":"string"},{"type":"null","description":"As stored, after normalisation. `null` only while the envelope is a `draft` and nobody has been named for this role yet (a draft prepared in the dashboard); every sent recipient has a name.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].name.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"recipients.items.[INDEX].name","typeLabel":"string | null"},"email":{"oneOf":[{"type":"string","format":"email","description":"As stored, after normalisation. `null` only while the envelope is a `draft` and nobody has been named for this role yet; every sent recipient has an address. A copied-in recipient with no address when the envelope is sent is left off it.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].email.oneOf.0","typeLabel":"string\u003cemail>"},{"type":"null","format":"email","description":"As stored, after normalisation. `null` only while the envelope is a `draft` and nobody has been named for this role yet; every sent recipient has an address. A copied-in recipient with no address when the envelope is sent is left off it.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].email.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"recipients.items.[INDEX].email","typeLabel":"string\u003cemail> | null"},"routing_type":{"type":"string","enum":["sign","approve","cc"],"description":"⚠️ FROM THE TEMPLATE, NEVER FROM THE REQUEST. Whether a role signs, approves or is copied in is part of the layout (§3), and a caller who could override it could send a document whose signature boxes nobody will ever be asked to fill.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].routing_type","typeLabel":"enum\u003cstring>"},"status":{"type":"string","description":"`recipients.status` verbatim. ⚠️ `pending` AFTER A SUCCESSFUL SEND IS NORMAL: an envelope in steps invites only its lowest unfinished step and holds the rest back until that step is finished.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].status","typeLabel":"string"},"invitation_delivered":{"oneOf":[{"type":"boolean","description":"Whether the email provider reports the invitation as DELIVERED. `null` when none was attempted — a draft, a `cc`, an embedded recipient, or a position held back.\n\n⚠️ ON A READ, THIS NO LONGER ANSWERS `true` AS SOON AS THE SEND RETURNS, and it used to. Accepting a message and delivering it are different events: we now record delivery only when the provider tells us it happened, on the provider's clock. A just-sent invitation therefore reads `false` on `GET /api/v1/envelopes/{id}` and turns `true` seconds to minutes later.\n\n⚠️ THE ONE EXCEPTION IS THE RESPONSE TO `POST .../send` ITSELF, where `true` means the provider ACCEPTED the message — the only thing anybody knows while the send is still running. That operation’s response description says so at length. The same recipient can therefore read `true` from the send and `false` from a read a second later; the read is the one to decide from.\n\n⚠️ `false` IS NOT A BOUNCE. It covers both \"the provider refused the send\" and \"we have not been told yet\", and you cannot tell those apart from this field — do not surface it to a human as a failure. `null` is the only value that has never changed meaning: nothing was attempted.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].invitation_delivered.oneOf.0","typeLabel":"boolean"},{"type":"null","description":"Whether the email provider reports the invitation as DELIVERED. `null` when none was attempted — a draft, a `cc`, an embedded recipient, or a position held back.\n\n⚠️ ON A READ, THIS NO LONGER ANSWERS `true` AS SOON AS THE SEND RETURNS, and it used to. Accepting a message and delivering it are different events: we now record delivery only when the provider tells us it happened, on the provider's clock. A just-sent invitation therefore reads `false` on `GET /api/v1/envelopes/{id}` and turns `true` seconds to minutes later.\n\n⚠️ THE ONE EXCEPTION IS THE RESPONSE TO `POST .../send` ITSELF, where `true` means the provider ACCEPTED the message — the only thing anybody knows while the send is still running. That operation’s response description says so at length. The same recipient can therefore read `true` from the send and `false` from a read a second later; the read is the one to decide from.\n\n⚠️ `false` IS NOT A BOUNCE. It covers both \"the provider refused the send\" and \"we have not been told yet\", and you cannot tell those apart from this field — do not surface it to a human as a failure. `null` is the only value that has never changed meaning: nothing was attempted.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].invitation_delivered.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"recipients.items.[INDEX].invitation_delivered","typeLabel":"boolean | null"},"embedded":{"type":"boolean","description":"Whether this recipient is reached by a minted signing URL instead of by email. ⚠️ RETURNED HERE PRECISELY BECAUSE DocuSign DOES NOT RETURN THEIRS: `clientUserId` is absent from their list endpoints, so an integrator who lost their own record of which recipients were embedded has no way to ask. When this is true, `invitation_delivered` is always `null` — nothing was attempted, and nothing was meant to be.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].embedded","typeLabel":"boolean"},"delegates_stay_embedded":{"type":"boolean","description":"Whether a person this recipient delegates to is kept embedded. Only ever `true` beside `embedded: true`: you sent it at creation, or this recipient took the place of one who had it (their delegate, a correction, or a new person in the same draft slot). When it is `false`, the delegate of an embedded recipient is emailed a signing link like any other recipient, and appears here as a new recipient with `embedded: false`.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].delegates_stay_embedded","typeLabel":"boolean"},"external_ref":{"oneOf":[{"type":"string","description":"Whatever you supplied at creation, normalised to Unicode NFC, or `null`: compare it in NFC, not byte for byte. Opaque to us and joined on by nothing — it is here so a webhook or this response can be matched to your own record of the same human without a side table.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].external_ref.oneOf.0","typeLabel":"string"},{"type":"null","description":"Whatever you supplied at creation, normalised to Unicode NFC, or `null`: compare it in NFC, not byte for byte. Opaque to us and joined on by nothing — it is here so a webhook or this response can be matched to your own record of the same human without a side table.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].external_ref.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"recipients.items.[INDEX].external_ref","typeLabel":"string | null"},"verification_method":{"type":"string","enum":["none","email_code","mobile_code","identity_check"],"description":"What this recipient must prove before the document opens, read back from the recipient as it was created — `none` when the request did not say, and `mobile_code` for a recipient created with the deprecated `sms_code`. Fixed once the envelope is sent. ⚠️ IT SAYS WHAT WAS ASKED, NOT WHETHER THEY HAVE DONE IT: whether a code was entered is in the audit trail and on the certificate of completion.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].verification_method","typeLabel":"enum\u003cstring>"},"mobile":{"oneOf":[{"type":"string","examples":["+27821234567"],"description":"The mobile a `mobile_code` recipient’s code is sent to, in E.164 as stored (`+27821234567`), returned in full because it is your own data. `null` for every other method. Fixed once the envelope is sent: a wrong number is fixed by correcting the recipient.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].mobile.oneOf.0","typeLabel":"string"},{"type":"null","examples":["+27821234567"],"description":"The mobile a `mobile_code` recipient’s code is sent to, in E.164 as stored (`+27821234567`), returned in full because it is your own data. `null` for every other method. Fixed once the envelope is sent: a wrong number is fixed by correcting the recipient.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].mobile.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"recipients.items.[INDEX].mobile","typeLabel":"string | null"},"identity_check":{"oneOf":[{"type":"object","description":"On a recipient asked for an identity check, what was asked: the documents they may use (`routes`) and the ID you said to expect, as its kind, its last digits behind bullets (`masked`) and a passport’s country — ⚠️ never the number, which is not stored — and, once the check has finished, how it ended (`outcome`). `null` for every other method.","properties":{"routes":{"type":"string","enum":["either","sa_id","passport"],"description":"The documents they may use.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].identity_check.oneOf.0.routes","typeLabel":"enum\u003cstring>"},"expected_id":{"oneOf":[{"type":"object","description":"The ID you said to expect, masked, or `null` when you gave none.","properties":{"kind":{"type":"string","enum":["sa_id","passport"],"description":"An SA ID number, or a passport number.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].identity_check.oneOf.0.expected_id.oneOf.0.kind","typeLabel":"enum\u003cstring>"},"masked":{"type":"string","examples":["•••••••••0087"],"description":"Its last digits behind bullets.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].identity_check.oneOf.0.expected_id.oneOf.0.masked","typeLabel":"string"},"country":{"oneOf":[{"type":"string","description":"A passport’s issuing country (ISO 3166 alpha-3); `null` for an SA ID.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].identity_check.oneOf.0.expected_id.oneOf.0.country.oneOf.0","typeLabel":"string"},{"type":"null","description":"A passport’s issuing country (ISO 3166 alpha-3); `null` for an SA ID.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].identity_check.oneOf.0.expected_id.oneOf.0.country.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"recipients.items.[INDEX].identity_check.oneOf.0.expected_id.oneOf.0.country","typeLabel":"string | null"}},"required":["kind","masked","country"],"isRequired":true,"uniqueKey":"recipients.items.[INDEX].identity_check.oneOf.0.expected_id.oneOf.0","typeLabel":"object"},{"type":"null","description":"The ID you said to expect, masked, or `null` when you gave none.","properties":{"kind":{"type":"string","enum":["sa_id","passport"],"description":"An SA ID number, or a passport number."},"masked":{"type":"string","examples":["•••••••••0087"],"description":"Its last digits behind bullets."},"country":{"oneOf":[{"type":"string","description":"A passport’s issuing country (ISO 3166 alpha-3); `null` for an SA ID."},{"type":"null","description":"A passport’s issuing country (ISO 3166 alpha-3); `null` for an SA ID."}]}},"required":["kind","masked","country"],"isRequired":true,"uniqueKey":"recipients.items.[INDEX].identity_check.oneOf.0.expected_id.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"recipients.items.[INDEX].identity_check.oneOf.0.expected_id","typeLabel":"object | null"},"outcome":{"oneOf":[{"type":"object","description":"`null` until the check finishes; then how it ended, from the same record the certificate of completion is built from. `recipient.identity_verified` and `recipient.identity_check_failed` are the webhooks that say when. ⚠️ Never the ID or passport number, a score, a photo or the name on the document: only the masked number and the name verdict.","properties":{"status":{"type":"string","enum":["passed","failed"],"description":"`passed`, or `failed` when the check cannot finish.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].identity_check.oneOf.0.outcome.oneOf.0.status","typeLabel":"enum\u003cstring>"},"reason":{"oneOf":[{"type":"string","enum":["attempts_exhausted","id_mismatch","cannot_use_camera",null],"description":"On `failed`, why: the same `reason` the `recipient.identity_check_failed` webhook carries. `null` on `passed`.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].identity_check.oneOf.0.outcome.oneOf.0.reason.oneOf.0","typeLabel":"enum\u003cstring>"},{"type":"null","enum":["attempts_exhausted","id_mismatch","cannot_use_camera",null],"description":"On `failed`, why: the same `reason` the `recipient.identity_check_failed` webhook carries. `null` on `passed`.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].identity_check.oneOf.0.outcome.oneOf.0.reason.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"recipients.items.[INDEX].identity_check.oneOf.0.outcome.oneOf.0.reason","typeLabel":"enum\u003cstring> | null"},"completed_at":{"type":"string","format":"date-time","description":"When it passed or failed.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].identity_check.oneOf.0.outcome.oneOf.0.completed_at","typeLabel":"string\u003cdate-time>"},"route":{"oneOf":[{"type":"string","enum":["sa_id","passport",null],"description":"The route the signer took. `null` on `failed`.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].identity_check.oneOf.0.outcome.oneOf.0.route.oneOf.0","typeLabel":"enum\u003cstring>"},{"type":"null","enum":["sa_id","passport",null],"description":"The route the signer took. `null` on `failed`.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].identity_check.oneOf.0.outcome.oneOf.0.route.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"recipients.items.[INDEX].identity_check.oneOf.0.outcome.oneOf.0.route","typeLabel":"enum\u003cstring> | null"},"document":{"oneOf":[{"type":"object","description":"The document checked, masked. `null` on `failed`.","properties":{"kind":{"type":"string","enum":["smart_id_card","id_book","passport"],"description":"A Smart ID card, a green ID book, or a passport.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].identity_check.oneOf.0.outcome.oneOf.0.document.oneOf.0.kind","typeLabel":"enum\u003cstring>"},"masked":{"type":"string","examples":["•••••••••0087"],"description":"Its number’s last digits behind bullets.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].identity_check.oneOf.0.outcome.oneOf.0.document.oneOf.0.masked","typeLabel":"string"},"country":{"oneOf":[{"type":"string","description":"A passport’s issuing country (ISO 3166 alpha-3); `null` for an SA ID.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].identity_check.oneOf.0.outcome.oneOf.0.document.oneOf.0.country.oneOf.0","typeLabel":"string"},{"type":"null","description":"A passport’s issuing country (ISO 3166 alpha-3); `null` for an SA ID.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].identity_check.oneOf.0.outcome.oneOf.0.document.oneOf.0.country.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"recipients.items.[INDEX].identity_check.oneOf.0.outcome.oneOf.0.document.oneOf.0.country","typeLabel":"string | null"}},"required":["kind","masked","country"],"isRequired":true,"uniqueKey":"recipients.items.[INDEX].identity_check.oneOf.0.outcome.oneOf.0.document.oneOf.0","typeLabel":"object"},{"type":"null","description":"The document checked, masked. `null` on `failed`.","properties":{"kind":{"type":"string","enum":["smart_id_card","id_book","passport"],"description":"A Smart ID card, a green ID book, or a passport."},"masked":{"type":"string","examples":["•••••••••0087"],"description":"Its number’s last digits behind bullets."},"country":{"oneOf":[{"type":"string","description":"A passport’s issuing country (ISO 3166 alpha-3); `null` for an SA ID."},{"type":"null","description":"A passport’s issuing country (ISO 3166 alpha-3); `null` for an SA ID."}]}},"required":["kind","masked","country"],"isRequired":true,"uniqueKey":"recipients.items.[INDEX].identity_check.oneOf.0.outcome.oneOf.0.document.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"recipients.items.[INDEX].identity_check.oneOf.0.outcome.oneOf.0.document","typeLabel":"object | null"},"expected_id_matched":{"oneOf":[{"type":"boolean","description":"`true` when you gave an `expected_id` of this route’s kind and the document’s number matched it; `false` when you gave none for this route. `null` on `failed` (a number that did not match fails as `id_mismatch`).","isRequired":true,"uniqueKey":"recipients.items.[INDEX].identity_check.oneOf.0.outcome.oneOf.0.expected_id_matched.oneOf.0","typeLabel":"boolean"},{"type":"null","description":"`true` when you gave an `expected_id` of this route’s kind and the document’s number matched it; `false` when you gave none for this route. `null` on `failed` (a number that did not match fails as `id_mismatch`).","isRequired":true,"uniqueKey":"recipients.items.[INDEX].identity_check.oneOf.0.outcome.oneOf.0.expected_id_matched.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"recipients.items.[INDEX].identity_check.oneOf.0.outcome.oneOf.0.expected_id_matched","typeLabel":"boolean | null"},"name_match":{"oneOf":[{"type":"string","enum":["match","partial","mismatch",null],"description":"The name on the document against the recipient’s `name`. Names are compared ignoring case, accents, spacing, apostrophes and full stops, with a hyphen read as a space, word by word and in any order. `match`: the surname on the document is in the name you gave, and one side’s given names are all in the other’s (a second name missing on either side is fine). `partial`: the surname matches but a given name differs only by an initial (J for John) or is missing, or the given names match and the surname differs (a maiden or married name). `mismatch`: anything else. `null`: no usable name on the document, or none on the recipient. A name never fails the check. `null` on `failed`.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].identity_check.oneOf.0.outcome.oneOf.0.name_match.oneOf.0","typeLabel":"enum\u003cstring>"},{"type":"null","enum":["match","partial","mismatch",null],"description":"The name on the document against the recipient’s `name`. Names are compared ignoring case, accents, spacing, apostrophes and full stops, with a hyphen read as a space, word by word and in any order. `match`: the surname on the document is in the name you gave, and one side’s given names are all in the other’s (a second name missing on either side is fine). `partial`: the surname matches but a given name differs only by an initial (J for John) or is missing, or the given names match and the surname differs (a maiden or married name). `mismatch`: anything else. `null`: no usable name on the document, or none on the recipient. A name never fails the check. `null` on `failed`.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].identity_check.oneOf.0.outcome.oneOf.0.name_match.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"recipients.items.[INDEX].identity_check.oneOf.0.outcome.oneOf.0.name_match","typeLabel":"enum\u003cstring> | null"},"provider":{"type":"string","enum":["verifynow"],"description":"Who checked it.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].identity_check.oneOf.0.outcome.oneOf.0.provider","typeLabel":"enum\u003cstring>"},"provider_reference":{"oneOf":[{"type":"string","description":"VerifyNow’s reference for the face match, which the certificate prints; `null` when it gave none, and on `failed`.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].identity_check.oneOf.0.outcome.oneOf.0.provider_reference.oneOf.0","typeLabel":"string"},{"type":"null","description":"VerifyNow’s reference for the face match, which the certificate prints; `null` when it gave none, and on `failed`.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].identity_check.oneOf.0.outcome.oneOf.0.provider_reference.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"recipients.items.[INDEX].identity_check.oneOf.0.outcome.oneOf.0.provider_reference","typeLabel":"string | null"},"test_mode":{"type":"boolean","description":"A test envelope’s check: VerifyNow’s sandbox returned a sample result.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].identity_check.oneOf.0.outcome.oneOf.0.test_mode","typeLabel":"boolean"}},"required":["status","reason","completed_at","route","document","expected_id_matched","name_match","provider","provider_reference","test_mode"],"isRequired":true,"uniqueKey":"recipients.items.[INDEX].identity_check.oneOf.0.outcome.oneOf.0","typeLabel":"object"},{"type":"null","description":"`null` until the check finishes; then how it ended, from the same record the certificate of completion is built from. `recipient.identity_verified` and `recipient.identity_check_failed` are the webhooks that say when. ⚠️ Never the ID or passport number, a score, a photo or the name on the document: only the masked number and the name verdict.","properties":{"status":{"type":"string","enum":["passed","failed"],"description":"`passed`, or `failed` when the check cannot finish."},"reason":{"oneOf":[{"type":"string","enum":["attempts_exhausted","id_mismatch","cannot_use_camera",null],"description":"On `failed`, why: the same `reason` the `recipient.identity_check_failed` webhook carries. `null` on `passed`."},{"type":"null","enum":["attempts_exhausted","id_mismatch","cannot_use_camera",null],"description":"On `failed`, why: the same `reason` the `recipient.identity_check_failed` webhook carries. `null` on `passed`."}]},"completed_at":{"type":"string","format":"date-time","description":"When it passed or failed."},"route":{"oneOf":[{"type":"string","enum":["sa_id","passport",null],"description":"The route the signer took. `null` on `failed`."},{"type":"null","enum":["sa_id","passport",null],"description":"The route the signer took. `null` on `failed`."}]},"document":{"oneOf":[{"type":"object","description":"The document checked, masked. `null` on `failed`.","properties":{"kind":{"type":"string","enum":["smart_id_card","id_book","passport"],"description":"A Smart ID card, a green ID book, or a passport."},"masked":{"type":"string","examples":["•••••••••0087"],"description":"Its number’s last digits behind bullets."},"country":{"oneOf":[{"type":"string","description":"A passport’s issuing country (ISO 3166 alpha-3); `null` for an SA ID."},{"type":"null","description":"A passport’s issuing country (ISO 3166 alpha-3); `null` for an SA ID."}]}},"required":["kind","masked","country"]},{"type":"null","description":"The document checked, masked. `null` on `failed`.","properties":{"kind":{"type":"string","enum":["smart_id_card","id_book","passport"],"description":"A Smart ID card, a green ID book, or a passport."},"masked":{"type":"string","examples":["•••••••••0087"],"description":"Its number’s last digits behind bullets."},"country":{"oneOf":[{"type":"string","description":"A passport’s issuing country (ISO 3166 alpha-3); `null` for an SA ID."},{"type":"null","description":"A passport’s issuing country (ISO 3166 alpha-3); `null` for an SA ID."}]}},"required":["kind","masked","country"]}]},"expected_id_matched":{"oneOf":[{"type":"boolean","description":"`true` when you gave an `expected_id` of this route’s kind and the document’s number matched it; `false` when you gave none for this route. `null` on `failed` (a number that did not match fails as `id_mismatch`)."},{"type":"null","description":"`true` when you gave an `expected_id` of this route’s kind and the document’s number matched it; `false` when you gave none for this route. `null` on `failed` (a number that did not match fails as `id_mismatch`)."}]},"name_match":{"oneOf":[{"type":"string","enum":["match","partial","mismatch",null],"description":"The name on the document against the recipient’s `name`. Names are compared ignoring case, accents, spacing, apostrophes and full stops, with a hyphen read as a space, word by word and in any order. `match`: the surname on the document is in the name you gave, and one side’s given names are all in the other’s (a second name missing on either side is fine). `partial`: the surname matches but a given name differs only by an initial (J for John) or is missing, or the given names match and the surname differs (a maiden or married name). `mismatch`: anything else. `null`: no usable name on the document, or none on the recipient. A name never fails the check. `null` on `failed`."},{"type":"null","enum":["match","partial","mismatch",null],"description":"The name on the document against the recipient’s `name`. Names are compared ignoring case, accents, spacing, apostrophes and full stops, with a hyphen read as a space, word by word and in any order. `match`: the surname on the document is in the name you gave, and one side’s given names are all in the other’s (a second name missing on either side is fine). `partial`: the surname matches but a given name differs only by an initial (J for John) or is missing, or the given names match and the surname differs (a maiden or married name). `mismatch`: anything else. `null`: no usable name on the document, or none on the recipient. A name never fails the check. `null` on `failed`."}]},"provider":{"type":"string","enum":["verifynow"],"description":"Who checked it."},"provider_reference":{"oneOf":[{"type":"string","description":"VerifyNow’s reference for the face match, which the certificate prints; `null` when it gave none, and on `failed`."},{"type":"null","description":"VerifyNow’s reference for the face match, which the certificate prints; `null` when it gave none, and on `failed`."}]},"test_mode":{"type":"boolean","description":"A test envelope’s check: VerifyNow’s sandbox returned a sample result."}},"required":["status","reason","completed_at","route","document","expected_id_matched","name_match","provider","provider_reference","test_mode"],"isRequired":true,"uniqueKey":"recipients.items.[INDEX].identity_check.oneOf.0.outcome.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"recipients.items.[INDEX].identity_check.oneOf.0.outcome","typeLabel":"object | null"}},"required":["routes","expected_id","outcome"],"isRequired":true,"uniqueKey":"recipients.items.[INDEX].identity_check.oneOf.0","typeLabel":"object"},{"type":"null","description":"On a recipient asked for an identity check, what was asked: the documents they may use (`routes`) and the ID you said to expect, as its kind, its last digits behind bullets (`masked`) and a passport’s country — ⚠️ never the number, which is not stored — and, once the check has finished, how it ended (`outcome`). `null` for every other method.","properties":{"routes":{"type":"string","enum":["either","sa_id","passport"],"description":"The documents they may use."},"expected_id":{"oneOf":[{"type":"object","description":"The ID you said to expect, masked, or `null` when you gave none.","properties":{"kind":{"type":"string","enum":["sa_id","passport"],"description":"An SA ID number, or a passport number."},"masked":{"type":"string","examples":["•••••••••0087"],"description":"Its last digits behind bullets."},"country":{"oneOf":[{"type":"string","description":"A passport’s issuing country (ISO 3166 alpha-3); `null` for an SA ID."},{"type":"null","description":"A passport’s issuing country (ISO 3166 alpha-3); `null` for an SA ID."}]}},"required":["kind","masked","country"]},{"type":"null","description":"The ID you said to expect, masked, or `null` when you gave none.","properties":{"kind":{"type":"string","enum":["sa_id","passport"],"description":"An SA ID number, or a passport number."},"masked":{"type":"string","examples":["•••••••••0087"],"description":"Its last digits behind bullets."},"country":{"oneOf":[{"type":"string","description":"A passport’s issuing country (ISO 3166 alpha-3); `null` for an SA ID."},{"type":"null","description":"A passport’s issuing country (ISO 3166 alpha-3); `null` for an SA ID."}]}},"required":["kind","masked","country"]}]},"outcome":{"oneOf":[{"type":"object","description":"`null` until the check finishes; then how it ended, from the same record the certificate of completion is built from. `recipient.identity_verified` and `recipient.identity_check_failed` are the webhooks that say when. ⚠️ Never the ID or passport number, a score, a photo or the name on the document: only the masked number and the name verdict.","properties":{"status":{"type":"string","enum":["passed","failed"],"description":"`passed`, or `failed` when the check cannot finish."},"reason":{"oneOf":[{"type":"string","enum":["attempts_exhausted","id_mismatch","cannot_use_camera",null],"description":"On `failed`, why: the same `reason` the `recipient.identity_check_failed` webhook carries. `null` on `passed`."},{"type":"null","enum":["attempts_exhausted","id_mismatch","cannot_use_camera",null],"description":"On `failed`, why: the same `reason` the `recipient.identity_check_failed` webhook carries. `null` on `passed`."}]},"completed_at":{"type":"string","format":"date-time","description":"When it passed or failed."},"route":{"oneOf":[{"type":"string","enum":["sa_id","passport",null],"description":"The route the signer took. `null` on `failed`."},{"type":"null","enum":["sa_id","passport",null],"description":"The route the signer took. `null` on `failed`."}]},"document":{"oneOf":[{"type":"object","description":"The document checked, masked. `null` on `failed`.","properties":{"kind":{"type":"string","enum":["smart_id_card","id_book","passport"],"description":"A Smart ID card, a green ID book, or a passport."},"masked":{"type":"string","examples":["•••••••••0087"],"description":"Its number’s last digits behind bullets."},"country":{"oneOf":[{"type":"string","description":"A passport’s issuing country (ISO 3166 alpha-3); `null` for an SA ID."},{"type":"null","description":"A passport’s issuing country (ISO 3166 alpha-3); `null` for an SA ID."}]}},"required":["kind","masked","country"]},{"type":"null","description":"The document checked, masked. `null` on `failed`.","properties":{"kind":{"type":"string","enum":["smart_id_card","id_book","passport"],"description":"A Smart ID card, a green ID book, or a passport."},"masked":{"type":"string","examples":["•••••••••0087"],"description":"Its number’s last digits behind bullets."},"country":{"oneOf":[{"type":"string","description":"A passport’s issuing country (ISO 3166 alpha-3); `null` for an SA ID."},{"type":"null","description":"A passport’s issuing country (ISO 3166 alpha-3); `null` for an SA ID."}]}},"required":["kind","masked","country"]}]},"expected_id_matched":{"oneOf":[{"type":"boolean","description":"`true` when you gave an `expected_id` of this route’s kind and the document’s number matched it; `false` when you gave none for this route. `null` on `failed` (a number that did not match fails as `id_mismatch`)."},{"type":"null","description":"`true` when you gave an `expected_id` of this route’s kind and the document’s number matched it; `false` when you gave none for this route. `null` on `failed` (a number that did not match fails as `id_mismatch`)."}]},"name_match":{"oneOf":[{"type":"string","enum":["match","partial","mismatch",null],"description":"The name on the document against the recipient’s `name`. Names are compared ignoring case, accents, spacing, apostrophes and full stops, with a hyphen read as a space, word by word and in any order. `match`: the surname on the document is in the name you gave, and one side’s given names are all in the other’s (a second name missing on either side is fine). `partial`: the surname matches but a given name differs only by an initial (J for John) or is missing, or the given names match and the surname differs (a maiden or married name). `mismatch`: anything else. `null`: no usable name on the document, or none on the recipient. A name never fails the check. `null` on `failed`."},{"type":"null","enum":["match","partial","mismatch",null],"description":"The name on the document against the recipient’s `name`. Names are compared ignoring case, accents, spacing, apostrophes and full stops, with a hyphen read as a space, word by word and in any order. `match`: the surname on the document is in the name you gave, and one side’s given names are all in the other’s (a second name missing on either side is fine). `partial`: the surname matches but a given name differs only by an initial (J for John) or is missing, or the given names match and the surname differs (a maiden or married name). `mismatch`: anything else. `null`: no usable name on the document, or none on the recipient. A name never fails the check. `null` on `failed`."}]},"provider":{"type":"string","enum":["verifynow"],"description":"Who checked it."},"provider_reference":{"oneOf":[{"type":"string","description":"VerifyNow’s reference for the face match, which the certificate prints; `null` when it gave none, and on `failed`."},{"type":"null","description":"VerifyNow’s reference for the face match, which the certificate prints; `null` when it gave none, and on `failed`."}]},"test_mode":{"type":"boolean","description":"A test envelope’s check: VerifyNow’s sandbox returned a sample result."}},"required":["status","reason","completed_at","route","document","expected_id_matched","name_match","provider","provider_reference","test_mode"]},{"type":"null","description":"`null` until the check finishes; then how it ended, from the same record the certificate of completion is built from. `recipient.identity_verified` and `recipient.identity_check_failed` are the webhooks that say when. ⚠️ Never the ID or passport number, a score, a photo or the name on the document: only the masked number and the name verdict.","properties":{"status":{"type":"string","enum":["passed","failed"],"description":"`passed`, or `failed` when the check cannot finish."},"reason":{"oneOf":[{"type":"string","enum":["attempts_exhausted","id_mismatch","cannot_use_camera",null],"description":"On `failed`, why: the same `reason` the `recipient.identity_check_failed` webhook carries. `null` on `passed`."},{"type":"null","enum":["attempts_exhausted","id_mismatch","cannot_use_camera",null],"description":"On `failed`, why: the same `reason` the `recipient.identity_check_failed` webhook carries. `null` on `passed`."}]},"completed_at":{"type":"string","format":"date-time","description":"When it passed or failed."},"route":{"oneOf":[{"type":"string","enum":["sa_id","passport",null],"description":"The route the signer took. `null` on `failed`."},{"type":"null","enum":["sa_id","passport",null],"description":"The route the signer took. `null` on `failed`."}]},"document":{"oneOf":[{"type":"object","description":"The document checked, masked. `null` on `failed`.","properties":{"kind":{"type":"string","enum":["smart_id_card","id_book","passport"],"description":"A Smart ID card, a green ID book, or a passport."},"masked":{"type":"string","examples":["•••••••••0087"],"description":"Its number’s last digits behind bullets."},"country":{"oneOf":[{"type":"string","description":"A passport’s issuing country (ISO 3166 alpha-3); `null` for an SA ID."},{"type":"null","description":"A passport’s issuing country (ISO 3166 alpha-3); `null` for an SA ID."}]}},"required":["kind","masked","country"]},{"type":"null","description":"The document checked, masked. `null` on `failed`.","properties":{"kind":{"type":"string","enum":["smart_id_card","id_book","passport"],"description":"A Smart ID card, a green ID book, or a passport."},"masked":{"type":"string","examples":["•••••••••0087"],"description":"Its number’s last digits behind bullets."},"country":{"oneOf":[{"type":"string","description":"A passport’s issuing country (ISO 3166 alpha-3); `null` for an SA ID."},{"type":"null","description":"A passport’s issuing country (ISO 3166 alpha-3); `null` for an SA ID."}]}},"required":["kind","masked","country"]}]},"expected_id_matched":{"oneOf":[{"type":"boolean","description":"`true` when you gave an `expected_id` of this route’s kind and the document’s number matched it; `false` when you gave none for this route. `null` on `failed` (a number that did not match fails as `id_mismatch`)."},{"type":"null","description":"`true` when you gave an `expected_id` of this route’s kind and the document’s number matched it; `false` when you gave none for this route. `null` on `failed` (a number that did not match fails as `id_mismatch`)."}]},"name_match":{"oneOf":[{"type":"string","enum":["match","partial","mismatch",null],"description":"The name on the document against the recipient’s `name`. Names are compared ignoring case, accents, spacing, apostrophes and full stops, with a hyphen read as a space, word by word and in any order. `match`: the surname on the document is in the name you gave, and one side’s given names are all in the other’s (a second name missing on either side is fine). `partial`: the surname matches but a given name differs only by an initial (J for John) or is missing, or the given names match and the surname differs (a maiden or married name). `mismatch`: anything else. `null`: no usable name on the document, or none on the recipient. A name never fails the check. `null` on `failed`."},{"type":"null","enum":["match","partial","mismatch",null],"description":"The name on the document against the recipient’s `name`. Names are compared ignoring case, accents, spacing, apostrophes and full stops, with a hyphen read as a space, word by word and in any order. `match`: the surname on the document is in the name you gave, and one side’s given names are all in the other’s (a second name missing on either side is fine). `partial`: the surname matches but a given name differs only by an initial (J for John) or is missing, or the given names match and the surname differs (a maiden or married name). `mismatch`: anything else. `null`: no usable name on the document, or none on the recipient. A name never fails the check. `null` on `failed`."}]},"provider":{"type":"string","enum":["verifynow"],"description":"Who checked it."},"provider_reference":{"oneOf":[{"type":"string","description":"VerifyNow’s reference for the face match, which the certificate prints; `null` when it gave none, and on `failed`."},{"type":"null","description":"VerifyNow’s reference for the face match, which the certificate prints; `null` when it gave none, and on `failed`."}]},"test_mode":{"type":"boolean","description":"A test envelope’s check: VerifyNow’s sandbox returned a sample result."}},"required":["status","reason","completed_at","route","document","expected_id_matched","name_match","provider","provider_reference","test_mode"]}]}},"required":["routes","expected_id","outcome"],"isRequired":true,"uniqueKey":"recipients.items.[INDEX].identity_check.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"recipients.items.[INDEX].identity_check","typeLabel":"object | null"},"completion_basis":{"oneOf":[{"type":"string","enum":["session","standing_authorisation",null],"description":"How this recipient completed: `session` for a person who signed or approved themselves, `standing_authorisation` for a role pre-signed when the document was sent, under a standing authorisation. `null` until they complete — including a draft’s pre-signed role, which completes only when the envelope is sent.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].completion_basis.oneOf.0","typeLabel":"enum\u003cstring>"},{"type":"null","enum":["session","standing_authorisation",null],"description":"How this recipient completed: `session` for a person who signed or approved themselves, `standing_authorisation` for a role pre-signed when the document was sent, under a standing authorisation. `null` until they complete — including a draft’s pre-signed role, which completes only when the envelope is sent.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].completion_basis.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"recipients.items.[INDEX].completion_basis","typeLabel":"enum\u003cstring> | null"},"standing_authorisation":{"oneOf":[{"type":"object","description":"The standing authorisation named on this role, or `null` for a person. Present from the draft on. The grantor named on it is never emailed about the document.","properties":{"id":{"type":"string","format":"uuid","description":"The authorisation.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].standing_authorisation.oneOf.0.id","typeLabel":"string\u003cuuid>"},"number":{"type":"string","examples":["SA-0012"],"description":"Its number, as printed.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].standing_authorisation.oneOf.0.number","typeLabel":"string"},"witness":{"type":"boolean","description":"Whether the mark was applied as a WITNESS’s: the role is a witness, the authorisation was granted for witness use, and the document, its certificate and its verification page say the witness was not present. `false` until the send applies it, and always for a party.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].standing_authorisation.oneOf.0.witness","typeLabel":"boolean"}},"required":["id","number","witness"],"isRequired":true,"uniqueKey":"recipients.items.[INDEX].standing_authorisation.oneOf.0","typeLabel":"object"},{"type":"null","description":"The standing authorisation named on this role, or `null` for a person. Present from the draft on. The grantor named on it is never emailed about the document.","properties":{"id":{"type":"string","format":"uuid","description":"The authorisation."},"number":{"type":"string","examples":["SA-0012"],"description":"Its number, as printed."},"witness":{"type":"boolean","description":"Whether the mark was applied as a WITNESS’s: the role is a witness, the authorisation was granted for witness use, and the document, its certificate and its verification page say the witness was not present. `false` until the send applies it, and always for a party."}},"required":["id","number","witness"],"isRequired":true,"uniqueKey":"recipients.items.[INDEX].standing_authorisation.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"recipients.items.[INDEX].standing_authorisation","typeLabel":"object | null"}},"required":["id","role","name","email","routing_type","status","invitation_delivered","embedded","delegates_stay_embedded","external_ref","verification_method","mobile","identity_check","completion_basis","standing_authorisation"],"uniqueKey":"recipients.items.[INDEX]","typeLabel":"object"},"isRequired":true,"uniqueKey":"recipients","typeLabel":"object[]"},"subjects":{"type":"array","description":"Who the envelope is about, such as a spouse or a dependant, in the order they were declared: the `subject` a value names. A one-off’s come from setting it up in the editor; an envelope made from a template has its template’s. Empty when the envelope is about nobody in particular.","items":{"type":"object","description":"One person the envelope is about.","properties":{"key":{"type":"string","examples":["spouse"],"description":"The key a value’s `subject` names.","isRequired":true,"uniqueKey":"subjects.items.[INDEX].key","typeLabel":"string"},"label":{"type":"string","examples":["Spouse"],"description":"What a person reads.","isRequired":true,"uniqueKey":"subjects.items.[INDEX].label","typeLabel":"string"},"presence":{"type":"string","enum":["required","conditional"],"description":"`required`: always on this envelope. `conditional`: may be left out.","isRequired":true,"uniqueKey":"subjects.items.[INDEX].presence","typeLabel":"enum\u003cstring>"},"present":{"type":"boolean","description":"Whether this envelope has this person. When `false`, their boxes are hidden from the signer and are not required. A `conditional` person may still be switched on or off by the signer. While the signer is still to be asked (`awaiting_signer`), this is `false`, which is what the signer sees until they answer.","isRequired":true,"uniqueKey":"subjects.items.[INDEX].present","typeLabel":"boolean"},"awaiting_signer":{"type":"boolean","description":"`true` while the signer is still to be asked whether this person is on the form: the sender chose Ask the signer, and nobody has answered yet. `present` is then `false`. Read the two together to tell a person left out from one not answered yet. Always `false` for a `required` person.","isRequired":true,"uniqueKey":"subjects.items.[INDEX].awaiting_signer","typeLabel":"boolean"},"starts_as":{"type":"string","enum":["ask","present","absent"],"description":"The sender’s choice for a `conditional` person: `ask` (the signer is asked), `present` (Include) or `absent` (Leave out). Fixed once the envelope is sent, while `present` is the fact now and can change. Read it with `present`: an envelope made before the sender could choose reads `absent`. Not meaningful for a `required` person.","isRequired":true,"uniqueKey":"subjects.items.[INDEX].starts_as","typeLabel":"enum\u003cstring>"}},"required":["key","label","presence","present","awaiting_signer","starts_as"],"uniqueKey":"subjects.items.[INDEX]","typeLabel":"object"},"isRequired":true,"uniqueKey":"subjects","typeLabel":"object[]"},"roles_left_out":{"type":"array","description":"The optional roles this envelope was sent without (`Role.presence` is `optional` on its template, and nobody was named for the role: no recipient in the request, or only an empty slot on a draft prepared in the dashboard). Each was left out when the envelope was sent, with every field it held, and the sealed certificate lists it as not on the envelope. Only a role that held fields is listed: one with none has nothing to leave out. Empty before the envelope is sent and for a one-off.","items":{"type":"object","description":"One optional role the envelope was sent without.","required":["role","kind"],"properties":{"role":{"type":"string","examples":["Surety"],"description":"The role’s name.","isRequired":true,"uniqueKey":"roles_left_out.items.[INDEX].role","typeLabel":"string"},"kind":{"type":"string","enum":["party","witness"],"description":"The role’s kind when it was left out.","isRequired":true,"uniqueKey":"roles_left_out.items.[INDEX].kind","typeLabel":"enum\u003cstring>"}},"uniqueKey":"roles_left_out.items.[INDEX]","typeLabel":"object"},"isRequired":true,"uniqueKey":"roles_left_out","typeLabel":"object[]"}},"required":["id","status","template_id","title","reference","created_at","sent_at","expires_at","recipients","subjects","roles_left_out"],"uniqueKey":"","typeLabel":"object"},"examples":{"example":{"title":"example","summary":"The draft, which emailed nobody","value":{"id":"01960000-0000-4000-8000-0000000000e5","status":"draft","template_id":"01960000-0000-4000-8000-0000000007e1","title":"Employment contract","reference":"hire-2026-0917","created_at":"2026-09-02T09:00:00.000Z","sent_at":null,"expires_at":null,"recipients":[{"id":"01960000-0000-4000-8000-00000000005e","role":"Employee","name":"Thandi Mokoena","email":"thandi@example.test","routing_type":"sign","status":"pending","invitation_delivered":null,"embedded":false,"delegates_stay_embedded":false,"external_ref":null,"verification_method":"email_code","mobile":null,"identity_check":null,"completion_basis":null,"standing_authorisation":null}],"subjects":[],"roles_left_out":[]}}},"exampleType":"examples"}},"headers":{"RateLimit-Limit":{"description":"How many requests this key may make per minute: 600 on any paid plan and 60 on the free plan, the same in both environments. Per key, not per organisation — a second key has its own allowance. ⚠️ READ IT RATHER THAN ASSUMING IT: it is the number the database applied to this request, so it is right even when this description is out of date.","schema":{"type":"integer","description":"Requests permitted in the current minute."}},"RateLimit-Remaining":{"description":"How many of them are left, this one already counted. Zero on the request that is refused, and zero on every further request of that minute — ⚠️ a refused request still counts.","schema":{"type":"integer","description":"Requests remaining in the current minute."}},"RateLimit-Reset":{"description":"Seconds until the current minute closes and the allowance returns. At most 60, which is what makes the published exponential backoff converge in about six doublings rather than eleven.","schema":{"type":"integer","description":"Seconds until the window resets."}}},"exampleType":"examples"},"581b0274-13ef-4fbf-934b-348226a0a68f":{"description":"`invalid_request` — The request is malformed, or breaks a rule about its own shape: a body that is not JSON or does not match the operation’s schema (a missing or mistyped property, a value out of range), a document that is not a PDF or a Word file we can read, a text tag that cannot be placed, an `Idempotency-Key` that is present but not a valid key, a query parameter outside its range, or a cursor that names nothing. The `message` says which, and for a body names the property path (`recipients[0].email`) — there is no separate `param` field. Fix the request; retrying it unchanged will fail identically.\n\n`idempotency_key_required` — Send `Idempotency-Key: \u003cuuid>` — this operation takes one and the request carried none. A distinct code from `invalid_request` because the remedy is to ADD a header, and an integrator reading it in a log should not have to work that out. (A key that is present but malformed is `invalid_request`, and its `message` names the header.)","content":{"application/json":{"schema":{"type":"object","description":"The refusal.","properties":{"error":{"type":"object","description":"The refusal. Anything added in future is added INSIDE this object.","properties":{"code":{"type":"string","description":"A stable snake_case identifier that will never change meaning or spelling. This is the contract; branch on it. See `x-error-codes` at the root of this document for retry semantics per code.","enum":["unauthenticated","forbidden","insufficient_scope","not_found","invalid_request","rate_limited","internal_error","service_unavailable","idempotency_key_required","idempotency_key_reused","request_in_progress","template_archived","template_unusable","template_has_no_fields","template_changed","template_document_not_omittable","precondition_required","field_unknown","naming_rule_broken","naming_run_not_ready","naming_run_failed","proposal_changed","decision_not_allowed","witness_is_permanent","recipient_role_unknown","recipient_role_missing","recipient_role_duplicated","recipient_step_partial","step_with_signing_mode","value_subject_unknown","value_address_unknown","value_not_writable","value_option_unknown","value_option_locked","value_selection_out_of_bounds","value_not_lockable","locked_answer_missing","locked_answer_unusable","cannot_be_drawn","send_allowance_exhausted","sms_allowance_exhausted","test_key_cannot_send","test_key_cannot_read_documents","test_key_cannot_edit_templates","document_too_complex","test_key_cannot_mint","test_key_cannot_extend","test_key_cannot_discard","test_key_cannot_void","webhook_url_invalid","webhook_events_invalid","webhook_brand_unknown","webhook_limit_reached","api_key_owner_removed","envelope_sender_removed","recipient_not_embedded","recipient_not_yet_turn","recipient_cannot_sign","envelope_not_sent","deadline_not_extendable","envelope_not_draft","brand_has_no_embed_origins","embed_origin_not_registered","recipient_cannot_be_embedded","recipient_verification_unavailable","recipient_mobile_unused","recipient_mobile_required","recipient_mobile_invalid","recipient_mobile_unsupported_country","recipient_verification_not_allowed","identity_check_requires_paid_plan","identity_check_not_live","recipient_identity_check_not_allowed","recipient_identity_routes_invalid","recipient_expected_id_invalid","batch_interrupted","brand_unknown","brand_is_archived","embed_origin_limit_reached","test_key_cannot_edit_brands","draft_not_available","standing_authorisations_not_enabled","authorisation_text_rejected","authorisation_validity_invalid","authorisation_not_revocable","authorisation_not_pending","authorisation_resend_limited","authorisation_not_renewable","authorisation_already_renewed","authorisation_unknown","authorisation_not_granted","authorisation_revoked","authorisation_expired","authorisation_not_yet_valid","authorisation_invalidated","authorisation_brand_mismatch","authorisation_environment_mismatch","authorisation_role_is_witness","authorisation_role_not_signing","authorisation_recipient_altered","authorisation_used_twice","authorisation_grantor_twice","authorisation_field_unsupported","authorisation_value_forbidden","value_for_left_out_role","authorisation_value_missing","authorisation_value_unlocked","authorisation_mark_too_small","authorisation_mark_unplaced","authorisation_mark_unavailable","authorisation_expires_during_batch"],"isRequired":true,"uniqueKey":"error.code","typeLabel":"enum\u003cstring>"},"message":{"type":"string","description":"⚠️ PROSE FOR A DEVELOPER READING A LOG, and NOT part of the contract. It may be reworded in any release; anything that parses it is broken by design.","isRequired":true,"uniqueKey":"error.message","typeLabel":"string"}},"required":["code","message"],"isRequired":true,"uniqueKey":"error","typeLabel":"object"}},"required":["error"],"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"error":{"code":"unauthenticated","message":"\u003cstring>"}}}},"exampleType":"generated"}},"exampleType":"generated"},"d253fab7-b7b5-492c-9173-4fc616fe004b":{"description":"`unauthenticated` — The credential was absent, unreadable, unknown, wrong or revoked — this answer is deliberately identical for all of them, so it cannot be used to probe which keys exist. Retrying the same request changes nothing. Check the key in Settings or issue a new one.","content":{"application/json":{"schema":{"type":"object","description":"The refusal.","properties":{"error":{"type":"object","description":"The refusal. Anything added in future is added INSIDE this object.","properties":{"code":{"type":"string","description":"A stable snake_case identifier that will never change meaning or spelling. This is the contract; branch on it. See `x-error-codes` at the root of this document for retry semantics per code.","enum":["unauthenticated","forbidden","insufficient_scope","not_found","invalid_request","rate_limited","internal_error","service_unavailable","idempotency_key_required","idempotency_key_reused","request_in_progress","template_archived","template_unusable","template_has_no_fields","template_changed","template_document_not_omittable","precondition_required","field_unknown","naming_rule_broken","naming_run_not_ready","naming_run_failed","proposal_changed","decision_not_allowed","witness_is_permanent","recipient_role_unknown","recipient_role_missing","recipient_role_duplicated","recipient_step_partial","step_with_signing_mode","value_subject_unknown","value_address_unknown","value_not_writable","value_option_unknown","value_option_locked","value_selection_out_of_bounds","value_not_lockable","locked_answer_missing","locked_answer_unusable","cannot_be_drawn","send_allowance_exhausted","sms_allowance_exhausted","test_key_cannot_send","test_key_cannot_read_documents","test_key_cannot_edit_templates","document_too_complex","test_key_cannot_mint","test_key_cannot_extend","test_key_cannot_discard","test_key_cannot_void","webhook_url_invalid","webhook_events_invalid","webhook_brand_unknown","webhook_limit_reached","api_key_owner_removed","envelope_sender_removed","recipient_not_embedded","recipient_not_yet_turn","recipient_cannot_sign","envelope_not_sent","deadline_not_extendable","envelope_not_draft","brand_has_no_embed_origins","embed_origin_not_registered","recipient_cannot_be_embedded","recipient_verification_unavailable","recipient_mobile_unused","recipient_mobile_required","recipient_mobile_invalid","recipient_mobile_unsupported_country","recipient_verification_not_allowed","identity_check_requires_paid_plan","identity_check_not_live","recipient_identity_check_not_allowed","recipient_identity_routes_invalid","recipient_expected_id_invalid","batch_interrupted","brand_unknown","brand_is_archived","embed_origin_limit_reached","test_key_cannot_edit_brands","draft_not_available","standing_authorisations_not_enabled","authorisation_text_rejected","authorisation_validity_invalid","authorisation_not_revocable","authorisation_not_pending","authorisation_resend_limited","authorisation_not_renewable","authorisation_already_renewed","authorisation_unknown","authorisation_not_granted","authorisation_revoked","authorisation_expired","authorisation_not_yet_valid","authorisation_invalidated","authorisation_brand_mismatch","authorisation_environment_mismatch","authorisation_role_is_witness","authorisation_role_not_signing","authorisation_recipient_altered","authorisation_used_twice","authorisation_grantor_twice","authorisation_field_unsupported","authorisation_value_forbidden","value_for_left_out_role","authorisation_value_missing","authorisation_value_unlocked","authorisation_mark_too_small","authorisation_mark_unplaced","authorisation_mark_unavailable","authorisation_expires_during_batch"],"isRequired":true,"uniqueKey":"error.code","typeLabel":"enum\u003cstring>"},"message":{"type":"string","description":"⚠️ PROSE FOR A DEVELOPER READING A LOG, and NOT part of the contract. It may be reworded in any release; anything that parses it is broken by design.","isRequired":true,"uniqueKey":"error.message","typeLabel":"string"}},"required":["code","message"],"isRequired":true,"uniqueKey":"error","typeLabel":"object"}},"required":["error"],"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"error":{"code":"unauthenticated","message":"\u003cstring>"}}}},"exampleType":"generated"}},"exampleType":"generated"},"fccf96d8-d500-4daa-bd2d-889db535294b":{"description":"`send_allowance_exhausted` — ⚠️ 402, THE ONLY STATUS IN THIS API THAT NAMES MONEY. Not 403 (the credential is permitted; the plan is not) and not 429 (waiting does not help until the month turns). Upgrade the plan, or wait for the period to roll over. ⚠️ RETRYING IS POINTLESS BUT NOT HARMFUL — nothing was created, so there is no partial envelope to clean up. Only the Free plan (5 envelopes a month) is ever blocked, once that many envelopes have been sent in the month; every other plan is counted and never stopped, and a `vsk_test_` key never meets this at all because a sandbox envelope consumes no allowance to exhaust.\n\n`sms_allowance_exhausted` — 402, for the reason `send_allowance_exhausted` gives. The envelope names a recipient asked for a mobile code (`mobile_code`), and the plan’s mobile codes for the month are used: only the Free plan, once 10 have been sent in the month. A code is counted once whether it went on WhatsApp, by SMS or both. Every other plan is charged per mobile code past its allowance and never stopped, and a code for an envelope already sent is never refused for billing. Send that recipient `email_code` or `none` instead, upgrade, or wait for the month to turn. Nothing was created. A `vsk_test_` key never meets this: a test envelope sends no message. (The code keeps its name, `sms_allowance_exhausted`, so integrations switching on it keep working.)\n\n`identity_check_requires_paid_plan` — 402, for the reason `send_allowance_exhausted` gives. A recipient is asked for `identity_check`, and the organisation is on Free, where it is not offered — or pays by card and has no card on file to add the check to. Raised when the envelope is created and again at send. Choose another `verification_method`, or change plan (or add a card) in Settings, Plan and usage. Nothing was created or sent.","content":{"application/json":{"schema":{"type":"object","description":"The refusal.","properties":{"error":{"type":"object","description":"The refusal. Anything added in future is added INSIDE this object.","properties":{"code":{"type":"string","description":"A stable snake_case identifier that will never change meaning or spelling. This is the contract; branch on it. See `x-error-codes` at the root of this document for retry semantics per code.","enum":["unauthenticated","forbidden","insufficient_scope","not_found","invalid_request","rate_limited","internal_error","service_unavailable","idempotency_key_required","idempotency_key_reused","request_in_progress","template_archived","template_unusable","template_has_no_fields","template_changed","template_document_not_omittable","precondition_required","field_unknown","naming_rule_broken","naming_run_not_ready","naming_run_failed","proposal_changed","decision_not_allowed","witness_is_permanent","recipient_role_unknown","recipient_role_missing","recipient_role_duplicated","recipient_step_partial","step_with_signing_mode","value_subject_unknown","value_address_unknown","value_not_writable","value_option_unknown","value_option_locked","value_selection_out_of_bounds","value_not_lockable","locked_answer_missing","locked_answer_unusable","cannot_be_drawn","send_allowance_exhausted","sms_allowance_exhausted","test_key_cannot_send","test_key_cannot_read_documents","test_key_cannot_edit_templates","document_too_complex","test_key_cannot_mint","test_key_cannot_extend","test_key_cannot_discard","test_key_cannot_void","webhook_url_invalid","webhook_events_invalid","webhook_brand_unknown","webhook_limit_reached","api_key_owner_removed","envelope_sender_removed","recipient_not_embedded","recipient_not_yet_turn","recipient_cannot_sign","envelope_not_sent","deadline_not_extendable","envelope_not_draft","brand_has_no_embed_origins","embed_origin_not_registered","recipient_cannot_be_embedded","recipient_verification_unavailable","recipient_mobile_unused","recipient_mobile_required","recipient_mobile_invalid","recipient_mobile_unsupported_country","recipient_verification_not_allowed","identity_check_requires_paid_plan","identity_check_not_live","recipient_identity_check_not_allowed","recipient_identity_routes_invalid","recipient_expected_id_invalid","batch_interrupted","brand_unknown","brand_is_archived","embed_origin_limit_reached","test_key_cannot_edit_brands","draft_not_available","standing_authorisations_not_enabled","authorisation_text_rejected","authorisation_validity_invalid","authorisation_not_revocable","authorisation_not_pending","authorisation_resend_limited","authorisation_not_renewable","authorisation_already_renewed","authorisation_unknown","authorisation_not_granted","authorisation_revoked","authorisation_expired","authorisation_not_yet_valid","authorisation_invalidated","authorisation_brand_mismatch","authorisation_environment_mismatch","authorisation_role_is_witness","authorisation_role_not_signing","authorisation_recipient_altered","authorisation_used_twice","authorisation_grantor_twice","authorisation_field_unsupported","authorisation_value_forbidden","value_for_left_out_role","authorisation_value_missing","authorisation_value_unlocked","authorisation_mark_too_small","authorisation_mark_unplaced","authorisation_mark_unavailable","authorisation_expires_during_batch"],"isRequired":true,"uniqueKey":"error.code","typeLabel":"enum\u003cstring>"},"message":{"type":"string","description":"⚠️ PROSE FOR A DEVELOPER READING A LOG, and NOT part of the contract. It may be reworded in any release; anything that parses it is broken by design.","isRequired":true,"uniqueKey":"error.message","typeLabel":"string"}},"required":["code","message"],"isRequired":true,"uniqueKey":"error","typeLabel":"object"}},"required":["error"],"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"error":{"code":"unauthenticated","message":"\u003cstring>"}}}},"exampleType":"generated"}},"exampleType":"generated"},"efa5dc1a-2420-4161-8df5-f22d63dd2a17":{"description":"`standing_authorisations_not_enabled` — Standing authorisations are switched off for this environment of your organisation. They are on for sandbox and live in every organisation unless Vumasign has switched one off, so a test key and a live key can get different answers. Retrying changes nothing; ask us to switch the environment you need back on. A request with `witness: true` gets the same answer while witness use, which is switched separately, is off for that environment: it is on for sandbox, and an owner or admin of your organisation switches it on for live, in Settings › Authorisations.\n\n`forbidden` — The key is valid and the organisation’s plan does not grant what this operation does. Nothing about the credential needs to change, and it is deliberately MORE specific than 401 because the caller has already proved they hold the key. TWO SITUATIONS PRODUCE IT. (1) THE PLAN EXCLUDES THE OPERATION: `POST /api/v1/templates` on the Free plan, which does not include authoring templates. A template that already exists stays readable at `GET /api/v1/templates`; authoring one needs a plan that includes templates. (2) WE CANNOT ESTABLISH WHAT THE PLAN INCLUDES, on any operation, so nothing is granted. That one is ours rather than yours, an ordinary account does not meet it, and it means ask us.\n\n`insufficient_scope` — This key is scoped and does not hold the scope this operation requires — `x-required-scope` on the operation names it, and the `WWW-Authenticate` header on the refusal repeats it (RFC 6750 §3.1). ⚠️ Retrying cannot help until the key changes: an owner or admin edits its permissions under Settings → API keys, and the same key holds the new scope from its next request — no new key is needed. A key created before scopes existed carries an empty scope list, which means EVERY capability, so this refusal cannot reach an integration that was already working.\n\n`test_key_cannot_send` — A `vsk_test_` key tried a send it may not make. TWO SITUATIONS PRODUCE IT. (1) `POST /api/v1/envelopes/{envelopeId}/send` on an envelope a LIVE key created: sending it would email its real recipients and spend real allowance, so send it with a live key. (2) Far more often, a recipient who would be EMAILED and whose address is not one this organisation may send rehearsals to. THE RULE IS ABOUT WHO, NOT ABOUT WHETHER: a test key may email anybody who is a MEMBER of the sending organisation, and any other address that has CONFIRMED a verification link sent to it (Settings → Test recipients). Nobody else at all. So a mixed envelope — one `\"embedded\": true` signer in your application and one emailed counterparty — is fully rehearsable, provided that counterparty is on the list. An `\"embedded\": true` recipient is never checked against it, because an embedded recipient is issued no invitation and is emailed by no code path at all. ⚠️ WHY THE LIMIT EXISTS: a sandbox send consumes no billing allowance, so an unbounded one would be an unmetered way to email strangers from a free account, over a sending domain every customer shares. The message names each address that was refused. Your options are: add and verify the address; make the recipient `\"embedded\": true`; create the draft with `\"send\": false`; or send with a live key, which may email anybody. What a test key still never does is consume billing allowance or produce a sealed artefact anybody can be held to — its documents are watermarked on every page and sealed by a certificate issued for the sandbox and for nothing else, so a PDF reader reports the signature as intact and its issuer as untrusted, and everyone who receives one is told so before they can open it.\n\n`api_key_owner_removed` — The person who created this key has left the organisation, and everything the key creates or sends — an envelope, a batch, a template — is attributed to that person, who must still be a member. The key is not revoked and its reads still work, and so does managing webhooks; mint a new key from a current member and use that.\n\n`identity_check_not_live` — A LIVE envelope names `identity_check`, and identity checks are not switched on for live envelopes on this deployment yet. Send it with a `vsk_test_` key (VerifyNow’s sandbox, at no cost), or choose another `verification_method` for the live envelope. Raised at send; nothing was sent.","content":{"application/json":{"schema":{"type":"object","description":"The refusal.","properties":{"error":{"type":"object","description":"The refusal. Anything added in future is added INSIDE this object.","properties":{"code":{"type":"string","description":"A stable snake_case identifier that will never change meaning or spelling. This is the contract; branch on it. See `x-error-codes` at the root of this document for retry semantics per code.","enum":["unauthenticated","forbidden","insufficient_scope","not_found","invalid_request","rate_limited","internal_error","service_unavailable","idempotency_key_required","idempotency_key_reused","request_in_progress","template_archived","template_unusable","template_has_no_fields","template_changed","template_document_not_omittable","precondition_required","field_unknown","naming_rule_broken","naming_run_not_ready","naming_run_failed","proposal_changed","decision_not_allowed","witness_is_permanent","recipient_role_unknown","recipient_role_missing","recipient_role_duplicated","recipient_step_partial","step_with_signing_mode","value_subject_unknown","value_address_unknown","value_not_writable","value_option_unknown","value_option_locked","value_selection_out_of_bounds","value_not_lockable","locked_answer_missing","locked_answer_unusable","cannot_be_drawn","send_allowance_exhausted","sms_allowance_exhausted","test_key_cannot_send","test_key_cannot_read_documents","test_key_cannot_edit_templates","document_too_complex","test_key_cannot_mint","test_key_cannot_extend","test_key_cannot_discard","test_key_cannot_void","webhook_url_invalid","webhook_events_invalid","webhook_brand_unknown","webhook_limit_reached","api_key_owner_removed","envelope_sender_removed","recipient_not_embedded","recipient_not_yet_turn","recipient_cannot_sign","envelope_not_sent","deadline_not_extendable","envelope_not_draft","brand_has_no_embed_origins","embed_origin_not_registered","recipient_cannot_be_embedded","recipient_verification_unavailable","recipient_mobile_unused","recipient_mobile_required","recipient_mobile_invalid","recipient_mobile_unsupported_country","recipient_verification_not_allowed","identity_check_requires_paid_plan","identity_check_not_live","recipient_identity_check_not_allowed","recipient_identity_routes_invalid","recipient_expected_id_invalid","batch_interrupted","brand_unknown","brand_is_archived","embed_origin_limit_reached","test_key_cannot_edit_brands","draft_not_available","standing_authorisations_not_enabled","authorisation_text_rejected","authorisation_validity_invalid","authorisation_not_revocable","authorisation_not_pending","authorisation_resend_limited","authorisation_not_renewable","authorisation_already_renewed","authorisation_unknown","authorisation_not_granted","authorisation_revoked","authorisation_expired","authorisation_not_yet_valid","authorisation_invalidated","authorisation_brand_mismatch","authorisation_environment_mismatch","authorisation_role_is_witness","authorisation_role_not_signing","authorisation_recipient_altered","authorisation_used_twice","authorisation_grantor_twice","authorisation_field_unsupported","authorisation_value_forbidden","value_for_left_out_role","authorisation_value_missing","authorisation_value_unlocked","authorisation_mark_too_small","authorisation_mark_unplaced","authorisation_mark_unavailable","authorisation_expires_during_batch"],"isRequired":true,"uniqueKey":"error.code","typeLabel":"enum\u003cstring>"},"message":{"type":"string","description":"⚠️ PROSE FOR A DEVELOPER READING A LOG, and NOT part of the contract. It may be reworded in any release; anything that parses it is broken by design.","isRequired":true,"uniqueKey":"error.message","typeLabel":"string"}},"required":["code","message"],"isRequired":true,"uniqueKey":"error","typeLabel":"object"}},"required":["error"],"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"error":{"code":"unauthenticated","message":"\u003cstring>"}}}},"exampleType":"generated"}},"exampleType":"generated"},"b1e75a45-8f19-49e8-8f02-f25b22adc626":{"description":"`not_found` — No such resource — or none this key’s organisation can see, or one that has been archived, or an id that is not a uuid. Those four are one answer on purpose: \"it exists but is not yours\" is itself a disclosure. Do not retry; check the id against the list endpoint.\n\n`template_archived` — The template exists and has been retired. It has a code of its own because a bare 404 tells an integrator whose template was archived yesterday nothing. It carries the same 404 status and it only ever fires for a template their own key could otherwise have read — discoverability without disclosure. Use a live template.","content":{"application/json":{"schema":{"type":"object","description":"The refusal.","properties":{"error":{"type":"object","description":"The refusal. Anything added in future is added INSIDE this object.","properties":{"code":{"type":"string","description":"A stable snake_case identifier that will never change meaning or spelling. This is the contract; branch on it. See `x-error-codes` at the root of this document for retry semantics per code.","enum":["unauthenticated","forbidden","insufficient_scope","not_found","invalid_request","rate_limited","internal_error","service_unavailable","idempotency_key_required","idempotency_key_reused","request_in_progress","template_archived","template_unusable","template_has_no_fields","template_changed","template_document_not_omittable","precondition_required","field_unknown","naming_rule_broken","naming_run_not_ready","naming_run_failed","proposal_changed","decision_not_allowed","witness_is_permanent","recipient_role_unknown","recipient_role_missing","recipient_role_duplicated","recipient_step_partial","step_with_signing_mode","value_subject_unknown","value_address_unknown","value_not_writable","value_option_unknown","value_option_locked","value_selection_out_of_bounds","value_not_lockable","locked_answer_missing","locked_answer_unusable","cannot_be_drawn","send_allowance_exhausted","sms_allowance_exhausted","test_key_cannot_send","test_key_cannot_read_documents","test_key_cannot_edit_templates","document_too_complex","test_key_cannot_mint","test_key_cannot_extend","test_key_cannot_discard","test_key_cannot_void","webhook_url_invalid","webhook_events_invalid","webhook_brand_unknown","webhook_limit_reached","api_key_owner_removed","envelope_sender_removed","recipient_not_embedded","recipient_not_yet_turn","recipient_cannot_sign","envelope_not_sent","deadline_not_extendable","envelope_not_draft","brand_has_no_embed_origins","embed_origin_not_registered","recipient_cannot_be_embedded","recipient_verification_unavailable","recipient_mobile_unused","recipient_mobile_required","recipient_mobile_invalid","recipient_mobile_unsupported_country","recipient_verification_not_allowed","identity_check_requires_paid_plan","identity_check_not_live","recipient_identity_check_not_allowed","recipient_identity_routes_invalid","recipient_expected_id_invalid","batch_interrupted","brand_unknown","brand_is_archived","embed_origin_limit_reached","test_key_cannot_edit_brands","draft_not_available","standing_authorisations_not_enabled","authorisation_text_rejected","authorisation_validity_invalid","authorisation_not_revocable","authorisation_not_pending","authorisation_resend_limited","authorisation_not_renewable","authorisation_already_renewed","authorisation_unknown","authorisation_not_granted","authorisation_revoked","authorisation_expired","authorisation_not_yet_valid","authorisation_invalidated","authorisation_brand_mismatch","authorisation_environment_mismatch","authorisation_role_is_witness","authorisation_role_not_signing","authorisation_recipient_altered","authorisation_used_twice","authorisation_grantor_twice","authorisation_field_unsupported","authorisation_value_forbidden","value_for_left_out_role","authorisation_value_missing","authorisation_value_unlocked","authorisation_mark_too_small","authorisation_mark_unplaced","authorisation_mark_unavailable","authorisation_expires_during_batch"],"isRequired":true,"uniqueKey":"error.code","typeLabel":"enum\u003cstring>"},"message":{"type":"string","description":"⚠️ PROSE FOR A DEVELOPER READING A LOG, and NOT part of the contract. It may be reworded in any release; anything that parses it is broken by design.","isRequired":true,"uniqueKey":"error.message","typeLabel":"string"}},"required":["code","message"],"isRequired":true,"uniqueKey":"error","typeLabel":"object"}},"required":["error"],"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"error":{"code":"unauthenticated","message":"\u003cstring>"}}}},"exampleType":"generated"}},"exampleType":"generated"},"8e549848-2046-40b9-a79d-663db51fc6cc":{"description":"`idempotency_key_reused` — This key was already used for a DIFFERENT request. ⚠️ The request itself may be perfectly valid — what conflicts is the key against state we already hold, which is what 409 means and why it is not a 400. Mint a new key. Do not retry with this one; it will conflict forever.\n\n`request_in_progress` — A request carrying this key has not finished. We deliberately do not block waiting for it — that would hold a connection across a send that calls an email provider N times. Retry the identical request; when the first one lands you will get its result, replayed.","content":{"application/json":{"schema":{"type":"object","description":"The refusal.","properties":{"error":{"type":"object","description":"The refusal. Anything added in future is added INSIDE this object.","properties":{"code":{"type":"string","description":"A stable snake_case identifier that will never change meaning or spelling. This is the contract; branch on it. See `x-error-codes` at the root of this document for retry semantics per code.","enum":["unauthenticated","forbidden","insufficient_scope","not_found","invalid_request","rate_limited","internal_error","service_unavailable","idempotency_key_required","idempotency_key_reused","request_in_progress","template_archived","template_unusable","template_has_no_fields","template_changed","template_document_not_omittable","precondition_required","field_unknown","naming_rule_broken","naming_run_not_ready","naming_run_failed","proposal_changed","decision_not_allowed","witness_is_permanent","recipient_role_unknown","recipient_role_missing","recipient_role_duplicated","recipient_step_partial","step_with_signing_mode","value_subject_unknown","value_address_unknown","value_not_writable","value_option_unknown","value_option_locked","value_selection_out_of_bounds","value_not_lockable","locked_answer_missing","locked_answer_unusable","cannot_be_drawn","send_allowance_exhausted","sms_allowance_exhausted","test_key_cannot_send","test_key_cannot_read_documents","test_key_cannot_edit_templates","document_too_complex","test_key_cannot_mint","test_key_cannot_extend","test_key_cannot_discard","test_key_cannot_void","webhook_url_invalid","webhook_events_invalid","webhook_brand_unknown","webhook_limit_reached","api_key_owner_removed","envelope_sender_removed","recipient_not_embedded","recipient_not_yet_turn","recipient_cannot_sign","envelope_not_sent","deadline_not_extendable","envelope_not_draft","brand_has_no_embed_origins","embed_origin_not_registered","recipient_cannot_be_embedded","recipient_verification_unavailable","recipient_mobile_unused","recipient_mobile_required","recipient_mobile_invalid","recipient_mobile_unsupported_country","recipient_verification_not_allowed","identity_check_requires_paid_plan","identity_check_not_live","recipient_identity_check_not_allowed","recipient_identity_routes_invalid","recipient_expected_id_invalid","batch_interrupted","brand_unknown","brand_is_archived","embed_origin_limit_reached","test_key_cannot_edit_brands","draft_not_available","standing_authorisations_not_enabled","authorisation_text_rejected","authorisation_validity_invalid","authorisation_not_revocable","authorisation_not_pending","authorisation_resend_limited","authorisation_not_renewable","authorisation_already_renewed","authorisation_unknown","authorisation_not_granted","authorisation_revoked","authorisation_expired","authorisation_not_yet_valid","authorisation_invalidated","authorisation_brand_mismatch","authorisation_environment_mismatch","authorisation_role_is_witness","authorisation_role_not_signing","authorisation_recipient_altered","authorisation_used_twice","authorisation_grantor_twice","authorisation_field_unsupported","authorisation_value_forbidden","value_for_left_out_role","authorisation_value_missing","authorisation_value_unlocked","authorisation_mark_too_small","authorisation_mark_unplaced","authorisation_mark_unavailable","authorisation_expires_during_batch"],"isRequired":true,"uniqueKey":"error.code","typeLabel":"enum\u003cstring>"},"message":{"type":"string","description":"⚠️ PROSE FOR A DEVELOPER READING A LOG, and NOT part of the contract. It may be reworded in any release; anything that parses it is broken by design.","isRequired":true,"uniqueKey":"error.message","typeLabel":"string"}},"required":["code","message"],"isRequired":true,"uniqueKey":"error","typeLabel":"object"}},"required":["error"],"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"error":{"code":"unauthenticated","message":"\u003cstring>"}}}},"exampleType":"generated"}},"exampleType":"generated"},"3b30130b-4193-480c-a7b7-d7d6324ab24b":{"description":"`template_changed` — The template is not the version you checked: the `If-Match` on a rename, or the `template_etag` on an envelope create, names an etag that is no longer current, or `documents` on an envelope create names a template document the template does not hold. Nothing was written or created. Read the template again (`GET /api/v1/templates/{templateId}`; a rename’s refusal also carries the current `ETag`), look at what changed — a rename can swap which box an address fills, and its `documents` lists the ids it holds now — and send again with the new etag or ids.","content":{"application/json":{"schema":{"type":"object","description":"The refusal.","properties":{"error":{"type":"object","description":"The refusal. Anything added in future is added INSIDE this object.","properties":{"code":{"type":"string","description":"A stable snake_case identifier that will never change meaning or spelling. This is the contract; branch on it. See `x-error-codes` at the root of this document for retry semantics per code.","enum":["unauthenticated","forbidden","insufficient_scope","not_found","invalid_request","rate_limited","internal_error","service_unavailable","idempotency_key_required","idempotency_key_reused","request_in_progress","template_archived","template_unusable","template_has_no_fields","template_changed","template_document_not_omittable","precondition_required","field_unknown","naming_rule_broken","naming_run_not_ready","naming_run_failed","proposal_changed","decision_not_allowed","witness_is_permanent","recipient_role_unknown","recipient_role_missing","recipient_role_duplicated","recipient_step_partial","step_with_signing_mode","value_subject_unknown","value_address_unknown","value_not_writable","value_option_unknown","value_option_locked","value_selection_out_of_bounds","value_not_lockable","locked_answer_missing","locked_answer_unusable","cannot_be_drawn","send_allowance_exhausted","sms_allowance_exhausted","test_key_cannot_send","test_key_cannot_read_documents","test_key_cannot_edit_templates","document_too_complex","test_key_cannot_mint","test_key_cannot_extend","test_key_cannot_discard","test_key_cannot_void","webhook_url_invalid","webhook_events_invalid","webhook_brand_unknown","webhook_limit_reached","api_key_owner_removed","envelope_sender_removed","recipient_not_embedded","recipient_not_yet_turn","recipient_cannot_sign","envelope_not_sent","deadline_not_extendable","envelope_not_draft","brand_has_no_embed_origins","embed_origin_not_registered","recipient_cannot_be_embedded","recipient_verification_unavailable","recipient_mobile_unused","recipient_mobile_required","recipient_mobile_invalid","recipient_mobile_unsupported_country","recipient_verification_not_allowed","identity_check_requires_paid_plan","identity_check_not_live","recipient_identity_check_not_allowed","recipient_identity_routes_invalid","recipient_expected_id_invalid","batch_interrupted","brand_unknown","brand_is_archived","embed_origin_limit_reached","test_key_cannot_edit_brands","draft_not_available","standing_authorisations_not_enabled","authorisation_text_rejected","authorisation_validity_invalid","authorisation_not_revocable","authorisation_not_pending","authorisation_resend_limited","authorisation_not_renewable","authorisation_already_renewed","authorisation_unknown","authorisation_not_granted","authorisation_revoked","authorisation_expired","authorisation_not_yet_valid","authorisation_invalidated","authorisation_brand_mismatch","authorisation_environment_mismatch","authorisation_role_is_witness","authorisation_role_not_signing","authorisation_recipient_altered","authorisation_used_twice","authorisation_grantor_twice","authorisation_field_unsupported","authorisation_value_forbidden","value_for_left_out_role","authorisation_value_missing","authorisation_value_unlocked","authorisation_mark_too_small","authorisation_mark_unplaced","authorisation_mark_unavailable","authorisation_expires_during_batch"],"isRequired":true,"uniqueKey":"error.code","typeLabel":"enum\u003cstring>"},"message":{"type":"string","description":"⚠️ PROSE FOR A DEVELOPER READING A LOG, and NOT part of the contract. It may be reworded in any release; anything that parses it is broken by design.","isRequired":true,"uniqueKey":"error.message","typeLabel":"string"}},"required":["code","message"],"isRequired":true,"uniqueKey":"error","typeLabel":"object"}},"required":["error"],"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"error":{"code":"unauthenticated","message":"\u003cstring>"}}}},"exampleType":"generated"}},"exampleType":"generated"},"1ff42552-5f12-4a1c-9834-df663249ba7c":{"description":"`authorisation_unknown` — The `authorisation_id` names no standing authorisation of your organisation. A test key cannot see a live authorisation and gets this answer for one: apply a sandbox authorisation with a test key, and a live one with a live key.\n\n`authorisation_not_granted` — The authorisation was never in force: it is still `invited`, or it was declined, lapsed unsigned or was cancelled. Wait for `authorisation.granted`, or request a new one.\n\n`authorisation_revoked` — The authorisation has been revoked. Documents already sent under it keep the signature applied when they were sent; this one cannot be pre-signed. Name another authorisation, or have a person sign the role.\n\n`authorisation_expired` — The authorisation’s `valid_until` has passed, by the database’s clock, whatever its status last said. Renewal is a new mandate: request one.\n\n`authorisation_not_yet_valid` — The authorisation runs from a `valid_from` that has not yet arrived. Send the document after it does.\n\n`authorisation_invalidated` — The authorisation ended because its brand’s name, email display name or logo changed, or the brand was archived, after it was granted. This is final: request a new mandate under the brand as it is now.\n\n`authorisation_brand_mismatch` — The document goes out under a different brand from the authorisation’s, or under no brand. Send `brand_id` naming the authorisation’s brand on every create, batch and one-off.\n\n`authorisation_environment_mismatch` — A live document names a sandbox authorisation. A sandbox authorisation pre-signs only sandbox documents (made with a test key), and a live one only live documents.\n\n`authorisation_role_is_witness` — The role witnesses a signature: the template marks it `witness`, or its name contains “witness” or “getuie” anywhere, in any case. A standing authorisation pre-signs a witness role only when its mandate was requested with `witness: true` AND witness use is enabled for this environment of your organisation; the message says which is missing. Have a person sign that role, or use an authorisation granted for witness use.\n\n`authorisation_role_not_signing` — The role approves or is copied in, so there is nothing to pre-sign. Name the authorisation on a role that signs.\n\n`authorisation_recipient_altered` — The pre-signed recipient on this draft no longer matches its authorisation’s grantor, so it was edited after it was named. Name the authorisation on the role again rather than editing the recipient.\n\n`authorisation_used_twice` — The same authorisation is named on more than one role of one document. One authorisation pre-signs one role per document; two roles need two authorisations, held by two people.\n\n`authorisation_grantor_twice` — One person would sign the document twice. Either two different authorisations on one document have the same grantor: one person’s signature may cover one role per document, so name one of them and have the person sign the other capacity themselves. Or a witness role is pre-signed under an authorisation whose grantor is also a recipient who signs or approves any document of the envelope: nobody witnesses their own signature, so have someone else sign that recipient’s role, or a different person witness.\n\n`authorisation_field_unsupported` — The pre-signed role carries a field it cannot: an initial, an attachment, an `email` tag (it would print the grantor’s address on the document), or a field that shows or hides depending on another answer or on who the document is about. Remove it from the role.\n\n`authorisation_value_forbidden` — A value was supplied for the pre-signed role’s title or company. Vumasign fills both from the authorisation (the capacity signed on the mandate, and the legal entity). Leave them out of `values`.\n\n`authorisation_value_missing` — A required text, date, checkbox or dropdown field of the pre-signed role has no value. Supply each one in `values` with `\"locked\": true`: a mandate applies a signature and never chooses an answer. An optional one you leave out is sealed blank. A one-off takes no values, so every required field of its pre-signed role must be one Vumasign fills.\n\n`authorisation_value_unlocked` — A value for the pre-signed role was supplied without `\"locked\": true`. Send it again locked.\n\n`authorisation_mark_too_small` — A signature box of the pre-signed role is too small to carry its caption, the authorisation's number (“SA-0012”), beside a signature. The number stands on the frame's bottom rule after the envelope reference where the box is wide enough, and under the frame where it is not. Make the box larger: a party role's box needs at least 76.32 by 18.88pt (beside the envelope reference) or 39.44 by 20.85pt (under the frame, on one line); a witness role's, whose caption is “SA-0012 · not present”, needs at least 109.11 by 19.02pt (beside the envelope reference), 72.24 by 20.85pt (under the frame, on one line), 48.16 by 26.10pt (under the frame, on two lines) or 42.22 by 31.35pt (under the frame, on three lines). Each digit of the number past four adds at most 3.003pt of width.\n\n`authorisation_mark_unplaced` — The pre-signed role has no signature box on the document, so its signature and the caption that says it was applied under a standing authorisation would appear nowhere on the page. Give the role a signature tag, or let a person sign it.\n\n`template_unusable` — The template cannot produce an envelope at all. The message says which way.\n\n`template_has_no_fields` — There are no fields, so the envelope would ask nobody to do anything. From a template — creating an envelope, a batch, or sending a draft made from one — place at least one field on the template in the editor; a template made from a document with text tags arrives with them already placed. On `POST /api/v1/envelopes/one-off`, which has no template and no editor, fields come only from text tags in the documents you send, and this is refused only when none of them places a field — an untagged annexure beside a tagged document is fine. Add a tag such as `\u003c\u003csig:Employee>>`, naming a recipient’s `role`, to any of them and send it again. Nothing is detected there, and the body has no property for placing a field. A batch refuses every row for this, because every row shares the template.\n\n`template_document_not_omittable` — `documents` on an envelope create left out a template document (`\"include\": false`) that the envelope cannot do without: it holds the last signature box a required role is sure to sign (and no attachment gives the role another), a box about a subject, a box that shows or hides a box on a document you kept, some options of a question a kept document also asks, or every box of a role you named a recipient for — or every template document was left out. The message names the document and the reason, and what would let it go where something would: leaving the recipient out, or an attachment tagged with the role’s signature. Otherwise keep it, or change the template; resending the same request fails the same way. Nothing was created.\n\n`recipient_role_unknown` — A recipient names a role the template does not declare. Read the roles from `GET /api/v1/templates/{templateId}` — they are matched by NAME, exactly, because a positional address breaks when a sender reorders.\n\n`recipient_role_missing` — A required role that has fields on it was given nobody to fill them. Every required role the template declares with work to do needs a recipient; an optional role (`Role.presence`) may be left out, and is, with its fields. From a send, it also means somebody who signs or approves on a draft prepared in the dashboard has no name or email yet (their `name` or `email` reads `null`): add them in the dashboard first.\n\n`recipient_role_duplicated` — Two recipients were given one role that the template does not route as `cc`. Everyone on a role is served the same fields and every one of them must sign, so both would answer the same boxes and the completed envelope could never be sealed. Give each person a role of their own; several `cc` readers may share a role. Answered by the create endpoints, naming each `recipients[i].role` that holds the role, and by the send endpoint for a draft saved before this was refused.\n\n`recipient_step_partial` — Some recipients carry a `step` and some do not. Give a `step` to every recipient, or to none and let the array decide; a missing step is never guessed. The message names a recipient with one and a recipient without.\n\n`value_subject_unknown` — A value names a subject the template does not declare. The subjects are in the template response; `null` is the subject for a field belonging to nobody in particular.\n\n`value_address_unknown` — The `(subject, key)` pair addresses no field of this template. ⚠️ This is the refusal that most often means the template has UNADDRESSED boxes rather than that you mistyped: `data_key` is null on any field the sender never gave an address to. Check the template response before blaming the value.\n\n`value_option_unknown` — A value for a question names an option it does not have. The message lists the question’s options as `{value, label}`; send one of those values (`options[].value` on the question in `GET /api/v1/templates/{templateId}`). On a rename, an `option_value` outside the options a core `choice` key fixes. Nothing was created or renamed.\n\n`value_option_locked` — A value for a question disagrees with an option the template locks (`questions[].options[].locked` in `GET /api/v1/templates/{templateId}`). Either it names an option locked `cleared`, which the sent document leaves unticked whatever a value says; or it leaves out an option locked `ticked`, which the document ticks anyway, and with it the question would tick more than `max_selected`. A locked-ticked option left out is otherwise added for you. The message names the option and says what to send: every option locked `ticked`, none locked `cleared`, and open options within the bounds. Not raised for an entry that sets `locked`, which replaces the template’s locks on every box. Nothing was created.\n\n`value_selection_out_of_bounds` — A value for a question ticks fewer options than its `min_selected` or more than its `max_selected`, counting every option the template locks `ticked` whether the value names it or not. The message states the bounds and the count. Send an array of option values within them — `[]` for none, where `min_selected` is 0.\n\n`value_not_writable` — The value cannot be written at this address. A field there is one nobody may fill in — a `date_signed`, a `signer_name`, a signature: those are written by the server or by the signer. Or a dropdown there does not offer the value. Or a lone tickbox there is given something other than `\"true\"`, `\"false\"` or `\"\"`. Or the value is an array, which only a question takes. Or, on a rename, a key is given to a field nobody may prefill.\n\n`value_for_left_out_role` — A value was supplied for a field of an optional role the request gives nobody. That role is left out when the envelope is sent, and its fields are removed with it, so the value would land nowhere. Give the role a recipient, or leave its fields out of `values`.\n\n`value_not_lockable` — The address names a `signer_title` or a `signer_company`, and `locked` cannot ride on a value for one. ⚠️ THE VALUE ITSELF IS FINE — send the same triple without `locked` and it is accepted. What is refused is FIXING the answer on the field: a title is a fact about whoever fills the slot, so it is seeded per recipient from the `job_title` and `company` you give on the recipient, while a locked answer is one value on one box — assert it and every party holding that role signs under the same title. Set `job_title` / `company` on each recipient instead. (A sender may still tick “Signer cannot change” on such a field in the editor: there the lock says *the roster’s value is final* and carries no answer of its own.)\n\n`locked_answer_missing` — A field on this envelope is locked, required and carries no answer — three statements that cannot all be honoured. A locked answer is the sender’s, so the signer is refused if they supply one and the completeness check does not ask them for it; once sent, nobody could fill the box and it would seal blank. ⚠️ THE LOCK MAY NOT HAVE COME FROM YOUR REQUEST — it can be authored on the template — so the message names the FIELD rather than a `values[i]` path. Send a value for that address, send `{\"value\": \"\", \"locked\": false}` to hand it back to the signer, or have the template make it optional. ⚠️ THE SAME CODE ALSO MEANS A QUESTION NOBODY LEFT COULD ANSWER. Grouped tickboxes — a Race or Gender question — are never individually `required`; the question’s own `min_selected` is what makes it compulsory. Lock every option of such a question with no tick in any of them and it asks for more answers than remain within anybody’s reach, which is the same unsatisfiable sentence and refuses the same way. There the message names the QUESTION, and the remedies are to tick one of the locked options, unlock one, or lower the question’s minimum.\n\n`locked_answer_unusable` — A field on this envelope carries a locked answer the field itself will not accept: a value its validation rule rejects, one its input format cannot carry, one longer than the printed cells of a comb or holding a character one of those cells does not accept, a `date` that is not a calendar day, or a dropdown answer that is not among the options it offers. ⚠️ A `date` DRAWN AS PRINTED CELLS IS MEASURED IN ITS OWN SPELLING: it holds the digits its boxes print — `15092026`, not `2026-09-15` — and those digits must still name a day that exists, read in the order the field’s label states (`Date of birth (DD/MM/YYYY)`). ⚠️ THIS IS NOT `locked_answer_missing` — that one is a box with NO answer. This is a box with an answer nobody can use: a locked answer is the sender’s, the signer may not change it, and their very first save would be refused over it on an envelope nobody can edit any more. Refused here so that it is still a draft. ⚠️ THE ANSWER MAY NOT HAVE COME FROM YOUR REQUEST — a lock and its value can be authored on the template, and a rule can be tightened after the answer was fixed — so the message names the FIELD rather than a `values[i]` path. Send a value that satisfies the field, send `{\"locked\": false}` to hand the box back to the signer, or change the rule on the template. ⚠️ THE SAME CODE ALSO MEANS A QUESTION THE SENDER ANSWERED MORE TIMES THAN IT PERMITS, AND THEN NO FIELD RULE IS BROKEN AT ALL. Grouped tickboxes — a Marital status question at `max_selected: 1` — can each carry a perfectly good locked tick while together they assert more than the question allows; every one of them would seal, side by side, on a question that says fewer can be true, and the signer may clear none of them. There the message names the QUESTION rather than a field, and sending a field-valid value resolves nothing because every value already is one. The remedies are to untick one of the locked options, to unlock one so the signer chooses, or to raise the question’s `max_selected`. ⚠️ AND THAT LAST ONE IS NOT SOMETHING YOU CAN SEND: `max_selected` is published by `GET /api/v1/templates/{templateId}` and NO ENDPOINT HERE SETS IT — a question’s bounds are authored on the template, and its `id` is a join key within that response rather than an address this API accepts. ⚠️ A QUESTION IS ANSWERED AT ITS OWN ADDRESS: its boxes have none. Send the option value you mean to the question’s `data_key` — `{\"key\": \"person.marital_status\", \"value\": \"married\", \"locked\": true}` — or an array of option values for a question that takes several, and only those boxes are ticked and locked. If this refusal names a question you sent several options to, send fewer.\n\n`cannot_be_drawn` — A value, a name or a title contains something the sealer cannot draw into the PDF, or a value has more characters than the printed boxes of a field split across several sets of them (`Field.continuations`). Asked BEFORE the send rather than discovered after everybody has signed. The message names which string, or for a split field which boxes, and never quotes the value.\n\n`brand_unknown` — `brand_id` names no live brand of your organisation — it may belong to another account, or have been archived. Read the ids from Settings, or omit the field to send under the default. ⚠️ IT IS REFUSED RATHER THAN IGNORED because the branding an envelope went out under is frozen the moment it is sent: a wrong constant would put somebody else’s letterhead on every envelope you send, permanently, and nothing else would say so. (The product’s own send screen falls through to the default instead, because there the id came from a list a person was shown rather than from a program.)\n\n`brand_has_no_embed_origins` — The brand has no embedding origins registered, so a signing URL for it could not be framed by anything — and an embedded recipient is never emailed, so they would be unreachable. Register the domains you embed on against that brand in Settings; they must be bare origins (`https://example.com`, no trailing slash and no path). ⚠️ THE BRAND IS THE ONE THE ENVELOPE GOES OUT UNDER — the `brand_id` you sent, or the organisation’s default when you sent none. It is NOT always the default: registering an origin against the default while sending under another brand is the mistake this refusal most often means.\n\n`recipient_cannot_be_embedded` — A recipient was declared `\"embedded\": true` on a role the template routes as `cc`. A copied-in reader is never asked to sign and is never issued a signing credential, so an embedded one could be reached by nothing at all — no email, and no URL. Either drop the flag, or give the role a routing type that signs, in the template editor.\n\n`recipient_mobile_unused` — A recipient carried a `mobile`, and their `verification_method` sends nothing to a mobile number. It is refused rather than dropped, because a number you sent being silently discarded would be a surprise, and rather than stored, because keeping a person’s phone number for no purpose is the thing not to do with it. Leave it out, or send `null`.\n\n`recipient_mobile_required` — A recipient asked for `mobile_code` and carried no `mobile`, so there is nowhere to send the code. Send their South African mobile number. The message names the recipient; nothing was created.\n\n`recipient_mobile_invalid` — A recipient’s `mobile` is not a mobile number a code can be sent to — too short, too long, letters, or a landline, toll-free or share-call number. Send it as `+27821234567`, `27821234567`, `082 123 4567` or `0821234567`. Nothing was created.\n\n`recipient_mobile_unsupported_country` — A recipient’s `mobile` is a valid number outside South Africa. Mobile codes can be sent only to South African (`+27`) mobiles for now. Use `email_code` or `none` for that recipient. Nothing was created.\n\n`recipient_verification_not_allowed` — A recipient was asked for a code they could never be asked for: `email_code` on an embedded recipient, who is never emailed by Vumasign — your application authenticated them — or any code on a role routed as `cc`, a copied-in reader who never opens a signing page. Use `none` for both. In a batch the message names the row, and nothing in the batch was created.\n\n`recipient_identity_check_not_allowed` — `identity_check` on a recipient who cannot take one: a role routed as `cc`, or any row of a batch (an identity check is chosen per signer, one envelope at a time). Use `mobile_code`, or send the envelope on its own. Nothing was created.\n\n`recipient_identity_routes_invalid` — `identity_check.routes` is not `either`, `sa_id` or `passport`, or `identity_check` was sent with a `verification_method` other than `identity_check`. Nothing was created.\n\n`recipient_expected_id_invalid` — `identity_check.expected_id` cannot be used: an SA ID number that is not 13 digits, fails the checksum, has no real date of birth or a citizenship digit other than 0, 1 or 2; a passport number that is not 5 to 15 letters and digits; a missing or malformed passport country; or a kind `routes` rules out (an SA ID number with `passport`, a passport number with `sa_id`). The number is never quoted back. Nothing was created.\n\n`document_too_complex` — The document needs more memory or time to read than one document is allowed, what reading it produced is larger than one document may produce, or it could not be read through at all. Every uploaded PDF is read in an isolated service, one document at a time, under a fixed memory limit and a fixed time limit, and this one went past one of them; the message says which. Because nothing else was running there, the same document fails the same way. On an upload (`POST /api/v1/templates`, `POST /api/v1/envelopes/one-off`) nothing was stored or created; printing the document to a new PDF usually makes it simpler. On `GET /api/v1/documents/{documentId}/pages/{pageNumber}` or `.../content`, the document was stored before uploads were checked this way and its viewing copy cannot be made; the template, with every field and its position, is still readable from `GET /api/v1/templates/{templateId}`. Retrying gives the same answer.","content":{"application/json":{"schema":{"type":"object","description":"The refusal.","properties":{"error":{"type":"object","description":"The refusal. Anything added in future is added INSIDE this object.","properties":{"code":{"type":"string","description":"A stable snake_case identifier that will never change meaning or spelling. This is the contract; branch on it. See `x-error-codes` at the root of this document for retry semantics per code.","enum":["unauthenticated","forbidden","insufficient_scope","not_found","invalid_request","rate_limited","internal_error","service_unavailable","idempotency_key_required","idempotency_key_reused","request_in_progress","template_archived","template_unusable","template_has_no_fields","template_changed","template_document_not_omittable","precondition_required","field_unknown","naming_rule_broken","naming_run_not_ready","naming_run_failed","proposal_changed","decision_not_allowed","witness_is_permanent","recipient_role_unknown","recipient_role_missing","recipient_role_duplicated","recipient_step_partial","step_with_signing_mode","value_subject_unknown","value_address_unknown","value_not_writable","value_option_unknown","value_option_locked","value_selection_out_of_bounds","value_not_lockable","locked_answer_missing","locked_answer_unusable","cannot_be_drawn","send_allowance_exhausted","sms_allowance_exhausted","test_key_cannot_send","test_key_cannot_read_documents","test_key_cannot_edit_templates","document_too_complex","test_key_cannot_mint","test_key_cannot_extend","test_key_cannot_discard","test_key_cannot_void","webhook_url_invalid","webhook_events_invalid","webhook_brand_unknown","webhook_limit_reached","api_key_owner_removed","envelope_sender_removed","recipient_not_embedded","recipient_not_yet_turn","recipient_cannot_sign","envelope_not_sent","deadline_not_extendable","envelope_not_draft","brand_has_no_embed_origins","embed_origin_not_registered","recipient_cannot_be_embedded","recipient_verification_unavailable","recipient_mobile_unused","recipient_mobile_required","recipient_mobile_invalid","recipient_mobile_unsupported_country","recipient_verification_not_allowed","identity_check_requires_paid_plan","identity_check_not_live","recipient_identity_check_not_allowed","recipient_identity_routes_invalid","recipient_expected_id_invalid","batch_interrupted","brand_unknown","brand_is_archived","embed_origin_limit_reached","test_key_cannot_edit_brands","draft_not_available","standing_authorisations_not_enabled","authorisation_text_rejected","authorisation_validity_invalid","authorisation_not_revocable","authorisation_not_pending","authorisation_resend_limited","authorisation_not_renewable","authorisation_already_renewed","authorisation_unknown","authorisation_not_granted","authorisation_revoked","authorisation_expired","authorisation_not_yet_valid","authorisation_invalidated","authorisation_brand_mismatch","authorisation_environment_mismatch","authorisation_role_is_witness","authorisation_role_not_signing","authorisation_recipient_altered","authorisation_used_twice","authorisation_grantor_twice","authorisation_field_unsupported","authorisation_value_forbidden","value_for_left_out_role","authorisation_value_missing","authorisation_value_unlocked","authorisation_mark_too_small","authorisation_mark_unplaced","authorisation_mark_unavailable","authorisation_expires_during_batch"],"isRequired":true,"uniqueKey":"error.code","typeLabel":"enum\u003cstring>"},"message":{"type":"string","description":"⚠️ PROSE FOR A DEVELOPER READING A LOG, and NOT part of the contract. It may be reworded in any release; anything that parses it is broken by design.","isRequired":true,"uniqueKey":"error.message","typeLabel":"string"}},"required":["code","message"],"isRequired":true,"uniqueKey":"error","typeLabel":"object"}},"required":["error"],"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"error":{"code":"unauthenticated","message":"\u003cstring>"}}}},"exampleType":"generated"}},"exampleType":"generated"},"bbdc509f-f9fb-4854-a393-2f5554cd9880":{"description":"`rate_limited` — This key has spent its minute. The limit is per KEY and per minute, and it follows your PLAN rather than the kind of key — 600 requests a minute on every paid plan, 60 on the free plan, and the sandbox gets the same number as production so that an integration which passes in rehearsal passes live. Every successful authenticated response, and this one, carries `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (seconds), so a client can slow down before it is made to. THREE OPERATIONS ALSO ANSWER IT FOR A REASON OF THEIR OWN. `POST /api/v1/envelopes/batches` costs one request per row and is refused WHOLE when its rows do not fit what is left of the key’s minute — `RateLimit-Remaining` says how many would. `GET /api/v1/envelopes/{envelopeId}/documents/{position}/draft` has its own per-envelope and per-organisation ceilings on renders each minute, and the `message` says which one refused; `POST /api/v1/templates/{templateId}/preview` shares the per-organisation one. There `Retry-After` is that ceiling’s, while the `RateLimit-*` headers still describe the key. `Retry-After` on this refusal is at most 60 and is read from the stored window rather than computed, so two of our instances refusing the same key quote the same instant. ⚠️ A REFUSED REQUEST STILL COUNTS: hammering a limit you have already exceeded pushes the counter higher rather than holding it. Honour `Retry-After`. If one key genuinely needs more throughput, issue a second one in Settings — the ceiling is a fairness and blast-radius control, not a commercial meter.","content":{"application/json":{"schema":{"type":"object","description":"The refusal.","properties":{"error":{"type":"object","description":"The refusal. Anything added in future is added INSIDE this object.","properties":{"code":{"type":"string","description":"A stable snake_case identifier that will never change meaning or spelling. This is the contract; branch on it. See `x-error-codes` at the root of this document for retry semantics per code.","enum":["unauthenticated","forbidden","insufficient_scope","not_found","invalid_request","rate_limited","internal_error","service_unavailable","idempotency_key_required","idempotency_key_reused","request_in_progress","template_archived","template_unusable","template_has_no_fields","template_changed","template_document_not_omittable","precondition_required","field_unknown","naming_rule_broken","naming_run_not_ready","naming_run_failed","proposal_changed","decision_not_allowed","witness_is_permanent","recipient_role_unknown","recipient_role_missing","recipient_role_duplicated","recipient_step_partial","step_with_signing_mode","value_subject_unknown","value_address_unknown","value_not_writable","value_option_unknown","value_option_locked","value_selection_out_of_bounds","value_not_lockable","locked_answer_missing","locked_answer_unusable","cannot_be_drawn","send_allowance_exhausted","sms_allowance_exhausted","test_key_cannot_send","test_key_cannot_read_documents","test_key_cannot_edit_templates","document_too_complex","test_key_cannot_mint","test_key_cannot_extend","test_key_cannot_discard","test_key_cannot_void","webhook_url_invalid","webhook_events_invalid","webhook_brand_unknown","webhook_limit_reached","api_key_owner_removed","envelope_sender_removed","recipient_not_embedded","recipient_not_yet_turn","recipient_cannot_sign","envelope_not_sent","deadline_not_extendable","envelope_not_draft","brand_has_no_embed_origins","embed_origin_not_registered","recipient_cannot_be_embedded","recipient_verification_unavailable","recipient_mobile_unused","recipient_mobile_required","recipient_mobile_invalid","recipient_mobile_unsupported_country","recipient_verification_not_allowed","identity_check_requires_paid_plan","identity_check_not_live","recipient_identity_check_not_allowed","recipient_identity_routes_invalid","recipient_expected_id_invalid","batch_interrupted","brand_unknown","brand_is_archived","embed_origin_limit_reached","test_key_cannot_edit_brands","draft_not_available","standing_authorisations_not_enabled","authorisation_text_rejected","authorisation_validity_invalid","authorisation_not_revocable","authorisation_not_pending","authorisation_resend_limited","authorisation_not_renewable","authorisation_already_renewed","authorisation_unknown","authorisation_not_granted","authorisation_revoked","authorisation_expired","authorisation_not_yet_valid","authorisation_invalidated","authorisation_brand_mismatch","authorisation_environment_mismatch","authorisation_role_is_witness","authorisation_role_not_signing","authorisation_recipient_altered","authorisation_used_twice","authorisation_grantor_twice","authorisation_field_unsupported","authorisation_value_forbidden","value_for_left_out_role","authorisation_value_missing","authorisation_value_unlocked","authorisation_mark_too_small","authorisation_mark_unplaced","authorisation_mark_unavailable","authorisation_expires_during_batch"],"isRequired":true,"uniqueKey":"error.code","typeLabel":"enum\u003cstring>"},"message":{"type":"string","description":"⚠️ PROSE FOR A DEVELOPER READING A LOG, and NOT part of the contract. It may be reworded in any release; anything that parses it is broken by design.","isRequired":true,"uniqueKey":"error.message","typeLabel":"string"}},"required":["code","message"],"isRequired":true,"uniqueKey":"error","typeLabel":"object"}},"required":["error"],"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"error":{"code":"unauthenticated","message":"\u003cstring>"}}}},"exampleType":"generated"}},"headers":{"RateLimit-Limit":{"description":"How many requests this key may make per minute: 600 on any paid plan and 60 on the free plan, the same in both environments. Per key, not per organisation — a second key has its own allowance. ⚠️ READ IT RATHER THAN ASSUMING IT: it is the number the database applied to this request, so it is right even when this description is out of date.","schema":{"type":"integer","description":"Requests permitted in the current minute."}},"RateLimit-Remaining":{"description":"How many of them are left, this one already counted. Zero on the request that is refused, and zero on every further request of that minute — ⚠️ a refused request still counts.","schema":{"type":"integer","description":"Requests remaining in the current minute."}},"RateLimit-Reset":{"description":"Seconds until the current minute closes and the allowance returns. At most 60, which is what makes the published exponential backoff converge in about six doublings rather than eleven.","schema":{"type":"integer","description":"Seconds until the window resets."}},"Retry-After":{"description":"Seconds to wait before retrying, from the stored end of the window. Always present on a 429, and never more than 60. On the per-key limit it equals `RateLimit-Reset`; a narrower limit, such as the draft render allowance, has a window of its own and may ask for a different wait. `x-error-codes` tells you to honour it; this is it.","schema":{"type":"integer","description":"Seconds to wait before retrying."}}},"exampleType":"generated"},"a31ecc7d-a4c5-45e9-acfb-30adcf25cd48":{"description":"`internal_error` — Ours, not yours. ⚠️ RETRY WITH THE SAME `Idempotency-Key` YOU SENT THE FIRST TIME, on any operation that takes one — that is what makes a retry safe here, and sending a NEW key would create a second envelope or send the same one twice. The safe GETs in this document can be retried freely. (This entry used to say every operation here was a GET; the write endpoints have since shipped, and the reasoning moved with them.)\n\n`internal_error` — Ours, not yours. ⚠️ RETRY WITH THE SAME `Idempotency-Key` YOU SENT THE FIRST TIME, on any operation that takes one — that is what makes a retry safe here, and sending a NEW key would create a second envelope or send the same one twice. The safe GETs in this document can be retried freely. (This entry used to say every operation here was a GET; the write endpoints have since shipped, and the reasoning moved with them.)","content":{"application/json":{"schema":{"type":"object","description":"The refusal.","properties":{"error":{"type":"object","description":"The refusal. Anything added in future is added INSIDE this object.","properties":{"code":{"type":"string","description":"A stable snake_case identifier that will never change meaning or spelling. This is the contract; branch on it. See `x-error-codes` at the root of this document for retry semantics per code.","enum":["unauthenticated","forbidden","insufficient_scope","not_found","invalid_request","rate_limited","internal_error","service_unavailable","idempotency_key_required","idempotency_key_reused","request_in_progress","template_archived","template_unusable","template_has_no_fields","template_changed","template_document_not_omittable","precondition_required","field_unknown","naming_rule_broken","naming_run_not_ready","naming_run_failed","proposal_changed","decision_not_allowed","witness_is_permanent","recipient_role_unknown","recipient_role_missing","recipient_role_duplicated","recipient_step_partial","step_with_signing_mode","value_subject_unknown","value_address_unknown","value_not_writable","value_option_unknown","value_option_locked","value_selection_out_of_bounds","value_not_lockable","locked_answer_missing","locked_answer_unusable","cannot_be_drawn","send_allowance_exhausted","sms_allowance_exhausted","test_key_cannot_send","test_key_cannot_read_documents","test_key_cannot_edit_templates","document_too_complex","test_key_cannot_mint","test_key_cannot_extend","test_key_cannot_discard","test_key_cannot_void","webhook_url_invalid","webhook_events_invalid","webhook_brand_unknown","webhook_limit_reached","api_key_owner_removed","envelope_sender_removed","recipient_not_embedded","recipient_not_yet_turn","recipient_cannot_sign","envelope_not_sent","deadline_not_extendable","envelope_not_draft","brand_has_no_embed_origins","embed_origin_not_registered","recipient_cannot_be_embedded","recipient_verification_unavailable","recipient_mobile_unused","recipient_mobile_required","recipient_mobile_invalid","recipient_mobile_unsupported_country","recipient_verification_not_allowed","identity_check_requires_paid_plan","identity_check_not_live","recipient_identity_check_not_allowed","recipient_identity_routes_invalid","recipient_expected_id_invalid","batch_interrupted","brand_unknown","brand_is_archived","embed_origin_limit_reached","test_key_cannot_edit_brands","draft_not_available","standing_authorisations_not_enabled","authorisation_text_rejected","authorisation_validity_invalid","authorisation_not_revocable","authorisation_not_pending","authorisation_resend_limited","authorisation_not_renewable","authorisation_already_renewed","authorisation_unknown","authorisation_not_granted","authorisation_revoked","authorisation_expired","authorisation_not_yet_valid","authorisation_invalidated","authorisation_brand_mismatch","authorisation_environment_mismatch","authorisation_role_is_witness","authorisation_role_not_signing","authorisation_recipient_altered","authorisation_used_twice","authorisation_grantor_twice","authorisation_field_unsupported","authorisation_value_forbidden","value_for_left_out_role","authorisation_value_missing","authorisation_value_unlocked","authorisation_mark_too_small","authorisation_mark_unplaced","authorisation_mark_unavailable","authorisation_expires_during_batch"],"isRequired":true,"uniqueKey":"error.code","typeLabel":"enum\u003cstring>"},"message":{"type":"string","description":"⚠️ PROSE FOR A DEVELOPER READING A LOG, and NOT part of the contract. It may be reworded in any release; anything that parses it is broken by design.","isRequired":true,"uniqueKey":"error.message","typeLabel":"string"}},"required":["code","message"],"isRequired":true,"uniqueKey":"error","typeLabel":"object"}},"required":["error"],"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"error":{"code":"unauthenticated","message":"\u003cstring>"}}}},"exampleType":"generated"}},"exampleType":"generated"},"b5e831d4-93bb-4b4b-9ad0-bc8b41d12ebe":{"description":"`authorisation_mark_unavailable` — The grantor’s stored signature could not be read intact, so nothing was applied. A brief storage failure clears on a retry; one that persists means the stored signature no longer matches what was granted, and needs Vumasign.\n\n`service_unavailable` — Ours, and briefly. Something this operation depends on was not answering, or was already doing as much as it will at once. What it was depends on the operation: on a create, the service that renders a Word document to a PDF, or the isolated service every uploaded document is read in, when it is starting up, at capacity, or did not answer in time; on `GET .../documents/{position}/draft` and `POST /api/v1/templates/{templateId}/preview`, the service that renders the draft or the preview itself; on the two template-document reads (`GET /api/v1/documents/{documentId}/pages/{pageNumber}` and `.../content`), that same isolated service, which says so with `Retry-After`. ⚠️ THE DISTINCTION FROM 400 IS THE WHOLE POINT: your request is fine and your document is fine, so do not go and re-save it. On a create, nothing was created and no allowance was spent. On an operation that takes an `Idempotency-Key`, retry the identical request with the SAME one — a completed key replays, so a retry can never make a second envelope or a second template even if the first attempt got further than this answer suggests. A new key could. ⚠️ ON THE DRAFT AND THE PREVIEW THE ATTEMPT WAS ALREADY PAID FOR: the render is charged to the per-minute draft ceilings (the envelope’s and the organisation’s, or the organisation’s alone) before the renderer is asked, and a render that then fails is not refunded. There is no key to reuse, because there is nothing to replay — so retry on the backoff above rather than at once, or an outage of ours becomes a `rate_limited` of yours.","content":{"application/json":{"schema":{"type":"object","description":"The refusal.","properties":{"error":{"type":"object","description":"The refusal. Anything added in future is added INSIDE this object.","properties":{"code":{"type":"string","description":"A stable snake_case identifier that will never change meaning or spelling. This is the contract; branch on it. See `x-error-codes` at the root of this document for retry semantics per code.","enum":["unauthenticated","forbidden","insufficient_scope","not_found","invalid_request","rate_limited","internal_error","service_unavailable","idempotency_key_required","idempotency_key_reused","request_in_progress","template_archived","template_unusable","template_has_no_fields","template_changed","template_document_not_omittable","precondition_required","field_unknown","naming_rule_broken","naming_run_not_ready","naming_run_failed","proposal_changed","decision_not_allowed","witness_is_permanent","recipient_role_unknown","recipient_role_missing","recipient_role_duplicated","recipient_step_partial","step_with_signing_mode","value_subject_unknown","value_address_unknown","value_not_writable","value_option_unknown","value_option_locked","value_selection_out_of_bounds","value_not_lockable","locked_answer_missing","locked_answer_unusable","cannot_be_drawn","send_allowance_exhausted","sms_allowance_exhausted","test_key_cannot_send","test_key_cannot_read_documents","test_key_cannot_edit_templates","document_too_complex","test_key_cannot_mint","test_key_cannot_extend","test_key_cannot_discard","test_key_cannot_void","webhook_url_invalid","webhook_events_invalid","webhook_brand_unknown","webhook_limit_reached","api_key_owner_removed","envelope_sender_removed","recipient_not_embedded","recipient_not_yet_turn","recipient_cannot_sign","envelope_not_sent","deadline_not_extendable","envelope_not_draft","brand_has_no_embed_origins","embed_origin_not_registered","recipient_cannot_be_embedded","recipient_verification_unavailable","recipient_mobile_unused","recipient_mobile_required","recipient_mobile_invalid","recipient_mobile_unsupported_country","recipient_verification_not_allowed","identity_check_requires_paid_plan","identity_check_not_live","recipient_identity_check_not_allowed","recipient_identity_routes_invalid","recipient_expected_id_invalid","batch_interrupted","brand_unknown","brand_is_archived","embed_origin_limit_reached","test_key_cannot_edit_brands","draft_not_available","standing_authorisations_not_enabled","authorisation_text_rejected","authorisation_validity_invalid","authorisation_not_revocable","authorisation_not_pending","authorisation_resend_limited","authorisation_not_renewable","authorisation_already_renewed","authorisation_unknown","authorisation_not_granted","authorisation_revoked","authorisation_expired","authorisation_not_yet_valid","authorisation_invalidated","authorisation_brand_mismatch","authorisation_environment_mismatch","authorisation_role_is_witness","authorisation_role_not_signing","authorisation_recipient_altered","authorisation_used_twice","authorisation_grantor_twice","authorisation_field_unsupported","authorisation_value_forbidden","value_for_left_out_role","authorisation_value_missing","authorisation_value_unlocked","authorisation_mark_too_small","authorisation_mark_unplaced","authorisation_mark_unavailable","authorisation_expires_during_batch"],"isRequired":true,"uniqueKey":"error.code","typeLabel":"enum\u003cstring>"},"message":{"type":"string","description":"⚠️ PROSE FOR A DEVELOPER READING A LOG, and NOT part of the contract. It may be reworded in any release; anything that parses it is broken by design.","isRequired":true,"uniqueKey":"error.message","typeLabel":"string"}},"required":["code","message"],"isRequired":true,"uniqueKey":"error","typeLabel":"object"}},"required":["error"],"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"error":{"code":"unauthenticated","message":"\u003cstring>"}}}},"exampleType":"generated"}},"headers":{"RateLimit-Limit":{"description":"How many requests this key may make per minute: 600 on any paid plan and 60 on the free plan, the same in both environments. Per key, not per organisation — a second key has its own allowance. ⚠️ READ IT RATHER THAN ASSUMING IT: it is the number the database applied to this request, so it is right even when this description is out of date.","schema":{"type":"integer","description":"Requests permitted in the current minute."}},"RateLimit-Remaining":{"description":"How many of them are left, this one already counted. Zero on the request that is refused, and zero on every further request of that minute — ⚠️ a refused request still counts.","schema":{"type":"integer","description":"Requests remaining in the current minute."}},"RateLimit-Reset":{"description":"Seconds until the current minute closes and the allowance returns. At most 60, which is what makes the published exponential backoff converge in about six doublings rather than eleven.","schema":{"type":"integer","description":"Seconds until the window resets."}}},"exampleType":"generated"}},"security":{"c67ebd9b-01c9-4e8b-b656-b871ff4a18fd":{"ApiKey":{"type":"http","scheme":"bearer","description":"`Authorization: Bearer vsk_live_…`. Chosen over a bespoke `X-API-KEY` header because every client, proxy and log-redaction rule already knows this one. What a key may DO is its scopes — see `x-scopes` at the root of this document and `x-required-scope` on each operation. The scope list is not written here because OpenAPI reserves a requirement’s scope array for `oauth2` and `openIdConnect` and requires it to be empty for an `http` scheme.","scopes":[],"schemeName":"ApiKey"}}},"servers":{"2ed67dbf-843b-4ce0-93c8-8c35248fcb3e":{"url":"https://app.vumasign.com"}},"processedSecurityOptions":[{"schemes":[{"scheme":{"type":"http","scheme":"bearer","description":"`Authorization: Bearer vsk_live_…`. Chosen over a bespoke `X-API-KEY` header because every client, proxy and log-redaction rule already knows this one. What a key may DO is its scopes — see `x-scopes` at the root of this document and `x-required-scope` on each operation. The scope list is not written here because OpenAPI reserves a requirement’s scope array for `oauth2` and `openIdConnect` and requires it to be empty for an `http` scheme.","scopes":[],"schemeName":"ApiKey"},"schema":{"title":"Bearer Auth","type":"string","isRequired":true,"description":"`Authorization: Bearer vsk_live_…`. Chosen over a bespoke `X-API-KEY` header because every client, proxy and log-redaction rule already knows this one. What a key may DO is its scopes — see `x-scopes` at the root of this document and `x-required-scope` on each operation. The scope list is not written here because OpenAPI reserves a requirement’s scope array for `oauth2` and `openIdConnect` and requires it to be empty for an `http` scheme.","format":"bearer","typeLabel":"string\u003cbearer>","deprecated":false},"schemeName":"ApiKey","name":"Authorization"}],"title":"ApiKey"}]},"originalFileLocation":"openapi.json"},"subdomain":"vumasign","siteName":"Vumasign","title":"Create an envelope from a template, and optionally send it. - Vumasign","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-11-16T05:07:56.153Z","originalFileLocation":"api-reference/create-envelope.mdx"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"system\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"THE ENDPOINT THAT EMAILS REAL PEOPLE AND SPENDS REAL MONEY, and the reason Idempotency-Key is required rather than optional. ⚠️ A REPLAY RETURNS THE SAME ENVELOPE AND CREATES NOTHING. Send the identical body under the identical key and you receive the first attempt’s answer, byte for byte, with Idempotency-Replayed: true. No second envelope, no second invitation, no second billed envelope. Thatis what makes a timeout safe to retry — and none of the three products this API was designed against offers it. A DIFFERENT BODY UNDER A USED KEY IS idempotency_key_reused, not a replay. A key identifies one request; answering a second one with the first one’s envelope is silent data loss wearing a 201. KEYS ARE REMEMBERED FOR 1 DAY, per organisation and per environment (live and test never answer for one another). Past that the key is forgotten and the same string is a new request. ⚠️ values IS A LIST OF TRIPLES AND ONE OF THEM MAY FILL SEVERAL BOXES. Read GET /api/v1/templates/{templateId} first: it is where the (subject, data_key) pairs come from. DOCUMENTS OF YOUR OWN MAY GO BESIDE THE TEMPLATE’S, in attachments. They follow the template’s documents in the order given, and their fields come from their own text tags, which may name a role the template does not. values fill only the template’s fields. Each recipient is shown the documents their role has fields on and those nobody has fields on, or every document when their role has none. See Attachments. A REFUSAL CREATES NOTHING. Every 4xx below leaves no envelope behind — including a send refused after the draft was built, which is deleted again — and leaves the idempotency key free for a corrected retry.\">\u003cmeta data-mint-head name=\"application-name\" content=\"Vumasign\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/vumasign/AZCH4Km_HnmKVeDU/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/mintlify-assets/_mintlify/favicons/vumasign/AZCH4Km_HnmKVeDU/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/vumasign/AZCH4Km_HnmKVeDU/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/vumasign/AZCH4Km_HnmKVeDU/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/vumasign/AZCH4Km_HnmKVeDU/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/vumasign/AZCH4Km_HnmKVeDU/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/vumasign/AZCH4Km_HnmKVeDU/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/vumasign/AZCH4Km_HnmKVeDU/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/vumasign/AZCH4Km_HnmKVeDU/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"Create an envelope from a template, and optionally send it. - Vumasign\">\u003cmeta data-mint-head property=\"og:description\" content=\"THE ENDPOINT THAT EMAILS REAL PEOPLE AND SPENDS REAL MONEY, and the reason Idempotency-Key is required rather than optional. ⚠️ A REPLAY RETURNS THE SAME ENVELOPE AND CREATES NOTHING. Send the identical body under the identical key and you receive the first attempt’s answer, byte for byte, with Idempotency-Replayed: true. No second envelope, no second invitation, no second billed envelope. Thatis what makes a timeout safe to retry — and none of the three products this API was designed against offers it. A DIFFERENT BODY UNDER A USED KEY IS idempotency_key_reused, not a replay. A key identifies one request; answering a second one with the first one’s envelope is silent data loss wearing a 201. KEYS ARE REMEMBERED FOR 1 DAY, per organisation and per environment (live and test never answer for one another). Past that the key is forgotten and the same string is a new request. ⚠️ values IS A LIST OF TRIPLES AND ONE OF THEM MAY FILL SEVERAL BOXES. Read GET /api/v1/templates/{templateId} first: it is where the (subject, data_key) pairs come from. DOCUMENTS OF YOUR OWN MAY GO BESIDE THE TEMPLATE’S, in attachments. They follow the template’s documents in the order given, and their fields come from their own text tags, which may name a role the template does not. values fill only the template’s fields. Each recipient is shown the documents their role has fields on and those nobody has fields on, or every document when their role has none. See Attachments. A REFUSAL CREATES NOTHING. Every 4xx below leaves no envelope behind — including a send refused after the draft was built, which is deleted again — and leaves the idempotency key free for a corrected retry.\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"Vumasign\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.vumasign.com/api-reference/create-envelope\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://vumasign.mintlify.site/_mintlify/api/og/v2?division=Envelopes\u0026amp;title=Create+an+envelope+from+a+template%2C+and+optionally+send+it.\u0026amp;description=THE+ENDPOINT+THAT+EMAILS+REAL+PEOPLE+AND+SPENDS+REAL+MONEY%2C+and+the+reason+%60Idempotency-Key%60+is+required+rather+than+optional.%0A%0A%E2%9A%A0%EF%B8%8F+A+REPLAY+RETURNS+THE+SAME+ENV\u0026amp;theme=5afaa4abac00f05afdc3c271\u0026amp;signature=f9b626fc4c698a549ab2d252f3dc4873ecdddd512d7cd0f7fcf4e570af49fdaf\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"Create an envelope from a template, and optionally send it. - Vumasign\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"THE ENDPOINT THAT EMAILS REAL PEOPLE AND SPENDS REAL MONEY, and the reason Idempotency-Key is required rather than optional. ⚠️ A REPLAY RETURNS THE SAME ENVELOPE AND CREATES NOTHING. Send the identical body under the identical key and you receive the first attempt’s answer, byte for byte, with Idempotency-Replayed: true. No second envelope, no second invitation, no second billed envelope. Thatis what makes a timeout safe to retry — and none of the three products this API was designed against offers it. A DIFFERENT BODY UNDER A USED KEY IS idempotency_key_reused, not a replay. A key identifies one request; answering a second one with the first one’s envelope is silent data loss wearing a 201. KEYS ARE REMEMBERED FOR 1 DAY, per organisation and per environment (live and test never answer for one another). Past that the key is forgotten and the same string is a new request. ⚠️ values IS A LIST OF TRIPLES AND ONE OF THEM MAY FILL SEVERAL BOXES. Read GET /api/v1/templates/{templateId} first: it is where the (subject, data_key) pairs come from. DOCUMENTS OF YOUR OWN MAY GO BESIDE THE TEMPLATE’S, in attachments. They follow the template’s documents in the order given, and their fields come from their own text tags, which may name a role the template does not. values fill only the template’s fields. Each recipient is shown the documents their role has fields on and those nobody has fields on, or every document when their role has none. See Attachments. A REFUSAL CREATES NOTHING. Every 4xx below leaves no envelope behind — including a send refused after the draft was built, which is deleted again — and leaves the idempotency key free for a corrected retry.\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://vumasign.mintlify.site/_mintlify/api/og/v2?division=Envelopes\u0026amp;title=Create+an+envelope+from+a+template%2C+and+optionally+send+it.\u0026amp;description=THE+ENDPOINT+THAT+EMAILS+REAL+PEOPLE+AND+SPENDS+REAL+MONEY%2C+and+the+reason+%60Idempotency-Key%60+is+required+rather+than+optional.%0A%0A%E2%9A%A0%EF%B8%8F+A+REPLAY+RETURNS+THE+SAME+ENV\u0026amp;theme=5afaa4abac00f05afdc3c271\u0026amp;signature=f9b626fc4c698a549ab2d252f3dc4873ecdddd512d7cd0f7fcf4e570af49fdaf\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"/mintlify-assets/_mintlify/favicons/vumasign/AZCH4Km_HnmKVeDU/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"Vumasign\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#00827B\">\u003clink data-mint-head rel=\"canonical\" href=\"https://docs.vumasign.com/api-reference/create-envelope\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/api-reference/create-envelope.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://docs.vumasign.com/#organization\",\"name\":\"Vumasign\",\"url\":\"https://docs.vumasign.com\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/vumasign/TFhwDypOVkWX-C3j/logo/vumasign.svg?fit=max\u0026auto=format\u0026n=TFhwDypOVkWX-C3j\u0026q=85\u0026s=f5e34bf1faf4c64eaa58dee0553702d6\"}},{\"@type\":\"WebSite\",\"@id\":\"https://docs.vumasign.com#website\",\"name\":\"Vumasign\",\"url\":\"https://docs.vumasign.com\",\"publisher\":{\"@id\":\"https://docs.vumasign.com/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://docs.vumasign.com/api-reference/create-envelope#webpage\",\"url\":\"https://docs.vumasign.com/api-reference/create-envelope\",\"name\":\"Create an envelope from a template, and optionally send it.\",\"description\":\"THE ENDPOINT THAT EMAILS REAL PEOPLE AND SPENDS REAL MONEY, and the reason Idempotency-Key is required rather than optional. ⚠️ A REPLAY RETURNS THE SAME ENVELOPE AND CREATES NOTHING. Send the identical body under the identical key and you receive the first attempt’s answer, byte for byte, with Idempotency-Replayed: true. No second envelope, no second invitation, no second billed envelope. Thatis what makes a timeout safe to retry — and none of the three products this API was designed against offers it. A DIFFERENT BODY UNDER A USED KEY IS idempotency_key_reused, not a replay. A key identifies one request; answering a second one with the first one’s envelope is silent data loss wearing a 201. KEYS ARE REMEMBERED FOR 1 DAY, per organisation and per environment (live and test never answer for one another). Past that the key is forgotten and the same string is a new request. ⚠️ values IS A LIST OF TRIPLES AND ONE OF THEM MAY FILL SEVERAL BOXES. Read GET /api/v1/templates/{templateId} first: it is where the (subject, data_key) pairs come from. DOCUMENTS OF YOUR OWN MAY GO BESIDE THE TEMPLATE’S, in attachments. They follow the template’s documents in the order given, and their fields come from their own text tags, which may name a role the template does not. values fill only the template’s fields. Each recipient is shown the documents their role has fields on and those nobody has fields on, or every document when their role has none. See Attachments. A REFUSAL CREATES NOTHING. Every 4xx below leaves no envelope behind — including a send refused after the draft was built, which is deleted again — and leaves the idempotency key free for a corrected retry.\",\"dateModified\":\"2026-11-16T05:07:56.153Z\",\"isPartOf\":{\"@id\":\"https://docs.vumasign.com#website\"},\"breadcrumb\":{\"@id\":\"https://docs.vumasign.com/api-reference/create-envelope#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.vumasign.com/api-reference/create-envelope#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Envelopes\",\"item\":\"https://docs.vumasign.com/api-reference/list-envelopes\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Create an envelope from a template, and optionally send it.\",\"item\":\"https://docs.vumasign.com/api-reference/create-envelope\"}]},{\"@type\":[\"TechArticle\",\"APIReference\"],\"@id\":\"https://docs.vumasign.com/api-reference/create-envelope#apireference\",\"headline\":\"Create an envelope from a template, and optionally send it.\",\"name\":\"Create an envelope from a template, and optionally send it.\",\"description\":\"THE ENDPOINT THAT EMAILS REAL PEOPLE AND SPENDS REAL MONEY, and the reason Idempotency-Key is required rather than optional. ⚠️ A REPLAY RETURNS THE SAME ENVELOPE AND CREATES NOTHING. Send the identical body under the identical key and you receive the first attempt’s answer, byte for byte, with Idempotency-Replayed: true. No second envelope, no second invitation, no second billed envelope. Thatis what makes a timeout safe to retry — and none of the three products this API was designed against offers it. A DIFFERENT BODY UNDER A USED KEY IS idempotency_key_reused, not a replay. A key identifies one request; answering a second one with the first one’s envelope is silent data loss wearing a 201. KEYS ARE REMEMBERED FOR 1 DAY, per organisation and per environment (live and test never answer for one another). Past that the key is forgotten and the same string is a new request. ⚠️ values IS A LIST OF TRIPLES AND ONE OF THEM MAY FILL SEVERAL BOXES. Read GET /api/v1/templates/{templateId} first: it is where the (subject, data_key) pairs come from. DOCUMENTS OF YOUR OWN MAY GO BESIDE THE TEMPLATE’S, in attachments. They follow the template’s documents in the order given, and their fields come from their own text tags, which may name a role the template does not. values fill only the template’s fields. Each recipient is shown the documents their role has fields on and those nobody has fields on, or every document when their role has none. See Attachments. A REFUSAL CREATES NOTHING. Every 4xx below leaves no envelope behind — including a send refused after the draft was built, which is deleted again — and leaves the idempotency key free for a corrected retry.\",\"url\":\"https://docs.vumasign.com/api-reference/create-envelope\",\"mainEntityOfPage\":{\"@id\":\"https://docs.vumasign.com/api-reference/create-envelope#webpage\"},\"dateModified\":\"2026-11-16T05:07:56.153Z\",\"publisher\":{\"@id\":\"https://docs.vumasign.com/#organization\"},\"isPartOf\":{\"@id\":\"https://docs.vumasign.com#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"Vumasign\",\"publisher\":{\"@type\":\"Organization\",\"name\":\"Vumasign\"},\"provider\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","agentPointerHref":"/api-reference/create-envelope.md","siteName":"Vumasign","nav":{"global":null,"tabs":[{"tab":"Guides","pages":[{"title":"Guides","href":""}]},{"tab":"API reference","groups":[{"group":"Specification","pages":[{"title":"This document, the machine-readable description of the API.","deprecated":null,"version":null,"sidebarTitle":"Get openapi document","openapi":"/openapi.json get /api/v1/openapi.json","href":"/api-reference/get-openapi-document"}]},{"group":"Templates","pages":[{"title":"List live templates, newest first.","deprecated":null,"version":null,"sidebarTitle":"List templates","openapi":"/openapi.json get /api/v1/templates","href":"/api-reference/list-templates"},{"title":"Upload a PDF or a Word document and get a template with its fields already placed.","deprecated":null,"version":null,"sidebarTitle":"Create template","openapi":"/openapi.json post /api/v1/templates","href":"/api-reference/create-template"},{"title":"One template, with every field address on it.","deprecated":null,"version":null,"sidebarTitle":"Get template","openapi":"/openapi.json get /api/v1/templates/{templateId}","href":"/api-reference/get-template"},{"title":"The core vocabulary, and your organisation’s own keys.","deprecated":null,"version":null,"sidebarTitle":"Get vocabulary","openapi":"/openapi.json get /api/v1/vocabulary","href":"/api-reference/get-vocabulary"},{"title":"A template’s field map, as a spreadsheet: one numbered row per field.","deprecated":null,"version":null,"sidebarTitle":"Get template field map","openapi":"/openapi.json get /api/v1/templates/{templateId}/field-map","href":"/api-reference/get-template-field-map"},{"title":"One document of a template with every field outlined and numbered on it, as a PDF.","deprecated":null,"version":null,"sidebarTitle":"Get template document field map","openapi":"/openapi.json get /api/v1/templates/{templateId}/documents/{documentId}/field-map","href":"/api-reference/get-template-document-field-map"},{"title":"Rename a template’s fields and questions: names only, all or nothing.","deprecated":null,"version":null,"sidebarTitle":"Rename template fields","openapi":"/openapi.json patch /api/v1/templates/{templateId}/fields","href":"/api-reference/rename-template-fields"},{"title":"Rename one field of a template.","deprecated":null,"version":null,"sidebarTitle":"Rename template field","openapi":"/openapi.json patch /api/v1/templates/{templateId}/fields/{fieldId}","href":"/api-reference/rename-template-field"},{"title":"Ask Vumasign to name a template’s fields: a naming run, produced in the background.","deprecated":null,"version":null,"sidebarTitle":"Request naming run","openapi":"/openapi.json post /api/v1/templates/{templateId}/naming-runs","href":"/api-reference/request-naming-run"},{"title":"Read a naming run: its status, its proposals with reasons, and the preview.","deprecated":null,"version":null,"sidebarTitle":"Get naming run","openapi":"/openapi.json get /api/v1/templates/{templateId}/naming-runs/{runId}","href":"/api-reference/get-naming-run"},{"title":"Accept a naming run’s proposals, all or some, with your own corrections: all or nothing.","deprecated":null,"version":null,"sidebarTitle":"Accept naming run","openapi":"/openapi.json post /api/v1/templates/{templateId}/naming-runs/{runId}/accept","href":"/api-reference/accept-naming-run"},{"title":"Accept a naming run’s own proposals, if the template has not changed since: no overrides.","deprecated":null,"version":null,"sidebarTitle":"Accept naming run current","openapi":"/openapi.json post /api/v1/templates/{templateId}/naming-runs/{runId}/accept-current","href":"/api-reference/accept-naming-run-current"},{"title":"The people a template is about or signed by, each with a proposed decision.","deprecated":null,"version":null,"sidebarTitle":"List template people","openapi":"/openapi.json get /api/v1/templates/{templateId}/people","href":"/api-reference/list-template-people"},{"title":"Decide one person: a subject for their details, a signing role, both, or a witness.","deprecated":null,"version":null,"sidebarTitle":"Decide template person","openapi":"/openapi.json put /api/v1/templates/{templateId}/people/{personId}","href":"/api-reference/decide-template-person"},{"title":"Apply Vumasign’s own current proposal for one person.","deprecated":null,"version":null,"sidebarTitle":"Accept template person proposal","openapi":"/openapi.json post /api/v1/templates/{templateId}/people/{personId}/accept-proposal","href":"/api-reference/accept-template-person-proposal"},{"title":"What creating an envelope would say about your values, without creating one.","deprecated":null,"version":null,"sidebarTitle":"Validate template values","openapi":"/openapi.json post /api/v1/templates/{templateId}/validate-values","href":"/api-reference/validate-template-values"},{"title":"One of a template’s documents, filled in with your values, as it would be sealed.","deprecated":null,"version":null,"sidebarTitle":"Preview template","openapi":"/openapi.json post /api/v1/templates/{templateId}/preview","href":"/api-reference/preview-template"}]},{"group":"Documents","pages":[{"title":"One page of a document, as a PDF, to look at.","deprecated":null,"version":null,"sidebarTitle":"Get document page","openapi":"/openapi.json get /api/v1/documents/{documentId}/pages/{pageNumber}","href":"/api-reference/get-document-page"},{"title":"A template document, every page, as one PDF.","deprecated":null,"version":null,"sidebarTitle":"Get document content","openapi":"/openapi.json get /api/v1/documents/{documentId}/content","href":"/api-reference/get-document-content"}]},{"group":"Envelopes","pages":[{"title":"List envelopes, newest first, optionally filtered by status or by your reference.","description":"`GET /api/v1/envelopes/{envelopeId}` reads one envelope by an id you already hold; this is how you find out which ids exist. The webhook delivery ladder gives up after 7 attempts, so an integrator who dropped a delivery has no way to learn what was missed except by asking here.\n\nWalked by keyset cursor rather than by offset, for the same reason `GET /api/v1/templates` is: this list is ordered newest first, so an envelope created between page 1 and page 2 would shift every row down under an offset, and a caller would receive one row twice and never see another.\n\n⚠️ `cursor` IS OPAQUE. It is the last envelope’s `id` in clear, but that is an implementation detail rather than a promise — pass back exactly the `next_cursor` a previous page gave you and never construct one by hand. A well-formed uuid naming no envelope of yours (yours or another organisation’s — this endpoint cannot tell the two apart, and does not try) is refused rather than answered with an empty page, for the same reason an unknown `status` is below: an empty page reads as \"you have none\", which is the single hardest defect class to notice because it looks exactly like data.\n\nEACH ROW IS A SUMMARY, not the full `Envelope` `GET /api/v1/envelopes/{envelopeId}` returns — no recipients, no delivery state. Read one envelope in full once you know which one you want.\n\nRECONCILING A LOST REQUEST IS ONE CALL WITH `?reference=`. Set a `reference` of your own when you create an envelope, and if you never learn what that request did, list by it: a row means it was created, no row means it was not. Make your references unique if you want exactly one — we do not.","deprecated":null,"version":null,"sidebarTitle":"List envelopes","openapi":"/openapi.json get /api/v1/envelopes","href":"/api-reference/list-envelopes"},{"title":"Create an envelope from a template, and optionally send it.","deprecated":null,"version":null,"sidebarTitle":"Create envelope","openapi":"/openapi.json post /api/v1/envelopes","href":"/api-reference/create-envelope"},{"title":"Send a document that is not a template, and optionally send it.","description":"THE ENDPOINT FOR A DOCUMENT THAT EXISTS ONCE — a Letter of Authority, an offer of employment, anything addressed to one person and never reused.\n\n⚠️ IT MAKES NO TEMPLATE, WHICH IS THE POINT. `template_id` comes back `null`. Registering a single-use document as a template to send it would leave one behind on every send, and this API has no way to delete one.\n\nLAYOUT COMES FROM THE DOCUMENT’S OWN TEXT TAGS. Write `\u003c\u003csig:Employee>>` where a signature goes and give a recipient the `role` `Employee`; the field is placed where the tag is. A tag naming a role no recipient holds is refused, with the tag, its page, and the roles the request does declare — because `fields.role_name` is matched to `recipients.role_name` by nothing the database checks, so a tag naming the PERSON would bind a field to a slot nobody holds, silently.\n\nEVERY TAG REFUSAL COMES BACK AT ONCE, not the first, so a document with four bad tags is one correction round rather than four. And a refusal creates nothing: no envelope, no recipients, no stored documents.\n\n✅ A PDF OR A WORD `.docx`, CHECKED BY THE BYTES. A Word document is accepted and converted to PDF on our side, so a docxtemplater or Word pipeline uploads the `.docx` it already has — text tags survive that render, and it is now our render. The envelope is over the converted PDF: that is what page numbers and field coordinates refer to, and it is what a signer sees. The `.docx` you sent is retained unchanged and is not what anybody signs. The older `.doc` format is not accepted.\n\nA REPLAY RETURNS THE SAME ENVELOPE AND CREATES NOTHING, exactly as `POST /api/v1/envelopes` does. ⚠️ Reordering `recipients` is a DIFFERENT request and will not replay across, because that order is the order recipients are listed in and, without `step`, may be the order they are asked.\n\nNO SIGNING URLS ARE RETURNED. Ask for one with `POST /api/v1/envelopes/{envelopeId}/recipients/{recipientId}/signing-url` when that signer is ready — minting them here would start every single-use URL’s expiry clock at creation, for people who may be days apart in the order.","deprecated":null,"version":null,"sidebarTitle":"Create one off envelope","openapi":"/openapi.json post /api/v1/envelopes/one-off","href":"/api-reference/create-one-off-envelope"},{"title":"Create and send many envelopes from one template, in one request.","deprecated":null,"version":null,"sidebarTitle":"Create envelope batch","openapi":"/openapi.json post /api/v1/envelopes/batches","href":"/api-reference/create-envelope-batch"},{"title":"One envelope, as it stands right now.","deprecated":null,"version":null,"sidebarTitle":"Get envelope","openapi":"/openapi.json get /api/v1/envelopes/{envelopeId}","href":"/api-reference/get-envelope"},{"title":"Discard a draft envelope. ⚠️ Drafts only, and it cannot be undone.","deprecated":null,"version":null,"sidebarTitle":"Delete envelope","openapi":"/openapi.json delete /api/v1/envelopes/{envelopeId}","href":"/api-reference/delete-envelope"},{"title":"Get an envelope’s document, and its certificate once sealed.","deprecated":null,"version":null,"sidebarTitle":"List envelope documents","openapi":"/openapi.json get /api/v1/envelopes/{envelopeId}/documents","href":"/api-reference/list-envelope-documents"},{"title":"The document as it stands, mid-flight, stamped DRAFT.","deprecated":null,"version":null,"sidebarTitle":"Get envelope document draft","openapi":"/openapi.json get /api/v1/envelopes/{envelopeId}/documents/{position}/draft","href":"/api-reference/get-envelope-document-draft"},{"title":"Withdraw a sent envelope.","deprecated":null,"version":null,"sidebarTitle":"Void envelope","openapi":"/openapi.json post /api/v1/envelopes/{envelopeId}/void","href":"/api-reference/void-envelope"},{"title":"Give a sent envelope a later deadline.","deprecated":null,"version":null,"sidebarTitle":"Extend envelope deadline","openapi":"/openapi.json post /api/v1/envelopes/{envelopeId}/extend","href":"/api-reference/extend-envelope-deadline"},{"title":"Send a draft envelope to its recipients.","deprecated":null,"version":null,"sidebarTitle":"Send envelope","openapi":"/openapi.json post /api/v1/envelopes/{envelopeId}/send","href":"/api-reference/send-envelope"},{"title":"Mint a short-lived, single-use URL for an embedded signer.","deprecated":null,"version":null,"sidebarTitle":"Create signing url","openapi":"/openapi.json post /api/v1/envelopes/{envelopeId}/recipients/{recipientId}/signing-url","href":"/api-reference/create-signing-url"}]},{"group":"Webhooks","pages":[{"title":"Every registered endpoint, with its health.","deprecated":null,"version":null,"sidebarTitle":"List webhooks","openapi":"/openapi.json get /api/v1/webhooks","href":"/api-reference/list-webhooks"},{"title":"Register an endpoint and mint its signing secret.","deprecated":null,"version":null,"sidebarTitle":"Create webhook","openapi":"/openapi.json post /api/v1/webhooks","href":"/api-reference/create-webhook"},{"title":"One endpoint, with its health.","deprecated":null,"version":null,"sidebarTitle":"Get webhook","openapi":"/openapi.json get /api/v1/webhooks/{webhookId}","href":"/api-reference/get-webhook"},{"title":"Remove an endpoint. ⚠️ Queued deliveries go with it.","deprecated":null,"version":null,"sidebarTitle":"Delete webhook","openapi":"/openapi.json delete /api/v1/webhooks/{webhookId}","href":"/api-reference/delete-webhook"},{"title":"Change the URL, the subscription, the brand filter or the active flag.","deprecated":null,"version":null,"sidebarTitle":"Update webhook","openapi":"/openapi.json patch /api/v1/webhooks/{webhookId}","href":"/api-reference/update-webhook"},{"title":"Mint a new signing secret, keeping the old one alive briefly.","deprecated":null,"version":null,"sidebarTitle":"Rotate webhook secret","openapi":"/openapi.json post /api/v1/webhooks/{webhookId}/rotate-secret","href":"/api-reference/rotate-webhook-secret"}]},{"group":"Brands","pages":[{"title":"List your organisation’s brands, newest first.","deprecated":null,"version":null,"sidebarTitle":"List brands","openapi":"/openapi.json get /api/v1/brands","href":"/api-reference/list-brands"},{"title":"One brand, archived or not.","deprecated":null,"version":null,"sidebarTitle":"Get brand","openapi":"/openapi.json get /api/v1/brands/{brandId}","href":"/api-reference/get-brand"},{"title":"Register one origin that may frame this brand’s signing pages.","deprecated":null,"version":null,"sidebarTitle":"Add brand embed origin","openapi":"/openapi.json post /api/v1/brands/{brandId}/embed-origins","href":"/api-reference/add-brand-embed-origin"},{"title":"Stop one origin framing this brand’s signing pages.","deprecated":null,"version":null,"sidebarTitle":"Remove brand embed origin","openapi":"/openapi.json delete /api/v1/brands/{brandId}/embed-origins","href":"/api-reference/remove-brand-embed-origin"}]},{"group":"Standing authorisations","pages":[{"title":"List standing authorisations, newest first, optionally filtered.","deprecated":null,"version":null,"sidebarTitle":"List standing authorisations","openapi":"/openapi.json get /api/v1/standing-authorisations","href":"/api-reference/list-standing-authorisations"},{"title":"One standing authorisation, as it stands now.","deprecated":null,"version":null,"sidebarTitle":"Get standing authorisation","openapi":"/openapi.json get /api/v1/standing-authorisations/{authorisationId}","href":"/api-reference/get-standing-authorisation"},{"title":"Cancel a pending standing authorisation request.","deprecated":null,"version":null,"sidebarTitle":"Cancel standing authorisation","openapi":"/openapi.json post /api/v1/standing-authorisations/{authorisationId}/cancel","href":"/api-reference/cancel-standing-authorisation"},{"title":"Email the grantor a fresh link to a pending request.","deprecated":null,"version":null,"sidebarTitle":"Resend standing authorisation","openapi":"/openapi.json post /api/v1/standing-authorisations/{authorisationId}/resend","href":"/api-reference/resend-standing-authorisation"},{"title":"Revoke a standing authorisation.","deprecated":null,"version":null,"sidebarTitle":"Revoke standing authorisation","openapi":"/openapi.json post /api/v1/standing-authorisations/{authorisationId}/revoke","href":"/api-reference/revoke-standing-authorisation"},{"title":"Renew a standing authorisation: send its grantor a new mandate that starts when it ends.","deprecated":null,"version":null,"sidebarTitle":"Renew standing authorisation","openapi":"/openapi.json post /api/v1/standing-authorisations/{authorisationId}/renew","href":"/api-reference/renew-standing-authorisation"},{"title":"Request a standing authorisation: generate the mandate and send it to the grantor.","deprecated":null,"version":null,"sidebarTitle":"Invite standing authorisation","openapi":"/openapi.json post /api/v1/standing-authorisations/invitations","href":"/api-reference/invite-standing-authorisation"}]}]}]},"basePath":"","title":"Create an envelope from a template, and optionally send it. - Vumasign","buildId":"dpl_GRSyrvXT6FFTpZZTGz5iZPp3D2zE","deploymentId":"dpl_GRSyrvXT6FFTpZZTGz5iZPp3D2zE","dynamics":["c2aa737661","2b790eda92","b0f84f53ff","a9bb46feb3"],"chunks":["OpenApiReferenceProvider-BFmjTMeT.js","utils-BWr-sjpP.js","cloneDeep-izs3Hzxb.js","_Uint8Array-BVIqJ90l.js","isObjectLike-C8vmzPEN.js","isArray-Dcu1dQ5t.js","utils-LafIDf0N.js","toString-BX-iyh8G.js","isSymbol-CSH9U2Gm.js","addUniqueKeysToSchema-MJNzuxek.js","snippetPresets-DPZEtUvW.js","style-to-object-BY3JEAdk.js","v4-DIgz8zy6.js","conditional-requirements-CFM0id0Q.js","ApiExamples-DQ2UhGIs.js","isEqual-BfaiBbcl.js","usePlaygroundInputsStore-DUUJTUkE.js","shallow-BTf5bw35.js","getApiPlaygroundDisplay-h2POYYOO.js","CodeSnippet-C4qEftRe.js","CodeSnippets-CsSrOqMC.js","Page-CWFqNdGh.js","getPastedJson-DU6W6y78.js","icon-2ZYNQ78y.js","MethodPill-BMXJzYMm.js","DuplicateIcon-DNjdEpYZ.js","createIcon-WdPVhKxl.js","DynamicMarkdown-Z_y464fM.js","SectionHeading-Bcrd8azU.js","axios-vUo_bRtp.js","Markdown-BnvucbFu.js","dist-D7YyC486.js","lib-DuNMoZ05.js","lib-B8HbPgcC.js","katex-YMM-FMeD.js","html-void-elements-mCSPHezU.js","marked.esm-CZWythHk.js","AssistantPageLink-D1I8TPjt.js"]}