I am using docusign to send off vendor agreements. The agreements are all the same wording, except for vendor name and address. Is there a way I can pass information to the envelope creation script (PHP) to dynamically populate name and address fields on a template document?
Yes you can definitely populate tabs in an embedded signing view. This is all controlled through the
tabLabel
property of each tab in your request body. For instance, if you login to the DocuSign Console and add two data fields (textTabs) to your envelope where one has the label "email" and the other has a label of "address" then the following JSON body prefills those tabs based on the value passed.
"tabs": {
"textTabs": [
{
"tabLabel": "address",
"value": "123 Main St. SF, CA"
},
{
"tabLabel": "email",
"value": "sample#email.com"
}
]
}
}
],
"status": "sent"
}
Related
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 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 have a situation where I want to be able to differentiate between envelopes based on a 'type'. For example, I'll have quotes and invoices, both of these can be sent to the same person so I'd like to know if there's a way of checking some sort of field that could differentiate the two. Currently I'm rather crudely post processing the API results and checking for 'quote' in the document type and I'd like a rather more reliable solution
thanks,
Oliver
You can use Envelope Custom Fields aka Document labels to specify additional metadata for an envelope.
Envelope Custom fields aka Document labels can be used in the envelopes for your account to record information about the envelope, help search for envelopes and track information. The envelope custom fields are not seen by the envelope recipients.
The DocuSign Web sending tool refers to the Envelope Custom fields as Document Labels. You can configure Document Labels as an Administrator on the Account. See instructions here
Once the Document labels are configured at the account level, you can provide label values for each envelope you send through the web sending tool. See instructions here
The other option is to specify Envelope Custom fields using the API. Here is a sample createEnvelope api request that specifies custom Fields associated with the envelope
{
"emailSubject": "Envelope with custom fields",
"status": "sent",
"customFields": {
"listCustomFields": [
{
"listItems": [
"sample string 1"
],
"name": "myListField",
"required": "true",
"show": "true",
"value": "MyListValue"
}
],
"textCustomFields": [
{
"name": "MyOwnTextField",
"required": "true",
"show": "true",
"value": "MyValue"
}
]
},
"recipients": {
"signers": [
{
"recipientId": 1,
"email": "kaysmith#acme.com",
"name": "kay smith",
"routingOrder": "1"
}
]
},
"documents": [
{
"documentId": "1",
"name": "Agreement",
"fileExtension": "txt",
"documentBase64": "RG9jIFRXTyBUV08gVFdP"
}
]
}
More good news: the DocuSign Sending web tool automatically enables the sender, from the web tool, to set the Envelope Custom Fields.
So if you are sending envelopes programmatically or your users are sending them, it is easy to set custom field values.
Using the docusign rest api i would like to create an envelope with 2 documents.
I will then be using the Post Recipient view to show document 1 to the first recipient (in an iframe) and once signed show document 2 in the same envelope to another recipients.
i have created the templates with different tempalteRoles (different names, order 5 and 10).
Its my understanding using a userId and the right settings in my docusign account, i can show document 1 to recipient 1 and then document 2 to recipient 2.
When i try and create the composite envelope the whole document is shown.
when i call the recipient status for the envelope it only shows one signer.
I have found the envelope will only create when the 2 template roles have the same clientUserId, userName and email, otherwise i get the error "ONESIGNALLSIGN_NOT_SATISFIED"
here is the envelope i am sending through
{
"accountId": "ACCOUNT_ID",
"emailSubject": "Email subject",
"status": "sent",
"templateId": "TEMPLATE_ID",
"templateRoles": [
{
"roleName": "PDS Customer",
"email": "pds#example.com",
"name": "TestFirstName TestSurname",
"clientUserId": "1",
"tabs": {
"textTabs": [
{
"tabLabel": "DocumentNumber",
"value": "123456789",
"locked": true,
"documentId": 1,
"pageNumber": 1
}
...removed some
]
}
},
{
"roleName": "Customer",
"email": "test#example.com",
"name": "mrTestFirstName TestSurname",
"clientUserId": "2",
"tabs": {
"textTabs": [
{
"tabLabel": "StorerEmail_LocalPart",
"value": "test",
"locked": true,
"documentId": 2,
"pageNumber": 1
}
...removed some
]
}
}
],
"compositeTemplates": [
{
"compositeTemplateId": 1,
"serverTemplates": [
{
"sequence": 1,
"templateId": "TEMPLATE_ID_2"
}
]
}
]
}
The error message is due to having Document Visibility enabled. In that scenario, each signer must have at least one tab present. Your second signer (embedded or not) must have at least one tab. In this case it'd probably be on the second document.
Your API call above does refer to a second documentId though so you may be okay there.
I would suggest that you not mix the "simple" sending (using templateRoles at the top level) with composite templates. Instead, add an inline template to the compositeTemplates structure with all of your recipient information. You may be seeing some odd behavior due to mixing those.
Lastly, the default Document Visibility configuration will show a document to a recipient only if they have a tab on that document. If your second signer should see all documents then you must either add a tab for them on each document or explicitly set visibility per document.
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.