What is an envelope?
An envelope is the top-level container for a signing transaction. It holds:
- One or more documents (PDFs)
- One or more signers with a defined routing order
- Fields positioned on pages (signature, initials, date, text, checkbox)
- An audit log tracking every event
Status flow
draft → sent → in_progress → completed
↓
declined | voided | expired
| Status | Meaning |
|---|
draft | Created but not sent. Fields can still be added or changed. |
sent | Signing invites dispatched. Waiting for the first signer to open their link. |
in_progress | At least one signer has viewed or started signing. |
completed | All signers have signed. Sealed PDF is available for download. |
declined | A signer declined to sign. No further signing is possible. |
voided | You cancelled the envelope. No further signing is possible. |
expired | The expires_at timestamp passed without all signers completing. |
Routing order
Signers are routed sequentially by routingOrder. Signer 2 does not receive their invite until
Signer 1 completes.
"signers": [
{ "name": "Alice Manager", "email": "alice@acme.com", "routingOrder": 1 },
{ "name": "Bob Client", "email": "bob@client.com", "routingOrder": 2 }
]
routingOrder.
Creating an envelope
See the Quickstart for the full curl walkthrough. The minimum required payload:
{
"tenantId": "your-tenant-id",
"subject": "Agreement Title",
"signers": [
{
"name": "Jane Smith",
"email": "jane@example.com",
"routingOrder": 1,
"authMethod": "email_otp"
}
]
}
/send.
Field types
| Type | Description |
|---|
signature | Drawn or typed signature image |
initial | Initials only |
date | Auto-populated with the signing date — not editable by signer |
text | Free-form text input |
checkbox | Boolean checkbox |
page, x, y, w, h coordinates. Origin is bottom-left of the page in
PDF points (1 pt = 1/72 inch).
Use the visual field placer in the Console (/envelopes/{id}/place) to position fields by
dragging without calculating coordinates manually.
Voiding an envelope
You can void any non-terminal envelope (status draft, sent, or in_progress):
curl -X POST https://api.getsigned.ca/v1/envelopes/env_01HX.../void \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{ "reason": "Sent to wrong recipient" }'
Expiry
Set expiresAt on the envelope to enforce a signing deadline:
{
"expiresAt": "2026-07-01T00:00:00Z"
}
expired and all remaining signing
links become invalid.
Downloading the sealed PDF
Available only when status = completed:
curl -L https://api.getsigned.ca/v1/envelopes/env_01HX.../document \
-H "Authorization: Bearer $TOKEN" \
-o signed_agreement.pdf
- Has all signature fields flattened into the document
- Carries a PKCS#7 digital signature verifiable in Adobe Acrobat
- Includes an audit certificate page listing every event with timestamps and IP addresses
This integration endpoint works any time within the retention window. On completion GetSigned
also emails every party the sealed copy automatically — attached if it’s small, or a secure download
link if it’s too large to attach. Archive the PDF to your own system on the envelope.completed
webhook rather than relying on GetSigned as a long-term store.
Document retention
Documents are retained for a per-tenant configurable window (default: 30 days). After it
expires the PDF blob is deleted from storage, but the audit trail — hashes, event metadata, and the
hash-chained log — is retained permanently, so a produced copy can still be verified against the
stored final hash.
Recipients who were emailed a download link (rather than an attachment) and haven’t saved their copy
are reminded at 20, 10, and 1 day before deletion.
You can check retention status via the retention_until and purge_status fields returned by
GET /v1/envelopes/{id}.
