I'm trying to figure out how to pass in form field values to my docusign template. I looked at the v2 API docs but found nothing.
You just specify in your JSON request properties (or XML) by using the tabLabel and value properties. For instance, this would populate 2 data fields, one named "ApplicantName" the second "ApplicantSSN"...
{
"accountId": "221765",
"emailSubject": "DocuSign Templates Webinar - Example 2",
"emailBlurb": "Example #2 - Dynamically Populate Form Fields",
"templateId": "44D9E888-3D86-4186-8EE9-7071BC87A0DA",
"templateRoles": [
{
"email": "jondow#email.com",
"name": "Jon Dow",
"roleName": "RoleOne",
"tabs": {
"textTabs": [
{
"tabLabel": "ApplicantName",
"value": "John Doe"
},
{
"tabLabel": "ApplicantSSN",
"value": "12-345-6789"
}
]
}
}
],
"status": "sent"
}
For a full code walkthrough you can combine the above JSON with one of the sample code walkthroughs here:
DocuSign API Walkthrough #1
Related
I am working with composite template because I need to include multiple templates in the envelope. In all templates, signing roles are same. I have following roles and signing order.
I also have need to provide custom email subject and body for each role, when I create envelope.
Here is my request json to create envelope using composite template. Purposefully left second composite template section empty so that its not too big.
{
"status": "created",
"compositeTemplates": [
{
"serverTemplates": [
{
"sequence": "1",
"templateId": "de231abb-4566-4433-8c10-6fae41d5f36e"
}
],
"inlineTemplates": [
{
"envelope": {
"customFields": {
"textCustomFields": [
{
"name": "policy",
"value": "12345"
}
]
}
},
"sequence": "1",
"recipients": {
"carbonCopies": [
{
"recipientId": "1",
"email": "email2#domain.com",
"name": "Supervisor Name",
"roleName": "Supervisor",
"routingOrder": "2",
"emailNotification": {
"supportedLanguage": "en",
"emailSubject": "Custom email subject for supervisor",
"emailBody": "Custom email body for supervisor"
}
},
{
"recipientId": "2",
"email": "email1#domain.com",
"name": "Admin Name",
"roleName": "Admin",
"routingOrder": "4",
"emailNotification": {
"supportedLanguage": "en",
"emailSubject": "Custom email subject for admin",
"emailBody": "Custom email body for admin"
}
}
],
"signers": [
{
"recipientId": "3",
"email": "email3#domain.com",
"name": "Data entry person Name",
"roleName": "DataEntry",
"routingOrder": "1",
"emailNotification": {
"supportedLanguage": "en",
"emailSubject": "Custom email subject for data entry person",
"emailBody": "Custom email body for data entry person"
},
"tabs": {
"textTabs": [
{
"tabLabel": "field name",
"value": "field value"
}
]
}
},
{
"recipientId": "4",
"email": "email4#domain.com",
"name": "client Name",
"roleName": "Client",
"routingOrder": "3",
"emailNotification": {
"supportedLanguage": "en",
"emailSubject": "Custom email subject for the client",
"emailBody": "Custom email body for the client"
},
"tabs": {
"textTabs": [
{
"tabLabel": "other field name",
"value": "other value"
},
{
"tabLabel": "other2 field name",
"value": "other2 value"
}
]
}
}
]
}
}
]
},
{
"serverTemplates": [
{
"sequence": "1",
"templateId": "de231abb-4566-4433-8c10-6fae41d5f36e"
}
],
"inlineTemplates": [
{
.
- repeat same recipient information again
.
}
]
}
]
}
When I am preparing envelope create request json, I have to create one CompositeTemplate for each template I need to include. Within compositeTemplates[x]/inlineTemplates[0]/recipients I have specify information (name, email, roleName, routingOrder, email subject, email body and tabs if applicable) for all 4 recipients. I have to repeat same compositeTemplates[x]/inlineTemplates[0]/recipients for with in CompositeTemplate with duplicate information (name, email, roleName, routingOrder, email subject, email body) which sounds not right to me.
Question#1 - Do you know if there is any way to provide recipient at one single place instead of duplicating it under each CompositeTemplate?
My next question is about proving recipient and tab information but from different viewpoint. In Composite template under inlineTemplates I have to use EnvelopeRecipients to specify recipient and it’s tabs. In this case I need to know signing authority of each recipient/role because I need to put them under signers, corbonCopy etc. In case of envelope with single template I can easily use templateRole under EnvelopDefinition to specify recipient and their tab information just by role. I don’t need to know role’s signing authority.
Question#2 – Is there way to specify recipient information by role in CompositeTemplate without knowing signing authority like we can do with single template envelope?
Answer # 1
I do not believe so. If this workflow is a common occurrence, you might consider creating a third template containing the documents & tabs of the first two templates.
Then, you could simply send an envelope containing just that third template. In this case, you would only have to specify the recipient's information once.
However, we usually advise the composite templates pattern since it's far easier to customize and scale when your use case changes in the future.
Answer # 2
No. You are mixing two different DocuSign design patterns, i.e you should not mix Composite Template and TemplateRole.
Template Role is needed when you have one server template and you want to prepopulate the signer information and/or any DocuSign tab information present in the template from your application.
What you can do (which I'm sure you've realized) is to retrieve the signing authorities for the templates with a GET /template before making your POST /envelopes containing composite templates.
I created a DocuSign template that contains two roles: Provider and Recipient. I did this via the DocuSign Sandbox UI.
In my template, I have one document, with four tabs on it:
1. ProviderName
2. ProviderAddress1
3. RecipientName
4. RecipientAddress
Should I be using CustomFields vs. Tabs?
What's the API call(s) that I should be making to do the following, given a template with a document in it:
create an envelope for specific users
update the text within the document in the template for the specific users
send it out?
In the POSTMan sample, I tried using this URL, doing a POST:
{{baseUrl}}/envelopes
passing in a templateId, and the following JSON below in the POST body:
JSON:
{
"templateRoles": [{
"email": "{{signer1Email}}",
"name": "The Provider",
"roleName": "Provider",
"tabs": {
"textTabs": [{
"tabLabel": "ProviderName",
"value": "This is the provider!"
},
{
"tabLabel": "ProviderAddress1",
"value": "10 Provider Street, Baltimore, MD 21212"
}]
}
},
{
"email": "{{otherEmail}}",
"name": "Test Recipient",
"roleName": "Recipient",
"tabs": {
"textTabs": [{
"tabLabel": "RecipientName",
"value": "This is the recipient!"
},
{
"tabLabel": "RecipientAddress",
"value": "10 Main Street, Baltimore, MD 21212"
}]
}
}],
"emailSubject": "DocuSign API - Signature Request on Document Call",
"templateId": "<<template ID>>",
"status": "sent"
}
This does return an Envelope Id in the response, and I do receive the email with the DocuSign document to sign.
However, the tabs are NOT populated, they're blank.
Are the roles in the Template empty placeholders? If a name/email is defined on the template, the API call won't populate them as you might expect.
Try to add the documentId and pageNumber properties to your tabs. Also, ensure the label matches what is in the original template.
Lastly, you may need to add recipientId as well to each of the recipients to match what is in the template (this one may not be required since you have the roleName but just in case)
I created a Template on the UI and uploaded a doc. I then added a Recipient from the UI and mapped a few fields in the document.
I want to create an envelope based on this template and populate some of the fields before sending for a signature. The idea is, we have a portal where a user can fill up a form and a document is sent to him for signing.
Looking at the docs here. I am supposed to send and populate it like so:
{
...
"templateId": "68a89cdc-xxxx-xxxx-xxxx-fa2ab60713e3",
"recipients": {
"signers": [
{
...
"name": "Example Name",
"email": "examplename#example.com",
"roleName": "Signer One",
}
]
...
},
...
}
This however gives me an error back:
Status: 400 INVALID_REQUEST_PARAMETER: The request contained at least one invalid parameter. 'recipients' may not be specifed when 'templateId' is set. Use 'templateRoles'.
I proceeded to use templateRoles as suggested:
{
"accountId": "301424",
"emailSubject": "API Example - Populating Data in Templates",
"templateId": "44D9E888-xxxx-xxxx-xxxx-7071BC87A0DA",
"templateRoles": [{
"email": "john.doe#email.com",
"name": "John Doe",
"roleName": "Customer",
"tabs": {
"textTabs": [{
"tabLabel": "CustomerAddress",
"value": "123 Main St. San Francisco, CA 94105"
},
{
"tabLabel": "CustomerSSN",
"value": "12-345-6789"
}]
}
}],
"status": "sent"
}
But this did not populate any of the fields with the data I supplied.
What am I missing here?
I recently came across this issue and got hold of their support team. The docs using templateId and Recipients are just basically wrong. It will always fail. I think they'll change that soon.
{
"accountId": "301424",
"emailSubject": "API Example - Populating Data in Templates",
"templateId": "44D9E888-xxxx-xxxx-xxxx-7071BC87A0DA",
"templateRoles": [{
"email": "john.doe#email.com",
"name": "John Doe",
"roleName": "Customer",
"tabs": {
"textTabs": [{
"tabLabel": "CustomerAddress",
"value": "123 Main St. San Francisco, CA 94105"
},
{
"tabLabel": "CustomerSSN",
"value": "12-345-6789"
}]
}
}],
"status": "sent"
}
I created a Template on the UI and uploaded a doc. I then added a
Recipient from the UI and mapped a few fields in the document.
Apparently, you can supply an empty Recipient name and email despite the UI showing a red asterisk on the input field, as if implying it was required.
You only need to define the role field and you're good to go. So in this example, in your template (from the UI):
And you should be good to go.
Your JSON looks pretty good to me.
You don't need the accountId or emailSubject attributes and I'd recommend you leave them out.
Double-check that your tabLabel values are the exact same as the UI's Data Label setting.
As a test, you could also download the template by using the API. See Templates::get
Here's a PHP code example that sets template tab values.
I am having trouble updating textTabs when creating an envelope using the rest API (v2).
The json I'm sending looks like this :
{
"status": "sent",
"emailSubject": "Yet another text 13:57",
"templateId": "xxxxxxx-4dcb-xxxx-xxxx-xxxxxxxx",
"templateRoles": [
{
"name": "Persons Name",
"email": "me#me.com",
"roleName": "Signer",
"tabs": {
"textTabs": [
{
"tabLabel": "ClientName",
"value": "My Name"
},
{
"tabLabel": "ClientAddress",
"value": "This will be the client address"
},
{
"tabLabel": "PhoneNumber",
"value": "+1 555 123 4561"
}
]
}
}
]
}
I have textTabs in the template identified with the template ID with tabLabels set to ClientName, etc.
However - when POSTING the JSON above, the text in the template tabLabels is not replaced.
How do I Change text in TextLabel tabs when creating an envelope in JSON?
Please make sure you are providing the correct tab labels in your request.
You can confirm the name of the tabLabels using the GetTemplateRecipients api
GET /v2/accounts/{accountId}/templates/{templateId}/recipients?include_tabs=true
You also need to make sure that the Role used to add the tabs (this is in the top right of the document entry page), is the same as the TemplateRole detailed in the RoleName attribute of your posted JSON.
I've been able to successfully start an envelope with a template using the templateID, but I'm attempting to generate an envelope with two documents inside that both have templates. In the DocuSign website interface it's possible to start a new envelope then "check off" multiple templates to add to the envelope.
I've found the API calls to:
Start an envelope with a template
Get a template
Add a document to an envelope
However, there's unfortunately nothing that I can find to add a template to a draft envelope once it's been created. The question here, in case it's not obvious, is: what is the API call to generate a new document from a template and add it to a pre-existing envelope in created status?
You can create an envelope based on multiple templates. The trick is to use the compositeTemplates optional property of the request.
Back in April 2013 I hosted a webinar focused on templates where I demonstrated 3 different template examples. They were increasing in complexity leading up to the third, where that last one shows how to combine multiple templates into one envelope. Here is the Gist for it, which contains PHP code and sample JSON bodies:
https://github.com/Ergin008/DocuSign-REST-API-Webinar-April2013
Here is the JSON for the third example, you'll want to add something similar to your request body:
{
"emailSubject": "DocuSign Templates Webinar - Example 3",
"emailBlurb": "Example #3 - Composite Templates",
"status": "sent",
"compositeTemplates": [
{
"serverTemplates": [
{
"sequence": "1",
"templateId": "55A80182-2E9F-435D-9B16-FD1E1C0F9D74"
}
],
"inlineTemplates": [
{
"sequence": "1",
"recipients": {
"signers": [
{
"email": "test#docusign.com",
"name": "First Recipient",
"recipientId": "1",
"roleName": "RoleOne"
}
]
}
}
]
},
{
"serverTemplates": [
{
"sequence": "2",
"templateId": "44D9E888-3D86-4186-8EE9-7071BC87A0DA"
}
],
"inlineTemplates": [
{
"sequence": "2",
"recipients": {
"signers": [
{
"email": "test2#docusign.com",
"name": "Recipient 2",
"recipientId": "1",
"roleName": "RoleOne"
}
]
}
}
]
}
]
}
Note that the sequence property of the server template can be used to change the order that the template documents show up in the envelope.
To add to Ergin's answer.
You can add a template to an existing envelope using the applyEnvelopeTemplates api.
You can add templates to a document in the specified envelope using the EnvelopeTemplate:applyToDocuments api