Templates

Templates are perfect for almost any DocuSign workflow that you do over and over again. They help streamline the sending process when you frequently send the same or similar documents, or send different documents to the same group of people.

Template Basics

One key difference between templates and documents is that a document is a one-time transaction whereas a template is a blueprint for repeatable transactions. For instance, you have an NDA you send to every potential client. Or every month, you send a report to your manager for their approval. Both of these situations are perfect use cases for templates.

With templates you can define placeholder roles, that is, not an actual person but rather a role that would regularly participate in a transaction using the template. Then at run-time you assign actual recipients to your template roles and they in turn automatically inherit all the workflow that was configured for that role at design-time.

Creating Templates

There are three ways to create a template:

For every new template you create a unique templateId is automatically generated by the DocuSign platform and assigned to the template. The templateId is needed to send envelopes from the template. You can retrieve the templateId of a template by logging in to your account, selecting the Templates tab, opening the template in question, then clicking the info button next to the template name. The templateId is also part of the template's URL.

Applying a Template to an Envelope

To apply a template to an envelope you must set the templateId and templateRoles properties in your envelope definition. Since the template contains document(s) already you do not need to configure the documents node.

{
    ...

    "templateId": "55A80182-2E9F-435D-9B16-FD1E1C0F9D74",
    "templateRoles": [{
        "roleName": "Signer1",
        "name": "Sally Doe",
        "email": "sally.doe@email.com"
    }],

    ...
}

It is important to note that the roleName parameter is case-sensitive and must match the placeholder name you saved for the template role. The above snippet would be enough to assign recipient Sally Doe to a role named Signer1 in the template. Another thing to note is that you can define multiple roles in a template and you do not have to assign all of them each time you use the template.

Sending from a Template

Let's say that we create a template with one recipient role, a signer recipient, and just one signature tab assigned to that role. To send an envelope from this template at run-time we need to reference the unique templateId as well as assign recipient data using the templateRoles node.

For instance, if our one template role is named Signer1 the following request creates and sends an envelope to recipient Sally Doe from the template referenced by the templateId:

{
    "accountId": "301424",
    "emailSubject": "This request is sent from a Template",
    "templateId": "55A80182-2E9F-435D-9B16-FD1E1C0F9D74",
    "templateRoles": [{
        "roleName": "Signer1",
        "name": "Sally Doe",
        "email": "sally.doe@email.com"
    }],
    "status": "sent"
}

Notice how no tabs or routing information is specified, nor is there any document information. This is because all the tabs, routing, documents, and workflow have been saved within the (server-side) template itself, at design-time. All we have to do is assign Sally Doe's name and email and make sure a role named "Signer1" exists on the template and she will in turn inherit all of that previous defined workflow we configured in the template.

Note that the status property in the request above is set to sent, which means the envelope will be sent immediately to the recipient. Alternatively, if we had set the status to created the envelope would be saved as a draft in our account, ready to be sent at a later time.

Populating Data in a Template

To populate tabs (aka fields) in a template you must match the name of the tab using the tabLabel property and set its value to the data you want to populate it with. For instance, let's say we have a template with a placeholder role named Customer and two data fields (aka textTabs) assigned to the role. We want to pre-populate the customer's address and social security number (SSN) to save them time and minimize errors. We could use the following request:

{
  "accountId": "301424",
  "emailSubject": "API Example - Populating Data in Templates",
  "templateId": "44D9E888-3D86-4186-8EE9-7071BC87A0DA",
  "templateRoles": [{
    "email": "john.doe@email.com",
    "name": "John Doe",
    "roleName": "Customer",
    "tabs": {
      "textTabs": [{
        "tabLabel": "CustomerAddress",
        "value": "123 Main St. San Francisco, CA 94105"
      }, {
        "tabLabel": "CustomerSSN",
        "value": "12-345-6789"
      }]
    }
  }],
  "status": "sent"
}

Composite Templates

The Composite Templates envelope property allows you to apply multiple templates to a single envelope, combine templates with PDF forms, and combine templates with documents from cloud sources. You can control the order the documents will display in the request and you can also add on-the-fly information using the inlineTemplates node. Composite templates also allow you to transform PDF form fields into DocuSign tags and dynamically assign them to your recipients.

Composite Templates are comprised of the following components:

  • serverTemplates - 0 or more server-side templates and their position in the overlay. If supplied they are overlaid into the envelope in the order of their Sequence value.
  • inlineTemplates - 0 or more inline templates and their position in the overlay. If supplied they are overlaid into the envelope in the order of their Sequence value.
  • pdfMetaDataTemplates – 0 or 1 embedded template in the PDF meta data. If supplied the PDF meta data template will be overlaid into the envelope in the order of their Sequence value.
  • document - 0 or 1 document. The document is used to specify a different document than the ones in the overlay templates. The PDF fields from this document will be transformed to DocuSign Secure Fields if the TransformPdfFields option is set to true.

For example, let's say we have a template that contains documents for a real estate buyer, and a second template that contains documents for the seller. The template role names are Buyer and Seller, respectively, and we want to apply both templates to the same envelope. The following request could be used to accomplish this:

{
    "emailSubject": "DocuSign API - Composite Templates",
    "emailBlurb": "Composite Templates Sample 1",
    "status": "sent",
    "compositeTemplates": [{
        "serverTemplates": [{
            "sequence": "1",
            "templateId": "55A80182-2E9F-435D-9B16-FD1E1C0F9D74"
        }],
        "inlineTemplates": [{
            "sequence": "1",
            "recipients": {
                "signers": [{
                    "email": "johndoe@email.com",
                    "name": "John Doe",
                    "recipientId": "1",
                    "roleName": "Buyer"
                }]
            }
        }]
    }, {
        "serverTemplates": [{
            "sequence": "2",
            "templateId": "44D9E888-3D86-4186-8EE9-7071BC87A0DA"
        }],
        "inlineTemplates": [{
            "sequence": "2",
            "recipients": {
                "signers": [{
                    "email": "sallydoe@email.com",
                    "name": "Sally Doe",
                    "recipientId": "1",
                    "roleName": "Seller"
                }]
            }
        }]
    }]
}

API Recipe

The following recipe sends a signature request from a template. The code is similar to the recipe for sending a signature request on a document - i.e. without the use of templates - however you'll notice the template request is shorter (since we don't need to specify things like the documents, recipients, tags, etc that are saved within the server template). We encourage you to create and test with multiple templates in your developer sandbox account and observe the different results.