Skip to main content
POST
Send a document that is not 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 sends the same document a second time. The caller’s own request identifier.

Example:

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

Body

application/json

The documents, the people, and whether to send.

The request.

title
string
required

What the signers see naming the document. Required — there is no template to borrow a name from.

Example:

"Offer of employment — A. Dlamini"

documents
object[]
required

The documents, base64-encoded, in the order a signer meets them. They are stacked into one scroll on the signing screen, and each is sealed on its own with its own Certificate of Completion. ⚠️ A PDF OR A WORD .docx, DECIDED BY THE BYTES AND NOT BY THE FILENAME — a .docx is converted to PDF on our side, and the envelope is over the converted PDF. Text tags survive that render, which is now OUR render rather than a step you take first. A tag addresses a page of the document it is written on, so <<sig:Employee>> on the annexure places a box on the annexure. ⚠️ EVERY DOCUMENT HERE SHARES ONE REQUEST BODY, so together they may hold about 6 MB of document — not that much each.

Required array length: 1 - 10 elements
recipients
object[]
required

⚠️ THE ORDER OF THIS ARRAY IS THE ORDER RECIPIENTS ARE LISTED IN, and without step and with signing_mode: sequential it is also the order they are asked. Each role is a slot a text tag can name — <<sig:Employee>> finds the recipient whose role is Employee. A tag naming anything else is refused rather than creating a role nobody fills.

Required array length: 1 - 100 elements

One recipient: a person, or a role pre-signed under a standing authorisation (an entry carrying completion). A one-off takes no values, so a pre-signed role may carry only the fields Vumasign fills.

sender
string<uuid>

Which member of this organisation the signer is asked BY — it becomes the name on the invitation, on every email the signers receive after it, and on the Certificate of Completion, whichever key later sends a draft. Omitted means the user who minted the key, which is a fallback rather than a choice: when that person leaves, every document still arrives from them.

Example:

"01960000-0000-4000-8000-000000000021"

signing_mode
enum<string>

Whether everyone is asked at once, or each in turn in the order of recipients. Defaults to parallel. ⚠️ NOT WITH step: the two answer the same question, and giving both is refused as step_with_signing_mode.

Available options:
parallel,
sequential
Example:

"sequential"

send
boolean

Optional, default false. False creates a draft and emails nobody; true sends it, consuming the plan’s allowance and delivering to whoever’s turn it is. Embedded recipients are never emailed either way.

Example:

false

expires_at
string<date-time> | null

When the envelope stops being signable. Omitted means it does not expire.

Example:

"2026-10-31T23:59:59Z"

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"

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.

Send it when a role is pre-signed under a standing authorisation: the authorisation covers one brand, and a document that goes out under another, or under none, is refused.

Response

The envelope, as it stands, with template_id null. 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, so 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.