Skip to main content
POST
Create an envelope from a template, and optionally send it.

Authorizations

Authorization
string
header
required

Authorization: Bearer vsk_live_…. Chosen over a bespoke X-API-KEY header because every client, proxy and log-redaction rule already knows this one. What a key may DO is its scopes — see x-scopes at the root of this document and x-required-scope on each operation. The scope list is not written here because OpenAPI reserves a requirement’s scope array for oauth2 and openIdConnect and requires it to be empty for an http scheme.

Headers

Idempotency-Key
string
required

Any string that identifies this request; a UUID is the usual choice, and at most 255 characters. ⚠️ REQUIRED. Without it a timeout is unresolvable: you cannot learn whether the envelope was created, and retrying makes a second one and emails everybody twice. The caller’s own request identifier.

Example:

"01960000-0000-4000-8000-00000000ffff"

Body

application/json

The template, the people, the values, and whether to send.

The request.

template_id
string<uuid>
required

The template to instantiate. Layout is authored there, never here (§3).

Example:

"01960000-0000-4000-8000-0000000007e1"

recipients
object[]
required

⚠️ THE ORDER OF THIS ARRAY IS THE ORDER RECIPIENTS ARE LISTED IN, and without step it is also when they are asked: everyone together when the template’s roles that are not cc all share one step, otherwise one at a time in this order. Give step on every recipient to say when directly. Reordering it is a different request either way, and an idempotency key will not replay across the two.

One recipient: a person, or a role pre-signed under a standing authorisation (an entry carrying completion).

values
object[]

Optional. Values to prefill, as triples. Omitted means none. ⚠️ A signature, a date_signed, a signer_name and a signer_email may not be prefilled — they are acts, or they are written by this system.

subjects
object

Optional. WHO THIS ENVELOPE IS ABOUT, as a map from a subject key the template declares to true (on this envelope), false (not), or "ask": the signer who holds that person’s section is asked first, in a required question, and their answer decides. While it is open the person reads present: false and awaiting_signer: true on the envelope. Two cases are settled at send instead, with nobody asked: a person no recipient holds a box for is left out, and a person a recipient signs for in a role standing for the same person is included. A field addressed to a subject that is not on the envelope is hidden from the signer and not required.

A subject you do not name takes the template’s own rule: a required subject is on every envelope, and a conditional one is absent and the signer is never asked about them, whatever the template’s Ask, Include or Leave out says (that choice applies to envelopes sent from the dashboard). Omitting subjects altogether opens the same sections as naming nobody — but see the next paragraph, because the two are not the same request. A key the template does not declare is refused, and so are false and "ask" for a required subject — all invalid_request, and nothing is created.

⚠️ IT SETS WHAT THE DOCUMENT OPENS WITH, NOT WHAT IT MUST STAY. The signer can switch a conditional subject on or off on the signing page, in either direction, and every such change is recorded in the envelope’s audit history.

⚠️ NAME AS true OR "ask" EVERY conditional SUBJECT YOU PREFILL. A value for a subject you ask about is shown if the signer answers Yes, and cleared if they answer No. A value in values for a conditional subject you did not name as present or asked is handled in one of two ways, depending on whether subjects is in the request at all:

  • subjects sent (even {}): the subject is absent — by false, or by the template’s rule when unnamed — so the value contradicts the request and is refused with invalid_request. Nothing is created.
  • subjects omitted: the value is accepted and stored, but the subject is absent by the template’s rule when the envelope is sent, so the prefilled section opens HIDDEN until the signer switches it on.

See Subjects.

Examples:
send
boolean

Optional, default false. False creates a draft and emails nobody; true sends it, consuming the plan’s allowance and delivering an invitation to everyone whose turn it is.

expires_at
string<date-time> | null

Optional, default null — no deadline. When this envelope stops being signable, as an ISO 8601 instant. ⚠️ AN ABSOLUTE TIME RATHER THAN A DURATION, so a retried request carrying the same Idempotency-Key asks for the same deadline the first attempt did. At least 1 hour out and at most 365 days out; anything else is invalid_request. ⚠️ IT CANNOT BE CHANGED AFTERWARDS — there is no endpoint that extends a deadline yet, and an envelope that reaches one while partly signed can only be voided and started again, discarding the signatures already collected. It is enforced: every signing link is capped by it, no link can be reissued past it, and the envelope transitions to expired and emits envelope.expired once it passes.

brand_id
string<uuid> | null

Optional, default null — the organisation’s default brand. Which brand the envelope goes out under: the letterhead, the colours and the sending name a signer sees. ⚠️ THIS IS THE FIELD FOR SENDING ON BEHALF OF MANY CUSTOMER BRANDS FROM ONE ACCOUNT — change it between calls and the same integration sends Customer A’s paperwork under Customer A’s brand and Customer B’s under Customer B’s.

⚠️ AN ID THAT NAMES NO LIVE BRAND OF YOUR ORGANISATION IS REFUSED WITH brand_unknown, NOT IGNORED — including one that has been archived. The branding an envelope went out under is frozen the moment it is sent and cannot be corrected afterwards, so a wrong constant in your configuration would otherwise put somebody else’s letterhead on every envelope you ever send and nothing would say so.

It is recorded on the envelope, so a draft created with send: false still goes out under this brand when it is sent later.

Copy the id from Settings → Brands in the dashboard: brands are made and managed there, and no endpoint lists them. What a brand controls, and what it does not, is on Brands.

completion_delivery
enum<string>

Who tells the recipients the envelope is done and sends them the executed document. vumasign (the default for a send from the dashboard) means we email the sender and every recipient we are able to email, with the sealed PDF attached. integrator (the default for a send made with an API key) means we send nothing at completion and you do it. Omit it and the origin of the send decides — an envelope created with send: false and then sent from the dashboard is vumasign. It cannot be changed once the envelope has been sent.

⚠️ AN embedded RECIPIENT IS NEVER EMAILED, WHATEVER THIS SAYS. We issue one no signing link and send them no invitation, because their address may be an identifier of yours rather than a mailbox — so they are not sent the completed document either, even under vumasign. Delivering the executed document to an embedded recipient is yours on every envelope, and this field only decides who tells everybody else.

⚠️ IF YOU TAKE THIS ON, SUBSCRIBE TO envelope.sealed RATHER THAN envelope.completed. envelope.completed fires when the last person signs, which is about a minute before the executed document exists, and envelope.sealing_failed tells you it never will.

Available options:
vumasign,
integrator
reference
string | null

Optional, default null. Your own name for this envelope — an order number, a case id, the id of the row in your database that asked for it — opaque to us. Not blank, and at most 255 UTF-16 code units once composed to NFC, as JavaScript counts string length: most characters count as one, some (outside the Basic Multilingual Plane, such as most emoji) count as two. No maxLength is declared, because JSON Schema counts code points and would admit a value the server refuses. Stored and returned in Unicode NFC. GET /api/v1/envelopes?reference= finds every envelope carrying it, which is how you find out whether a request whose answer you lost created anything.

⚠️ IT IS NOT UNIQUE. We accept the same reference on any number of envelopes, and the list returns all of them, newest first. If you want one envelope per reference, make your references unique — derive it from the record that asked for the envelope, not from the attempt.

⚠️ IT CANNOT BE SET OR CHANGED AFTER CREATION. Not on a draft, not by a later request: a reference that could move would not identify anything.

Example:

"hire-2026-0917"

template_etag
string

Optional. The ETag of the template as you checked it — from GET /api/v1/templates/{templateId} or the template_etag of validate-values — with or without its quotes. When it is no longer current the request is refused with template_changed and nothing is created: the template has been renamed since, and a value could now fill a different box. ⚠️ SEND IT ON EVERY ENVELOPE. An unknown key fails loudly, but a SWAPPED one — two addresses exchanged — does not, and this is what catches it. Compared under the template’s lock, so nothing can change between the check and the copy.

Required string length: 1 - 200
attachments
object[]

Optional. Documents of your own sent beside the template’s, after them, in the order given — each a PDF or a Word .docx, base64-encoded, exactly as documents on POST /api/v1/envelopes/one-off. Their fields come from their own text tags, which name the roles in recipients: a template role, or a role only an attachment names, whose recipient then signs. A tag naming a role nobody holds, or using subject(...), is invalid_request, and values never fill an attachment. ⚠️ THE TEMPLATE’S DOCUMENTS AND THESE TOGETHER MAY BE AT MOST 10, and together these may hold at most 6 MB of document. Absent and [] are different requests under one Idempotency-Key; both make the template’s envelope alone.

Maximum array length: 9
documents
object[]

Optional. The order the envelope’s documents are presented in: the signing page, the “Document N of M” above each page, the order fields are walked in, the completion email’s attachments, display_position on GET /api/v1/envelopes/{envelopeId}/documents, and the “document N of M” on each certificate. Absent: the template’s documents in its order, then attachments in the order given. Present: EVERY template document and EVERY attachment exactly once, each entry naming one of them — { "attachment": 0 } for the first of attachments, { "template_document": "<id>" } for a template document, by its id in GET /api/v1/templates/{templateId}’s documents. Allowed without attachments, to reorder a template of several documents. TO LEAVE A TEMPLATE DOCUMENT OFF THE ENVELOPE, name it with "include": false: it, its fields and any question wholly on it are not part of the envelope, and the rest close up. It is refused template_document_not_omittable when the envelope cannot do without it — the last signature box a required role is sure to sign, when no attachment gives another, a subject, a box that decides a kept box, part of a question a kept document also asks, every box of a role you name a recipient for — or when every template document is left out. ⚠️ A TEMPLATE DOCUMENT NOT NAMED AT ALL IS invalid_request, not left out, so a document is never dropped without your saying so; so is an attachment left out, a document named twice, "include": false on an attachment, or an index past attachments. An id the template does not hold is template_changed: read the template again. The first of the template’s documents you keep is position 1 of the envelope, whatever its place here. A different order is a different request under one Idempotency-Key. Not accepted on a batch.

Required array length: 1 - 19 elements

One document of the envelope, by exactly one key: attachment or template_document.

Response

The envelope, as it stands. Idempotency-Replayed says whether this request created it (false) or is being shown an earlier one’s result (true); the status is 201 either way, deliberately, so that a client branching on it behaves identically on a retry.

The envelope.

id
string<uuid>
required

The envelope’s id. A bare uuid.

status
string
required

draft or sent from this endpoint. Later states arrive as people act.

template_id
string<uuid> | null
required

The template this was made from, or null when there was none — an envelope created by POST /api/v1/envelopes/one-off carries the document itself and never had a template. Branch on null, never on the empty string.

title
string
required

What the signers see naming the document. Defaults to the template’s name.

reference
string | null
required

The reference you set when you created it, in Unicode NFC, or null. Not unique, and never changed after creation.

Example:

"hire-2026-0917"

created_at
string<date-time>
required

ISO 8601, UTC.

sent_at
string<date-time> | null
required

ISO 8601, UTC. Null while it is a draft.

expires_at
string<date-time> | null
required

ISO 8601, UTC. Null when this envelope has no deadline, which is the default. Read back from the stored value rather than echoed, so an offset you sent comes back as the same instant in UTC.

recipients
object[]
required

In routing order.

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.

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.