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
Section titled “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
Section titled “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
Section titled “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
Section titled “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, ordate. - 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
Section titled “Recipients”Recipients are listed via envelope/list-recipients. Each recipient has:
- email, firstname, lastname, phone - Identity.
- role -
signer,approver, orviewer. - order - Routing order within the recipient’s role group (approvers or signers).
- status -
pending,approved,signed,declined, orcanceled. - verificationType -
none,sms, oremail. - 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
Section titled “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
Section titled “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
Section titled “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.