Skip to navigation
How-to guidesUse envelopes and templates

How to create a template

View as Markdown

This topic demonstrates how to create a template.

Run this code example from our Quickstart or launcher projects: Bash, C#, Java, Node.js, PHP, PowerShell, Python, or Ruby.

Required data

Running the code in this how-to requires this data:

Data elementDescription
{API_ACCOUNT_ID}A GUID value that identifies your account. This value is automatically generated by Docusign for any account you create. Copy the value from the API Account ID field on the Apps and Keys page.
{BASE_PATH}A string value that forms the root of the URL required to make API calls. The base path value in the example code is set to target the developer environment at
https://<domain>/restapi
Where <domain> is demo.docusign.net for the developer environment and is the result of the GetUserInfo call in production.
{DOCS_PATH}A string value for the file path to the folder containing the documents you want to include in the envelope.
Document to be signedYou must provide at least one document to be signed. Document used in this how-to:
{TEMPLATE_NAME}The template name should be set to “Example Signer and CC template” for this example.

Step 1. Obtain your OAuth token

To make the API call shown in this how-to, you need a valid OAuth access token. Docusign supports access tokens for three different recommended OAuth grant types: Public Authorization Code Grant, Confidential Authorization Code Grant, and JSON Web Token (JWT) Grant. Choose the OAuth grant type appropriate for your scenario.

See Confidential Authorization Code Grant for guidance on your options to get an Confidential Authorization Code Grant OAuth token.

Three icons that represent the three methods a user can use to obtain an OAuth token: JSON Web Token (JWT), Public Authorization Code Grant (ACG), and Confidential Authorization Code grant

Step 2. Create a template

  • Create a new template definition.

    • Add a document to the definition by saving it to a variable as a base64 string. If you intend to attach multiple documents, specify the document order using an array. The order of the array will be the document order.
    • Create role placeholders for your recipients. For this template, we are assigning placeholders to a ‘Signer’ role and a carbon copy ‘CC’ role. These placeholder roles contain an ID, a role name, and a routing order that determines the order of delivery.
    • Create and assign signable fields (also known as tabs) for each specific signer within the document. This code example uses absolute positioning to set each tab a specific number of points from the corner of the screen.
    • Set the template definition data, including a description, name, email subject, recipients, and status.

  • Create the template object from your definition using the Templates:create method.

printf \
'{
    "description": "Example template created via the API",
    "name": "Example Signer and CC template v2",
    "shared": "false",
    "documents": [
        {
            "documentBase64": "' > $request_data
            cat $doc1_base64 >> $request_data
            printf '",
            "documentId": "1", "fileExtension": "pdf",
            "name": "Lorem Ipsum"
        }
    ],
    "emailSubject": "Please sign this document",
   "recipients": {
        "carbonCopies": [
            {"recipientId": "2", "roleName": "cc", "routingOrder": "2"}
        ],
        "signers": [
            {
                "recipientId": "1", "roleName": "signer", "routingOrder": "1",
                "tabs": {
                    "checkboxTabs": [
                        {
                            "documentId": "1", "pageNumber": "1",
                            "tabLabel": "ckAuthorization", "xPosition": "75",
                            "yPosition": "417"
                        },
                        {
                            "documentId": "1", "pageNumber": "1",
                            "tabLabel": "ckAuthentication", "xPosition": "75",
                            "yPosition": "447"
                        },
                        {
                            "documentId": "1", "pageNumber": "1",
                            "tabLabel": "ckAgreement", "xPosition": "75",
                            "yPosition": "478"
                        },
                        {
                            "documentId": "1", "pageNumber": "1",
                            "tabLabel": "ckAcknowledgement", "xPosition": "75",
                            "yPosition": "508"
                        }
                    ],
                    "listTabs": [
                        {
                            "documentId": "1", "font": "helvetica",
                            "fontSize": "size14",
                            "listItems": [
                                {"text": "Red", "value": "red"},
                                {"text": "Orange", "value": "orange"},
                                {"text": "Yellow", "value": "yellow"},
                                {"text": "Green", "value": "green"},
                                {"text": "Blue", "value": "blue"},
                                {"text": "Indigo", "value": "indigo"},
                                {"text": "Violet", "value": "violet"}
                            ],
                            "pageNumber": "1", "required": "false",
                            "tabLabel": "list", "xPosition": "142",
                            "yPosition": "291"
                        }
                    ],
                    "radioGroupTabs": [
                        {
                            "documentId": "1", "groupName": "radio1",
                            "radios": [
                                {
                                    "pageNumber": "1", "required": "false",
                                    "value": "white", "xPosition": "142",
                                    "yPosition": "384"
                                },
                                {
                                    "pageNumber": "1", "required": "false",
                                    "value": "red", "xPosition": "74",
                                    "yPosition": "384"
                                },
                                {
                                    "pageNumber": "1", "required": "false",
                                    "value": "blue", "xPosition": "220",
                                    "yPosition": "384"
                                }
                            ]
                        }
                    ],
                    "signHereTabs": [
                        {
                            "documentId": "1", "pageNumber": "1",
                            "xPosition": "191", "yPosition": "148"
                        }
                    ],
                    "textTabs": [
                        {
                            "documentId": "1", "font": "helvetica",
                            "fontSize": "size14", "height": 23,
                            "pageNumber": "1", "required": "false",
                            "tabLabel": "text", "width": 84,
                            "xPosition": "153", "yPosition": "230"
                        }
                    ],
                    "numericalTabs" : [
                        {
                            "validationType": "Currency",
                            "documentId": "1", "font": "helvetica",
                            "fontSize": "size14", "height": 23,
                            "pageNumber": "1", "required": "false",
                            "tabLabel": "numericalCurrency", "width": 84,
                            "xPosition": "153", "yPosition": "260"
                        }]
                }
            }
        ]
    },
    "status": "created"
}' >> $request_data

Step 3. Call the eSignature REST API

Make a POST request to Templates:create to create the template. Here’s how you make the call, but make sure to substitute your API account ID for {ACCOUNT_ID} and your template ID for {TEMPLATE_ID}.

View the source code for this how-to on GitHub: Bash, C#, Java, Node.js, PHP, PowerShell, Python, or Ruby.

curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
     --header "Content-Type: application/json" \
     --data-binary @${request_data} \
     --request POST ${base_path}/v2.1/accounts/${account_id}/templates \
     --output $response

Expected response

“Example Signer and CC template” is created under Templates in the Templates.

Next steps