Skip to main content

​
Overview

A single envelope can contain multiple PDFs. Each document is independently sealed with its own SHA-256 hash; the envelope’s document_hash_final is derived from all per-document hashes combined. Signers see every document in one signing session and cannot submit until they have scrolled through all pages of all documents. Multi-document envelopes require a Pro plan or higher.

​
Creating a multi-document envelope

Upload each PDF separately using the console document upload endpoint, then reference all document IDs when building the envelope. 
# 1. Upload document 1
curl -X POST https://api.getsigned.ca/v1/console/envelopes/{id}/documents \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@contract.pdf"

# 2. Upload document 2  (Pro+ only — rejected on Starter / Solo)
curl -X POST https://api.getsigned.ca/v1/console/envelopes/{id}/documents \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@exhibit-a.pdf"
The second upload is gated: if your plan is below Pro, it returns 402 Payment Required.

​
Signer experience

When a signer opens their tokenized link, the signing UI fetches the full document list: 
GET /v1/signing/{token}/documents

[
  { "documentId": "doc-uuid-1", "pageCount": 6, "order": 1 },
  { "documentId": "doc-uuid-2", "pageCount": 3, "order": 2 }
]
The UI presents a document navigator. Signers step through each document in order using GET /v1/signing/{token}/documents/{docId} to stream each PDF. The Sign button stays disabled until all pages of all documents have been scrolled — enforced client-side with a toast prompt (“Please read all documents before signing”). Each page view is recorded: 
POST /v1/signing/{token}/page-view
Content-Type: application/json

{
  "documentId": "doc-uuid-1",
  "page": 3,
  "dwellMs": 4200
}
These events appear in the audit trail export as page_viewed entries.

​
Sealing

On completion, SealingService seals each document independently and stores:
  • envelopes/{id}/sealed/{docId}.pdf per document
  • envelopes/{id}/sealed.pdf for the first document (legacy path, backward compatible)
The envelope’s document_hash_final is computed as: 
SHA-256( SHA-256(doc1) ‖ SHA-256(doc2) ‖ … )
where hashes are sorted by document_order before concatenation. This means tampering with any single document breaks the combined hash, and the full set of per-document hashes is preserved in the audit log for independent verification.

​
Delivery

On completion, the sealed copy of every document is emailed to all parties. Large payloads (total > Email:MaxAttachmentBytes, default 10 MB) fall back to a tokenized /download/{token} link. Each document is delivered as a separate attachment or link.

​
Backward compatibility

Existing single-document integrations are unaffected. The document_order column defaults to 1, and GET /v1/signing/{token}/document (without /{docId}) continues to serve the single original PDF. The document_hash_final for a single-document envelope equals the hash of that one document — identical to the pre-multi-doc behavior.