⚠️ THIS IS WHAT EVERY WEBHOOK BODY’S uri POINTS AT, AND WHY THAT FIELD EXISTS. A webhook payload is a snapshot of a moment; this is the resource. Anything you are about to do because of an event — release goods, bill somebody, advance a workflow — should be decided from a read here rather than from the body you were posted, because the body cannot have changed since it was written and the envelope can.
It is a safe GET: it writes nothing, mints nothing and takes no Idempotency-Key. Poll it if you must, but the webhook is the signal and this is the confirmation.
⚠️ invitation_delivered IS ANSWERED HERE FROM THE EVIDENCE, not left null. A recipient the provider has reported delivery for reads true weeks later, and a recipient nobody was ever meant to email — a cc, an embedded signer, somebody in a later step the envelope is still holding back — reads null. Those two are different facts and this endpoint keeps them different.
⚠️ AND THIS IS THE ENDPOINT TO RE-READ IT FROM, BECAUSE THE TWO ENDPOINTS MEAN DIFFERENT THINGS BY true AND THAT IS DELIBERATE. Here, true means THE PROVIDER REPORTED A DELIVERY, on the provider’s clock; an invitation the provider has merely accepted and not yet reported on reads false. POST .../send answers true for that same recipient — it is built from the answers the provider gave while the send was running, and acceptance is the only thing anybody knows at that moment. Its own description says so, and says it is the one place true means acceptance. So a recipient can read true from the send and false here seconds later, and neither answer is wrong: deciding anything real from the send response is deciding from a snapshot taken before the fact existed. Re-read here.
⚠️ FOUR SITUATIONS ANSWER WITH THE SAME 404: no such envelope anywhere; one belonging to another organisation; a draft that has since been deleted; and an id that is not a uuid. “It exists but is not yours” is itself the secret, and the handler could not tell the first two apart if it wanted to — the read runs inside a transaction already scoped to the key’s tenant.
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.
Path Parameters
envelopeId
string<uuid>
required
The envelope’s id, as returned by POST /api/v1/envelopes or carried as envelope_id on every webhook event.
An envelope id.
Example:
"01960000-0000-4000-8000-0000000000e5"
Response
The envelope, with its recipients in routing order.
The envelope.
id
string<uuid>
required
The envelope’s id. A bare uuid.
status
string
required
draft or sent from this endpoint. Later states arrive as people act.
template_id
string<uuid> | null
required
The template this was made from, or null when there was none — an envelope created by POST /api/v1/envelopes/one-off carries the document itself and never had a template. Branch on null, never on the empty string.
title
string
required
What the signers see naming the document. Defaults to the template’s name.
reference
string | null
required
The reference you set when you created it, in Unicode NFC, or null. Not unique, and never changed after creation.
Example:
"hire-2026-0917"
created_at
string<date-time>
required
ISO 8601, UTC.
sent_at
string<date-time> | null
required
ISO 8601, UTC. Null while it is a draft.
expires_at
string<date-time> | null
required
ISO 8601, UTC. Null when this envelope has no deadline, which is the default. Read back from the stored value rather than echoed, so an offset you sent comes back as the same instant in UTC.
recipients
object[]
required
In routing order.
Show child attributes
subjects
object[]
required
Who the envelope is about, such as a spouse or a dependant, in the order they were declared: the subject a value names. A one-off’s come from setting it up in the editor; an envelope made from a template has its template’s. Empty when the envelope is about nobody in particular.
Show child attributes
roles_left_out
object[]
required
The optional roles this envelope was sent without (Role.presence is optional on its template, and nobody was named for the role: no recipient in the request, or only an empty slot on a draft prepared in the dashboard). Each was left out when the envelope was sent, with every field it held, and the sealed certificate lists it as not on the envelope. Only a role that held fields is listed: one with none has nothing to leave out. Empty before the envelope is sent and for a one-off.
Show child attributes
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"Vumasign","description":"The Vumasign API: templates, envelopes, embedded signing and signed webhooks.","colors":{"primary":"#00827B","light":"#30B3AB","dark":"#00827B"},"logo":{"light":"https://mintcdn.com/vumasign/TFhwDypOVkWX-C3j/logo/vumasign.svg?fit=max\u0026auto=format\u0026n=TFhwDypOVkWX-C3j\u0026q=85\u0026s=f5e34bf1faf4c64eaa58dee0553702d6","dark":"https://mintcdn.com/vumasign/TFhwDypOVkWX-C3j/logo/vumasign-dark.svg?fit=max\u0026auto=format\u0026n=TFhwDypOVkWX-C3j\u0026q=85\u0026s=6288e3bd6e02af7f9ef27aa71b7df32c","href":"https://vumasign.com"},"favicon":"https://mintcdn.com/vumasign/TFhwDypOVkWX-C3j/logo/favicon.svg?fit=max\u0026auto=format\u0026n=TFhwDypOVkWX-C3j\u0026q=85\u0026s=ca1830bf11181e8ce259f0ca820ba7a9","api":{"openapi":"openapi.json","playground":{"display":"interactive"},"examples":{"defaults":"required","languages":["curl","python","javascript","go"],"prefill":true}},"background":{"color":{"light":"#F7F7F8","dark":"#0F1419"}},"navbar":{"primary":{"type":"button","label":"Get an API key","href":"https://app.vumasign.com/settings/api-keys"}},"fonts":{"family":"Inter"},"icons":{"library":"lucide"},"styling":{"latex":false},"navigation":{"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"vumasign","hasAudioNarration":false,"actualSubdomain":"vumasign","customDomains":["docs.vumasign.com"],"gitSource":{"type":"github","owner":"hellocrowd","repo":"vumasign","deployBranch":"main","contentDirectory":"docs-site","isPrivate":true,"mountPath":"","label":""},"entitlements":{"AI_CHAT":{"status":"DISABLED"},"WEB_MCP":{"status":"DISABLED"},"NARRATION":{"status":"DISABLED"}},"buildId":"6afa8fa53b9b1d7bae84e26b","clientVersion":"0.0.4160","searchFilterCounts":[{"language":"default","tag":"API reference","count":49},{"language":"default","tag":"Guides","count":34},{"language":"default","tag":"Concepts","count":17},{"language":"default","tag":"Templates","count":17},{"language":"default","tag":"Envelopes","count":12},{"language":"default","tag":"Standing authorisations","count":7},{"language":"default","tag":"Webhooks","count":6},{"language":"default","tag":"Get started","count":5},{"language":"default","tag":"Brands","count":4},{"language":"default","tag":"Documents","count":2}]},"assistantConfig":{"enableAskAiButton":false,"enableStarterQuestions":false,"enableContextualStarterQuestions":false,"enableAskAiSearchBar":true},"basePath":"","hasChatPermissions":false,"hasWebMcpPermissions":false,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-rbac-roles","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"rbac-expansion","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"full-page-search","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-sso-scim","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-signup","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-dual-write","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"approve-review-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-metadata","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"sso-setup-deadline-banner","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-serve","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"live-agents","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"googleFontsInlined":false},"customCss":[],"page":{"pagePath":"api-reference/get-envelope","slug":"/api-reference/get-envelope","pageMetadata":{"title":"One envelope, as it stands right now.","description":"⚠️ **THIS IS WHAT EVERY WEBHOOK BODY’S `uri` POINTS AT, AND WHY THAT FIELD EXISTS.** A webhook payload is a snapshot of a moment; this is the resource. Anything you are about to do because of an event — release goods, bill somebody, advance a workflow — should be decided from a read here rather than from the body you were posted, because the body cannot have changed since it was written and the envelope can.\n\nIt is a safe GET: it writes nothing, mints nothing and takes no `Idempotency-Key`. Poll it if you must, but the webhook is the signal and this is the confirmation.\n\n⚠️ `invitation_delivered` IS ANSWERED HERE FROM THE EVIDENCE, not left null. A recipient the provider has reported delivery for reads `true` weeks later, and a recipient nobody was ever meant to email — a `cc`, an embedded signer, somebody in a later step the envelope is still holding back — reads `null`. Those two are different facts and this endpoint keeps them different.\n\n⚠️ AND THIS IS THE ENDPOINT TO RE-READ IT FROM, BECAUSE THE TWO ENDPOINTS MEAN DIFFERENT THINGS BY `true` AND THAT IS DELIBERATE. Here, `true` means THE PROVIDER REPORTED A DELIVERY, on the provider’s clock; an invitation the provider has merely accepted and not yet reported on reads `false`. `POST .../send` answers `true` for that same recipient — it is built from the answers the provider gave while the send was running, and acceptance is the only thing anybody knows at that moment. Its own description says so, and says it is the one place `true` means acceptance. So a recipient can read `true` from the send and `false` here seconds later, and neither answer is wrong: deciding anything real from the send response is deciding from a snapshot taken before the fact existed. Re-read here.\n\n⚠️ FOUR SITUATIONS ANSWER WITH THE SAME 404: no such envelope anywhere; one belonging to another organisation; a draft that has since been deleted; and an id that is not a uuid. \"It exists but is not yours\" is itself the secret, and the handler could not tell the first two apart if it wanted to — the read runs inside a transaction already scoped to the key’s tenant.\n\nA `vsk_test_` key may read. Reading emails nobody.","deprecated":null,"version":null,"sidebarTitle":"Get envelope","openapi":"/openapi.json get /api/v1/envelopes/{envelopeId}","href":"/api-reference/get-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 p: \"p\",\n strong: \"strong\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsxs(_Fragment, {\n children: [_jsxs(_components.p, {\n children: [\"⚠️ \", _jsxs(_components.strong, {\n children: [\"THIS IS WHAT EVERY WEBHOOK BODY’S \", _jsx(_components.code, {\n children: \"uri\"\n }), \" POINTS AT, AND WHY THAT FIELD EXISTS.\"]\n }), \" A webhook payload is a snapshot of a moment; this is the resource. Anything you are about to do because of an event — release goods, bill somebody, advance a workflow — should be decided from a read here rather than from the body you were posted, because the body cannot have changed since it was written and the envelope can.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"It is a safe GET: it writes nothing, mints nothing and takes no \", _jsx(_components.code, {\n children: \"Idempotency-Key\"\n }), \". Poll it if you must, but the webhook is the signal and this is the confirmation.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"⚠️ \", _jsx(_components.code, {\n children: \"invitation_delivered\"\n }), \" IS ANSWERED HERE FROM THE EVIDENCE, not left null. A recipient the provider has reported delivery for reads \", _jsx(_components.code, {\n children: \"true\"\n }), \" weeks later, and a recipient nobody was ever meant to email — a \", _jsx(_components.code, {\n children: \"cc\"\n }), \", an embedded signer, somebody in a later step the envelope is still holding back — reads \", _jsx(_components.code, {\n children: \"null\"\n }), \". Those two are different facts and this endpoint keeps them different.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"⚠️ AND THIS IS THE ENDPOINT TO RE-READ IT FROM, BECAUSE THE TWO ENDPOINTS MEAN DIFFERENT THINGS BY \", _jsx(_components.code, {\n children: \"true\"\n }), \" AND THAT IS DELIBERATE. Here, \", _jsx(_components.code, {\n children: \"true\"\n }), \" means THE PROVIDER REPORTED A DELIVERY, on the provider’s clock; an invitation the provider has merely accepted and not yet reported on reads \", _jsx(_components.code, {\n children: \"false\"\n }), \". \", _jsx(_components.code, {\n children: \"POST .../send\"\n }), \" answers \", _jsx(_components.code, {\n children: \"true\"\n }), \" for that same recipient — it is built from the answers the provider gave while the send was running, and acceptance is the only thing anybody knows at that moment. Its own description says so, and says it is the one place \", _jsx(_components.code, {\n children: \"true\"\n }), \" means acceptance. So a recipient can read \", _jsx(_components.code, {\n children: \"true\"\n }), \" from the send and \", _jsx(_components.code, {\n children: \"false\"\n }), \" here seconds later, and neither answer is wrong: deciding anything real from the send response is deciding from a snapshot taken before the fact existed. Re-read here.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"⚠️ FOUR SITUATIONS ANSWER WITH THE SAME 404: no such envelope anywhere; one belonging to another organisation; a draft that has since been deleted; and an id that is not a uuid. “It exists but is not yours” is itself the secret, and the handler could not tell the first two apart if it wanted to — the read runs inside a transaction already scoped to the key’s tenant.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"A \", _jsx(_components.code, {\n children: \"vsk_test_\"\n }), \" key may read. Reading emails nobody.\"]\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":"One envelope, as it stands right now.","description":"⚠️ **THIS IS WHAT EVERY WEBHOOK BODY’S `uri` POINTS AT, AND WHY THAT FIELD EXISTS.** A webhook payload is a snapshot of a moment; this is the resource. Anything you are about to do because of an event — release goods, bill somebody, advance a workflow — should be decided from a read here rather than from the body you were posted, because the body cannot have changed since it was written and the envelope can.\n\nIt is a safe GET: it writes nothing, mints nothing and takes no `Idempotency-Key`. Poll it if you must, but the webhook is the signal and this is the confirmation.\n\n⚠️ `invitation_delivered` IS ANSWERED HERE FROM THE EVIDENCE, not left null. A recipient the provider has reported delivery for reads `true` weeks later, and a recipient nobody was ever meant to email — a `cc`, an embedded signer, somebody in a later step the envelope is still holding back — reads `null`. Those two are different facts and this endpoint keeps them different.\n\n⚠️ AND THIS IS THE ENDPOINT TO RE-READ IT FROM, BECAUSE THE TWO ENDPOINTS MEAN DIFFERENT THINGS BY `true` AND THAT IS DELIBERATE. Here, `true` means THE PROVIDER REPORTED A DELIVERY, on the provider’s clock; an invitation the provider has merely accepted and not yet reported on reads `false`. `POST .../send` answers `true` for that same recipient — it is built from the answers the provider gave while the send was running, and acceptance is the only thing anybody knows at that moment. Its own description says so, and says it is the one place `true` means acceptance. So a recipient can read `true` from the send and `false` here seconds later, and neither answer is wrong: deciding anything real from the send response is deciding from a snapshot taken before the fact existed. Re-read here.\n\n⚠️ FOUR SITUATIONS ANSWER WITH THE SAME 404: no such envelope anywhere; one belonging to another organisation; a draft that has since been deleted; and an id that is not a uuid. \"It exists but is not yours\" is itself the secret, and the handler could not tell the first two apart if it wanted to — the read runs inside a transaction already scoped to the key’s tenant.\n\nA `vsk_test_` key may read. Reading emails nobody.","deprecated":null,"version":null,"sidebarTitle":"Get envelope","openapi":"/openapi.json get /api/v1/envelopes/{envelopeId}","href":"/api-reference/get-envelope","autogeneratedByOpenApi":true}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[],"codeExamples":{}},"jsLinks":[],"openApiReferenceData":{"operation":{"operationId":"getEnvelope","tags":["Envelopes"],"x-mint":{"href":"/api-reference/get-envelope"},"summary":"One envelope, as it stands right now.","description":"⚠️ **THIS IS WHAT EVERY WEBHOOK BODY’S `uri` POINTS AT, AND WHY THAT FIELD EXISTS.** A webhook payload is a snapshot of a moment; this is the resource. Anything you are about to do because of an event — release goods, bill somebody, advance a workflow — should be decided from a read here rather than from the body you were posted, because the body cannot have changed since it was written and the envelope can.\n\nIt is a safe GET: it writes nothing, mints nothing and takes no `Idempotency-Key`. Poll it if you must, but the webhook is the signal and this is the confirmation.\n\n⚠️ `invitation_delivered` IS ANSWERED HERE FROM THE EVIDENCE, not left null. A recipient the provider has reported delivery for reads `true` weeks later, and a recipient nobody was ever meant to email — a `cc`, an embedded signer, somebody in a later step the envelope is still holding back — reads `null`. Those two are different facts and this endpoint keeps them different.\n\n⚠️ AND THIS IS THE ENDPOINT TO RE-READ IT FROM, BECAUSE THE TWO ENDPOINTS MEAN DIFFERENT THINGS BY `true` AND THAT IS DELIBERATE. Here, `true` means THE PROVIDER REPORTED A DELIVERY, on the provider’s clock; an invitation the provider has merely accepted and not yet reported on reads `false`. `POST .../send` answers `true` for that same recipient — it is built from the answers the provider gave while the send was running, and acceptance is the only thing anybody knows at that moment. Its own description says so, and says it is the one place `true` means acceptance. So a recipient can read `true` from the send and `false` here seconds later, and neither answer is wrong: deciding anything real from the send response is deciding from a snapshot taken before the fact existed. Re-read here.\n\n⚠️ FOUR SITUATIONS ANSWER WITH THE SAME 404: no such envelope anywhere; one belonging to another organisation; a draft that has since been deleted; and an id that is not a uuid. \"It exists but is not yours\" is itself the secret, and the handler could not tell the first two apart if it wanted to — the read runs inside a transaction already scoped to the key’s tenant.\n\nA `vsk_test_` key may read. Reading emails nobody.","security":["b2cf0f5c-441d-4c24-a30d-a8465199be4c"],"x-required-scope":"envelopes:read","parameters":["8df087e6-fd29-408d-adbc-aa181da96132"],"responses":{"200":"6d07e14a-7721-4738-ac5c-63a117d51ed3","401":"507cc2bd-9ad5-45ae-a65a-9f12414d65ef","403":"a7b83491-1b90-4b9e-a37a-d9bf78471aa3","404":"39fc74bc-a259-4447-8c95-06de107467eb","429":"8ebea358-7cad-4a7e-93de-49780706dc1c","500":"893ab7e5-dbc1-49a5-a2ea-b3d55244f558"},"method":"get","type":"path","servers":["2ed67dbf-843b-4ce0-93c8-8c35248fcb3e"],"path":"/api/v1/envelopes/{envelopeId}","baseUrlOptions":["https://app.vumasign.com"],"title":"One envelope, as it stands right now.","codeSamples":[],"requestExampleLanguages":["bash","python","javascript","go"],"requiredOnlyExamples":true,"requestExampleType":"generated","responseExampleType":"generated","prefillPlaygroundWithExample":true,"prefillPlaygroundExamples":[]},"dependencies":{"parameters":{"8df087e6-fd29-408d-adbc-aa181da96132":{"name":"envelopeId","in":"path","required":true,"description":"The envelope’s `id`, as returned by `POST /api/v1/envelopes` or carried as `envelope_id` on every webhook event.","schema":{"type":"string","format":"uuid","examples":["01960000-0000-4000-8000-0000000000e5"],"description":"The envelope’s `id`, as returned by `POST /api/v1/envelopes` or carried as `envelope_id` on every webhook event.\nAn envelope id.","isRequired":true,"uniqueKey":"","typeLabel":"string\u003cuuid>"}}},"responses":{"6d07e14a-7721-4738-ac5c-63a117d51ed3":{"description":"The envelope, with its recipients in routing order.","content":{"application/json":{"schema":{"type":"object","description":"The envelope.","properties":{"id":{"type":"string","format":"uuid","description":"The envelope’s id. A bare uuid.","isRequired":true,"uniqueKey":"id","typeLabel":"string\u003cuuid>"},"status":{"type":"string","description":"`draft` or `sent` from this endpoint. Later states arrive as people act.","isRequired":true,"uniqueKey":"status","typeLabel":"string"},"template_id":{"oneOf":[{"type":"string","format":"uuid","description":"The template this was made from, or `null` when there was none — an envelope created by `POST /api/v1/envelopes/one-off` carries the document itself and never had a template. Branch on `null`, never on the empty string.","isRequired":true,"uniqueKey":"template_id.oneOf.0","typeLabel":"string\u003cuuid>"},{"type":"null","format":"uuid","description":"The template this was made from, or `null` when there was none — an envelope created by `POST /api/v1/envelopes/one-off` carries the document itself and never had a template. Branch on `null`, never on the empty string.","isRequired":true,"uniqueKey":"template_id.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"template_id","typeLabel":"string\u003cuuid> | null"},"title":{"type":"string","description":"What the signers see naming the document. Defaults to the template’s name.","isRequired":true,"uniqueKey":"title","typeLabel":"string"},"reference":{"oneOf":[{"type":"string","examples":["hire-2026-0917"],"description":"The `reference` you set when you created it, in Unicode NFC, or `null`. Not unique, and never changed after creation.","isRequired":true,"uniqueKey":"reference.oneOf.0","typeLabel":"string"},{"type":"null","examples":["hire-2026-0917"],"description":"The `reference` you set when you created it, in Unicode NFC, or `null`. Not unique, and never changed after creation.","isRequired":true,"uniqueKey":"reference.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"reference","typeLabel":"string | null"},"created_at":{"type":"string","format":"date-time","description":"ISO 8601, UTC.","isRequired":true,"uniqueKey":"created_at","typeLabel":"string\u003cdate-time>"},"sent_at":{"oneOf":[{"type":"string","format":"date-time","description":"ISO 8601, UTC. Null while it is a draft.","isRequired":true,"uniqueKey":"sent_at.oneOf.0","typeLabel":"string\u003cdate-time>"},{"type":"null","format":"date-time","description":"ISO 8601, UTC. Null while it is a draft.","isRequired":true,"uniqueKey":"sent_at.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"sent_at","typeLabel":"string\u003cdate-time> | null"},"expires_at":{"oneOf":[{"type":"string","format":"date-time","description":"ISO 8601, UTC. Null when this envelope has no deadline, which is the default. Read back from the stored value rather than echoed, so an offset you sent comes back as the same instant in UTC.","isRequired":true,"uniqueKey":"expires_at.oneOf.0","typeLabel":"string\u003cdate-time>"},{"type":"null","format":"date-time","description":"ISO 8601, UTC. Null when this envelope has no deadline, which is the default. Read back from the stored value rather than echoed, so an offset you sent comes back as the same instant in UTC.","isRequired":true,"uniqueKey":"expires_at.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"expires_at","typeLabel":"string\u003cdate-time> | null"},"recipients":{"type":"array","description":"In routing order.","items":{"type":"object","description":"One recipient.","properties":{"id":{"type":"string","format":"uuid","description":"This recipient. Published where a template ROLE’s id deliberately is not, because a recipient has no natural key — one person may hold two roles and two people may hold one.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].id","typeLabel":"string\u003cuuid>"},"role":{"type":"string","description":"The template role they were given.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].role","typeLabel":"string"},"name":{"oneOf":[{"type":"string","description":"As stored, after normalisation. `null` only while the envelope is a `draft` and nobody has been named for this role yet (a draft prepared in the dashboard); every sent recipient has a name.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].name.oneOf.0","typeLabel":"string"},{"type":"null","description":"As stored, after normalisation. `null` only while the envelope is a `draft` and nobody has been named for this role yet (a draft prepared in the dashboard); every sent recipient has a name.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].name.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"recipients.items.[INDEX].name","typeLabel":"string | null"},"email":{"oneOf":[{"type":"string","format":"email","description":"As stored, after normalisation. `null` only while the envelope is a `draft` and nobody has been named for this role yet; every sent recipient has an address. A copied-in recipient with no address when the envelope is sent is left off it.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].email.oneOf.0","typeLabel":"string\u003cemail>"},{"type":"null","format":"email","description":"As stored, after normalisation. `null` only while the envelope is a `draft` and nobody has been named for this role yet; every sent recipient has an address. A copied-in recipient with no address when the envelope is sent is left off it.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].email.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"recipients.items.[INDEX].email","typeLabel":"string\u003cemail> | null"},"routing_type":{"type":"string","enum":["sign","approve","cc"],"description":"⚠️ FROM THE TEMPLATE, NEVER FROM THE REQUEST. Whether a role signs, approves or is copied in is part of the layout (§3), and a caller who could override it could send a document whose signature boxes nobody will ever be asked to fill.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].routing_type","typeLabel":"enum\u003cstring>"},"status":{"type":"string","description":"`recipients.status` verbatim. ⚠️ `pending` AFTER A SUCCESSFUL SEND IS NORMAL: an envelope in steps invites only its lowest unfinished step and holds the rest back until that step is finished.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].status","typeLabel":"string"},"invitation_delivered":{"oneOf":[{"type":"boolean","description":"Whether the email provider reports the invitation as DELIVERED. `null` when none was attempted — a draft, a `cc`, an embedded recipient, or a position held back.\n\n⚠️ ON A READ, THIS NO LONGER ANSWERS `true` AS SOON AS THE SEND RETURNS, and it used to. Accepting a message and delivering it are different events: we now record delivery only when the provider tells us it happened, on the provider's clock. A just-sent invitation therefore reads `false` on `GET /api/v1/envelopes/{id}` and turns `true` seconds to minutes later.\n\n⚠️ THE ONE EXCEPTION IS THE RESPONSE TO `POST .../send` ITSELF, where `true` means the provider ACCEPTED the message — the only thing anybody knows while the send is still running. That operation’s response description says so at length. The same recipient can therefore read `true` from the send and `false` from a read a second later; the read is the one to decide from.\n\n⚠️ `false` IS NOT A BOUNCE. It covers both \"the provider refused the send\" and \"we have not been told yet\", and you cannot tell those apart from this field — do not surface it to a human as a failure. `null` is the only value that has never changed meaning: nothing was attempted.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].invitation_delivered.oneOf.0","typeLabel":"boolean"},{"type":"null","description":"Whether the email provider reports the invitation as DELIVERED. `null` when none was attempted — a draft, a `cc`, an embedded recipient, or a position held back.\n\n⚠️ ON A READ, THIS NO LONGER ANSWERS `true` AS SOON AS THE SEND RETURNS, and it used to. Accepting a message and delivering it are different events: we now record delivery only when the provider tells us it happened, on the provider's clock. A just-sent invitation therefore reads `false` on `GET /api/v1/envelopes/{id}` and turns `true` seconds to minutes later.\n\n⚠️ THE ONE EXCEPTION IS THE RESPONSE TO `POST .../send` ITSELF, where `true` means the provider ACCEPTED the message — the only thing anybody knows while the send is still running. That operation’s response description says so at length. The same recipient can therefore read `true` from the send and `false` from a read a second later; the read is the one to decide from.\n\n⚠️ `false` IS NOT A BOUNCE. It covers both \"the provider refused the send\" and \"we have not been told yet\", and you cannot tell those apart from this field — do not surface it to a human as a failure. `null` is the only value that has never changed meaning: nothing was attempted.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].invitation_delivered.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"recipients.items.[INDEX].invitation_delivered","typeLabel":"boolean | null"},"embedded":{"type":"boolean","description":"Whether this recipient is reached by a minted signing URL instead of by email. ⚠️ RETURNED HERE PRECISELY BECAUSE DocuSign DOES NOT RETURN THEIRS: `clientUserId` is absent from their list endpoints, so an integrator who lost their own record of which recipients were embedded has no way to ask. When this is true, `invitation_delivered` is always `null` — nothing was attempted, and nothing was meant to be.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].embedded","typeLabel":"boolean"},"delegates_stay_embedded":{"type":"boolean","description":"Whether a person this recipient delegates to is kept embedded. Only ever `true` beside `embedded: true`: you sent it at creation, or this recipient took the place of one who had it (their delegate, a correction, or a new person in the same draft slot). When it is `false`, the delegate of an embedded recipient is emailed a signing link like any other recipient, and appears here as a new recipient with `embedded: false`.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].delegates_stay_embedded","typeLabel":"boolean"},"external_ref":{"oneOf":[{"type":"string","description":"Whatever you supplied at creation, normalised to Unicode NFC, or `null`: compare it in NFC, not byte for byte. Opaque to us and joined on by nothing — it is here so a webhook or this response can be matched to your own record of the same human without a side table.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].external_ref.oneOf.0","typeLabel":"string"},{"type":"null","description":"Whatever you supplied at creation, normalised to Unicode NFC, or `null`: compare it in NFC, not byte for byte. Opaque to us and joined on by nothing — it is here so a webhook or this response can be matched to your own record of the same human without a side table.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].external_ref.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"recipients.items.[INDEX].external_ref","typeLabel":"string | null"},"verification_method":{"type":"string","enum":["none","email_code","mobile_code","identity_check"],"description":"What this recipient must prove before the document opens, read back from the recipient as it was created — `none` when the request did not say, and `mobile_code` for a recipient created with the deprecated `sms_code`. Fixed once the envelope is sent. ⚠️ IT SAYS WHAT WAS ASKED, NOT WHETHER THEY HAVE DONE IT: whether a code was entered is in the audit trail and on the certificate of completion.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].verification_method","typeLabel":"enum\u003cstring>"},"mobile":{"oneOf":[{"type":"string","examples":["+27821234567"],"description":"The mobile a `mobile_code` recipient’s code is sent to, in E.164 as stored (`+27821234567`), returned in full because it is your own data. `null` for every other method. Fixed once the envelope is sent: a wrong number is fixed by correcting the recipient.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].mobile.oneOf.0","typeLabel":"string"},{"type":"null","examples":["+27821234567"],"description":"The mobile a `mobile_code` recipient’s code is sent to, in E.164 as stored (`+27821234567`), returned in full because it is your own data. `null` for every other method. Fixed once the envelope is sent: a wrong number is fixed by correcting the recipient.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].mobile.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"recipients.items.[INDEX].mobile","typeLabel":"string | null"},"identity_check":{"oneOf":[{"type":"object","description":"On a recipient asked for an identity check, what was asked: the documents they may use (`routes`) and the ID you said to expect, as its kind, its last digits behind bullets (`masked`) and a passport’s country — ⚠️ never the number, which is not stored — and, once the check has finished, how it ended (`outcome`). `null` for every other method.","properties":{"routes":{"type":"string","enum":["either","sa_id","passport"],"description":"The documents they may use.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].identity_check.oneOf.0.routes","typeLabel":"enum\u003cstring>"},"expected_id":{"oneOf":[{"type":"object","description":"The ID you said to expect, masked, or `null` when you gave none.","properties":{"kind":{"type":"string","enum":["sa_id","passport"],"description":"An SA ID number, or a passport number.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].identity_check.oneOf.0.expected_id.oneOf.0.kind","typeLabel":"enum\u003cstring>"},"masked":{"type":"string","examples":["•••••••••0087"],"description":"Its last digits behind bullets.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].identity_check.oneOf.0.expected_id.oneOf.0.masked","typeLabel":"string"},"country":{"oneOf":[{"type":"string","description":"A passport’s issuing country (ISO 3166 alpha-3); `null` for an SA ID.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].identity_check.oneOf.0.expected_id.oneOf.0.country.oneOf.0","typeLabel":"string"},{"type":"null","description":"A passport’s issuing country (ISO 3166 alpha-3); `null` for an SA ID.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].identity_check.oneOf.0.expected_id.oneOf.0.country.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"recipients.items.[INDEX].identity_check.oneOf.0.expected_id.oneOf.0.country","typeLabel":"string | null"}},"required":["kind","masked","country"],"isRequired":true,"uniqueKey":"recipients.items.[INDEX].identity_check.oneOf.0.expected_id.oneOf.0","typeLabel":"object"},{"type":"null","description":"The ID you said to expect, masked, or `null` when you gave none.","properties":{"kind":{"type":"string","enum":["sa_id","passport"],"description":"An SA ID number, or a passport number."},"masked":{"type":"string","examples":["•••••••••0087"],"description":"Its last digits behind bullets."},"country":{"oneOf":[{"type":"string","description":"A passport’s issuing country (ISO 3166 alpha-3); `null` for an SA ID."},{"type":"null","description":"A passport’s issuing country (ISO 3166 alpha-3); `null` for an SA ID."}]}},"required":["kind","masked","country"],"isRequired":true,"uniqueKey":"recipients.items.[INDEX].identity_check.oneOf.0.expected_id.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"recipients.items.[INDEX].identity_check.oneOf.0.expected_id","typeLabel":"object | null"},"outcome":{"oneOf":[{"type":"object","description":"`null` until the check finishes; then how it ended, from the same record the certificate of completion is built from. `recipient.identity_verified` and `recipient.identity_check_failed` are the webhooks that say when. ⚠️ Never the ID or passport number, a score, a photo or the name on the document: only the masked number and the name verdict.","properties":{"status":{"type":"string","enum":["passed","failed"],"description":"`passed`, or `failed` when the check cannot finish.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].identity_check.oneOf.0.outcome.oneOf.0.status","typeLabel":"enum\u003cstring>"},"reason":{"oneOf":[{"type":"string","enum":["attempts_exhausted","id_mismatch","cannot_use_camera",null],"description":"On `failed`, why: the same `reason` the `recipient.identity_check_failed` webhook carries. `null` on `passed`.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].identity_check.oneOf.0.outcome.oneOf.0.reason.oneOf.0","typeLabel":"enum\u003cstring>"},{"type":"null","enum":["attempts_exhausted","id_mismatch","cannot_use_camera",null],"description":"On `failed`, why: the same `reason` the `recipient.identity_check_failed` webhook carries. `null` on `passed`.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].identity_check.oneOf.0.outcome.oneOf.0.reason.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"recipients.items.[INDEX].identity_check.oneOf.0.outcome.oneOf.0.reason","typeLabel":"enum\u003cstring> | null"},"completed_at":{"type":"string","format":"date-time","description":"When it passed or failed.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].identity_check.oneOf.0.outcome.oneOf.0.completed_at","typeLabel":"string\u003cdate-time>"},"route":{"oneOf":[{"type":"string","enum":["sa_id","passport",null],"description":"The route the signer took. `null` on `failed`.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].identity_check.oneOf.0.outcome.oneOf.0.route.oneOf.0","typeLabel":"enum\u003cstring>"},{"type":"null","enum":["sa_id","passport",null],"description":"The route the signer took. `null` on `failed`.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].identity_check.oneOf.0.outcome.oneOf.0.route.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"recipients.items.[INDEX].identity_check.oneOf.0.outcome.oneOf.0.route","typeLabel":"enum\u003cstring> | null"},"document":{"oneOf":[{"type":"object","description":"The document checked, masked. `null` on `failed`.","properties":{"kind":{"type":"string","enum":["smart_id_card","id_book","passport"],"description":"A Smart ID card, a green ID book, or a passport.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].identity_check.oneOf.0.outcome.oneOf.0.document.oneOf.0.kind","typeLabel":"enum\u003cstring>"},"masked":{"type":"string","examples":["•••••••••0087"],"description":"Its number’s last digits behind bullets.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].identity_check.oneOf.0.outcome.oneOf.0.document.oneOf.0.masked","typeLabel":"string"},"country":{"oneOf":[{"type":"string","description":"A passport’s issuing country (ISO 3166 alpha-3); `null` for an SA ID.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].identity_check.oneOf.0.outcome.oneOf.0.document.oneOf.0.country.oneOf.0","typeLabel":"string"},{"type":"null","description":"A passport’s issuing country (ISO 3166 alpha-3); `null` for an SA ID.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].identity_check.oneOf.0.outcome.oneOf.0.document.oneOf.0.country.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"recipients.items.[INDEX].identity_check.oneOf.0.outcome.oneOf.0.document.oneOf.0.country","typeLabel":"string | null"}},"required":["kind","masked","country"],"isRequired":true,"uniqueKey":"recipients.items.[INDEX].identity_check.oneOf.0.outcome.oneOf.0.document.oneOf.0","typeLabel":"object"},{"type":"null","description":"The document checked, masked. `null` on `failed`.","properties":{"kind":{"type":"string","enum":["smart_id_card","id_book","passport"],"description":"A Smart ID card, a green ID book, or a passport."},"masked":{"type":"string","examples":["•••••••••0087"],"description":"Its number’s last digits behind bullets."},"country":{"oneOf":[{"type":"string","description":"A passport’s issuing country (ISO 3166 alpha-3); `null` for an SA ID."},{"type":"null","description":"A passport’s issuing country (ISO 3166 alpha-3); `null` for an SA ID."}]}},"required":["kind","masked","country"],"isRequired":true,"uniqueKey":"recipients.items.[INDEX].identity_check.oneOf.0.outcome.oneOf.0.document.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"recipients.items.[INDEX].identity_check.oneOf.0.outcome.oneOf.0.document","typeLabel":"object | null"},"expected_id_matched":{"oneOf":[{"type":"boolean","description":"`true` when you gave an `expected_id` of this route’s kind and the document’s number matched it; `false` when you gave none for this route. `null` on `failed` (a number that did not match fails as `id_mismatch`).","isRequired":true,"uniqueKey":"recipients.items.[INDEX].identity_check.oneOf.0.outcome.oneOf.0.expected_id_matched.oneOf.0","typeLabel":"boolean"},{"type":"null","description":"`true` when you gave an `expected_id` of this route’s kind and the document’s number matched it; `false` when you gave none for this route. `null` on `failed` (a number that did not match fails as `id_mismatch`).","isRequired":true,"uniqueKey":"recipients.items.[INDEX].identity_check.oneOf.0.outcome.oneOf.0.expected_id_matched.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"recipients.items.[INDEX].identity_check.oneOf.0.outcome.oneOf.0.expected_id_matched","typeLabel":"boolean | null"},"name_match":{"oneOf":[{"type":"string","enum":["match","partial","mismatch",null],"description":"The name on the document against the recipient’s `name`. Names are compared ignoring case, accents, spacing, apostrophes and full stops, with a hyphen read as a space, word by word and in any order. `match`: the surname on the document is in the name you gave, and one side’s given names are all in the other’s (a second name missing on either side is fine). `partial`: the surname matches but a given name differs only by an initial (J for John) or is missing, or the given names match and the surname differs (a maiden or married name). `mismatch`: anything else. `null`: no usable name on the document, or none on the recipient. A name never fails the check. `null` on `failed`.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].identity_check.oneOf.0.outcome.oneOf.0.name_match.oneOf.0","typeLabel":"enum\u003cstring>"},{"type":"null","enum":["match","partial","mismatch",null],"description":"The name on the document against the recipient’s `name`. Names are compared ignoring case, accents, spacing, apostrophes and full stops, with a hyphen read as a space, word by word and in any order. `match`: the surname on the document is in the name you gave, and one side’s given names are all in the other’s (a second name missing on either side is fine). `partial`: the surname matches but a given name differs only by an initial (J for John) or is missing, or the given names match and the surname differs (a maiden or married name). `mismatch`: anything else. `null`: no usable name on the document, or none on the recipient. A name never fails the check. `null` on `failed`.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].identity_check.oneOf.0.outcome.oneOf.0.name_match.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"recipients.items.[INDEX].identity_check.oneOf.0.outcome.oneOf.0.name_match","typeLabel":"enum\u003cstring> | null"},"provider":{"type":"string","enum":["verifynow"],"description":"Who checked it.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].identity_check.oneOf.0.outcome.oneOf.0.provider","typeLabel":"enum\u003cstring>"},"provider_reference":{"oneOf":[{"type":"string","description":"VerifyNow’s reference for the face match, which the certificate prints; `null` when it gave none, and on `failed`.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].identity_check.oneOf.0.outcome.oneOf.0.provider_reference.oneOf.0","typeLabel":"string"},{"type":"null","description":"VerifyNow’s reference for the face match, which the certificate prints; `null` when it gave none, and on `failed`.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].identity_check.oneOf.0.outcome.oneOf.0.provider_reference.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"recipients.items.[INDEX].identity_check.oneOf.0.outcome.oneOf.0.provider_reference","typeLabel":"string | null"},"test_mode":{"type":"boolean","description":"A test envelope’s check: VerifyNow’s sandbox returned a sample result.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].identity_check.oneOf.0.outcome.oneOf.0.test_mode","typeLabel":"boolean"}},"required":["status","reason","completed_at","route","document","expected_id_matched","name_match","provider","provider_reference","test_mode"],"isRequired":true,"uniqueKey":"recipients.items.[INDEX].identity_check.oneOf.0.outcome.oneOf.0","typeLabel":"object"},{"type":"null","description":"`null` until the check finishes; then how it ended, from the same record the certificate of completion is built from. `recipient.identity_verified` and `recipient.identity_check_failed` are the webhooks that say when. ⚠️ Never the ID or passport number, a score, a photo or the name on the document: only the masked number and the name verdict.","properties":{"status":{"type":"string","enum":["passed","failed"],"description":"`passed`, or `failed` when the check cannot finish."},"reason":{"oneOf":[{"type":"string","enum":["attempts_exhausted","id_mismatch","cannot_use_camera",null],"description":"On `failed`, why: the same `reason` the `recipient.identity_check_failed` webhook carries. `null` on `passed`."},{"type":"null","enum":["attempts_exhausted","id_mismatch","cannot_use_camera",null],"description":"On `failed`, why: the same `reason` the `recipient.identity_check_failed` webhook carries. `null` on `passed`."}]},"completed_at":{"type":"string","format":"date-time","description":"When it passed or failed."},"route":{"oneOf":[{"type":"string","enum":["sa_id","passport",null],"description":"The route the signer took. `null` on `failed`."},{"type":"null","enum":["sa_id","passport",null],"description":"The route the signer took. `null` on `failed`."}]},"document":{"oneOf":[{"type":"object","description":"The document checked, masked. `null` on `failed`.","properties":{"kind":{"type":"string","enum":["smart_id_card","id_book","passport"],"description":"A Smart ID card, a green ID book, or a passport."},"masked":{"type":"string","examples":["•••••••••0087"],"description":"Its number’s last digits behind bullets."},"country":{"oneOf":[{"type":"string","description":"A passport’s issuing country (ISO 3166 alpha-3); `null` for an SA ID."},{"type":"null","description":"A passport’s issuing country (ISO 3166 alpha-3); `null` for an SA ID."}]}},"required":["kind","masked","country"]},{"type":"null","description":"The document checked, masked. `null` on `failed`.","properties":{"kind":{"type":"string","enum":["smart_id_card","id_book","passport"],"description":"A Smart ID card, a green ID book, or a passport."},"masked":{"type":"string","examples":["•••••••••0087"],"description":"Its number’s last digits behind bullets."},"country":{"oneOf":[{"type":"string","description":"A passport’s issuing country (ISO 3166 alpha-3); `null` for an SA ID."},{"type":"null","description":"A passport’s issuing country (ISO 3166 alpha-3); `null` for an SA ID."}]}},"required":["kind","masked","country"]}]},"expected_id_matched":{"oneOf":[{"type":"boolean","description":"`true` when you gave an `expected_id` of this route’s kind and the document’s number matched it; `false` when you gave none for this route. `null` on `failed` (a number that did not match fails as `id_mismatch`)."},{"type":"null","description":"`true` when you gave an `expected_id` of this route’s kind and the document’s number matched it; `false` when you gave none for this route. `null` on `failed` (a number that did not match fails as `id_mismatch`)."}]},"name_match":{"oneOf":[{"type":"string","enum":["match","partial","mismatch",null],"description":"The name on the document against the recipient’s `name`. Names are compared ignoring case, accents, spacing, apostrophes and full stops, with a hyphen read as a space, word by word and in any order. `match`: the surname on the document is in the name you gave, and one side’s given names are all in the other’s (a second name missing on either side is fine). `partial`: the surname matches but a given name differs only by an initial (J for John) or is missing, or the given names match and the surname differs (a maiden or married name). `mismatch`: anything else. `null`: no usable name on the document, or none on the recipient. A name never fails the check. `null` on `failed`."},{"type":"null","enum":["match","partial","mismatch",null],"description":"The name on the document against the recipient’s `name`. Names are compared ignoring case, accents, spacing, apostrophes and full stops, with a hyphen read as a space, word by word and in any order. `match`: the surname on the document is in the name you gave, and one side’s given names are all in the other’s (a second name missing on either side is fine). `partial`: the surname matches but a given name differs only by an initial (J for John) or is missing, or the given names match and the surname differs (a maiden or married name). `mismatch`: anything else. `null`: no usable name on the document, or none on the recipient. A name never fails the check. `null` on `failed`."}]},"provider":{"type":"string","enum":["verifynow"],"description":"Who checked it."},"provider_reference":{"oneOf":[{"type":"string","description":"VerifyNow’s reference for the face match, which the certificate prints; `null` when it gave none, and on `failed`."},{"type":"null","description":"VerifyNow’s reference for the face match, which the certificate prints; `null` when it gave none, and on `failed`."}]},"test_mode":{"type":"boolean","description":"A test envelope’s check: VerifyNow’s sandbox returned a sample result."}},"required":["status","reason","completed_at","route","document","expected_id_matched","name_match","provider","provider_reference","test_mode"],"isRequired":true,"uniqueKey":"recipients.items.[INDEX].identity_check.oneOf.0.outcome.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"recipients.items.[INDEX].identity_check.oneOf.0.outcome","typeLabel":"object | null"}},"required":["routes","expected_id","outcome"],"isRequired":true,"uniqueKey":"recipients.items.[INDEX].identity_check.oneOf.0","typeLabel":"object"},{"type":"null","description":"On a recipient asked for an identity check, what was asked: the documents they may use (`routes`) and the ID you said to expect, as its kind, its last digits behind bullets (`masked`) and a passport’s country — ⚠️ never the number, which is not stored — and, once the check has finished, how it ended (`outcome`). `null` for every other method.","properties":{"routes":{"type":"string","enum":["either","sa_id","passport"],"description":"The documents they may use."},"expected_id":{"oneOf":[{"type":"object","description":"The ID you said to expect, masked, or `null` when you gave none.","properties":{"kind":{"type":"string","enum":["sa_id","passport"],"description":"An SA ID number, or a passport number."},"masked":{"type":"string","examples":["•••••••••0087"],"description":"Its last digits behind bullets."},"country":{"oneOf":[{"type":"string","description":"A passport’s issuing country (ISO 3166 alpha-3); `null` for an SA ID."},{"type":"null","description":"A passport’s issuing country (ISO 3166 alpha-3); `null` for an SA ID."}]}},"required":["kind","masked","country"]},{"type":"null","description":"The ID you said to expect, masked, or `null` when you gave none.","properties":{"kind":{"type":"string","enum":["sa_id","passport"],"description":"An SA ID number, or a passport number."},"masked":{"type":"string","examples":["•••••••••0087"],"description":"Its last digits behind bullets."},"country":{"oneOf":[{"type":"string","description":"A passport’s issuing country (ISO 3166 alpha-3); `null` for an SA ID."},{"type":"null","description":"A passport’s issuing country (ISO 3166 alpha-3); `null` for an SA ID."}]}},"required":["kind","masked","country"]}]},"outcome":{"oneOf":[{"type":"object","description":"`null` until the check finishes; then how it ended, from the same record the certificate of completion is built from. `recipient.identity_verified` and `recipient.identity_check_failed` are the webhooks that say when. ⚠️ Never the ID or passport number, a score, a photo or the name on the document: only the masked number and the name verdict.","properties":{"status":{"type":"string","enum":["passed","failed"],"description":"`passed`, or `failed` when the check cannot finish."},"reason":{"oneOf":[{"type":"string","enum":["attempts_exhausted","id_mismatch","cannot_use_camera",null],"description":"On `failed`, why: the same `reason` the `recipient.identity_check_failed` webhook carries. `null` on `passed`."},{"type":"null","enum":["attempts_exhausted","id_mismatch","cannot_use_camera",null],"description":"On `failed`, why: the same `reason` the `recipient.identity_check_failed` webhook carries. `null` on `passed`."}]},"completed_at":{"type":"string","format":"date-time","description":"When it passed or failed."},"route":{"oneOf":[{"type":"string","enum":["sa_id","passport",null],"description":"The route the signer took. `null` on `failed`."},{"type":"null","enum":["sa_id","passport",null],"description":"The route the signer took. `null` on `failed`."}]},"document":{"oneOf":[{"type":"object","description":"The document checked, masked. `null` on `failed`.","properties":{"kind":{"type":"string","enum":["smart_id_card","id_book","passport"],"description":"A Smart ID card, a green ID book, or a passport."},"masked":{"type":"string","examples":["•••••••••0087"],"description":"Its number’s last digits behind bullets."},"country":{"oneOf":[{"type":"string","description":"A passport’s issuing country (ISO 3166 alpha-3); `null` for an SA ID."},{"type":"null","description":"A passport’s issuing country (ISO 3166 alpha-3); `null` for an SA ID."}]}},"required":["kind","masked","country"]},{"type":"null","description":"The document checked, masked. `null` on `failed`.","properties":{"kind":{"type":"string","enum":["smart_id_card","id_book","passport"],"description":"A Smart ID card, a green ID book, or a passport."},"masked":{"type":"string","examples":["•••••••••0087"],"description":"Its number’s last digits behind bullets."},"country":{"oneOf":[{"type":"string","description":"A passport’s issuing country (ISO 3166 alpha-3); `null` for an SA ID."},{"type":"null","description":"A passport’s issuing country (ISO 3166 alpha-3); `null` for an SA ID."}]}},"required":["kind","masked","country"]}]},"expected_id_matched":{"oneOf":[{"type":"boolean","description":"`true` when you gave an `expected_id` of this route’s kind and the document’s number matched it; `false` when you gave none for this route. `null` on `failed` (a number that did not match fails as `id_mismatch`)."},{"type":"null","description":"`true` when you gave an `expected_id` of this route’s kind and the document’s number matched it; `false` when you gave none for this route. `null` on `failed` (a number that did not match fails as `id_mismatch`)."}]},"name_match":{"oneOf":[{"type":"string","enum":["match","partial","mismatch",null],"description":"The name on the document against the recipient’s `name`. Names are compared ignoring case, accents, spacing, apostrophes and full stops, with a hyphen read as a space, word by word and in any order. `match`: the surname on the document is in the name you gave, and one side’s given names are all in the other’s (a second name missing on either side is fine). `partial`: the surname matches but a given name differs only by an initial (J for John) or is missing, or the given names match and the surname differs (a maiden or married name). `mismatch`: anything else. `null`: no usable name on the document, or none on the recipient. A name never fails the check. `null` on `failed`."},{"type":"null","enum":["match","partial","mismatch",null],"description":"The name on the document against the recipient’s `name`. Names are compared ignoring case, accents, spacing, apostrophes and full stops, with a hyphen read as a space, word by word and in any order. `match`: the surname on the document is in the name you gave, and one side’s given names are all in the other’s (a second name missing on either side is fine). `partial`: the surname matches but a given name differs only by an initial (J for John) or is missing, or the given names match and the surname differs (a maiden or married name). `mismatch`: anything else. `null`: no usable name on the document, or none on the recipient. A name never fails the check. `null` on `failed`."}]},"provider":{"type":"string","enum":["verifynow"],"description":"Who checked it."},"provider_reference":{"oneOf":[{"type":"string","description":"VerifyNow’s reference for the face match, which the certificate prints; `null` when it gave none, and on `failed`."},{"type":"null","description":"VerifyNow’s reference for the face match, which the certificate prints; `null` when it gave none, and on `failed`."}]},"test_mode":{"type":"boolean","description":"A test envelope’s check: VerifyNow’s sandbox returned a sample result."}},"required":["status","reason","completed_at","route","document","expected_id_matched","name_match","provider","provider_reference","test_mode"]},{"type":"null","description":"`null` until the check finishes; then how it ended, from the same record the certificate of completion is built from. `recipient.identity_verified` and `recipient.identity_check_failed` are the webhooks that say when. ⚠️ Never the ID or passport number, a score, a photo or the name on the document: only the masked number and the name verdict.","properties":{"status":{"type":"string","enum":["passed","failed"],"description":"`passed`, or `failed` when the check cannot finish."},"reason":{"oneOf":[{"type":"string","enum":["attempts_exhausted","id_mismatch","cannot_use_camera",null],"description":"On `failed`, why: the same `reason` the `recipient.identity_check_failed` webhook carries. `null` on `passed`."},{"type":"null","enum":["attempts_exhausted","id_mismatch","cannot_use_camera",null],"description":"On `failed`, why: the same `reason` the `recipient.identity_check_failed` webhook carries. `null` on `passed`."}]},"completed_at":{"type":"string","format":"date-time","description":"When it passed or failed."},"route":{"oneOf":[{"type":"string","enum":["sa_id","passport",null],"description":"The route the signer took. `null` on `failed`."},{"type":"null","enum":["sa_id","passport",null],"description":"The route the signer took. `null` on `failed`."}]},"document":{"oneOf":[{"type":"object","description":"The document checked, masked. `null` on `failed`.","properties":{"kind":{"type":"string","enum":["smart_id_card","id_book","passport"],"description":"A Smart ID card, a green ID book, or a passport."},"masked":{"type":"string","examples":["•••••••••0087"],"description":"Its number’s last digits behind bullets."},"country":{"oneOf":[{"type":"string","description":"A passport’s issuing country (ISO 3166 alpha-3); `null` for an SA ID."},{"type":"null","description":"A passport’s issuing country (ISO 3166 alpha-3); `null` for an SA ID."}]}},"required":["kind","masked","country"]},{"type":"null","description":"The document checked, masked. `null` on `failed`.","properties":{"kind":{"type":"string","enum":["smart_id_card","id_book","passport"],"description":"A Smart ID card, a green ID book, or a passport."},"masked":{"type":"string","examples":["•••••••••0087"],"description":"Its number’s last digits behind bullets."},"country":{"oneOf":[{"type":"string","description":"A passport’s issuing country (ISO 3166 alpha-3); `null` for an SA ID."},{"type":"null","description":"A passport’s issuing country (ISO 3166 alpha-3); `null` for an SA ID."}]}},"required":["kind","masked","country"]}]},"expected_id_matched":{"oneOf":[{"type":"boolean","description":"`true` when you gave an `expected_id` of this route’s kind and the document’s number matched it; `false` when you gave none for this route. `null` on `failed` (a number that did not match fails as `id_mismatch`)."},{"type":"null","description":"`true` when you gave an `expected_id` of this route’s kind and the document’s number matched it; `false` when you gave none for this route. `null` on `failed` (a number that did not match fails as `id_mismatch`)."}]},"name_match":{"oneOf":[{"type":"string","enum":["match","partial","mismatch",null],"description":"The name on the document against the recipient’s `name`. Names are compared ignoring case, accents, spacing, apostrophes and full stops, with a hyphen read as a space, word by word and in any order. `match`: the surname on the document is in the name you gave, and one side’s given names are all in the other’s (a second name missing on either side is fine). `partial`: the surname matches but a given name differs only by an initial (J for John) or is missing, or the given names match and the surname differs (a maiden or married name). `mismatch`: anything else. `null`: no usable name on the document, or none on the recipient. A name never fails the check. `null` on `failed`."},{"type":"null","enum":["match","partial","mismatch",null],"description":"The name on the document against the recipient’s `name`. Names are compared ignoring case, accents, spacing, apostrophes and full stops, with a hyphen read as a space, word by word and in any order. `match`: the surname on the document is in the name you gave, and one side’s given names are all in the other’s (a second name missing on either side is fine). `partial`: the surname matches but a given name differs only by an initial (J for John) or is missing, or the given names match and the surname differs (a maiden or married name). `mismatch`: anything else. `null`: no usable name on the document, or none on the recipient. A name never fails the check. `null` on `failed`."}]},"provider":{"type":"string","enum":["verifynow"],"description":"Who checked it."},"provider_reference":{"oneOf":[{"type":"string","description":"VerifyNow’s reference for the face match, which the certificate prints; `null` when it gave none, and on `failed`."},{"type":"null","description":"VerifyNow’s reference for the face match, which the certificate prints; `null` when it gave none, and on `failed`."}]},"test_mode":{"type":"boolean","description":"A test envelope’s check: VerifyNow’s sandbox returned a sample result."}},"required":["status","reason","completed_at","route","document","expected_id_matched","name_match","provider","provider_reference","test_mode"]}]}},"required":["routes","expected_id","outcome"],"isRequired":true,"uniqueKey":"recipients.items.[INDEX].identity_check.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"recipients.items.[INDEX].identity_check","typeLabel":"object | null"},"completion_basis":{"oneOf":[{"type":"string","enum":["session","standing_authorisation",null],"description":"How this recipient completed: `session` for a person who signed or approved themselves, `standing_authorisation` for a role pre-signed when the document was sent, under a standing authorisation. `null` until they complete — including a draft’s pre-signed role, which completes only when the envelope is sent.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].completion_basis.oneOf.0","typeLabel":"enum\u003cstring>"},{"type":"null","enum":["session","standing_authorisation",null],"description":"How this recipient completed: `session` for a person who signed or approved themselves, `standing_authorisation` for a role pre-signed when the document was sent, under a standing authorisation. `null` until they complete — including a draft’s pre-signed role, which completes only when the envelope is sent.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].completion_basis.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"recipients.items.[INDEX].completion_basis","typeLabel":"enum\u003cstring> | null"},"standing_authorisation":{"oneOf":[{"type":"object","description":"The standing authorisation named on this role, or `null` for a person. Present from the draft on. The grantor named on it is never emailed about the document.","properties":{"id":{"type":"string","format":"uuid","description":"The authorisation.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].standing_authorisation.oneOf.0.id","typeLabel":"string\u003cuuid>"},"number":{"type":"string","examples":["SA-0012"],"description":"Its number, as printed.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].standing_authorisation.oneOf.0.number","typeLabel":"string"},"witness":{"type":"boolean","description":"Whether the mark was applied as a WITNESS’s: the role is a witness, the authorisation was granted for witness use, and the document, its certificate and its verification page say the witness was not present. `false` until the send applies it, and always for a party.","isRequired":true,"uniqueKey":"recipients.items.[INDEX].standing_authorisation.oneOf.0.witness","typeLabel":"boolean"}},"required":["id","number","witness"],"isRequired":true,"uniqueKey":"recipients.items.[INDEX].standing_authorisation.oneOf.0","typeLabel":"object"},{"type":"null","description":"The standing authorisation named on this role, or `null` for a person. Present from the draft on. The grantor named on it is never emailed about the document.","properties":{"id":{"type":"string","format":"uuid","description":"The authorisation."},"number":{"type":"string","examples":["SA-0012"],"description":"Its number, as printed."},"witness":{"type":"boolean","description":"Whether the mark was applied as a WITNESS’s: the role is a witness, the authorisation was granted for witness use, and the document, its certificate and its verification page say the witness was not present. `false` until the send applies it, and always for a party."}},"required":["id","number","witness"],"isRequired":true,"uniqueKey":"recipients.items.[INDEX].standing_authorisation.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"recipients.items.[INDEX].standing_authorisation","typeLabel":"object | null"}},"required":["id","role","name","email","routing_type","status","invitation_delivered","embedded","delegates_stay_embedded","external_ref","verification_method","mobile","identity_check","completion_basis","standing_authorisation"],"uniqueKey":"recipients.items.[INDEX]","typeLabel":"object"},"isRequired":true,"uniqueKey":"recipients","typeLabel":"object[]"},"subjects":{"type":"array","description":"Who the envelope is about, such as a spouse or a dependant, in the order they were declared: the `subject` a value names. A one-off’s come from setting it up in the editor; an envelope made from a template has its template’s. Empty when the envelope is about nobody in particular.","items":{"type":"object","description":"One person the envelope is about.","properties":{"key":{"type":"string","examples":["spouse"],"description":"The key a value’s `subject` names.","isRequired":true,"uniqueKey":"subjects.items.[INDEX].key","typeLabel":"string"},"label":{"type":"string","examples":["Spouse"],"description":"What a person reads.","isRequired":true,"uniqueKey":"subjects.items.[INDEX].label","typeLabel":"string"},"presence":{"type":"string","enum":["required","conditional"],"description":"`required`: always on this envelope. `conditional`: may be left out.","isRequired":true,"uniqueKey":"subjects.items.[INDEX].presence","typeLabel":"enum\u003cstring>"},"present":{"type":"boolean","description":"Whether this envelope has this person. When `false`, their boxes are hidden from the signer and are not required. A `conditional` person may still be switched on or off by the signer. While the signer is still to be asked (`awaiting_signer`), this is `false`, which is what the signer sees until they answer.","isRequired":true,"uniqueKey":"subjects.items.[INDEX].present","typeLabel":"boolean"},"awaiting_signer":{"type":"boolean","description":"`true` while the signer is still to be asked whether this person is on the form: the sender chose Ask the signer, and nobody has answered yet. `present` is then `false`. Read the two together to tell a person left out from one not answered yet. Always `false` for a `required` person.","isRequired":true,"uniqueKey":"subjects.items.[INDEX].awaiting_signer","typeLabel":"boolean"},"starts_as":{"type":"string","enum":["ask","present","absent"],"description":"The sender’s choice for a `conditional` person: `ask` (the signer is asked), `present` (Include) or `absent` (Leave out). Fixed once the envelope is sent, while `present` is the fact now and can change. Read it with `present`: an envelope made before the sender could choose reads `absent`. Not meaningful for a `required` person.","isRequired":true,"uniqueKey":"subjects.items.[INDEX].starts_as","typeLabel":"enum\u003cstring>"}},"required":["key","label","presence","present","awaiting_signer","starts_as"],"uniqueKey":"subjects.items.[INDEX]","typeLabel":"object"},"isRequired":true,"uniqueKey":"subjects","typeLabel":"object[]"},"roles_left_out":{"type":"array","description":"The optional roles this envelope was sent without (`Role.presence` is `optional` on its template, and nobody was named for the role: no recipient in the request, or only an empty slot on a draft prepared in the dashboard). Each was left out when the envelope was sent, with every field it held, and the sealed certificate lists it as not on the envelope. Only a role that held fields is listed: one with none has nothing to leave out. Empty before the envelope is sent and for a one-off.","items":{"type":"object","description":"One optional role the envelope was sent without.","required":["role","kind"],"properties":{"role":{"type":"string","examples":["Surety"],"description":"The role’s name.","isRequired":true,"uniqueKey":"roles_left_out.items.[INDEX].role","typeLabel":"string"},"kind":{"type":"string","enum":["party","witness"],"description":"The role’s kind when it was left out.","isRequired":true,"uniqueKey":"roles_left_out.items.[INDEX].kind","typeLabel":"enum\u003cstring>"}},"uniqueKey":"roles_left_out.items.[INDEX]","typeLabel":"object"},"isRequired":true,"uniqueKey":"roles_left_out","typeLabel":"object[]"}},"required":["id","status","template_id","title","reference","created_at","sent_at","expires_at","recipients","subjects","roles_left_out"],"uniqueKey":"","typeLabel":"object"},"examples":{"example":{"title":"example","summary":"A sent envelope","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"},"507cc2bd-9ad5-45ae-a65a-9f12414d65ef":{"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"},"a7b83491-1b90-4b9e-a37a-d9bf78471aa3":{"description":"`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.","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"},"39fc74bc-a259-4447-8c95-06de107467eb":{"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"},"8ebea358-7cad-4a7e-93de-49780706dc1c":{"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"},"893ab7e5-dbc1-49a5-a2ea-b3d55244f558":{"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"}},"security":{"b2cf0f5c-441d-4c24-a30d-a8465199be4c":{"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":"One envelope, as it stands right now. - Vumasign","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-11-16T05:07:56.202Z","originalFileLocation":"api-reference/get-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=\"⚠️ THIS IS WHAT EVERY WEBHOOK BODY’S uri POINTS AT, AND WHY THAT FIELD EXISTS. A webhook payload is a snapshot of a moment; this is the resource. Anything you are about to do because of an event — release goods, bill somebody, advance a workflow — should be decided from a read here rather than from the body you were posted, because the body cannot have changed since it was written and the envelope can. It is a safe GET: it writes nothing, mints nothing and takes no Idempotency-Key. Poll it if you must, but the webhook is the signal and this is the confirmation. ⚠️ invitation_delivered IS ANSWERED HERE FROM THE EVIDENCE, not left null. A recipient the provider has reported delivery for reads true weeks later, and a recipient nobody was ever meant to email — a cc, an embedded signer, somebody in a later step the envelope is still holding back — reads null. Those two are different facts and this endpoint keeps them different. ⚠️ AND THIS IS THE ENDPOINT TO RE-READ IT FROM, BECAUSE THE TWO ENDPOINTS MEAN DIFFERENT THINGS BY true AND THAT IS DELIBERATE. Here, true means THE PROVIDER REPORTED A DELIVERY, on the provider’s clock; an invitation the provider has merely accepted and not yet reported on reads false. POST .../send answers true for that same recipient — it is built from the answers the provider gave while the send was running, and acceptance is the only thing anybody knows at that moment. Its own description says so, and says it is the one place true means acceptance. So a recipient can read true from the send and false here seconds later, and neither answer is wrong: deciding anything real from the send response is deciding from a snapshot taken before the fact existed. Re-read here. ⚠️ FOUR SITUATIONS ANSWER WITH THE SAME 404: no such envelope anywhere; one belonging to another organisation; a draft that has since been deleted; and an id that is not a uuid. \u0026quot;It exists but is not yours\u0026quot; is itself the secret, and the handler could not tell the first two apart if it wanted to — the read runs inside a transaction already scoped to the key’s tenant. A vsk_test_ key may read. Reading emails nobody.\">\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=\"One envelope, as it stands right now. - Vumasign\">\u003cmeta data-mint-head property=\"og:description\" content=\"⚠️ THIS IS WHAT EVERY WEBHOOK BODY’S uri POINTS AT, AND WHY THAT FIELD EXISTS. A webhook payload is a snapshot of a moment; this is the resource. Anything you are about to do because of an event — release goods, bill somebody, advance a workflow — should be decided from a read here rather than from the body you were posted, because the body cannot have changed since it was written and the envelope can. It is a safe GET: it writes nothing, mints nothing and takes no Idempotency-Key. Poll it if you must, but the webhook is the signal and this is the confirmation. ⚠️ invitation_delivered IS ANSWERED HERE FROM THE EVIDENCE, not left null. A recipient the provider has reported delivery for reads true weeks later, and a recipient nobody was ever meant to email — a cc, an embedded signer, somebody in a later step the envelope is still holding back — reads null. Those two are different facts and this endpoint keeps them different. ⚠️ AND THIS IS THE ENDPOINT TO RE-READ IT FROM, BECAUSE THE TWO ENDPOINTS MEAN DIFFERENT THINGS BY true AND THAT IS DELIBERATE. Here, true means THE PROVIDER REPORTED A DELIVERY, on the provider’s clock; an invitation the provider has merely accepted and not yet reported on reads false. POST .../send answers true for that same recipient — it is built from the answers the provider gave while the send was running, and acceptance is the only thing anybody knows at that moment. Its own description says so, and says it is the one place true means acceptance. So a recipient can read true from the send and false here seconds later, and neither answer is wrong: deciding anything real from the send response is deciding from a snapshot taken before the fact existed. Re-read here. ⚠️ FOUR SITUATIONS ANSWER WITH THE SAME 404: no such envelope anywhere; one belonging to another organisation; a draft that has since been deleted; and an id that is not a uuid. \u0026quot;It exists but is not yours\u0026quot; is itself the secret, and the handler could not tell the first two apart if it wanted to — the read runs inside a transaction already scoped to the key’s tenant. A vsk_test_ key may read. Reading emails nobody.\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"Vumasign\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.vumasign.com/api-reference/get-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=One+envelope%2C+as+it+stands+right+now.\u0026amp;description=%E2%9A%A0%EF%B8%8F+**THIS+IS+WHAT+EVERY+WEBHOOK+BODY%E2%80%99S+%60uri%60+POINTS+AT%2C+AND+WHY+THAT+FIELD+EXISTS.**+A+webhook+payload+is+a+snapshot+of+a+moment%3B+this+is+the+resource.+Anything\u0026amp;theme=5afaa4abac00f05afdc3c271\u0026amp;signature=8445c1036b0a3a92d2f87c88084c7e90d8ad8cadccd8ded45ac8cceda6c52890\">\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=\"One envelope, as it stands right now. - Vumasign\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"⚠️ THIS IS WHAT EVERY WEBHOOK BODY’S uri POINTS AT, AND WHY THAT FIELD EXISTS. A webhook payload is a snapshot of a moment; this is the resource. Anything you are about to do because of an event — release goods, bill somebody, advance a workflow — should be decided from a read here rather than from the body you were posted, because the body cannot have changed since it was written and the envelope can. It is a safe GET: it writes nothing, mints nothing and takes no Idempotency-Key. Poll it if you must, but the webhook is the signal and this is the confirmation. ⚠️ invitation_delivered IS ANSWERED HERE FROM THE EVIDENCE, not left null. A recipient the provider has reported delivery for reads true weeks later, and a recipient nobody was ever meant to email — a cc, an embedded signer, somebody in a later step the envelope is still holding back — reads null. Those two are different facts and this endpoint keeps them different. ⚠️ AND THIS IS THE ENDPOINT TO RE-READ IT FROM, BECAUSE THE TWO ENDPOINTS MEAN DIFFERENT THINGS BY true AND THAT IS DELIBERATE. Here, true means THE PROVIDER REPORTED A DELIVERY, on the provider’s clock; an invitation the provider has merely accepted and not yet reported on reads false. POST .../send answers true for that same recipient — it is built from the answers the provider gave while the send was running, and acceptance is the only thing anybody knows at that moment. Its own description says so, and says it is the one place true means acceptance. So a recipient can read true from the send and false here seconds later, and neither answer is wrong: deciding anything real from the send response is deciding from a snapshot taken before the fact existed. Re-read here. ⚠️ FOUR SITUATIONS ANSWER WITH THE SAME 404: no such envelope anywhere; one belonging to another organisation; a draft that has since been deleted; and an id that is not a uuid. \u0026quot;It exists but is not yours\u0026quot; is itself the secret, and the handler could not tell the first two apart if it wanted to — the read runs inside a transaction already scoped to the key’s tenant. A vsk_test_ key may read. Reading emails nobody.\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://vumasign.mintlify.site/_mintlify/api/og/v2?division=Envelopes\u0026amp;title=One+envelope%2C+as+it+stands+right+now.\u0026amp;description=%E2%9A%A0%EF%B8%8F+**THIS+IS+WHAT+EVERY+WEBHOOK+BODY%E2%80%99S+%60uri%60+POINTS+AT%2C+AND+WHY+THAT+FIELD+EXISTS.**+A+webhook+payload+is+a+snapshot+of+a+moment%3B+this+is+the+resource.+Anything\u0026amp;theme=5afaa4abac00f05afdc3c271\u0026amp;signature=8445c1036b0a3a92d2f87c88084c7e90d8ad8cadccd8ded45ac8cceda6c52890\">\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/get-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/get-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/get-envelope#webpage\",\"url\":\"https://docs.vumasign.com/api-reference/get-envelope\",\"name\":\"One envelope, as it stands right now.\",\"description\":\"⚠️ THIS IS WHAT EVERY WEBHOOK BODY’S uri POINTS AT, AND WHY THAT FIELD EXISTS. A webhook payload is a snapshot of a moment; this is the resource. Anything you are about to do because of an event — release goods, bill somebody, advance a workflow — should be decided from a read here rather than from the body you were posted, because the body cannot have changed since it was written and the envelope can. It is a safe GET: it writes nothing, mints nothing and takes no Idempotency-Key. Poll it if you must, but the webhook is the signal and this is the confirmation. ⚠️ invitation_delivered IS ANSWERED HERE FROM THE EVIDENCE, not left null. A recipient the provider has reported delivery for reads true weeks later, and a recipient nobody was ever meant to email — a cc, an embedded signer, somebody in a later step the envelope is still holding back — reads null. Those two are different facts and this endpoint keeps them different. ⚠️ AND THIS IS THE ENDPOINT TO RE-READ IT FROM, BECAUSE THE TWO ENDPOINTS MEAN DIFFERENT THINGS BY true AND THAT IS DELIBERATE. Here, true means THE PROVIDER REPORTED A DELIVERY, on the provider’s clock; an invitation the provider has merely accepted and not yet reported on reads false. POST .../send answers true for that same recipient — it is built from the answers the provider gave while the send was running, and acceptance is the only thing anybody knows at that moment. Its own description says so, and says it is the one place true means acceptance. So a recipient can read true from the send and false here seconds later, and neither answer is wrong: deciding anything real from the send response is deciding from a snapshot taken before the fact existed. Re-read here. ⚠️ FOUR SITUATIONS ANSWER WITH THE SAME 404: no such envelope anywhere; one belonging to another organisation; a draft that has since been deleted; and an id that is not a uuid. \\\"It exists but is not yours\\\" is itself the secret, and the handler could not tell the first two apart if it wanted to — the read runs inside a transaction already scoped to the key’s tenant. A vsk_test_ key may read. Reading emails nobody.\",\"dateModified\":\"2026-11-16T05:07:56.202Z\",\"isPartOf\":{\"@id\":\"https://docs.vumasign.com#website\"},\"breadcrumb\":{\"@id\":\"https://docs.vumasign.com/api-reference/get-envelope#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.vumasign.com/api-reference/get-envelope#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Envelopes\",\"item\":\"https://docs.vumasign.com/api-reference/list-envelopes\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"One envelope, as it stands right now.\",\"item\":\"https://docs.vumasign.com/api-reference/get-envelope\"}]},{\"@type\":[\"TechArticle\",\"APIReference\"],\"@id\":\"https://docs.vumasign.com/api-reference/get-envelope#apireference\",\"headline\":\"One envelope, as it stands right now.\",\"name\":\"One envelope, as it stands right now.\",\"description\":\"⚠️ THIS IS WHAT EVERY WEBHOOK BODY’S uri POINTS AT, AND WHY THAT FIELD EXISTS. A webhook payload is a snapshot of a moment; this is the resource. Anything you are about to do because of an event — release goods, bill somebody, advance a workflow — should be decided from a read here rather than from the body you were posted, because the body cannot have changed since it was written and the envelope can. It is a safe GET: it writes nothing, mints nothing and takes no Idempotency-Key. Poll it if you must, but the webhook is the signal and this is the confirmation. ⚠️ invitation_delivered IS ANSWERED HERE FROM THE EVIDENCE, not left null. A recipient the provider has reported delivery for reads true weeks later, and a recipient nobody was ever meant to email — a cc, an embedded signer, somebody in a later step the envelope is still holding back — reads null. Those two are different facts and this endpoint keeps them different. ⚠️ AND THIS IS THE ENDPOINT TO RE-READ IT FROM, BECAUSE THE TWO ENDPOINTS MEAN DIFFERENT THINGS BY true AND THAT IS DELIBERATE. Here, true means THE PROVIDER REPORTED A DELIVERY, on the provider’s clock; an invitation the provider has merely accepted and not yet reported on reads false. POST .../send answers true for that same recipient — it is built from the answers the provider gave while the send was running, and acceptance is the only thing anybody knows at that moment. Its own description says so, and says it is the one place true means acceptance. So a recipient can read true from the send and false here seconds later, and neither answer is wrong: deciding anything real from the send response is deciding from a snapshot taken before the fact existed. Re-read here. ⚠️ FOUR SITUATIONS ANSWER WITH THE SAME 404: no such envelope anywhere; one belonging to another organisation; a draft that has since been deleted; and an id that is not a uuid. \\\"It exists but is not yours\\\" is itself the secret, and the handler could not tell the first two apart if it wanted to — the read runs inside a transaction already scoped to the key’s tenant. A vsk_test_ key may read. Reading emails nobody.\",\"url\":\"https://docs.vumasign.com/api-reference/get-envelope\",\"mainEntityOfPage\":{\"@id\":\"https://docs.vumasign.com/api-reference/get-envelope#webpage\"},\"dateModified\":\"2026-11-16T05:07:56.202Z\",\"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/get-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.","description":"ONE REQUEST, ONE `Idempotency-Key`, UP TO 100 ENVELOPES. What this saves is not our time but your error handling: a thousand loops of `POST /api/v1/envelopes` is a thousand keys to mint and persist, a thousand timeouts to resolve, and a thousand places to be halfway through.\n\n⚠️ **THE STATUS LINE IS THE ANSWER. YOU NEVER HAVE TO WALK THE BODY TO FIND OUT WHETHER IT WORKED.**\n\n- `201` — every row went out (or, with `send: false`, every draft exists). `failed` is 0.\n- `207` — at least one row did not. `failed` says how many and `results[i].error` says why. This is the only status that requires reading a body.\n- any `4xx` — **nothing was created at all.**\n\n⚠️ ONE BAD ROW REFUSES THE WHOLE BATCH, AND THAT IS DELIBERATE. Every refusal your own data can earn — an unknown role, an address matching no field, a value that cannot be drawn, a mailbox a test key may not write to — is decided in ONE transaction before anything is sent, so a hundred envelopes roll back together and your key is free for a corrected retry. A mistake in mapping code is systematic: if row 7 names a role the template does not have, rows 8 to 99 probably do too, and sending 93 binding documents to prove it is the expensive way to find out. Refusals name the row: `rows[7].recipients[2].role`.\n\nPAST THAT POINT IT IS PER ROW, because an email handed to a provider cannot be recalled. A row whose send is refused KEEPS ITS DRAFT, with its recipients and values already on it, and its id is in the answer — so the remedy is `POST /api/v1/envelopes/{envelopeId}/send` on the ones that failed rather than rebuilding the ones that did not.\n\n⚠️ A REPLAY RETURNS THE SAME BATCH AND CREATES NOTHING, including a replay of a `207` — which returns the same `207`, failed rows and all, rather than retrying them. If a replay could DO something, two replays could give two different answers and a retry after a timeout would tell you nothing.\n\n⚠️ IT IS SYNCHRONOUS. There is no job to poll, because the answer is the response. That is what the 100-row bound buys, and it is why the bound is not larger.\n\n⚠️ **IT COSTS N AGAINST THE RATE LIMIT, NOT 1** — one unit per row, because one row is one envelope and an envelope is what costs us. A batch that does not fit in what the minute has left is refused WHOLE with `rate_limited`, never partly, and is charged 1 rather than N for being refused. `RateLimit-Remaining` tells you how many rows would fit now.","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.","description":"DELETES A DRAFT: an envelope created with `\"send\": false` (or saved as a draft in the dashboard) that has not been sent. Its recipients, its placed fields and the values filled in go with it. It is the same rule as the dashboard’s **Discard** button, and there is no list of discarded drafts to restore one from.\n\n⚠️ **ONLY A DRAFT.** An envelope that has gone out is refused with `envelope_not_draft` and left exactly as it was. To withdraw a `sent` or `partially_signed` envelope, use `POST /api/v1/envelopes/{envelopeId}/void`, which keeps the envelope and its evidence and records why. A completed, declined, voided or expired envelope is finished and stays as it is.\n\nWhy a delete rather than a void: a draft has asked nobody to do anything, so there is nothing to withdraw and no history worth keeping. Voiding one would leave a permanent record of a document that was never sent.\n\n**204, with no body.** The envelope is gone, so there is nothing true to return.\n\n⚠️ A SECOND DELETE IS 404, NOT 204, as for webhooks. The act is idempotent — the end state is identical — so it takes no `Idempotency-Key` and a retry after a timeout is safe; but a 404 is the only answer that tells \"I removed it\" apart from \"there was never one there\". If you retried after a timeout and got 404, the first attempt deleted it. Another organisation’s envelope, and an id that is not a uuid, are the same 404.\n\nNO WEBHOOK FIRES: a draft produces no events, and neither does its deletion. A `POST /api/v1/envelopes` retried with the `Idempotency-Key` that created the draft makes a new draft after this, rather than replaying the deleted one.\n\n⚠️ A `vsk_test_` KEY MAY DISCARD ONLY A DRAFT A TEST KEY CREATED. Any envelope made in the dashboard or with a live key, draft or not, is refused with `test_key_cannot_discard` before its status is considered.","deprecated":null,"version":null,"sidebarTitle":"Delete envelope","openapi":"/openapi.json delete /api/v1/envelopes/{envelopeId}","href":"/api-reference/delete-envelope"},{"title":"Get an envelope’s document, and its certificate once sealed.","deprecated":null,"version":null,"sidebarTitle":"List envelope documents","openapi":"/openapi.json get /api/v1/envelopes/{envelopeId}/documents","href":"/api-reference/list-envelope-documents"},{"title":"The document as it stands, mid-flight, stamped DRAFT.","deprecated":null,"version":null,"sidebarTitle":"Get envelope document draft","openapi":"/openapi.json get /api/v1/envelopes/{envelopeId}/documents/{position}/draft","href":"/api-reference/get-envelope-document-draft"},{"title":"Withdraw a sent envelope.","deprecated":null,"version":null,"sidebarTitle":"Void envelope","openapi":"/openapi.json post /api/v1/envelopes/{envelopeId}/void","href":"/api-reference/void-envelope"},{"title":"Give a sent envelope a later deadline.","deprecated":null,"version":null,"sidebarTitle":"Extend envelope deadline","openapi":"/openapi.json post /api/v1/envelopes/{envelopeId}/extend","href":"/api-reference/extend-envelope-deadline"},{"title":"Send a draft envelope to its recipients.","deprecated":null,"version":null,"sidebarTitle":"Send envelope","openapi":"/openapi.json post /api/v1/envelopes/{envelopeId}/send","href":"/api-reference/send-envelope"},{"title":"Mint a short-lived, single-use URL for an embedded signer.","deprecated":null,"version":null,"sidebarTitle":"Create signing url","openapi":"/openapi.json post /api/v1/envelopes/{envelopeId}/recipients/{recipientId}/signing-url","href":"/api-reference/create-signing-url"}]},{"group":"Webhooks","pages":[{"title":"Every registered endpoint, with its health.","deprecated":null,"version":null,"sidebarTitle":"List webhooks","openapi":"/openapi.json get /api/v1/webhooks","href":"/api-reference/list-webhooks"},{"title":"Register an endpoint and mint its signing secret.","deprecated":null,"version":null,"sidebarTitle":"Create webhook","openapi":"/openapi.json post /api/v1/webhooks","href":"/api-reference/create-webhook"},{"title":"One endpoint, with its health.","deprecated":null,"version":null,"sidebarTitle":"Get webhook","openapi":"/openapi.json get /api/v1/webhooks/{webhookId}","href":"/api-reference/get-webhook"},{"title":"Remove an endpoint. ⚠️ Queued deliveries go with it.","deprecated":null,"version":null,"sidebarTitle":"Delete webhook","openapi":"/openapi.json delete /api/v1/webhooks/{webhookId}","href":"/api-reference/delete-webhook"},{"title":"Change the URL, the subscription, the brand filter or the active flag.","deprecated":null,"version":null,"sidebarTitle":"Update webhook","openapi":"/openapi.json patch /api/v1/webhooks/{webhookId}","href":"/api-reference/update-webhook"},{"title":"Mint a new signing secret, keeping the old one alive briefly.","deprecated":null,"version":null,"sidebarTitle":"Rotate webhook secret","openapi":"/openapi.json post /api/v1/webhooks/{webhookId}/rotate-secret","href":"/api-reference/rotate-webhook-secret"}]},{"group":"Brands","pages":[{"title":"List your organisation’s brands, newest first.","deprecated":null,"version":null,"sidebarTitle":"List brands","openapi":"/openapi.json get /api/v1/brands","href":"/api-reference/list-brands"},{"title":"One brand, archived or not.","deprecated":null,"version":null,"sidebarTitle":"Get brand","openapi":"/openapi.json get /api/v1/brands/{brandId}","href":"/api-reference/get-brand"},{"title":"Register one origin that may frame this brand’s signing pages.","deprecated":null,"version":null,"sidebarTitle":"Add brand embed origin","openapi":"/openapi.json post /api/v1/brands/{brandId}/embed-origins","href":"/api-reference/add-brand-embed-origin"},{"title":"Stop one origin framing this brand’s signing pages.","deprecated":null,"version":null,"sidebarTitle":"Remove brand embed origin","openapi":"/openapi.json delete /api/v1/brands/{brandId}/embed-origins","href":"/api-reference/remove-brand-embed-origin"}]},{"group":"Standing authorisations","pages":[{"title":"List standing authorisations, newest first, optionally filtered.","deprecated":null,"version":null,"sidebarTitle":"List standing authorisations","openapi":"/openapi.json get /api/v1/standing-authorisations","href":"/api-reference/list-standing-authorisations"},{"title":"One standing authorisation, as it stands now.","deprecated":null,"version":null,"sidebarTitle":"Get standing authorisation","openapi":"/openapi.json get /api/v1/standing-authorisations/{authorisationId}","href":"/api-reference/get-standing-authorisation"},{"title":"Cancel a pending standing authorisation request.","deprecated":null,"version":null,"sidebarTitle":"Cancel standing authorisation","openapi":"/openapi.json post /api/v1/standing-authorisations/{authorisationId}/cancel","href":"/api-reference/cancel-standing-authorisation"},{"title":"Email the grantor a fresh link to a pending request.","deprecated":null,"version":null,"sidebarTitle":"Resend standing authorisation","openapi":"/openapi.json post /api/v1/standing-authorisations/{authorisationId}/resend","href":"/api-reference/resend-standing-authorisation"},{"title":"Revoke a standing authorisation.","deprecated":null,"version":null,"sidebarTitle":"Revoke standing authorisation","openapi":"/openapi.json post /api/v1/standing-authorisations/{authorisationId}/revoke","href":"/api-reference/revoke-standing-authorisation"},{"title":"Renew a standing authorisation: send its grantor a new mandate that starts when it ends.","deprecated":null,"version":null,"sidebarTitle":"Renew standing authorisation","openapi":"/openapi.json post /api/v1/standing-authorisations/{authorisationId}/renew","href":"/api-reference/renew-standing-authorisation"},{"title":"Request a standing authorisation: generate the mandate and send it to the grantor.","deprecated":null,"version":null,"sidebarTitle":"Invite standing authorisation","openapi":"/openapi.json post /api/v1/standing-authorisations/invitations","href":"/api-reference/invite-standing-authorisation"}]}]}]},"basePath":"","title":"One envelope, as it stands right now. - 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"]}