Templates

 

Templates help streamline the sending (signature request) process. They allow you to create standard envelopes with set documents, recipient roles, routing, and signing and information tags. Then when it's time to request signature(s) you assign recipients to the pre-configured template roles and those recipients automatically inherit all the tabs, routing, and workflow setup for each individual role. Templates are one of the most widely used features in the DocuSign platform and adding them to your API calls is easy.

Creating Templates

There are numerous ways to create templates - through the DocuSign Console they can be created manually by a logged-in user or imported through an XML file. These templates are referred to as Server Templates and once created they can be used in your API calls. Server Templates can also be created through the API. More advanced features, such as Composite Templates can be used to combine multiple server templates in a single envelope as well as supply inline, on-the-fly template information (see Composite Templates section below for more info).

Adding Templates to your API calls

For every server template that is created a GUID (globally unique identifier) is automatically generated, which you can then reference in your API calls. Note: If this is your first exposure to DocuSign Templates then it is strongly recommended that you read on how to create a template through the Console.

Let's say that we create a template which contains two recipient roles - one being a signing recipient and the other a carbon copy (CC) recipient, and let's also say we add one signature tab for the signing recipient. If we set the templateId property in the request body to the GUID of a given template, the document(s) of that template will be used in that signature request. Furthermore, we can then use the templateRoles property to assign the recipient data (name and email for example) to the various template role(s).

For instance, the request body for sending a signature request on the template we describe above, with one signing role and one CC role, might look like the following:

{
    "accountId": "123456",
    "emailSubject": "API Call that uses a Template",
    "templateId": "AAAA-BBBB-CCCC-DDDD",
    "templateRoles": [
        {
            "roleName": "Signer"
            "name": "Sally Doe",
            "email": "sally.doe@email.com"
        },
        {
            "roleName": "CarbonCopy"
            "name": "John Doe",
            "email": "john.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 template itself, at design-time. All we have to do is assign recipients to the pre-configured template roles, using the roleName property as seen above. It should also be noted that the status property in the sample request above is set to sent, which means to immediately send this envelope to the first recipient(s). Alternatively, we could have set the status to created which would instead save the envelope as a draft envelope, ready to be sent later.

API Walkthrough - Request Signature via Template

One of the API Walkthroughs demonstrates the use of a template in a signature request. The code is similar to the walkthrough for sending a signature request on a document (i.e. without the use of templates), however you'll notice that the request body of the API call with templates is much shorter.

In particular, this API Walkthrough shows how to request a signature from a template. We encourage you to play around with the template walkthrough by creating several templates in your demo account, adding them to your API calls, and observing the results. You just have to make sure the roleName value you pass in your request body matches an existing role name saved in your template, noting that they are case-sensitive. Also note that if you do not have to assign recipients to all available template roles if you have multiple. For instance, if you have a template with 3 roles- it is ok to only specify recipient information for one role and fire off that request, not using the other 2 roles at all.

Composite Templates

You can combine DocuSign templates and PDF forms in a single envelope by using the compositeTemplates node. The basic envelope remains the same while the composite template adds new document and template overlays into the envelope. The compositeTemplates node is an array meaning you can have 0 or more composite templates in a given envelope.

It's possible for templates to contain conflicting or overriding information (i.e. one template defines tabs for a role at certain locations and a second template defines tabs for that role at different locations). Therefore the sequence value is used to determine the order of template application, and thus the final location of the tabs in this case. Note that since this sequence value determines the order of template application it also controls the order your template documents appear in the envelope.

The compositeTemplates node goes in the JSON (or XML) formatted body of your requests and consists of the following:

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, the following JSON formatted request body could be used to create and send an envelope that combines two different server templates, the first template referenced by template ID 55A80182-2E9F-435D-9B16-FD1E1C0F9D74 and the second template referenced by template ID 44D9E888-3D86-4186-8EE9-7071BC87A0DA. In this example the first template contains a role named RoleOne, which is the role the first recipient gets assigned, and the second template contains a role named Signer1, which is the role the second recipient is assigned to. Note that the sequence property set for each server template is used to determine the order you want the templates (documents) to appear in the envelope.

{
  "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": "firstrecipient@email.com",
                "name": "John Doe",
                "recipientId": "1",
                "roleName": "RoleOne"
              }
            ]
          }
        }
      ]
    },
    {
      "serverTemplates": [
        {
          "sequence": "2",
          "templateId": "44D9E888-3D86-4186-8EE9-7071BC87A0DA"
        }
      ],
      "inlineTemplates": [
        {
          "sequence": "2",
          "recipients": {
            "signers": [
              {
                "email": "secondrecipient@email.com",
                "name": "Jane Doe",
                "recipientId": "1",
                "roleName": "Signer1"
              }
            ]
          }
        }
      ]
    }
  ]
}

For more information on compositeTemplates please see the REST API Guide.

Sample Request using compositeTemplates

The following is the basic format of a signature request which contains the compositeTemplates element, along with the corresponding response on a successful call.

POST https://{server}/restapi/{apiVersion}/accounts/{accountId}/envelopes

X-DocuSign-Authentication: <DocuSignCredentials><Username>{name}</Username><Password>{password}</Password><IntegratorKey>{integrator_key}</IntegratorKey></DocuSignCredentials>
Accept: application/json
Content-Type: application/json
Content-Disposition: form-data

{
  "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": "firstrecipient@email.com",
                "name": "John Doe",
                "recipientId": "1",
                "roleName": "RoleOne"
              }
            ]
          }
        }
      ]
    },
    {
      "serverTemplates": [
        {
          "sequence": "2",
          "templateId": "44D9E888-3D86-4186-8EE9-7071BC87A0DA"
        }
      ],
      "inlineTemplates": [
        {
          "sequence": "2",
          "recipients": {
            "signers": [
              {
                "email": "secondrecipient@email.com",
                "name": "Jane Doe",
                "recipientId": "1",
                "roleName": "Signer1"
              }
            ]
          }
        }
      ]
    }
  ]
}

Sample response:

The response to a successful call contains the envelopeId of the envelope that was just created, along with additional envelope information:

{
  "envelopeId":"String content",
  "status":"String content",
  "statusDateTime":"String content",
  "uri":"String content"
}

As always, please see the REST API Guide for more information.