Composite Templates: Unable to Upload Multiple Additional Documents When Server Template Already Has Documents

Hi ​@Aung 

Composite templates are extremely flexible and allow for very advanced use cases.
Without examining your code and API logs, it is difficult to suggest what went wrong. All new documents should either be added or replace existing ones if the composite template body is built correctly.

We have plenty of guides you can have a look

https://www.docusign.com/blog/developers/dsdev-why-use-composite-templates
https://www.docusign.com/blog/developers/pro-tips-working-composite-templates
https://www.docusign.com/blog/developers/pro-tips-working-composite-templates-part-ii
https://www.docusign.com/blog/developers/pro-tips-working-composite-templates-part-iii

Alternatively, collect the API logs while creating a test envelope and open a case with support
You can capture API logs by following the steps shown here while logged into the account of the user making the API request: https://support.docusign.com/s/document-item?language=en_US&rsc_301&bundleId=jux1643235969954&topicId=poz1578456669909.html&_LANG=enus
The important part is to ensure you're logged in as the user your code runs as because the logs only capture data on the logged in user inside Docusign. 

Regards
Ivan D

​@Ivan.Dinkov

Thanks for the clarification.

To be precise, here is what we are observing with the same request structure:

Actual Behavior Observed

• ✅ Envelope is created and sent successfully

• ✅ The template document is present

• ⚠️ When multiple documents are specified in inlineTemplates.documents:

  • Only one document is applied

  • In some cases, the template document is overwritten

  • Additional documents are not added to the envelope

There is no API error returned, which makes this difficult to detect programmatically.

Scenario

• Server template:

  • Contains 1 base document

  • Recipients and tabs are defined in the template

• Runtime:

  • Add 2 additional PDF documents

• API:

  • POST /v2.1/accounts/{accountId}/envelopes

  • Using compositeTemplates

Failing Request Body (Simplified)

{
  "status": "sent",
  "compositeTemplates": [
    {
      "compositeTemplateId": "1",
      "serverTemplates": [
        {
          "sequence": "1",
          "templateId": "b52ee1f6-7238-4fc3-b78b-bee4a2a0bb29"
        }
      ],
      "inlineTemplates": [
        {
          "sequence": "2",
          "recipients": {
            "signers": [
              {
                "email": "testUser@test.com",
                "name": "Test User",
                "recipientId": "1",
                "routingOrder": "1",
                "roleName": "Test User"
              }
            ]
          },
          "documents": [
            {
              "documentBase64": "BASE64_PDF_2",
              "documentId": "2",
              "fileExtension": "pdf",
              "name": "attachment_1.pdf"
            },
            {
              "documentBase64": "BASE64_PDF_3",
              "documentId": "3",
              "name": "attachment_2.pdf",
              "fileExtension": "pdf"
            }
          ]
        }
      ],
      "document": {
        "documentBase64": "BASE64_PDF_1",
        "documentId": "1",
        "fileExtension": "pdf",
        "name": "replacement.pdf"
      }
    }
  ]
}

Key Observation

This occurs when the server template already contains a document.

If the server template has no documents, then:

• Documents defined in inlineTemplates.documents are applied as expected

Clarification Request

Could you please confirm:

1. Are documents under inlineTemplates.documents supported only for replacement, not addition, when a server template already has documents?

2. Is adding new documents only supported via compositeTemplate.documents in this scenario?

3. Is there a documented or undocumented rule that prevents appending documents to a template that already includes documents?

Understanding the intended behavior here would help us determine whether:

• Our request structure is incorrect, or

• This is an expected limitation of composite templates

Thanks again for your guidance — any insight into the document handling rules would be greatly appreciated.