THE SECOND HALF OF THE CREATED-VERSUS-SENT SPLIT. POST /api/v1/envelopes with "send": false makes a draft and emails nobody; this is how that draft goes out. Two acts an integrator can separate — build the envelope when a form is submitted, send it when a human approves — which is the arrangement a one-shot create cannot express without either sending too early or holding a request open.
⚠️ A SUB-RESOURCE AND NOT PATCH {"status": "sent"}. Sending emails people, consumes billing allowance and writes an audit event; making that look like editing a property would make an irreversible, billable act look reversible.
200, not 201. Nothing was created — the envelope existed before this call. A client branching on 201 to mean “store this new id” would be wrong here every time.
The idempotency, which is the point
⚠️ Idempotency-Key IS REQUIRED. None of DocuSign, Dropbox Sign or BoldSign offers one on the endpoint that costs real money; this is that endpoint, and an optional guarantee is one nobody sends until they have already been burned.
A REPLAY MEANS “you already sent this, and here is what happened” — the first attempt’s answer, byte for byte, with Idempotency-Replayed: true. Not a second send, not a resend, not a refusal. That is what makes a timeout safe to retry.
A DIFFERENT ENVELOPE UNDER A USED KEY IS idempotency_key_reused, never a replay — including a key you already used to CREATE something. A key identifies one request.
KEYS ARE REMEMBERED FOR 1 DAY, per organisation and per environment. Past that the same string is a new request — and a new request to send an envelope that has already gone out is envelope_not_draft, not a second send. Two mechanisms, and the second one is the database: draft → sent is a locked, one-way transition, so a duplicate send is impossible whatever the key says. The key decides what the second caller is TOLD.
What it refuses
A REFUSAL SENDS NOTHING AND CHANGES NOTHING. The envelope is left exactly as it was — unlike a refused "send": true on the create endpoint, which deletes the draft it had just built — and the idempotency key is freed, so a caller who upgrades their plan or fixes their roster retries with the same key.
⚠️ A vsk_test_ KEY MAY SEND ONLY A SANDBOX ENVELOPE — one a test key created — and only to people it may email. A draft a live key created is refused with test_key_cannot_send, and so is one whose emailed recipients include an address that is neither a member of your organisation nor a confirmed test recipient (Settings → Test recipients). An "embedded": true recipient is never emailed and is never checked. A test send consumes no allowance.
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 went out, and retrying either sends it twice or tells you it is not a draft without saying who sent it.
The caller’s own request identifier.
Example:
"01960000-0000-4000-8000-00000000ffff"
Path Parameters
envelopeId
string<uuid>
required
The draft envelope’s id, as returned when it was created.
An envelope id.
Example:
"01960000-0000-4000-8000-0000000000e5"
Response
The envelope, now sent. invitation_delivered on each recipient is what the email provider said about that invitation — null where none was attempted, which on an envelope in steps is everybody outside the first step.
⚠️ HERE, AND ONLY HERE, true MEANS "THE PROVIDER ACCEPTED IT" RATHER THAN "THE PROVIDER DELIVERED IT". This response is built from the answers the provider gave while the send was running, and at that moment nobody — us or them — knows whether the message will arrive. Delivery is reported afterwards, and GET /api/v1/envelopes/{id} is where it shows up. If the distinction matters to you, re-read there rather than trusting this snapshot.
⚠️ A recipient still reading pending after a successful send is NORMAL on an envelope in steps, not a failure.
The envelope, as it now stands.
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/send-envelope","slug":"/api-reference/send-envelope","pageMetadata":{"title":"Send a draft envelope to its recipients.","description":"THE SECOND HALF OF THE CREATED-VERSUS-SENT SPLIT. `POST /api/v1/envelopes` with `\"send\": false` makes a draft and emails nobody; this is how that draft goes out. Two acts an integrator can separate — build the envelope when a form is submitted, send it when a human approves — which is the arrangement a one-shot create cannot express without either sending too early or holding a request open.\n\n⚠️ A SUB-RESOURCE AND NOT `PATCH {\"status\": \"sent\"}`. Sending emails people, consumes billing allowance and writes an audit event; making that look like editing a property would make an irreversible, billable act look reversible.\n\n**200, not 201.** Nothing was created — the envelope existed before this call. A client branching on 201 to mean \"store this new id\" would be wrong here every time.\n\n## The idempotency, which is the point\n\n⚠️ `Idempotency-Key` IS REQUIRED. None of DocuSign, Dropbox Sign or BoldSign offers one on the endpoint that costs real money; this is that endpoint, and an optional guarantee is one nobody sends until they have already been burned.\n\nA REPLAY MEANS \"you already sent this, and here is what happened\" — the first attempt’s answer, byte for byte, with `Idempotency-Replayed: true`. Not a second send, not a resend, not a refusal. That is what makes a timeout safe to retry.\n\nA DIFFERENT ENVELOPE UNDER A USED KEY IS `idempotency_key_reused`, never a replay — including a key you already used to CREATE something. A key identifies one request.\n\nKEYS ARE REMEMBERED FOR 1 DAY, per organisation and per environment. Past that the same string is a new request — and a new request to send an envelope that has already gone out is `envelope_not_draft`, not a second send. Two mechanisms, and the second one is the database: `draft → sent` is a locked, one-way transition, so a duplicate send is impossible whatever the key says. The key decides what the second caller is TOLD.\n\n## What it refuses\n\nA REFUSAL SENDS NOTHING AND CHANGES NOTHING. The envelope is left exactly as it was — unlike a refused `\"send\": true` on the create endpoint, which deletes the draft it had just built — and the idempotency key is freed, so a caller who upgrades their plan or fixes their roster retries with the same key.\n\n⚠️ A `vsk_test_` KEY MAY SEND ONLY A SANDBOX ENVELOPE — one a test key created — and only to people it may email. A draft a live key created is refused with `test_key_cannot_send`, and so is one whose emailed recipients include an address that is neither a member of your organisation nor a confirmed test recipient (Settings → Test recipients). An `\"embedded\": true` recipient is never emailed and is never checked. A test send consumes no allowance.","deprecated":null,"version":null,"sidebarTitle":"Send envelope","openapi":"/openapi.json post /api/v1/envelopes/{envelopeId}/send","href":"/api-reference/send-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 code: \"code\",\n h2: \"h2\",\n p: \"p\",\n strong: \"strong\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsxs(_components.p, {\n children: [\"THE SECOND HALF OF THE CREATED-VERSUS-SENT SPLIT. \", _jsx(_components.code, {\n children: \"POST /api/v1/envelopes\"\n }), \" with \", _jsx(_components.code, {\n children: \"\\\"send\\\": false\"\n }), \" makes a draft and emails nobody; this is how that draft goes out. Two acts an integrator can separate — build the envelope when a form is submitted, send it when a human approves — which is the arrangement a one-shot create cannot express without either sending too early or holding a request open.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"⚠️ A SUB-RESOURCE AND NOT \", _jsx(_components.code, {\n children: \"PATCH {\\\"status\\\": \\\"sent\\\"}\"\n }), \". Sending emails people, consumes billing allowance and writes an audit event; making that look like editing a property would make an irreversible, billable act look reversible.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [_jsx(_components.strong, {\n children: \"200, not 201.\"\n }), \" Nothing was created — the envelope existed before this call. A client branching on 201 to mean “store this new id” would be wrong here every time.\"]\n }), \"\\n\", _jsx(_components.h2, {\n children: \"The idempotency, which is the point\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"⚠️ \", _jsx(_components.code, {\n children: \"Idempotency-Key\"\n }), \" IS REQUIRED. None of DocuSign, Dropbox Sign or BoldSign offers one on the endpoint that costs real money; this is that endpoint, and an optional guarantee is one nobody sends until they have already been burned.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"A REPLAY MEANS “you already sent this, and here is what happened” — the first attempt’s answer, byte for byte, with \", _jsx(_components.code, {\n children: \"Idempotency-Replayed: true\"\n }), \". Not a second send, not a resend, not a refusal. That is what makes a timeout safe to retry.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"A DIFFERENT ENVELOPE UNDER A USED KEY IS \", _jsx(_components.code, {\n children: \"idempotency_key_reused\"\n }), \", never a replay — including a key you already used to CREATE something. A key identifies one request.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"KEYS ARE REMEMBERED FOR 1 DAY, per organisation and per environment. Past that the same string is a new request — and a new request to send an envelope that has already gone out is \", _jsx(_components.code, {\n children: \"envelope_not_draft\"\n }), \", not a second send. Two mechanisms, and the second one is the database: \", _jsx(_components.code, {\n children: \"draft → sent\"\n }), \" is a locked, one-way transition, so a duplicate send is impossible whatever the key says. The key decides what the second caller is TOLD.\"]\n }), \"\\n\", _jsx(_components.h2, {\n children: \"What it refuses\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"A REFUSAL SENDS NOTHING AND CHANGES NOTHING. The envelope is left exactly as it was — unlike a refused \", _jsx(_components.code, {\n children: \"\\\"send\\\": true\"\n }), \" on the create endpoint, which deletes the draft it had just built — and the idempotency key is freed, so a caller who upgrades their plan or fixes their roster retries with the same key.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"⚠️ A \", _jsx(_components.code, {\n children: \"vsk_test_\"\n }), \" KEY MAY SEND ONLY A SANDBOX ENVELOPE — one a test key created — and only to people it may email. A draft a live key created is refused with \", _jsx(_components.code, {\n children: \"test_key_cannot_send\"\n }), \", and so is one whose emailed recipients include an address that is neither a member of your organisation nor a confirmed test recipient (Settings → Test recipients). An \", _jsx(_components.code, {\n children: \"\\\"embedded\\\": true\"\n }), \" recipient is never emailed and is never checked. A test send consumes no allowance.\"]\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":"Send a draft envelope to its recipients.","description":"THE SECOND HALF OF THE CREATED-VERSUS-SENT SPLIT. `POST /api/v1/envelopes` with `\"send\": false` makes a draft and emails nobody; this is how that draft goes out. Two acts an integrator can separate — build the envelope when a form is submitted, send it when a human approves — which is the arrangement a one-shot create cannot express without either sending too early or holding a request open.\n\n⚠️ A SUB-RESOURCE AND NOT `PATCH {\"status\": \"sent\"}`. Sending emails people, consumes billing allowance and writes an audit event; making that look like editing a property would make an irreversible, billable act look reversible.\n\n**200, not 201.** Nothing was created — the envelope existed before this call. A client branching on 201 to mean \"store this new id\" would be wrong here every time.\n\n## The idempotency, which is the point\n\n⚠️ `Idempotency-Key` IS REQUIRED. None of DocuSign, Dropbox Sign or BoldSign offers one on the endpoint that costs real money; this is that endpoint, and an optional guarantee is one nobody sends until they have already been burned.\n\nA REPLAY MEANS \"you already sent this, and here is what happened\" — the first attempt’s answer, byte for byte, with `Idempotency-Replayed: true`. Not a second send, not a resend, not a refusal. That is what makes a timeout safe to retry.\n\nA DIFFERENT ENVELOPE UNDER A USED KEY IS `idempotency_key_reused`, never a replay — including a key you already used to CREATE something. A key identifies one request.\n\nKEYS ARE REMEMBERED FOR 1 DAY, per organisation and per environment. Past that the same string is a new request — and a new request to send an envelope that has already gone out is `envelope_not_draft`, not a second send. Two mechanisms, and the second one is the database: `draft → sent` is a locked, one-way transition, so a duplicate send is impossible whatever the key says. The key decides what the second caller is TOLD.\n\n## What it refuses\n\nA REFUSAL SENDS NOTHING AND CHANGES NOTHING. The envelope is left exactly as it was — unlike a refused `\"send\": true` on the create endpoint, which deletes the draft it had just built — and the idempotency key is freed, so a caller who upgrades their plan or fixes their roster retries with the same key.\n\n⚠️ A `vsk_test_` KEY MAY SEND ONLY A SANDBOX ENVELOPE — one a test key created — and only to people it may email. A draft a live key created is refused with `test_key_cannot_send`, and so is one whose emailed recipients include an address that is neither a member of your organisation nor a confirmed test recipient (Settings → Test recipients). An `\"embedded\": true` recipient is never emailed and is never checked. A test send consumes no allowance.","deprecated":null,"version":null,"sidebarTitle":"Send envelope","openapi":"/openapi.json post /api/v1/envelopes/{envelopeId}/send","href":"/api-reference/send-envelope","autogeneratedByOpenApi":true}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[],"codeExamples":{}},"jsLinks":[],"openApiReferenceData":{"operation":{"operationId":"sendEnvelope","tags":["Envelopes"],"x-mint":{"href":"/api-reference/send-envelope"},"summary":"Send a draft envelope to its recipients.","description":"THE SECOND HALF OF THE CREATED-VERSUS-SENT SPLIT. `POST /api/v1/envelopes` with `\"send\": false` makes a draft and emails nobody; this is how that draft goes out. Two acts an integrator can separate — build the envelope when a form is submitted, send it when a human approves — which is the arrangement a one-shot create cannot express without either sending too early or holding a request open.\n\n⚠️ A SUB-RESOURCE AND NOT `PATCH {\"status\": \"sent\"}`. Sending emails people, consumes billing allowance and writes an audit event; making that look like editing a property would make an irreversible, billable act look reversible.\n\n**200, not 201.** Nothing was created — the envelope existed before this call. A client branching on 201 to mean \"store this new id\" would be wrong here every time.\n\n## The idempotency, which is the point\n\n⚠️ `Idempotency-Key` IS REQUIRED. None of DocuSign, Dropbox Sign or BoldSign offers one on the endpoint that costs real money; this is that endpoint, and an optional guarantee is one nobody sends until they have already been burned.\n\nA REPLAY MEANS \"you already sent this, and here is what happened\" — the first attempt’s answer, byte for byte, with `Idempotency-Replayed: true`. Not a second send, not a resend, not a refusal. That is what makes a timeout safe to retry.\n\nA DIFFERENT ENVELOPE UNDER A USED KEY IS `idempotency_key_reused`, never a replay — including a key you already used to CREATE something. A key identifies one request.\n\nKEYS ARE REMEMBERED FOR 1 DAY, per organisation and per environment. Past that the same string is a new request — and a new request to send an envelope that has already gone out is `envelope_not_draft`, not a second send. Two mechanisms, and the second one is the database: `draft → sent` is a locked, one-way transition, so a duplicate send is impossible whatever the key says. The key decides what the second caller is TOLD.\n\n## What it refuses\n\nA REFUSAL SENDS NOTHING AND CHANGES NOTHING. The envelope is left exactly as it was — unlike a refused `\"send\": true` on the create endpoint, which deletes the draft it had just built — and the idempotency key is freed, so a caller who upgrades their plan or fixes their roster retries with the same key.\n\n⚠️ A `vsk_test_` KEY MAY SEND ONLY A SANDBOX ENVELOPE — one a test key created — and only to people it may email. A draft a live key created is refused with `test_key_cannot_send`, and so is one whose emailed recipients include an address that is neither a member of your organisation nor a confirmed test recipient (Settings → Test recipients). An `\"embedded\": true` recipient is never emailed and is never checked. A test send consumes no allowance.","security":["8d0198da-20b0-413d-89bb-544a5309d376"],"x-required-scope":"envelopes:write","parameters":["b5da8dbf-71cc-49ce-8977-e4027d599681","78147005-681d-40d5-a8d8-0d04133ec8d6"],"responses":{"200":"be4d41a7-83f5-48e8-875d-8de33238d94d","400":"075793e8-2d80-4910-9df3-6a08ca926c63","401":"0bb19937-c3fd-474a-828e-3c6803945463","402":"f22738bd-5cbd-487e-bd8f-f0e965c30dbf","403":"9dd85216-0c6d-4fcf-b56d-643d02ee003f","404":"63fbc3cf-c1e5-4ef6-ad70-b45415f3b7b2","409":"8dee848e-b429-4a78-b991-8dcc9eae41d4","422":"a2457b65-2a5f-44ee-bf7d-783ca7f27694","429":"c6fb4b8a-a490-47a7-b0b1-57f6868bde79","500":"25dac76f-50a6-4610-aea4-cbeee02e5991","503":"f8617767-0f2f-45ca-984f-f8a1e1b2a092"},"method":"post","type":"path","servers":["2ed67dbf-843b-4ce0-93c8-8c35248fcb3e"],"path":"/api/v1/envelopes/{envelopeId}/send","baseUrlOptions":["https://app.vumasign.com"],"title":"Send a draft envelope to its recipients.","codeSamples":[],"requestExampleLanguages":["bash","python","javascript","go"],"requiredOnlyExamples":true,"requestExampleType":"generated","responseExampleType":"generated","prefillPlaygroundWithExample":true,"prefillPlaygroundExamples":[]},"dependencies":{"parameters":{"b5da8dbf-71cc-49ce-8977-e4027d599681":{"name":"envelopeId","in":"path","required":true,"description":"The draft envelope’s `id`, as returned when it was created.","schema":{"type":"string","format":"uuid","examples":["01960000-0000-4000-8000-0000000000e5"],"description":"The draft envelope’s `id`, as returned when it was created.\nAn envelope id.","isRequired":true,"uniqueKey":"","typeLabel":"string\u003cuuid>"}},"78147005-681d-40d5-a8d8-0d04133ec8d6":{"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 went out, and retrying either sends it twice or tells you it is not a draft without saying who sent it.","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 went out, and retrying either sends it twice or tells you it is not a draft without saying who sent it.\nThe caller’s own request identifier.","isRequired":true,"uniqueKey":"","typeLabel":"string"}}},"responses":{"be4d41a7-83f5-48e8-875d-8de33238d94d":{"description":"The envelope, now `sent`. `invitation_delivered` on each recipient is what the email provider said about that invitation — `null` where none was attempted, which on an envelope in steps is everybody outside the first step.\n\n⚠️ HERE, AND ONLY HERE, `true` MEANS \"THE PROVIDER ACCEPTED IT\" RATHER THAN \"THE PROVIDER DELIVERED IT\". This response is built from the answers the provider gave while the send was running, and at that moment nobody — us or them — knows whether the message will arrive. Delivery is reported afterwards, and `GET /api/v1/envelopes/{id}` is where it shows up. If the distinction matters to you, re-read there rather than trusting this snapshot.\n\n⚠️ A recipient still reading `pending` after a successful send is NORMAL on an envelope in steps, not a failure.","content":{"application/json":{"schema":{"type":"object","description":"The envelope, as it now stands.","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":"Sent, and accepted by the email provider","value":{"id":"01960000-0000-4000-8000-0000000000e5","status":"sent","template_id":"01960000-0000-4000-8000-0000000007e1","title":"Employment contract","reference":"hire-2026-0917","created_at":"2026-09-02T09:00:00.000Z","sent_at":"2026-09-02T09:05:00.000Z","expires_at":null,"recipients":[{"id":"01960000-0000-4000-8000-00000000005e","role":"Employee","name":"Thandi Mokoena","email":"thandi@example.test","routing_type":"sign","status":"sent","invitation_delivered":true,"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"},"075793e8-2d80-4910-9df3-6a08ca926c63":{"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"},"0bb19937-c3fd-474a-828e-3c6803945463":{"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"},"f22738bd-5cbd-487e-bd8f-f0e965c30dbf":{"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"},"9dd85216-0c6d-4fcf-b56d-643d02ee003f":{"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`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.\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.","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"},"63fbc3cf-c1e5-4ef6-ad70-b45415f3b7b2":{"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.","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"},"8dee848e-b429-4a78-b991-8dcc9eae41d4":{"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.\n\n`envelope_not_draft` — Only a draft can be sent, and this envelope has already left draft — through this API, through the sender’s own Send button, or by being voided. ⚠️ THE EXACT OPPOSITE OF `envelope_not_sent`, and the two are not interchangeable: that one means the envelope has NOT gone out. An envelope never returns to draft, so this is terminal — read it with `GET /api/v1/envelopes/{envelopeId}` to see where it got to. ⚠️ If you were retrying a request that timed out, send the SAME `Idempotency-Key` instead and you will be told what the first attempt did. ⚠️ Discarding answers it too: `DELETE /api/v1/envelopes/{envelopeId}` deletes only a draft, so an envelope that has gone out is refused with this code and left as it was. Withdraw a `sent` or `partially_signed` one with `POST /api/v1/envelopes/{envelopeId}/void` instead; a finished one has nothing left to withdraw. The `message` says which state it is in.","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"},"a2457b65-2a5f-44ee-bf7d-783ca7f27694":{"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`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`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`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`envelope_sender_removed` — The envelope you asked to send was created in the name of somebody who has since left the organisation. An envelope sent through the API is sent in its creator’s name — the one-off’s `sender`, or whoever created the key that created it — and every email its signers receive names that person, so it cannot go out in the name of somebody who is no longer here, whichever key asks. The creator is fixed when the envelope is made: create it again in the name of a current member.","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"},"c6fb4b8a-a490-47a7-b0b1-57f6868bde79":{"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"},"25dac76f-50a6-4610-aea4-cbeee02e5991":{"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.)","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"},"f8617767-0f2f-45ca-984f-f8a1e1b2a092":{"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.","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":{"8d0198da-20b0-413d-89bb-544a5309d376":{"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":"Send a draft envelope to its recipients. - Vumasign","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-11-16T05:07:56.303Z","originalFileLocation":"api-reference/send-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 SECOND HALF OF THE CREATED-VERSUS-SENT SPLIT. POST /api/v1/envelopes with \u0026quot;send\u0026quot;: false makes a draft and emails nobody; this is how that draft goes out. Two acts an integrator can separate — build the envelope when a form is submitted, send it when a human approves — which is the arrangement a one-shot create cannot express without either sending too early or holding a request open. ⚠️ A SUB-RESOURCE AND NOT PATCH {\u0026quot;status\u0026quot;: \u0026quot;sent\u0026quot;}. Sending emails people, consumes billing allowance and writes an audit event; making that look like editing a property would make an irreversible, billable act look reversible. 200, not 201. Nothing was created — the envelope existed before this call. A client branching on 201 to mean \u0026quot;store this new id\u0026quot; would be wrong here every time. ## The idempotency, which is the point ⚠️ Idempotency-Key IS REQUIRED. None of DocuSign, Dropbox Sign or BoldSign offers one on the endpoint that costs real money; this is that endpoint, and an optional guarantee is one nobody sends until they have already been burned. A REPLAY MEANS \u0026quot;you already sent this, and here is what happened\u0026quot; — the first attempt’s answer, byte for byte, with Idempotency-Replayed: true. Not a second send, not a resend, not a refusal. That is what makes a timeout safe to retry. A DIFFERENT ENVELOPE UNDER A USED KEY IS idempotency_key_reused, never a replay — including a key you already used to CREATE something. A key identifies one request. KEYS ARE REMEMBERED FOR 1 DAY, per organisation and per environment. Past that the same string is a new request — and a new request to send an envelope that has already gone out is envelope_not_draft, not a second send. Two mechanisms, and the second one is the database: draft → sent is a locked, one-way transition, so a duplicate send is impossible whatever the key says. The key decides what the second caller is TOLD. ## What it refuses A REFUSAL SENDS NOTHING AND CHANGES NOTHING. The envelope is left exactly as it was — unlike a refused \u0026quot;send\u0026quot;: true on the create endpoint, which deletes the draft it had just built — and the idempotency key is freed, so a caller who upgrades their plan or fixes their roster retries with the same key. ⚠️ A vsk_test_ KEY MAY SEND ONLY A SANDBOX ENVELOPE — one a test key created — and only to people it may email. A draft a live key created is refused with test_key_cannot_send, and so is one whose emailed recipients include an address that is neither a member of your organisation nor a confirmed test recipient (Settings → Test recipients). An \u0026quot;embedded\u0026quot;: true recipient is never emailed and is never checked. A test send consumes no allowance.\">\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=\"Send a draft envelope to its recipients. - Vumasign\">\u003cmeta data-mint-head property=\"og:description\" content=\"THE SECOND HALF OF THE CREATED-VERSUS-SENT SPLIT. POST /api/v1/envelopes with \u0026quot;send\u0026quot;: false makes a draft and emails nobody; this is how that draft goes out. Two acts an integrator can separate — build the envelope when a form is submitted, send it when a human approves — which is the arrangement a one-shot create cannot express without either sending too early or holding a request open. ⚠️ A SUB-RESOURCE AND NOT PATCH {\u0026quot;status\u0026quot;: \u0026quot;sent\u0026quot;}. Sending emails people, consumes billing allowance and writes an audit event; making that look like editing a property would make an irreversible, billable act look reversible. 200, not 201. Nothing was created — the envelope existed before this call. A client branching on 201 to mean \u0026quot;store this new id\u0026quot; would be wrong here every time. ## The idempotency, which is the point ⚠️ Idempotency-Key IS REQUIRED. None of DocuSign, Dropbox Sign or BoldSign offers one on the endpoint that costs real money; this is that endpoint, and an optional guarantee is one nobody sends until they have already been burned. A REPLAY MEANS \u0026quot;you already sent this, and here is what happened\u0026quot; — the first attempt’s answer, byte for byte, with Idempotency-Replayed: true. Not a second send, not a resend, not a refusal. That is what makes a timeout safe to retry. A DIFFERENT ENVELOPE UNDER A USED KEY IS idempotency_key_reused, never a replay — including a key you already used to CREATE something. A key identifies one request. KEYS ARE REMEMBERED FOR 1 DAY, per organisation and per environment. Past that the same string is a new request — and a new request to send an envelope that has already gone out is envelope_not_draft, not a second send. Two mechanisms, and the second one is the database: draft → sent is a locked, one-way transition, so a duplicate send is impossible whatever the key says. The key decides what the second caller is TOLD. ## What it refuses A REFUSAL SENDS NOTHING AND CHANGES NOTHING. The envelope is left exactly as it was — unlike a refused \u0026quot;send\u0026quot;: true on the create endpoint, which deletes the draft it had just built — and the idempotency key is freed, so a caller who upgrades their plan or fixes their roster retries with the same key. ⚠️ A vsk_test_ KEY MAY SEND ONLY A SANDBOX ENVELOPE — one a test key created — and only to people it may email. A draft a live key created is refused with test_key_cannot_send, and so is one whose emailed recipients include an address that is neither a member of your organisation nor a confirmed test recipient (Settings → Test recipients). An \u0026quot;embedded\u0026quot;: true recipient is never emailed and is never checked. A test send consumes no allowance.\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"Vumasign\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.vumasign.com/api-reference/send-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=Send+a+draft+envelope+to+its+recipients.\u0026amp;description=THE+SECOND+HALF+OF+THE+CREATED-VERSUS-SENT+SPLIT.+%60POST+%2Fapi%2Fv1%2Fenvelopes%60+with+%60%22send%22%3A+false%60+makes+a+draft+and+emails+nobody%3B+this+is+how+that+draft+goes+out\u0026amp;theme=5afaa4abac00f05afdc3c271\u0026amp;signature=d90a1f0ac308ce56d63bf1000a666df6836a1b783d03e6a5b10acc7f8b016719\">\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=\"Send a draft envelope to its recipients. - Vumasign\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"THE SECOND HALF OF THE CREATED-VERSUS-SENT SPLIT. POST /api/v1/envelopes with \u0026quot;send\u0026quot;: false makes a draft and emails nobody; this is how that draft goes out. Two acts an integrator can separate — build the envelope when a form is submitted, send it when a human approves — which is the arrangement a one-shot create cannot express without either sending too early or holding a request open. ⚠️ A SUB-RESOURCE AND NOT PATCH {\u0026quot;status\u0026quot;: \u0026quot;sent\u0026quot;}. Sending emails people, consumes billing allowance and writes an audit event; making that look like editing a property would make an irreversible, billable act look reversible. 200, not 201. Nothing was created — the envelope existed before this call. A client branching on 201 to mean \u0026quot;store this new id\u0026quot; would be wrong here every time. ## The idempotency, which is the point ⚠️ Idempotency-Key IS REQUIRED. None of DocuSign, Dropbox Sign or BoldSign offers one on the endpoint that costs real money; this is that endpoint, and an optional guarantee is one nobody sends until they have already been burned. A REPLAY MEANS \u0026quot;you already sent this, and here is what happened\u0026quot; — the first attempt’s answer, byte for byte, with Idempotency-Replayed: true. Not a second send, not a resend, not a refusal. That is what makes a timeout safe to retry. A DIFFERENT ENVELOPE UNDER A USED KEY IS idempotency_key_reused, never a replay — including a key you already used to CREATE something. A key identifies one request. KEYS ARE REMEMBERED FOR 1 DAY, per organisation and per environment. Past that the same string is a new request — and a new request to send an envelope that has already gone out is envelope_not_draft, not a second send. Two mechanisms, and the second one is the database: draft → sent is a locked, one-way transition, so a duplicate send is impossible whatever the key says. The key decides what the second caller is TOLD. ## What it refuses A REFUSAL SENDS NOTHING AND CHANGES NOTHING. The envelope is left exactly as it was — unlike a refused \u0026quot;send\u0026quot;: true on the create endpoint, which deletes the draft it had just built — and the idempotency key is freed, so a caller who upgrades their plan or fixes their roster retries with the same key. ⚠️ A vsk_test_ KEY MAY SEND ONLY A SANDBOX ENVELOPE — one a test key created — and only to people it may email. A draft a live key created is refused with test_key_cannot_send, and so is one whose emailed recipients include an address that is neither a member of your organisation nor a confirmed test recipient (Settings → Test recipients). An \u0026quot;embedded\u0026quot;: true recipient is never emailed and is never checked. A test send consumes no allowance.\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://vumasign.mintlify.site/_mintlify/api/og/v2?division=Envelopes\u0026amp;title=Send+a+draft+envelope+to+its+recipients.\u0026amp;description=THE+SECOND+HALF+OF+THE+CREATED-VERSUS-SENT+SPLIT.+%60POST+%2Fapi%2Fv1%2Fenvelopes%60+with+%60%22send%22%3A+false%60+makes+a+draft+and+emails+nobody%3B+this+is+how+that+draft+goes+out\u0026amp;theme=5afaa4abac00f05afdc3c271\u0026amp;signature=d90a1f0ac308ce56d63bf1000a666df6836a1b783d03e6a5b10acc7f8b016719\">\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/send-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/send-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/send-envelope#webpage\",\"url\":\"https://docs.vumasign.com/api-reference/send-envelope\",\"name\":\"Send a draft envelope to its recipients.\",\"description\":\"THE SECOND HALF OF THE CREATED-VERSUS-SENT SPLIT. POST /api/v1/envelopes with \\\"send\\\": false makes a draft and emails nobody; this is how that draft goes out. Two acts an integrator can separate — build the envelope when a form is submitted, send it when a human approves — which is the arrangement a one-shot create cannot express without either sending too early or holding a request open. ⚠️ A SUB-RESOURCE AND NOT PATCH {\\\"status\\\": \\\"sent\\\"}. Sending emails people, consumes billing allowance and writes an audit event; making that look like editing a property would make an irreversible, billable act look reversible. 200, not 201. Nothing was created — the envelope existed before this call. A client branching on 201 to mean \\\"store this new id\\\" would be wrong here every time. ## The idempotency, which is the point ⚠️ Idempotency-Key IS REQUIRED. None of DocuSign, Dropbox Sign or BoldSign offers one on the endpoint that costs real money; this is that endpoint, and an optional guarantee is one nobody sends until they have already been burned. A REPLAY MEANS \\\"you already sent this, and here is what happened\\\" — the first attempt’s answer, byte for byte, with Idempotency-Replayed: true. Not a second send, not a resend, not a refusal. That is what makes a timeout safe to retry. A DIFFERENT ENVELOPE UNDER A USED KEY IS idempotency_key_reused, never a replay — including a key you already used to CREATE something. A key identifies one request. KEYS ARE REMEMBERED FOR 1 DAY, per organisation and per environment. Past that the same string is a new request — and a new request to send an envelope that has already gone out is envelope_not_draft, not a second send. Two mechanisms, and the second one is the database: draft → sent is a locked, one-way transition, so a duplicate send is impossible whatever the key says. The key decides what the second caller is TOLD. ## What it refuses A REFUSAL SENDS NOTHING AND CHANGES NOTHING. The envelope is left exactly as it was — unlike a refused \\\"send\\\": true on the create endpoint, which deletes the draft it had just built — and the idempotency key is freed, so a caller who upgrades their plan or fixes their roster retries with the same key. ⚠️ A vsk_test_ KEY MAY SEND ONLY A SANDBOX ENVELOPE — one a test key created — and only to people it may email. A draft a live key created is refused with test_key_cannot_send, and so is one whose emailed recipients include an address that is neither a member of your organisation nor a confirmed test recipient (Settings → Test recipients). An \\\"embedded\\\": true recipient is never emailed and is never checked. A test send consumes no allowance.\",\"dateModified\":\"2026-11-16T05:07:56.303Z\",\"isPartOf\":{\"@id\":\"https://docs.vumasign.com#website\"},\"breadcrumb\":{\"@id\":\"https://docs.vumasign.com/api-reference/send-envelope#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.vumasign.com/api-reference/send-envelope#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Envelopes\",\"item\":\"https://docs.vumasign.com/api-reference/list-envelopes\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Send a draft envelope to its recipients.\",\"item\":\"https://docs.vumasign.com/api-reference/send-envelope\"}]},{\"@type\":[\"TechArticle\",\"APIReference\"],\"@id\":\"https://docs.vumasign.com/api-reference/send-envelope#apireference\",\"headline\":\"Send a draft envelope to its recipients.\",\"name\":\"Send a draft envelope to its recipients.\",\"description\":\"THE SECOND HALF OF THE CREATED-VERSUS-SENT SPLIT. POST /api/v1/envelopes with \\\"send\\\": false makes a draft and emails nobody; this is how that draft goes out. Two acts an integrator can separate — build the envelope when a form is submitted, send it when a human approves — which is the arrangement a one-shot create cannot express without either sending too early or holding a request open. ⚠️ A SUB-RESOURCE AND NOT PATCH {\\\"status\\\": \\\"sent\\\"}. Sending emails people, consumes billing allowance and writes an audit event; making that look like editing a property would make an irreversible, billable act look reversible. 200, not 201. Nothing was created — the envelope existed before this call. A client branching on 201 to mean \\\"store this new id\\\" would be wrong here every time. ## The idempotency, which is the point ⚠️ Idempotency-Key IS REQUIRED. None of DocuSign, Dropbox Sign or BoldSign offers one on the endpoint that costs real money; this is that endpoint, and an optional guarantee is one nobody sends until they have already been burned. A REPLAY MEANS \\\"you already sent this, and here is what happened\\\" — the first attempt’s answer, byte for byte, with Idempotency-Replayed: true. Not a second send, not a resend, not a refusal. That is what makes a timeout safe to retry. A DIFFERENT ENVELOPE UNDER A USED KEY IS idempotency_key_reused, never a replay — including a key you already used to CREATE something. A key identifies one request. KEYS ARE REMEMBERED FOR 1 DAY, per organisation and per environment. Past that the same string is a new request — and a new request to send an envelope that has already gone out is envelope_not_draft, not a second send. Two mechanisms, and the second one is the database: draft → sent is a locked, one-way transition, so a duplicate send is impossible whatever the key says. The key decides what the second caller is TOLD. ## What it refuses A REFUSAL SENDS NOTHING AND CHANGES NOTHING. The envelope is left exactly as it was — unlike a refused \\\"send\\\": true on the create endpoint, which deletes the draft it had just built — and the idempotency key is freed, so a caller who upgrades their plan or fixes their roster retries with the same key. ⚠️ A vsk_test_ KEY MAY SEND ONLY A SANDBOX ENVELOPE — one a test key created — and only to people it may email. A draft a live key created is refused with test_key_cannot_send, and so is one whose emailed recipients include an address that is neither a member of your organisation nor a confirmed test recipient (Settings → Test recipients). An \\\"embedded\\\": true recipient is never emailed and is never checked. A test send consumes no allowance.\",\"url\":\"https://docs.vumasign.com/api-reference/send-envelope\",\"mainEntityOfPage\":{\"@id\":\"https://docs.vumasign.com/api-reference/send-envelope#webpage\"},\"dateModified\":\"2026-11-16T05:07:56.303Z\",\"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/send-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.","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.","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.","description":"MOVES `expires_at` LATER on an envelope that is out for signature. The envelope stays open until the new deadline and expires then, with `envelope.expired`, exactly as it would have at the old one.\n\n⚠️ NOBODY IS EMAILED AND NO LINK IS REPLACED. Every signing link keeps the life it was given when it was sent, which was never longer than the old deadline. A signer whose link stops working at the old deadline can ask for a fresh one from the page the link opens, and that one runs to the new deadline; so do the links in reminders. A signer who already has a shorter-lived link is unaffected.\n\n**Later, never earlier.** A deadline can only be extended: one that is not later than the current deadline, or a request for an envelope with no deadline, is `deadline_not_extendable`. The new deadline must also be within the bounds `POST /api/v1/envelopes` applies to `expires_at`: at least an hour from now, and at most a year from when the envelope was sent (`sent_at`), however many times it is extended. A deadline outside them is `invalid_request`.\n\n**A test key extends only a sandbox envelope.** A `vsk_test_` key naming an envelope a test key did not create is `test_key_cannot_extend`.\n\n**Only while it is still running.** A draft takes its deadline when it is created; a finished envelope has none left; and once a deadline has passed it cannot be extended, even before the envelope is marked `expired`. All three are `envelope_not_sent`.\n\nThe change is recorded in the envelope’s audit trail with both deadlines. No webhook event is sent for it: read the new deadline from the response, or from `GET /api/v1/envelopes/{envelopeId}`.\n\n**200, not 201.** Nothing was created.\n\n## The idempotency\n\n`Idempotency-Key` IS REQUIRED. A retry under the same key replays the first 200 rather than being refused because the deadline is no longer later. THE NEW DEADLINE IS PART OF THE KEY’S FINGERPRINT: the same key sent with a different `expires_at` is `idempotency_key_reused`.","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.","description":"THE ONE ENDPOINT IN THIS API THAT RETURNS A BEARER CREDENTIAL FOR A LEGAL ACT. Anyone holding the `url` can open the document as that signer. **Do not log it, cache it, store it or put it in a support ticket** — put it in an `iframe src` and nowhere else.\n\n⚠️ 10 MINUTES, AND SINGLE USE. The first GET spends it. A second GET within the 10 minutes renders a page that posts `signing_url_invalid` to your host page and signs nothing. A URL — opened or not — or the session it began, loaded after its lifetime is up (which the envelope’s deadline can shorten), renders the same kind of page and posts `signing_url_invalid` with `reason: \"expired\"` and `can_remint: true`, for 1 hour after that expiry; later than that it is refused a frame and posts nothing. Mint it when the signer arrives, not when the envelope is created — Dropbox Sign’s own advice, and the reason a recipient id is durable while a URL is not.\n\n⚠️ THE URL AND THE SESSION HAVE DIFFERENT LIVES. `expires_at` is when the URL stops being redeemable; a signer who redeems it just before then gets 1 hour from that moment to read and sign (or less, if the envelope’s deadline is sooner). Reload the iframe on this timer only if nobody ever opened it.\n\nFOUR THINGS MUST BE TRUE, and each has its own code: the envelope is open for signing, the recipient was created with `\"embedded\": true`, they have not already acted, and it is their turn (a later step is held back until the one before it finishes — `recipient_not_yet_turn` is a 409 and the identical call succeeds once it has).\n\n⚠️ A `vsk_test_` key may mint only on a sandbox envelope — one a test key created — and is refused `test_key_cannot_mint` on any other.\n\n## Framing\n\nThe page is served with `Content-Security-Policy: frame-ancestors ` naming the origins registered against the brand this envelope was sent under, and with **no** `X-Frame-Options`. Register those origins in Settings first; they must be bare — `https://example.com`, no trailing slash, no path, no wildcard — and an unregistered parent cannot frame the page at all. An expired URL or session we minted is framed for the same origins for 1 hour after it expires, so its refusal can reach you; it grants nothing, and after that it is refused. A URL we cannot verify — unreadable or altered — gets `X-Frame-Options: DENY` instead, and the ordinary emailed signing page keeps `X-Frame-Options: DENY` unconditionally.\n\n## Talking to your page\n\nThe iframe posts `{ action, ...payload }` to each registered origin, never to `*`. Actions: `ready`, `signed`, `declined`, `delegated`, `signing_url_invalid`. `signing_url_invalid` carries `can_remint` — branch on that, not on `reason`, or a signer who finishes in another tab turns your retry into an infinite loop.\n\n⚠️ `delegated` MEANS THEY HANDED IT TO SOMEBODY ELSE: this recipient is retired and a replacement holds their position, so take the iframe down — but the envelope is not finished. `recipient.delegated` follows on your webhook. By default the replacement is NOT embedded: we email them a signing link when their turn comes, and minting for them is refused. Only when the recipient was created with `delegates_stay_embedded: true` is the replacement embedded: then mint a URL for `delegate_recipient_id` when you want them to sign in your page.\n\n⚠️ **NEITHER A postMessage NOR A RETURN URL IS A COMPLETION SIGNAL, AND THERE IS NO `return_url` ON THIS ENDPOINT FOR EXACTLY THAT REASON.** `signed` is a browser event: the signer can close the tab, lose connectivity, or have any script on your own page forge it. **The webhook is authoritative.** Use these messages to move your interface — close the modal, navigate onwards — and use `recipient.completed` and `envelope.completed` to decide that a document was signed, to release goods, or to bill anybody. This is the mistake every first integration makes, and it is the one that is expensive.\n\nNO `Idempotency-Key`, unlike `POST /api/v1/envelopes`. A retry mints a second URL, which emails nobody and bills nothing — and the response IS the credential, so \"I do not know which state I am in\" is not reachable. ⚠️ Redeeming a second URL does revoke the session a first one began.\n\n## Saying where you will frame it\n\nSend `embed_origin` — the origin of the page the iframe goes on — and the mint is refused `embed_origin_not_registered` when that origin is not registered against the envelope’s brand, before anything is minted or recorded. Without it, an unregistered parent gets a URL that works and a frame the browser refuses: a blank box for the signer, and no response anywhere to say why. Omitting it changes nothing.","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":"Send a draft envelope to its recipients. - 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"]}