Pro tips for working with composite templates, Part II

In my previous blog post, I explained that the InlineTemplate::documents resource exists purely for legacy reasons and you should avoid using it at all costs. In this blog post, I am going to share a pro tip on how to apply a Docusign template to your uploaded documents.

Imagine a scenario where you have an agreement envelope that includes a document with a logo. Further imagine that the logo needs to be updated for every agreement sent; however, the metadata such as tabs remain the same. Since the document will be changing every time, does this mean you’re stuck with having to create the envelope from scratch every time? 

Luckily, the answer is no. Composite templates are here to the rescue. It’s in fact possible to create a template with a reference document that includes all the agreement metadata, such as where the tabs are placed and who the recipients are.  You can then override the reference document with a final version at the time of envelope creation.

To use this method, create a ServerTemplate object in your Docusign account that includes the document and the associated metadata. Then, in your application, you can override the document attached to the ServerTemplate by specifying your final version of the document in the document field of your envelope's compositeTemplates property. With this approach, the document is replaced, but your tabs and recipients from your ServerTemplate are carried over.

Step 1: Create the ServerTemplate

You can easily create a ServerTemplate by navigating to the Templates tab in your Docusign Dashboard:

  1. Select Create a Template.
  2. Set your template's name and description.
  3. Upload your reference document.
  4. Add your signers and any additional recipients; set rules for routing order.
  5. Set the template's other properties.
  6. Select Next, and then create tabs.
  7. Select Save and Close. 

Now your serverTemplate is ready to use. 

Step 2: Create the envelope 

At the time of envelope creation, you can use the following compositeTemplates syntax to override the reference document from your ServerTemplate with a final document (see the Envelopes: create method):

   "compositeTemplates": [
           "compositeTemplateId": "1",
           "document": {
               "documentBase64": "Document in Base64",
               "documentId": "1",
               "fileExtension": "pdf",
               "name": "Letter"
           "serverTemplates": [
                   "sequence": "1",
                   "templateId": "867a37ef-xxxx-xxxx-xxxx-1a3619ada310"
           "inlineTemplates": [
              "recipients": {
                 "signers": [
                       "email": "",
                       "name": "Peter Gunn",
                       "recipientId": "1",
                       "roleName": "Seller"
              "sequence": "2"
   "emailSubject": "Applying Docusign templates to your uploaded documents",
   "status": "sent"

To reference this template from your code, you'll need the template ID. You can use the Templates: list method to pull a list of templates in your account, parse the JSON response for the template name to locate the template you want, and then pull the value of the templateId property.

You can also find the template ID in your Docusign account. To do so:

  1. Select the template from the Templates page in your Docusign account. On the template's page, you'll find a link labeled "Template ID" under the template name. 
  2. Select this link to pop up a message box with the ID displayed.
  3. Select Copy and you're all set!

This is simple, yet very powerful. Thank you for reading and I hope you learned something new from this blog.

Additional resources

Nima Poulad
Nima Poulad
Senior Developer Advocate