Common API Tasks🐈: Create a template from an envelope

Inbar GazitSr. Manager, Developer Content

•

Summary•3 min read

You can use the eSignature REST API to create a template based on an envelope you configured with the settings you want.

C#
Java
Node.js
PHP
Python
Ruby
Additional resources

C#
Java
Node.js
PHP
Python
Ruby
Additional resources

Common API Tasks: Create a template from an envelope

Welcome to a fantastic new edition of the CAT🐈 (Common API Tasks) blog series. The CAT blogs provide all you need to complete small, specific, SDK-supported tasks using one of our APIs. You can find all articles in this series on the Docusign Developer Blog.

In this issue we’re going to discuss a little-known feature of Docusign eSignature and how you can use it via the eSignature REST API.

First, let’s talk about envelopes and templates. In Docusign eSignature an envelope is a singular container for a transaction. It includes all the relevant pieces of information needed to complete a transaction: documents, recipients, and tabs (or signing elements). When you need to repeat a certain transaction multiple times as part of your business process, you can use a template. A template is just like an envelope: it includes all the same information. However, you never use the template directly, you never send it, and it never gets signed. Instead, you use the template to create envelopes from it. When you create an envelope from a template, all the information (documents, recipients, tabs) gets copied from the template to the envelope.

What most people don’t know is that you can also do the reverse: copy from an envelope to create a template. This is a very useful feature to create templates with minimal effort. Imagine you just sent an envelope for signature. You worked hard setting all the documents and tabs and it was a success. Now you need to do it again and again. You can set up a template, right? Well, sure, but even doing that is an effort. So, what would be nice is if you could take the envelope and use it to make a template. You can do that! You can either do it from the Docusign web app, by finding the envelope and in the menu on the right side and picking Save as Template, like this:

Create a template from an envelope in the DocuSign web app

Or, if you built an integration and you want to provide this functionality as part of your app, you could do this programmatically, and that’s where I come in.

Creating a template from an envelope uses the same Templates::Create endpoint that you normally use to create templates. However, you don’t have to provide documents, recipients, or tabs. These are all copied over from the envelope you selected.

You only need to provide two pieces of information:

EnvelopeId: the unique identifier of the envelope you wish to use.
Name: the name of the new template to be created.

And that’s it! You get back a TemplateId with your new template.

Important notes: The EnvelopeId must be from the same account used for the API call and must be one that the user has access to. The envelope can be in draft, sent, or completed status, but not in voided status.

Here are code snippets in our usual six languages:

C#

var apiClient = new ApiClient(basePath);
// You will need to obtain an access token using your chosen authentication method
apiClient.Configuration.DefaultHeader.Add("Authorization", "Bearer " + accessToken);
TemplatesApi templatesApi = new TemplatesApi(apiClient);
var envTemplate = new EnvelopeTemplate();
envTemplate.EnvelopeId = "10e12b73-xxxx-xxxx-xxxx-8c9cc933142e";
envTemplate.Name = "My Template";
var templateSummary = templatesApi.CreateTemplate(accountId, envTemplate);
var templateId = templateSummary.TemplateId;

Java

// You will need to obtain an access token using your chosen authentication flow 
Configuration config = new Configuration(new ApiClient(basePath));
config.addDefaultHeader("Authorization", "Bearer " + accessToken);
TemplatesApi templatesApi = new TemplatesApi(config);
EnvelopeTemplate envTemplate = new EnvelopeTemplate();
envTemplate.setEnvelopeId("10e12b73-xxxx-xxxx-xxxx-8c9cc933142e");
envTemplate.setName("My Template");
TemplateSummary templateSummary = templatesApi.CreateTemplate(accountId, envTemplate);
string templateId = templateSummary.getTemplateId();

Node.js

// You will need to obtain an access token using your chosen authentication flow 
let dsApiClient = new docusign.ApiClient();
dsApiClient.setBasePath(basePath);
dsApiClient.addDefaultHeader('Authorization', 'Bearer ' + accessToken);
TemplatesApi templatesApi = new docusign.TemplatesApi(apiClient);
let envTemplate = new docusign.EnvelopeTemplate();
envTemplate.envelopeId = '10e12b73-xxxx-xxxx-xxxx-8c9cc933142e';
envTemplate.name = 'My Template';
let templateSummary = templatesApi.createTemplate(accountId, envTemplate);
let templateId = templateSummary.templateId;

PHP

# You will need to obtain an access token using your chosen authentication flow 
$api_client = new \Docusign\eSign\client\ApiClient($base_path);
$config = new \Docusign\eSign\Model\Configuration($api_client);
$config->addDefaultHeader('Authorization', 'Bearer ' + $access_token);
$templates_api = new \Docusign\eSign\Api\TemplatesApi($api_client);
$env_template = new \Docusign\eSign\Model\EnvelopeTemplate();
$env_template->setEnvelopeId('10e12b73-xxxx-xxxx-xxxx-8c9cc933142e');
$env_template->setName('My Template');
$template_summary = $templates_api->createTemplate($account_id, $env_template);
$template_id = $template_summary->getTemplateId();

Python

# You will need to obtain an access token using your chosen authentication flow 
api_client = ApiClient()
api_client.set_default_header('Authorization', 'Bearer ' + access_token)
templates_api = TemplatesApi(api_client)
env_template = EnvelopeTemplate()
env_template.envelope_id = '10e12b73-xxxx-xxxx-xxxx-8c9cc933142e'
Env_template.name = 'My Template'
template_summary = templates_api.create_template(account_id, env_template)
template_id = template_summary.template_id

Ruby

# You will need to obtain an access token using your chosen authentication flow 
config = DocuSign_eSign::Configuration.new
config.host = base_path
api_client = DocuSign_eSign::ApiClient.new config
api_client.DefaultHeader['Authorization'] = 'Bearer ' + access_token
templates_api = DocuSign_eSign::TemplatesApi.new api_client
env_template = DocuSign_eSign::EnvelopeTemplate.new
env_template.envelope_id = '10e12b73-xxxx-xxxx-xxxx-8c9cc933142e'
env_template.name = 'My Template'
template_summary = templates_api.create_template(account_id, env_template)
template_id = template_summary.template_id

And that’s a wrap! I hope you found it useful. If you have any questions, comments, or suggestions for topics for future Common API Tasks posts, feel free to email me. Until next time...

Additional resources

Inbar GazitSr. Manager, Developer Content

Inbar Gazit has been with Docusign since 2013 in various engineering roles. Since 2019 he has focused on developer content. Inbar works on code examples including the launchers, available on GitHub in eight languages, and helps build sample apps showcasing the various Docusign APIs. He is also active on StackOverflow, answering your questions. Inbar can be reached at inbar.gazit@docusign.com.