DocuSign API: How to use "Composite Templates" to merge multiple PDFs?

Navigating DocuSign API for Efficient Document Workflows

In the fast-paced world of digital business operations, electronic signature platforms like DocuSign have become essential for streamlining contract management and reducing paperwork. From small teams to large enterprises, these tools enable secure, compliant signing processes. A key feature in DocuSign’s API ecosystem is Composite Templates, which allow developers to merge multiple PDFs into a single envelope for signing. This capability is particularly valuable for businesses handling complex workflows, such as multi-party agreements or automated document assembly. In this article, we’ll explore how to implement Composite Templates in the DocuSign API, drawing from official documentation and practical business applications, while maintaining a neutral lens on its utility in commercial settings.

Comparing eSignature platforms with DocuSign or Adobe Sign?

eSignGlobal delivers a more flexible and cost-effective eSignature solution with global compliance, transparent pricing, and faster onboarding.

👉 Start Free Trial

Leveraging DocuSign API’s Composite Templates for PDF Merging

What Are Composite Templates?

Composite Templates in the DocuSign eSignature API represent a powerful method to combine multiple documents and signing configurations within a single envelope. An “envelope” in DocuSign terminology is the container for one or more documents that require signatures. Traditional envelopes handle documents sequentially, but Composite Templates enable parallel assembly, allowing you to attach different PDFs to specific recipients while defining tabs (signature fields) that span across documents. This is ideal for scenarios like loan applications, where a cover sheet, terms PDF, and disclosure form need to be signed by the same party without manual merging.

From a business perspective, this feature reduces API calls, minimizes errors in document routing, and accelerates turnaround times—critical for sales teams closing deals or HR processing onboarding packets. According to DocuSign’s developer resources, Composite Templates are available in plans like Intermediate and Advanced API tiers, which start at around $3,600 annually for moderate usage.

Step-by-Step Guide to Using Composite Templates

To merge multiple PDFs using Composite Templates, you’ll interact with the DocuSign REST API (version 2.1 or later). Prerequisites include a DocuSign developer account (free sandbox available) and API credentials via OAuth. Here’s a practical walkthrough:

1. Prepare Your Documents and Templates:

   • Upload your PDFs to DocuSign’s temporary storage or reference them via base64 encoding. For example, have pdf1.pdf (a contract) and pdf2.pdf (an addendum).
   • Create templates in the DocuSign web app if reusable. Each template can include predefined tabs like signature, date, or text fields. Note the Template ID from the DocuSign dashboard.

2. Set Up the Envelope Definition:

   • Use the /envelopes endpoint to create a new envelope. Structure your JSON request body with a compositeTemplates array.
   • Key elements:
     • document: Inline or remote PDFs.
     • serverTemplates or inlineTemplates: Link to existing templates.
     • recipients: Define signers (e.g., signer role) and attach them to composites.

   Example JSON snippet (using Node.js or similar for API call):

   {
     "status": "sent",
     "emailSubject": "Please sign the merged agreement",
     "compositeTemplates": [
       {
         "compositeTemplateId": "template1",
         "document": {
           "documentBase64": "base64_of_pdf1",
           "name": "Main Contract",
           "fileExtension": "pdf",
           "documentId": "1"
         },
         "serverTemplates": [
           {
             "sequence": "1",
             "templateId": "your-template-id-1"
           }
         ],
         "inlineTemplates": [
           {
             "sequence": "1",
             "recipients": {
               "signers": [
                 {
                   "email": "signer@example.com",
                   "name": "John Doe",
                   "recipientId": "1",
                   "tabs": {
                     "signHereTabs": [
                       {
                         "documentId": "1",
                         "pageNumber": "1",
                         "xPosition": "100",
                         "yPosition": "200"
                       }
                     ]
                   }
                 }
               ]
             }
           }
         ]
       },
       {
         "compositeTemplateId": "template2",
         "document": {
           "documentBase64": "base64_of_pdf2",
           "name": "Addendum",
           "fileExtension": "pdf",
           "documentId": "2"
         },
         "serverTemplates": [
           {
             "sequence": "2",
             "templateId": "your-template-id-2"
           }
         ]
       }
     ],
     "recipients": {
       "signers": [
         {
           "email": "signer@example.com",
           "name": "John Doe",
           "recipientId": "1",
           "routingOrder": "1"
         }
       ]
     }
   }
   

   This merges pdf1 and pdf2 into one envelope. The first composite attaches Template 1 to the first PDF with a signature tab; the second adds the addendum via Template 2. Recipients sign across the merged document without seeing separate envelopes.

3. Handle Merging Logic:

   • Use documentId to reference PDFs uniquely. Tabs from templates apply to specific documents but appear in the unified view.
   • For bulk merging, integrate with Bulk Send API (Business Pro or Advanced plans), capping at ~100 sends per user annually.
   • Error handling: Validate base64 sizes (up to 5MB per document) and ensure OAuth scopes include signature.

4. Send and Monitor the Envelope:

   • POST to https://demo.docusign.net/restapi/v2.1/accounts/{accountId}/envelopes.
   • Retrieve status via /envelopes/{envelopeId}. Completed envelopes return a merged PDF via the API.
   • Business tip: In production, use webhooks (Connect feature in Advanced plans) for real-time notifications on signing completion.

5. Testing and Optimization:

   • Sandbox testing incurs no envelope quotas. Monitor usage in the API dashboard to avoid overages—Starter plans limit to 40 envelopes/month.
   • For complex merges, combine with PowerForms for public-facing templates, enhancing scalability for e-commerce or partner onboarding.

This approach can cut document preparation time by 50-70% in high-volume environments, per industry benchmarks. However, for enterprises, custom integrations may require the Enterprise API plan, with pricing tailored to volume.

Integration with DocuSign IAM CLM

DocuSign’s Intelligent Agreement Management (IAM) and Contract Lifecycle Management (CLM) extend Composite Templates’ value. IAM provides AI-driven risk assessment and clause extraction, while CLM offers end-to-end workflow automation, including template libraries and analytics. In API contexts, these tie into Composite Templates for dynamic PDF generation—e.g., pulling data from CRM systems to populate merged docs. Businesses in regulated sectors like finance benefit from IAM’s compliance tools, such as audit trails and SSO, though add-ons like Identity Verification incur metered fees.

Evaluating eSignature Platforms in a Competitive Landscape

As businesses globalize, selecting an eSignature provider involves balancing API flexibility, compliance, and cost. DocuSign leads with robust API features like Composite Templates, but alternatives offer varying strengths. Adobe Sign excels in PDF-centric workflows, integrating seamlessly with Adobe Acrobat for advanced editing before merging. Its API supports similar composite-like structures via “agreements,” with plans starting at $10/user/month for basics.

HelloSign (now Dropbox Sign) provides a user-friendly API for simple merges, emphasizing ease for SMBs with unlimited templates in its $15/user/month plan. It lacks DocuSign’s depth in conditional logic but shines in quick integrations with tools like Google Workspace.

eSignGlobal positions itself as a global contender, supporting compliance in 100 mainstream countries and regions. It holds advantages in the Asia-Pacific (APAC), where electronic signature regulations are fragmented, high-standard, and strictly regulated—often requiring ecosystem-integrated approaches rather than the framework-based ESIGN/eIDAS models common in the US and Europe. APAC demands deep hardware/API-level docking with government-to-business (G2B) digital identities, raising technical barriers beyond email verification or self-declaration. eSignGlobal integrates seamlessly with Hong Kong’s iAM Smart and Singapore’s Singpass, offering features like Bulk Send and AI contract tools. Its Essential plan, at $16.6/month (annual), allows 100 document sends, unlimited user seats, and access code verification—providing strong value on compliance foundations, at a slight cost edge over competitors. The platform is expanding aggressively in Europe and the Americas to challenge incumbents.

Looking for a smarter alternative to DocuSign?

eSignGlobal delivers a more flexible and cost-effective eSignature solution with global compliance, transparent pricing, and faster onboarding.

👉 Start Free Trial

Competitor Comparison Table

This table highlights neutral trade-offs: DocuSign suits high-volume API needs, while others prioritize affordability or regional fit.

Final Thoughts on eSignature Choices

In summary, DocuSign’s Composite Templates offer a reliable way to merge PDFs via API, enhancing efficiency for business workflows. For teams seeking alternatives, eSignGlobal emerges as a neutral, regionally compliant option, particularly for APAC operations.