# Envelopes

_Send a contract for signature in one HTTPS call. $0.10 per envelope. Full feature set, no subscription._

_Last updated: 2026-05-15_

---

# Envelopes

Send a PDF (or up to 10 PDFs) for signature in one HTTPS call. **$0.10 per envelope.** The full feature set — not a stripped-down "API-only" tier:

- **Multi-document.** Up to 10 documents per envelope.
- **5 recipient roles** in up to 10 recipients: `SIGNER`, `APPROVER`, `VIEWER`, `CC`, `ASSISTANT`.
- **10 field types:** `SIGNATURE`, `INITIALS`, `NAME`, `EMAIL`, `DATE`, `TEXT`, `NUMBER`, `CHECKBOX`, `RADIO`, `DROPDOWN`.
- **Positional or placeholder field placement.** Pixel-based (page + x/y/width/height percentage) or PDF-placeholder markers (`[component]}`) embedded in the source PDF.
- **Draft workflow.** Create envelope, place fields later, send — charging fires at send, not draft.
- **Templates.** Reusable envelope definitions instantiated with just-the-recipients-changed.
- **Direct signing links.** No email invite required when you want to drive distribution yourself.
- **Live status tracking + 7 webhook events:** `envelope.sent`, `.viewed`, `.signed`, `.completed`, `.rejected`, `.expired`, `.cancelled`.
- **Resend reminders** to unsigned recipients.
- **Cancel + auto-refund** on terminal failures, up to a per-envelope cap.
- **Download** signed + original PDFs.
- **eIDAS signature levels:** Simple, Advanced, Qualified.
- **X.509 signing certificates** on every completed document — cryptographic proof of authenticity and integrity.
- **Compliance built in:** ESIGN Act (US), UETA (US), eIDAS (EU). SOC 2 framework. 21 CFR Part 11 (FDA pharma/healthcare). GDPR data handling.

## How it compares

DocuSign, Adobe Sign, and the enterprise incumbents charge ~$3 per envelope. They include the signing AND enterprise wrappers — account management, contract minimums, regulated workflows, liability transfer, compliance reporting bundles. If you need those, the incumbents are still your path.

**We sell the signing, not the wrappers.** Same core feature set at $0.10. When you need the full enterprise bundle, the incumbents are still there. When you just need "send this contract for signature," we're ~30x cheaper because we're not making you pay for services you didn't ask for.

| Provider | Price per envelope | Feature set |
|---|---|---|
| Verafirma | **$0.10** | eIDAS-Advanced + X.509 + multi-document + 5 roles + 10 field types + templates + webhooks + ESIGN/UETA/GDPR |
| DocuSign / Adobe Sign | ~$3 | Same core + enterprise wrappers (account management, contract minimums, liability, compliance bundles) |

## The pieces

### Envelope

The container. Carries:

- **A PDF.** Either uploaded directly (multipart form on `POST /v1/envelopes`) or instantiated from a [template](#templates).
- **A title.** Free-text label for the customer side; appears in dashboards and notification emails.
- **A status.** Tracks the envelope's lifecycle.
- **A storage expiry.** Optional; the underlying signing engine retains the completed PDF for the configured number of days, after which it's purged.

### Recipient

A person or role that interacts with the envelope. One envelope can have up to ten recipients in V1. Each recipient has:

- **Email.** Where the signing-link notification is sent.
- **Name.** Displayed in the signing UI.
- **Role.** One of:
  - `SIGNER` — adds a binding signature.
  - `APPROVER` — must approve before signers can sign (sequenced workflows).
  - `VIEWER` — can read the envelope but doesn't sign.
  - `CC` — receives a copy of the completed envelope but doesn't interact.
  - `ASSISTANT` — fills fields on behalf of a signer (delegated data entry, no signature authority).

### Field

A placeable element on the PDF. Coordinate-based (percentage of page) OR PDF-placeholder-marker-based (`[component]}` literals embedded in the source PDF).

Field types:

`SIGNATURE`, `INITIALS`, `NAME`, `EMAIL`, `DATE`, `TEXT`, `NUMBER`, `CHECKBOX`, `RADIO`, `DROPDOWN`.

Each field is bound to one recipient via their email; only that recipient can fill the field.

### Template

A saved envelope definition. PDFs + field placements + recipient roles, parameterized so a new envelope can be instantiated from the template with just-the-recipients-changed.

Templates are esignature-specific; they don't surface on the lodestone path (which is single-shot by design). Created via `POST /v1/templates`; instantiated via `POST /v1/templates/id/from-template`.

## Lifecycle

```
DRAFT → PENDING → SENT → PARTIALLY_SIGNED → COMPLETED
```

With three alternative terminal states:

```
SENT → REJECTED   (a signer rejected; flow halts; refund-on-terminal triggers)
SENT → EXPIRED    (the signing window closed without all signers; refund-on-terminal triggers)
SENT → CANCELLED  (the customer or operator cancelled; refund-on-terminal triggers)
```

The four terminal states (`COMPLETED`, `REJECTED`, `EXPIRED`, `CANCELLED`) are the only states from which an envelope cannot transition.

`DRAFT` is the initial status when `POST /v1/envelopes` is called without a `fields` array. Mutations on the draft (`POST /:id/fields`, `DELETE /:id/fields/fid`) only work while the envelope is `DRAFT`. Once `POST /:id/send` distributes the envelope, no more field changes are allowed.

For the simple workflow — one PDF, fields known up front — call `POST /v1/envelopes` with the fields array included in the payload, and the envelope skips `DRAFT` and goes straight to `PENDING`/`SENT`.

## Sending and signing

### Distribution

When an envelope transitions to `SENT`, each recipient gets a signing-link email. The link carries a token bound to that recipient; opening it loads the signing UI with their fields pre-targeted.

### Signing

The signing UI is hosted by Verafirma at `sign.verafirma.com`. Signers fill their fields, click sign, and the system generates a signed-PDF artifact bound to the envelope (eIDAS-Advanced level, X.509 certificate embedded). When all `SIGNER` recipients have signed, the envelope transitions to `COMPLETED`.

The signing UI reflects the operator's brand — the API consumer doesn't supply a signing UI.

### Reminders

Recipients who haven't signed get periodic reminder emails (cadence configured at the engine). The customer can also chase manually:

```sh
curl -X POST https://api.verafirma.com/v1/envelopes/id/resend \
  -H "Authorization: Bearer vf_live_..."
```

This re-sends the signing link to NOT_SIGNED recipients without changing the envelope's state.

### Cancellation

A SENT envelope can be cancelled before all signatures land:

```sh
curl -X DELETE https://api.verafirma.com/v1/envelopes/id \
  -H "Authorization: Bearer vf_live_..."
```

Cancellation transitions the envelope to `CANCELLED` and triggers the refund-on-terminal flow (the original charge is refunded up to the per-envelope cap).

## Reading state

### Cached vs. live

Two read endpoints with different freshness:

- `GET /v1/envelopes/id` — returns the wrapper's cached state. Fast (sub-100ms typically); reflects whatever the wrapper last persisted from a webhook event or read.
- `GET /v1/envelopes/id/status` — fetches authoritative state from the underlying signing engine, reconciles the cache if it had drifted, and returns the live shape.

Use `/status` when accuracy matters (e.g. before completing a downstream action that depends on signature completion). Use the cached read for high-volume polling where eventual consistency is fine.

### Listing

`GET /v1/envelopes?limit=&offset=&status=` returns paginated envelopes for the authenticated customer. The `status` filter is exact-match against the V1 status enum.

### Downloading

`GET /v1/envelopes/id/download?version=signed` streams `application/pdf`. Only available when the envelope is `COMPLETED`. The `version` query is `signed` (default — the signed artifact) or `original` (the source PDF before signing).

## Limits

V1 caps each envelope at:

- **≤10 signers** AND **≤10 documents.** Anything larger returns `400 OUT_OF_SCOPE_V1`.

These limits are tunable post-deploy (per the operator's configuration surface) but the V1 defaults won't move without explicit operator action. If you have a use case that needs >10 of either, contact the operator.

## Pricing

$0.10 per envelope, charged at creation. Full feature set in the price: eIDAS-Advanced signing, X.509 certificates, up to 10 documents and 10 recipients in 5 roles, 10 field types, templates, webhooks, ESIGN + UETA + eIDAS + SOC 2 + 21 CFR Part 11 + GDPR compliance. Refunded on terminal failure (`REJECTED`, `EXPIRED`, `CANCELLED`) up to a configurable per-envelope cap. See [`/pricing`](/pricing) for the per-mode breakdown.

## When you outgrow us

Verafirma is built to be replaceable. We host battle-tested open-source software ourselves on cheap infrastructure and charge you what it costs to run plus a markup. When your volume reaches the point where running it yourself makes sense, ask us — we'll point you at exactly what we use and how we configured it. No vendor lock-in. No proprietary client SDK you'd have to throw away. The on-the-wire contract is standard HTTPS + x402; you can swap us out without changing client code.