Envelopes and signers

ConceptSep 27, 20263 min read

An envelope is one document on its way to being signed. It holds the PDF, the signers (who signs), and where each of them signs. You create envelopes from a PDF or from a template.

Envelope status

draft→sent→completedorvoided

Status	Meaning
`draft`	Created with send: false. Nothing has gone out. Send it later with POST /v1/envelopes/{id}/send.
`sent`	Signers can sign. Envelopes are sent right away unless you set send: false.
`completed`	Everyone signed. The signed PDF and audit trail are ready to download.
`voided`	Cancelled before completion. Signing links stop working.

Signers

Each signer has a role, such as client or agent. Fields in the document belong to a role, so the same template works for every client. Signer status is pending, viewed, completed or declined.

By default everyone can sign at once. Set signing_order: true to have signers go one after another, in the order you list them.

The envelope object

{
  "id": "env_7Kd2mQ9xLp4R2sVt8nB1cW0a",
  "object": "envelope",
  "livemode": false,
  "status": "sent",
  "name": "Purchase agreement",
  "template": "tmpl_purchase_agreement",
  "delivery": "email",
  "signing_order": false,
  "signers": [
    {
      "id": "sgn_5b1c...",
      "role": "client",
      "name": "Jane Doe",
      "email": "jane@acme.com",
      "order": 1,
      "status": "pending",
      "viewed_at": null,
      "signed_at": null
    }
  ],
  "files": { "signed": false, "audit_trail": false },
  "metadata": { "crm_deal_id": "D-1042" },
  "created_at": "2026-09-27T15:04:05.000Z",
  "sent_at": "2026-09-27T15:04:06.000Z",
  "completed_at": null,
  "voided_at": null,
  "expires_at": null
}

Use metadata to store your own IDs (up to 20 keys). It comes back on every read and every webhook, so you can match an envelope to your records without a lookup.

Next steps

Was this page helpful?