Common API Tasks🐈: Create a PowerForm programmatically
Welcome to a glorious 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 post, I'm going to show you how you can take your existing DocuSign templates and turn them into PowerForms that can then be used by your users to sign envelopes.
What is a PowerForm?
Typically, when you think of DocuSign eSignature, you think of the process as being initiated by a DocuSign user, who is either signing an envelope or requesting someone else sign the envelope. This user has to know the name and email address of the recipient. They have to initiate the sending of the envelope. They can use a template, which helps make a repeatable process simpler. For example, if you have a waiver that your customers need to sign, then the waiver document can be added to a template and a single signer with a placeholder recipient (meaning that the details of the recipient will only be available when an envelope is created from the template).
However, this still limits your ability to have anyone sign this waiver. You need to know who they are, and you need to initiate the envelope from the template before they can sign it.
This is where PowerForms can help. A PowerForm is a template that has been transformed into a custom URL. The URL can then be embedded in your website or app and be used to collect signatures using the template you already have in your account. Whenever someone selects this URL, they’ll be asked to provide their name and email address, and they’ll then be redirected to sign the document. Behind the scenes, the DocuSign system creates an envelope from the template the same way you can do using code, by adding the details of the recipient that was provided to the PowerForm as the single signer.
PowerForms can also be extended to support additional parameters that can be passed in via the URL to enable collecting additional information from the signer before they start the signing process.
PowerForms can be created manually using the DocuSign web application, but can also be created programmatically using the DocuSign eSignature REST API. Here are some code snippets that demonstrate how to do this using our eSignature SDKs.
One additional thing to consider is that you have the option to validate the email address provided by the user who fills in the PowerForm. To do that, use the value "email" for the SigningMode property. If you choose "direct" as in my code below, the email address is not verified and your signer can put any email address they choose.
C#
var apiClient = new ApiClient(basePath);
// You will need to obtain an access token using your chosen authentication flow
apiClient.Configuration.DefaultHeader.Add("Authorization", "Bearer " + accessToken);
PowerFormsApi powerFormsApi = new PowerFormsApi(apiClient);
var powerForm = new PowerForm();
powerForm.TemplateId = "5c282dbd-xxxx-xxxx-xxxx-d653f09836d3"; // Enter the ID for your template
powerForm.Name = "My PowerForm";
powerForm.SigningMode = "direct";
powerForm = powerFormsApi.CreatePowerForm(accountId, powerForm);
// Get the URL of the newly created PowerForm
var url = powerForm.PowerFormUrl;
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);
PowerFormsApi powerFormsApi = new PowerFormsApi(config);
PowerForm powerForm = new PowerForm();
powerForm.setTemplateId("5c282dbd-xxxx-xxxx-xxxx-d653f09836d3"); // Enter the ID for your template
powerForm.setName("My PowerForm");
powerForm.setSigningMode("direct");
powerForm = powerFormsApi.CreatePowerForm(accountId, powerForm);
// Get the URL of the newly created PowerForm
string url = powerForm.getPowerFormUrl();
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);
let powerFormsApi = new PowerFormsApi(config);
let powerForm = new PowerForm();
powerForm.templateId = '5c282dbd-xxxx-xxxx-xxxx-d653f09836d3'; // Enter the ID for your template
powerForm.name = 'My PowerForm';
powerForm.signingMode = 'direct';
powerForm = powerFormsApi.ceatePowerForm(accountId, powerForm);
// Get the URL of the newly created PowerForm
let url = powerForm.powerFormUrl;
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);
$powerFormsApi = new \DocuSign\eSign\Api\PowerFormsApi($config);
$powerForm = new PowerForm();
$powerForm->setTemplateId('5c282dbd-xxxx-xxxx-xxxx-d653f09836d3'); // Enter the ID for your template
$powerForm->setName('My PowerForm');
$powerForm->setSigningMode('direct');
$powerForm = $powerFormsApi->ceatePowerForm($account_Id, $powerForm);
# Get the URL of the newly created PowerForm
$url = $powerForm->getPowerFormUrl();
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)
PowerForms_Api = PowerFormsApi(api_client)
powerForm = PowerForm()
powerForm.template_id = '5c282dbd-xxxx-xxxx-xxxx-d653f09836d3' # Enter the ID for your template
powerForm.name = 'My PowerForm'
powerForm.signing_mode = 'direct'
powerForm = powerForms_Api.create_power_form(account_id, powerForm)
# Get the URL of the newly created PowerForm
url = powerForm.powerForm_url
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
PowerForms_Api = DocuSign_eSign::PowerFormsApi.new api_client
powerForm = DocuSign_eSign::PowerForm.new
powerForm.template_id = '5c282dbd-xxxx-xxxx-xxxx-d653f09836d3' # Enter the ID for your template
powerForm.name = 'My PowerForm'
powerForm.signing_mode = 'direct'
powerForm = powerForms_Api.ceate_power_form(account_id, powerForm)
# Get the URL of the newly created PowerForm
url = powerForm.powerForm_url
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...
