Envelope lifecycle
Every state an envelope passes through, and what triggers each transition.
An envelope is the unit of signing in legesis. It bundles one or more files, a list of recipients, and the metadata required to produce a legally valid signed PDF.
Envelopes move through a small, well-defined state machine.
States
| State | Meaning |
|---|---|
draft | Created but not yet sent. Fields and recipients can be edited. |
sent | Recipients have been notified. Fields are locked. |
in_progress | At least one signer has interacted, but signing is incomplete. |
completed | All recipients have signed. Final PDF is generated. |
voided | Cancelled by sender. Cannot be reopened. |
expired | Reached its expiry without completion. |
declined | A recipient explicitly declined to sign. |
Transitions
| From | Event | To |
|---|---|---|
draft | POST /envelopes/:id/send | sent |
sent | First signer opens the envelope | in_progress |
in_progress | Last signer completes | completed |
draft / sent / in_progress | POST /envelopes/:id/void | voided |
draft / sent / in_progress | POST /envelopes/:id/expire | expired |
draft / sent / in_progress | A recipient declines | declined |
A visual state diagram (Mermaid) ships with the API reference in week 2.
Why this matters for webhooks
Each transition emits an event. Subscribe to them via webhook endpoints to keep your own systems in sync without polling.
| Event | Fires when |
|---|---|
envelope.sent | Sender calls /send. |
envelope.viewed | Any signer opens. |
envelope.signed | A signer completes. |
envelope.completed | Last signer completes. |
envelope.voided | Sender voids. |
envelope.expired | Expiry timestamp passes. |
envelope.declined | A signer declines. |
envelope.field_added | Sender adds a field while in draft. |
The full payload schema for each event ships with the webhook reference (coming in week 2).