Attempting to use the REST API Envelope Create to include Supplemental Documents in the envelope [no templates], so with the first object in the Documents array having a display value of ‘inline’ and the signerMustAcknowledge set to ‘null’ we have for the second object in the array used the display value of ‘modal’ and the signerMustAcknowledge set to ‘no_interaction’ or to ‘view’. When the recipient reviews the envelop online the supplemental document is not shown as grey strip below the primary document offering the reviewer any options, instead the document is expanded and shown in full. What other options do we need to set to get DocuSign to treat the second document as supplemental, as described in https://support.docusign.com/en/guides/ndse-user-guide-send-supplements.
Spoke to DocuSign Support yesterday to get the ‘Supplemental Documents’ functionality added to our Demo Account and the Permission Set on the User being used for this REST API connection has the ‘Disable document upload’ unchecked and the Allow supplemental documents option (and all related options below) is checked.
Example anonymised JSON:
{
"recipients": {
"signers": [
{
"routingOrder": 1,
"recipientId": "1",
"name": "Person-A",
"email": "person-a#website.com"
}
]
},
"emailSubject": "Test subject",
"emailBlurb": "Test blurb",
"documents": [
{
"signerMustAcknowledge": null,
"order": "asc",
"name": "MyCompany Quote",
"includeInDownload": null,
"documentId": "1",
"documentBase64": "JVBERi0xLjMKJcTl8uXrp/Og0M……",
"display": "inline"
},
{
"signerMustAcknowledge": "no_interaction",``
"order": "asc",
"name": "MyCompany Quote",
"includeInDownload": false,
"documentId": "2",
"documentBase64": "JVBERi0xLjQKJeLjz9MKMiAw……",
"display": "modal"
}
]
}
You are not assigning any DocuSign tabs to the signer? your documents part of JSON is correct, just not assigning tabs might be creating an issue. If you don't assign tabs then it is called free form signing which is not allowed in most of the plans and might not work for supplemental docs. Try by assigning atleast one tab to signer in the non-supplemental document. Lack of tabs is causing the issue.
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 have a Word document that serves as the Document template. It only has an outline on it. I then added text fields to the template.
for example, the template JSON, it looks like this:
"recipients":
{ ...
"signers": [
{ ...
"tabs":
{
"listTabs": [
{
"documentId": "1",
"pageNumber": "1",
"recipientId": "55177519",
"tabType": "list",
"tabLabel": "##parentf2e8b853-3ef1-4872-af19-4f1e3c60a3a7##recipient",
"listItems": [
{
"text": "Dealer",
"value": "Dealer"
},
{
"text": "Customer",
"value": "Customer"
}
],
"required": "true",
"shared": "true",
"value": ""
}
],
"textTabs": [
{
"documentId": "1",
"height": "19",
"pageNumber": "1",
"recipientId": "55177519",
"tabId": "55ab5a10-54d6-4ca0-a66b-7c637c8ad61a",
...
"tabLabel": "DealerPhone",
...
},
My questions are:
How can I get all of the text fields to display the data, no matter who the recipient is- for example, the DealerPhone above? Under "Collaboration", I have set the fields set to "Recipients can Collaborate".
Once the first user selects the user from the drop-down list (the listTab below), I do not want subsequent users to go in and change that selection, but I do need the users to see who the previous / first user selected in that drop-down list.
I can share JSON files of both the template and what I'm sending to create the envelope. The template displays, but the text data is blank.
Sample JSON request body:
{
"email": "...email....",
"name": "Test Dealer",
"roleName": "Dealer",
"tabs": {
"textTabs": [
{
"tabLabel": "DealerPhone",
"value": "1-800-111-2222"
},
{
"tabLabel": "DealerContact",
"value": "Billy Dealer"
}]
}
}],
"emailSubject": "DocuSign API - TEST!!!",
"templateId": "{{templateId}}",
"status": "sent"
}
There's an account-level setting that's relevant here, available from Go to Admin > Sending Settings > When an envelope is sent, write the initial value of the field for all recipients. With that enabled, all pre-populated data will be visible to all recipients. With that disabled, data only gets 'burned in' to the PDF when the assigned recipient completes their role.
If you do not want later recipients to be able to change the value of the dropdown, you will want to disable Collaboration on it. Later signers will be able to see that selection regardless of if Collaboration is enabled or not.
Finally, you'll want to avoid using Conditional Logic on fields that should always appear. Setting a tag to be a conditional child means that it will only appear if circumstances are met.
If recipients sign sequentially (increasing routing order) then every subsequent recipient can see the tabs that prior recipients have filled and they cannot modify them. If you have all tabs assigned to your first recipient, all the other recipients will see them but they'll be read-only for them.
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 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.