Skip to main content
POST
Withdraw a sent envelope.

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 — see the note above on why a void without one cannot be retried safely. The caller’s own request identifier.

Example:

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

Path Parameters

envelopeId
string<uuid>
required

The envelope to withdraw, as returned when it was created. An envelope id.

Example:

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

Body

application/json

Why this envelope is being withdrawn.

Why this envelope is being withdrawn.

reason
string
required

WHY, IN WORDS SOMEBODY WILL READ MONTHS LATER. Required, and kept on the envelope record and in the audit event — it is the answer to “why is this contract withdrawn”, asked by somebody who was not there. At most 500 characters.

Maximum string length: 500
Example:

"Superseded by a corrected offer"

Response

The envelope, now voided, with the reason it carries. Its recipients are returned as they stand — a recipient who had already signed still reads signed, because they did.

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.