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:
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...
