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.
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'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
I'm integrating Docusign so that recipients can see their envelopes embedded on my site. I first create the envelope with the api, and I'm attempting to prefill Data Fields using dynamic data.
As far as I can tell, there's nothing wrong with my json that I'm using to create the envelopes. None of the other solutions on StackOverflow to this issue have helped. My json looks like this (which I send to https://demo.docusign.net/restapi/v2/accounts/360734/envelopes):
{
"status": "sent",
"emailBlurb": "Please sign the document.",
"emailSubject": "Please sign your agreement",
"templateId": "TEMPLATE_ID",
"templateRoles": [
{
"clientUserId": "EMAIL",
"name": "NAME",
"email": "EMAIL",
"roleName": "Signer1",
"tabs": {
"textTabs": [
{
"tabLabel": "address",
"value": "ADDRESS "
},
{
"tabLabel": "multi_address",
"value": "ADDRESSES"
}
]
}
},
{
"name": "ANOTHER NAME",
"email": "ANOTHER EMAIL",
"roleName": "Random1"
}
]
}
And I get the following response:
{
"envelopeId": "ENVELOPE_ID",
"uri": "/envelopes/ENVELOPE_ID",
"statusDateTime": "2013-10-25T01:20:55.6750772Z",
"status": "sent"
}
I then get the link to show the client by posting to https://demo.docusign.net/restapi/v2/accounts/360734/envelopes/ENVELOPE_ID/views/recipient
{
"authenticationMethod": "email",
"clientUserId": "EMAIL",
"email": "EMAIL",
"returnUrl": "MYURL",
"userName": "NAME"
}
And I get this response:
{
"url": "https://demo.docusign.net/Member/StartInSession.aspx?t=REDACTED"
}
This follows the example seen here: https://github.com/Ergin008/DocuSign-REST-API-Webinar-April2013/blob/master/example2.json
After creating the envelope this way, it appears that the tags do not prefill. When I view the envelope embedded on my site, nothing is filled. I'm certain the tabLabels are correct. Everything otherwise seems to be working okay. Is there some kind of setting I'm missing?
UPDATE
Looks like it could be a bug! All I change is the role name and it works!
{
"status": "sent",
"emailBlurb": "Please sign the document.",
"emailSubject": "Please sign your agreement",
"templateId": "TEMPLATE_ID",
"templateRoles": [
{
"clientUserId": "EMAIL",
"name": "NAME",
"email": "EMAIL",
"roleName": "Signer1",
"tabs": {
"textTabs": [
{
"tabLabel": "address",
"value": "ADDRESS "
},
{
"tabLabel": "multi_address",
"value": "ADDRESSES"
}
]
}
},
{
"name": "ANOTHER NAME",
"email": "ANOTHER EMAIL",
"roleName": "Signer2"
}
]
}
And it populated! It seems if I start the role name with anything other than Signer it doesn't work. Weird!
And yes, I'm changing the role name on Docusign from Random1 to Signer2, in this case. For example, Signer3 also worked.
Your question says your submitting that JSON to the "Get Recipient View" resource:
https://demo.docusign.net/restapi/v2/accounts/ACCOUNT_ID/envelopes/ENVELOPE_ID/views/recipient)
...but that JSON looks like what you use in the "Create Envelope" request, not the "Get Recipient View" request. So, let me start by clarifying the process of facilitating Embedded/captive signing (i.e., presenting the recipient's envelope within your site). Doing so is a two-step process:
STEP 1: Create the envelope (request includes data to pre-populate fields for each recipient, if needed).
POST https://{server}/restapi/{apiVersion}/accounts/{accountId}/envelopes
See "Creating an Envelope From a Template" section that starts on p27 of the REST API guide (http://www.docusign.com/sites/default/files/REST_API_Guide_v2.pdf) for detailed info about request and response.
STEP 2: Retrieve the URL that can be used to launch the recipient's envelope (signing session).
POST https://{server}/restapi/{apiVersion}/accounts/{accountId}/envelopes/{envelopeId}/views/recipient
{
"authenticationMethod":"Email",
"clientUserId":"CLIENT_USERID_SPECIFIED_IN_REQUEST",
"email":"RECIPIENT_EMAIL",
"returnUrl":"URL_TO_REDIRECT_TO_WHEN_SIGNING_COMPLETE",
"userName":"RECIPIENT_NAME"
}
The response will contain the URL that can be used to launch the Recipient's Envelope:
{
"url":"URL_THAT_WILL_LAUNCH_ENVELOPE"
}
See the "Post Recipient View" section that starts on p160 of the REST API guide (http://www.docusign.com/sites/default/files/REST_API_Guide_v2.pdf) for more detailed info about request and response.
Now, assuming you're doing all this correctly (step 1 and step 2) -- let's get back to the issue you're reporting: difficulty pre-populating fields for the recipient. A few comments about the "Create Envelope from Template" JSON that you included in your question:
You don't need accountId in request.
You don't need to include documentId and pageNumber in the request for the tab.
You DO need to include clientUserId for the recipient in the request, if you want the recipient to sign embedded/captive within your site.
So, here's a "Create/Send Envelope From Template" example request (step 1 above) that pre-populates the tab named "FIELD_1" with the value "VALUE_A" anywhere that it appears in the envelope:
POST https://{{env}}.docusign.net/restapi/{{version}}/accounts/{{acctId}}/envelopes
{
"status" : "sent",
"emailBlurb" : "please sign",
"emailSubject" : "Please sign your document",
"templateId" : "TEMPLATE_ID",
"templateRoles" : [{
"name" : "John Doe",
"email" : "JohnsEmail#outlook.com",
"roleName" : "Signer1Role",
"clientUserId" : "123",
"tabs" :
{"textTabs":[{
"tabLabel":"\\*FIELD_1",
"value":"VALUE_A"}
]}
}]
}
Then, you'd take the Envelope Id that's returned in the response and call the "Get Recipient View" resource (step 2 above) to get the URL to launch the signing session:
POST https://{{env}}.docusign.net/restapi/{{version}}/accounts/{{acctId}}/envelopes/ENVELOPE_ID/views/recipient
{
"authenticationMethod": "Email",
"clientUserId": "123",
"userName": "John Doe",
"email": "JohnsEmail#outlook.com",
"returnUrl": "http://www.google.com"
}
Finally, one last comment (but an important one): if you're just wanting to inject the recipient's "full name" in the document -- use the "Full Name" tab when creating the Template and DocuSign will automatically inject the recipient's name in place of that tag, anywhere that it appears (instead of you using a Text Tab and having to populate it via the API request). Here's the Full Name tag in the DocuSign UI tagger view:
Another Create Envelope Example (with screenshot of data field properties):
If I submit this request:
POST https://{{env}}.docusign.net/restapi/{{version}}/accounts/{{acctId}}/envelopes
{
"emailSubject": "Please sign this",
"emailBlurb": "Please sign...thanks!",
"templateId": "TEMPLATE_ID",
"envelopeIdStamping": "false",
"templateRoles": [
{
"roleName": "Signer1",
"name": "John Doe",
"email": "JohnsEmail#outlook.com",
"recipientId": "1",
"tabs":{
"textTabs":[
{
"tabLabel":"\\*address",
"value":"123 Main Street"
},
],
}
}
],
"status": "sent"
}
And the Data Field properties (when Editing the Template via the DocuSign UI) look like this:
Then the result is that field(s) with Label = address that are assigned to Recipient Role Signer1 will be prepopulated with the value "123 Main Street" when the signer views their envelope. If this isn't working for you, I suggest that you:
Verify that the value of roleName in the API request exactly matches the Recipient value I've highlighted in the prior screenshot (in my example, "Signer1").
Verify that the value of tabLabel in the API request exactly matches the Label value I've highlighted in the prior screenshot (in my example, "address).
Note: Values are case-sensitive, so be sure values in your request are an exact match (including upper-case/lower-case) with the values in the Data Field Tag Properties.