> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thesignproof.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Envelopes

> The envelope lifecycle — draft, sent, in progress, completed, and terminal states.

## 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.

```json theme={null}
"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](/quickstart) for the full curl walkthrough. The minimum required payload:

```json theme={null}
{
  "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).

<Tip>
  Use the visual field placer in the Console (`/envelopes/{id}/place`) to position fields by
  dragging without calculating coordinates manually.
</Tip>

***

## Voiding an envelope

You can void any non-terminal envelope (status `draft`, `sent`, or `in_progress`):

```bash theme={null}
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:

```json theme={null}
{
  "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`:

```bash theme={null}
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}`.