Skip to main content
POST
Send a draft envelope to its recipients.

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 went out, and retrying either sends it twice or tells you it is not a draft without saying who sent it. The caller’s own request identifier.

Example:

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

Path Parameters

envelopeId
string<uuid>
required

The draft envelope’s id, as returned when it was created. An envelope id.

Example:

"01960000-0000-4000-8000-0000000000e5"

Response

The envelope, now sent. invitation_delivered on each recipient is what the email provider said about that invitation — null where none was attempted, which on an envelope in steps is everybody outside the first step.

⚠️ HERE, AND ONLY HERE, true MEANS "THE PROVIDER ACCEPTED IT" RATHER THAN "THE PROVIDER DELIVERED IT". This response is built from the answers the provider gave while the send was running, and at that moment nobody — us or them — knows whether the message will arrive. Delivery is reported afterwards, and GET /api/v1/envelopes/{id} is where it shows up. If the distinction matters to you, re-read there rather than trusting this snapshot.

⚠️ A recipient still reading pending after a successful send is NORMAL on an envelope in steps, not a failure.

The envelope, as it now stands.

id
string<uuid>
required

The envelope’s id. A bare uuid.

status
string
required

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

template_id
string<uuid> | null
required

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

title
string
required

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

reference
string | null
required

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

Example:

"hire-2026-0917"

created_at
string<date-time>
required

ISO 8601, UTC.

sent_at
string<date-time> | null
required

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

expires_at
string<date-time> | null
required

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

recipients
object[]
required

In routing order.

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.