DocuSign envelope created via API shows no documents - the document bytes were dropped

TL;DR

An envelope that creates successfully but shows no documents means the documents array in your request was empty, malformed, or silently dropped: the usual cause is an empty documentBase64 string, a name without a .pdf extension, or building the request in a code path that serializes documents separately from the envelope. Decode your own base64 locally and confirm it is a PDF before sending, check the documents array shape against the API reference, and read the envelope's document list back after creation. The envelope itself is valid - only the attachment step failed.

The query

DocuSign envelope created via API shows no documents  -  the document bytes were dropped

Use this when

• Create-envelope returns 201 but the envelope shows no documents in the console
• Recipients get signing links with nothing to sign
• The same code works for templates but fails when you attach raw PDFs

Not for

• Envelopes rejected at creation with PDFVALIDATIONFAILED - those never create at all
• Documents that appear but render blank - a rendering problem, not a missing-documents problem
• Composite-template tab errors, which fail creation rather than dropping documents

Steps

1. Decode your own base64 before blaming the API

Take the exact documentBase64 string from the outgoing request (not the source file) and decode it locally. If it decodes to zero bytes or is not a PDF, the bug is in your encoding step - a file read that returned empty, a stream consumed twice, or a variable shadowed between building the envelope and building the documents.

import base64
raw = base64.b64decode(req["documents"][0]["documentBase64"])
print(len(raw), raw[:5])

Expected output: a real byte count and the %PDF magic. Zero bytes means your encoder sent nothing.

2. Check the documents array shape field by field

Each entry needs a unique documentId, a name ending in .pdf, and a non-empty documentBase64. A missing name extension or a duplicate documentId can cause the entry to be dropped without an error on creation.

"documents": [{"documentId": "1", "name": "agreement.pdf", "documentBase64": "[BASE64_BYTES]"}]

Expected output: every entry has all three fields populated and documentIds are unique strings.

3. Look for the envelope/documents split in your code

A common pattern: one function builds the envelope skeleton and another attaches documents, and the second never runs on some code path (an early return, a conditional for templates, an exception swallowed by a try/except). Trace the actual request object sent on the wire - log the full JSON at send time. Expected output: the logged request JSON contains the documents array you expected.

4. Read the envelope's document list back after creation

Call the envelope documents list endpoint for the created envelopeId. If it is empty, the documents were dropped at creation; if it lists them, the problem is display-side. This read-back is also a good permanent assertion in your integration tests. Expected output: the list endpoint returns the same document count you sent.

5. Resend with a minimal hardcoded document

Replace your dynamic document building with a tiny hardcoded PDF's base64. If documents appear, bisect your document pipeline; if they still do not, the bug is in the request assembly itself. Expected output: the hardcoded document shows up, isolating the failure to your pipeline or your assembly code.

Tool compatibility

DocuSign eSignature REST API v2.1 envelope creation, any SDK or direct REST. The documents-array contract is identical on demo and production.

Variant phrasings

• DocuSign envelope created via API shows no documents
• DocuSign API envelope empty no documents attached
• document bytes dropped DocuSign envelope creation
• DocuSign create envelope 201 but documents missing

Why it happens

The create-envelope endpoint is lenient about the documents array: it validates the envelope shell (recipients, status, email subject) strictly but treats a missing or empty documents list as 'an envelope with no documents yet', which is a legal state for drafts. So an encoding bug that empties the bytes does not fail creation - it succeeds and leaves you with a document-less envelope, which only surfaces when a human opens it.

Edge cases / pitfalls

• Composite templates have their own document-merge rules - documents supplied there follow the composite assembly, not the plain documents array.
• Base64 strings with data-URI prefixes or whitespace can decode to garbage; strip prefixes before encoding.
• Watch request-size limits: very large documents can be truncated by proxies, arriving as valid JSON with clipped base64.
• Void the document-less test envelopes so they do not linger in sent state confusing recipients.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstiX7qyow0EzChu933qwXmA