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 or viewer.
• order - Order in the signing flow.
• status - pending, 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.

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