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.

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.