Envelopes

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 }
]

To send to all signers simultaneously, give them the same 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"
    }
  ]
}

Then upload the PDF and place fields before calling /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

All fields have 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.thesignproof.com/v1/envelopes/env_01HX.../void \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Sent to wrong recipient" }'

Voiding is permanent. The voided event is recorded in the audit log.

Expiry

Set expiresAt on the envelope to enforce a signing deadline:

{
  "expiresAt": "2026-07-01T00:00:00Z"
}

When the deadline passes, the envelope status transitions to expired and all remaining signing links become invalid.

Downloading the sealed PDF

Available only when status = completed:

curl -L https://api.thesignproof.com/v1/envelopes/env_01HX.../document \
  -H "Authorization: Bearer $TOKEN" \
  -o signed_agreement.pdf

The downloaded 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 SignProof 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 SignProof 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}.

Get Started

Guides

What is an envelope?

Status flow

Routing order

Creating an envelope

Field types

Voiding an envelope

Expiry

Downloading the sealed PDF

Document retention

​What is an envelope?

​Status flow

​Routing order

​Creating an envelope

​Field types

​Voiding an envelope

​Expiry

​Downloading the sealed PDF

​Document retention

What is an envelope?

Status flow

Routing order

Creating an envelope

Field types

Voiding an envelope

Expiry

Downloading the sealed PDF

Document retention