Envelope structure

This page describes the API usage model of an envelope: the resources you create and read via the API and how they relate. It does not describe the internal database schema.

Envelope

The envelope is the top-level resource. When you get an envelope (e.g. envelope/get), the response includes:

• Metadata: uuid, title, status, creationDate, updateDate, sentDate, owner, sender, tags, metrics (signature counts), signatureOrder, expirationPeriod, and related options.
• documents: Array of document objects (see below).
• attachments: Array of attachment objects (see below).

Recipients are not embedded in the get response. You list them with a separate call: envelope/list-recipients (with workspaceUuid and envelopeUuid).

Documents

Each document in documents[] has:

• uuid, title — Identity and label.
• blocks - A map from page index (string) to an array of blocks on that page. This is the only per-document structure exposed in the get response.
• pageCount, snapshotDate - Page count and optional snapshot timestamp.
• signaturesOnSeparatePage, initialsOnAllPages, mustReadAllPages - Signing options.

Attachments

Each attachment has uuid and title. Attachments do not have blocks; they are supporting files (e.g. PDFs) that recipients can view or download.

Blocks

Blocks are stored per document, keyed by page. In the API, document.blocks is a record from page key to an array of blocks. Each block has:

• type - signature, text, image, or date.
• uuid, label - Identity and optional label.
• x, y (and optionally width, height) - Position on the page.
• recipientEmail, recipientLabel - For signature (and some text) blocks, the recipient who must sign or whose data is shown.

So from an API perspective: you assign blocks to a page on a document, and for signature blocks you set recipientEmail to the recipient who must sign there.

Recipients

Recipients are listed via envelope/list-recipients. Each recipient has:

• email, firstname, lastname, phone - Identity.
• role - signer, approver, or viewer.
• order - Routing order within the recipient’s role group (approvers or signers).
• status - pending, approved, signed, declined, or canceled.
• verificationType - none, sms, or email.
• invitation - Optional object with valid, expirationDate, medium, etc.

Signature blocks on documents reference recipients by recipientEmail; that links “this block” to “this recipient” in the API model. Only signers need signature blocks; approvers and viewers do not.

Approval workflow

When an envelope has at least one recipient with role: "approver", sending it sets the envelope status to approving. Approvers must approve before signers are invited. After all approvers reach status approved, the envelope transitions to signing and signer invitations are sent.

Envelopes with no approvers go directly to signing on send. Every envelope must have at least one signer; send fails with NO_SIGNERS otherwise.

The same email can appear on multiple recipient rows with different roles (for example, both approver and signer).

API credits

Public API sends (envelope/send on the team API) deduct one API credit per recipient with role: "signer". Approver and viewer rows are not billed.

Structure diagram

Summary:

• Envelope has documents and attachments in the get response; recipients come from a separate endpoint.
• Each document has blocks keyed by page; blocks can reference a recipient via recipientEmail.

Next steps

Lexical

Create and send your first envelope