This document is generated by Apidog. Apidog: All-in-one workspace for API design, document, debug, test, mock
Envelope lifecycle
States
Draft — the usual starting state: the envelope exists and no signer can see it. Not always where you begin, though: creating an envelope with toBePublishedAtUtc set returns it already in PublishScheduled.PublishScheduled — publication is booked and has not happened yet. It can be published early, put on hold, or cancelled. It cannot expire from here; expiry applies only to published envelopes.Published — signers have been invited and can act. Every terminal outcome leads from here.Hold — paused; signers cannot act. From hold the envelope can be published again, rescheduled, or cancelled. Hold is also the way back for envelopes that expired or were cancelled.Expired — expiresAtUtc passed without every signer completing. All remaining signers are reset, so republishing starts them over.CancelledBySignerMfaError — a signer failed identity validation in a way that stopped the workflow.Cancelled — cancelled by the account. Not a dead end: it can go to Hold and back into circulation.Signed — every required signer completed. Terminal.Rejected — a signer declined. Terminal.Signed and Rejected are truly terminal. If you are modelling this on your side, do not treat a cancellation or an expiry as the end of the envelope's life.Publishing
POST /{id}/publish is accepted from Draft, Hold and PublishScheduled only. Publishing an envelope that is already Published returns 400, which is what makes a retry after an ambiguous failure safe: either it publishes, or it tells you it already did.POST /{id}/unschedule puts the envelope on Hold, not back to Draft. A PUT that omits toBePublishedAtUtc on an envelope that had one does the same thing silently.Hold and the owner is emailed.Trash
Published envelope cannot be trashed — you get a 400. Cancel or hold it first.404 for it, and it is excluded from vault listings. There is no endpoint that lists the trash, so keep the id if you intend to restore it.POST /{id}/restore/to/{vaultId} — and the envelope moves there. It keeps the status it had when it was trashed.Modified at 2026-08-30 02:26:52