I have had plenty of success using docusign API with single template, roles, tabs, etc... My use case is now:
1) Have a single envelope that contains multiple server templates
2) The roles will be the same for both server templates
3) However there may be different tabs for each role for each template
Through reading the Docusign API and trial and error I am close, but just cant get across the finish line here. Here is my current JSON:
accountId = 414772
baseUrl = https://demo.docusign.net/restapi/v2/accounts/414772
{
"accountId": "414772",
"emailSubject": "DocuSign API - Signature Request from Template",
"compositeTemplates": [
{
"serverTemplates": [
{
"sequence": 1,
"templateId": "F42C617E-0C61-4A98-944E-F9CAA0AE55D9"
}
],
"inlineTemplates": [
{
"sequence": 2,
"recipients": {
"signers": [
{
"recipientId": 1,
"email": "reirealtor#mailinator.com",
"name": "REI Realtor",
"roleName": "Realtor",
"tabs": {
"textTabs": [
{
"tabLabel": "\\*header_address",
"value": "SOME TEST INFO GOES HERE"
},
{
"tabLabel": "Address",
"value": "123 REally Cool St"
}
]
}
},
{
"recipientId": 2,
"email": "reibuyer#mailinator.com",
"name": "John Doe",
"roleName": "Client"
}
]
}
}
]
},
{
"serverTemplates": [
{
"sequence": 1,
"templateId": "47F5C07B-016C-4E6D-B31D-DCEF9AEAAA69"
}
],
"inlineTemplates": [
{
"sequence": 2,
"recipients": {
"signers": [
{
"recipientId": 1,
"email": "reirealtor#mailinator.com",
"name": "REI Realtor",
"roleName": "Realtor",
"tabs": {
"textTabs": [
{
"tabLabel": "\\*header_address",
"value": "SOME TEST INFO GOES HERE"
},
{
"tabLabel": "Some Other Tab",
"value": "Populate some text here"
}
]
}
},
{
"recipientId": 2,
"email": "reibuyer#mailinator.com",
"name": "John Doe",
"roleName": "Client"
}
]
}
}
]
}
],
"status": "sent"
}
So obviously this doesn't work, but I don't really get any feedback as to why, Docusign just doesn't reply. I have narrowed it down to the 4th signer block
"recipientId": 2,
"email": "reibuyer#mailinator.com",
"name": "John Doe",
"roleName": "Client"
If I remove this block, it creates the envelope and sends it, but then my second template doesn't have a signing block. I suspect I am just doing this all wrong to begin with.
Any ideas?
I think your real issue is number vs string on sequence and ids. I will mock up a POST with your JSDON later today, but here is a valid sample for you to review in the mean time:
{
"emailSubject": "Test 3",
"emailBlurb": "Using two templates from composite template structure",
"brandId" : "f8c86e34-722e-4360-a9a0-54647bcd3004",
"status": "created",
"compositeTemplates": [{
"serverTemplates": [{
"sequence": "1",
"templateId": "6E558133-112C-434E-BF84-7C4DF340F042"
}],
"inlineTemplates": [{
"sequence": "1",
"recipients": {
"signers": [{
"email": "David.grigsby#docusign.com",
"name": "David W. Grigsby",
"recipientId": "1",
"roleName": "Role",
"tabs": {
"textTabs": [{
"value": "David Grigsby",
"tabLabel": "name"
},
{
"value": "David",
"tabLabel": "first_name"
}]
}
}]
}
}]
},
{
"serverTemplates": [{
"sequence": "2",
"templateId": "12C8894E-505C-480F-92FF-245DC387AD34"
}],
"inlineTemplates": [{
"sequence": "2",
"recipients": {
"signers": [{
"email": "David.grigsby#docusign.com",
"name": "David W. Grigsby",
"recipientId": "1",
"roleName": "Role",
"tabs": {
"textTabs": [{
"value": "David W. Grigsby",
"tabLabel": "name"
},
{
"value": "Grigsby",
"tabLabel": "last_name"
}]
}
}]
}
}]
}]
}
Related
I am running some tests with the DocuSign API via PostMan for a solution proof of concept. My goal is to create a single envelope with multiple documents, each assigned to its own template.
Our goal is to create a dynamic envelope of templates as needed; i.e. sometimes we will only need to put one template into the envelope, other times we might need five or six. The tricky bit is that a single person might be a recipient on multiple documents at once. We are looking to see if its possible to configure the envelope so that they can sign all of their documents at once.
I've been able to use the API to generate an envelope with two documents assigned to two templates. Each template has three recipients (the same three people for both document). The envelope is automatically assigned to the first batch of recipients for the first template (Recipients A and B since they both have a routing order of 1). But when the recipient goes to sign the envelope, they only see the signature option for the first document and don't have an option to sign the second document.
Is what I am trying to achieve possible?
I'm testing this process in Postman. Below is a copy of the POST body. I appreciate any advice.
{
"compositeTemplates": [
{
"document": {
"documentBase64": "<<BinaryDataA>>",
"documentId": "1",
"fileExtension": "pdf",
"name": "Test Document A"
},
"inlineTemplates": [
{
"sequence": "1",
"recipients": {
"signers": [
{
"email": "<<recipient_a_email>>",
"name": "<<recipient_a_name>>",
"recipientId": "1",
"roleName": "Client A",
"routingOrder":"1"
},
{
"email": "<<recipient_b_email>>",
"name": "<<recipient_b_name>>",
"recipientId": "2",
"roleName": "Client B",
"routingOrder":"1"
},
{
"email": "<<recipient_c_email>>",
"name": "<<recipient_c_name>>",
"recipientId": "3",
"roleName": "Internal Review",
"routingOrder":"2"
}
]
}
}
],
"serverTemplates": [
{
"sequence": "1",
"templateId": "<<templateID_1>>"
}
]
},
{
"document": {
"documentBase64": "<<BinaryDataB>>",
"documentId": "2",
"fileExtension": "pdf",
"name": "Test Landscape Document"
},
"inlineTemplates": [
{
"sequence": "1",
"recipients": {
"signers": [
{
"email": "<<recipient_a_email>>",
"name": "<<recipient_a_name>>",
"recipientId": "1",
"roleName": "Client A",
"routingOrder":"1"
},
{
"email": "<<recipient_b_email>>",
"name": "<<recipient_b_name>>",
"recipientId": "2",
"roleName": "Client B",
"routingOrder":"1"
},
{
"email": "<<recipient_c_email>>",
"name": "<<recipient_c_name>>",
"recipientId": "3",
"roleName": "Internal Review",
"routingOrder":"2"
}
]
}
}
],
"serverTemplates": [
{
"sequence": "1",
"templateId": "<<templateID_2>>"
}
]
}
],
"status": "sent",
"emailSubject":"Please Sign this Document"}
Try this: (taken out of Gil's Composite Template Blog Post)
{
"emailSubject": "Please sign your lease agreement.",
"emailBlurb": "Each tenant must sign individual lease.",
"status": "sent",
"compositeTemplates": [{
"document": {
"documentId": "1",
"name": "Property-A",
"fileExtension": "pdf",
"documentBase64": "JVBERi...NCg=="
}
},
{
"serverTemplates": [{
"sequence": "1",
"templateId": "E5577130-xxxx-xxxx-xxxx-95DD79644971"
}],
"inlineTemplates": [{
"recipients": {
"signers": [{
"email": "wile.e.coyote#example.com",
"name": "Wile E. Coyote",
"roleName": "Tenant"
}]
},
"sequence": "2"
}]
},
{
"serverTemplates": [{
"sequence": "1",
"templateId": "E5577130-xxxx-xxxx-xxxx-95DD79644971"
}],
"inlineTemplates": [{
"recipients": {
"signers": [{
"email": "hunter_of_rabbits#example.com",
"name": "Elmer Fudd",
"roleName": "Tenant"
}]
},
"sequence": "2"
}]
}
]
}
The following JSON body allowed me to create an envelope with two Documents, each assigned to a different template. I did have to define the recipient information per composite item, but DocuSign recognised that they were the same person and they were able to sign both documents in a single session.
The blog (https://www.docusign.com/blog/dsdev-why-use-composite-templates) helped describe how composite envelopes are structured which was a big help.
{
"compositeTemplates": [
{
"compositeTemplateId": "1",
"document": {
"documentBase64": "<<BinaryDataA>>",
"documentId": "1",
"fileExtension": "pdf",
"name": "Test Document A"
},
"serverTemplates": [
{
"sequence": "1",
"templateId": "<<TemplateIDA>>"
}
],
"inlineTemplates": [
{
"sequence": "1",
"recipients": {
"signers": [
{
"email": "<<recipient_A_Email>>",
"name": "<<recipient_A_Name>>",
"recipientId": "1",
"roleName": "Client A",
"routingOrder":"1"
},
{
"email": "<<recipient_B_Email>>",
"name": "<<recipient_B_Name>>",
"recipientId": "2",
"roleName": "Client B",
"routingOrder":"1"
},
{
"email": "<<recipient_C_Email>>",
"name": "<<recipient_C_Name>>",
"recipientId": "3",
"roleName": "Internal Review",
"routingOrder":"2"
}
]
}
}
]
},
{
"compositeTemplateId": "2",
"document": {
"documentBase64": "<<BinaryDataB>>",
"documentId": "2",
"fileExtension": "pdf",
"name": "Test Document B"
},
"serverTemplates": [
{
"sequence": "1",
"templateId": "<<TemplateIDB>>"
}
],
"inlineTemplates": [
{
"sequence": "1",
"recipients": {
"signers": [
{
"email": "<<recipient_A_Email>>",
"name": "<<recipient_A_Name>>",
"recipientId": "1",
"roleName": "Client A",
"routingOrder":"1"
},
{
"email": "<<recipient_B_Email>>",
"name": "<<recipient_B_Name>>",
"recipientId": "2",
"roleName": "Client B",
"routingOrder":"1"
},
{
"email": "<<recipient_C_Email>>",
"name": "<<recipient_C_Name>>",
"recipientId": "3",
"roleName": "Internal Review",
"routingOrder":"2"
}
]
}
}
]
}
],
"status": "sent",
"emailSubject":"Please Sign this Document",
"emailBlurb":"This is a test email blurb"}
Using the below code, everything works except I am only able to fill the Tabs from whatever document I attach second. Tabs from the first don't even show up on the "Form Data" list. I'm sure this is something minor that I am overlooking, but I can not see a differance between what I have and what I have seen elsewhere on this forum, and I can not find another post with this problem. Any help would be appreciated.
{
"emailSubject": "DocuSign API - Composite Test",
"status": "sent",
"compositeTemplates": [
{
"serverTemplates": [
{
"sequence": "1",
"templateId": "TEMPLATEID"
}
],
"inlineTemplates":[
{
"sequence":"1",
"recipients": {
"inPersonSigner": [
{
"hostEmail": "HOTEMAIL",
"hostName": "HOSTNAME",
"inPersonSigningType": "inPersonSigner",
"recipientId": "1",
"roleName": "Primary",
"signerName": "John Doe",
"signerEmail": "Test#Test.com",
"clientUserId": "1001"
}
]
},
"tabs": {
"textTabs": [
{
"tabLabel": "Address",
"value": "221 Cherry St"
}
]
}
}
]
},
{
"serverTemplates":[
{
"sequence": "2",
"templateId": "TEMPLATEID"
}
],
"inlineTemplates":[
{
"sequence":"2",
"recipients": {
"inPersonSigners": [
{
"hostEmail": "HOSTEMAIL",
"hostName": "HOSTNAME",
"inPersonSigningType": "inPersonSigner",
"recipientId": "1",
"roleName": "Primary",
"signerName": "John Doe",
"signerEmail": "test#test.com",
"clientUserId": "1001"
}
]
},
"tabs": {
"textTabs": [
{
"tabLabel": "ApplicantPhone",
"value": "123-456-7890"
}
]
}
}
]
}
]
}
A couple of comments about the JSON you've posted:
the property name for the inPersonSigners should be plural (in your JSON, it's singular InPersonSigner in the first composite template object)
tabs should be a property of each inPersonSigner object (in your JSON, it's a property of the inlineTemplate object)
With this feedback in mind, here's how your inPersonSigners section should be structured:
"inPersonSigners": [
{
"hostEmail": "HOSTEMAIL",
"hostName": "HOSTNAME",
"inPersonSigningType": "inPersonSigner",
"recipientId": "1",
"roleName": "Primary",
"signerName": "John Doe",
"signerEmail": "Test#Test.com",
"clientUserId": "1001",
"tabs": {
"textTabs": [
{
"tabLabel": "...",
"value": "..."
}
]
}
}
]
And, here's your entire JSON request, modified to reflect the changes I've described above:
{
"emailSubject": "DocuSign API - Composite Test",
"status": "sent",
"compositeTemplates": [
{
"serverTemplates": [
{
"sequence": "1",
"templateId": "TEMPLATEID"
}
],
"inlineTemplates":[
{
"sequence":"2",
"recipients": {
"inPersonSigners": [
{
"hostEmail": "HOSTMAIL",
"hostName": "HOSTNAME",
"inPersonSigningType": "inPersonSigner",
"recipientId": "1",
"roleName": "Primary",
"signerName": "John Doe",
"signerEmail": "Test#Test.com",
"clientUserId": "1001",
"tabs": {
"textTabs": [
{
"tabLabel": "Address",
"value": "221 Cherry St"
}
]
}
}
]
}
}
]
},
{
"serverTemplates":[
{
"sequence": "1",
"templateId": "TEMPLATEID"
}
],
"inlineTemplates":[
{
"sequence":"2",
"recipients": {
"inPersonSigners": [
{
"hostEmail": "HOSTEMAIL",
"hostName": "HOSTNAME",
"inPersonSigningType": "inPersonSigner",
"recipientId": "1",
"roleName": "Primary",
"signerName": "John Doe",
"signerEmail": "test#test.com",
"clientUserId": "1001",
"tabs": {
"textTabs": [
{
"tabLabel": "ApplicantPhone",
"value": "123-456-7890"
}
]
}
}
]
}
}
]
}
]
}
How do I specify prefilled fields with composite templates when creating an envelope.
I tried including the tabs information in the inlineTemplate.recipients.signers[0].tabs, but I get an error that System.String cannot be cast to API_REST.Models.v2.tabs.
If I include information as a template role in templateRoles, it is ignored. The documentation is light on information about how to do this. It seems like the prefill data should be specified in the inline template.
Other open questions I have include what does the recipientId do. What is the clientUserIdused for? We currently set clientUserId to the same value for all signers. I see it's used when signer requests a signature. Should it be unique to every signer for some reason?
It also looks like a single composite template overlays the server and inline templates on top of each other. What's the use case for having multiple server templates or multiple inline templates in a single composite template?
Are there plans to improve the documentation to describe how to use composite templates for various purposes?
Signer/template role:
{
"clientUserId": "clientUserId",
"email": "first+last#email.com",
"name": "First Last",
"roleName": "role1",
"tabs": {
"textTabs": [
{
"locked": true,
"tabLabel": "\\*FieldName",
"value": "prefillValue"
}
]
}
}
Example request:
{
"compositeTemplates": [
{
"inlineTemplates": [
{
"recipients": {
"signers": [
{
"clientUserId": "clientUserId",
"email": "first+last#email.com",
"name": "First Last",
"recipientId": 1,
"roleName": "role1",
"tabs": {
"textTabs": [{"tabLabel": "label", "value": "val"}]
}
}
]
},
"sequence": 1
}
],
"serverTemplates": [
{
"sequence": 1,
"templateId": "templateId1"
}
]
},
{
"inlineTemplates": [
{
"recipients": {
"signers": [
{
"clientUserId": "clientUserId",
"email": "first+last#better.com",
"name": "First Last",
"recipientId": 1,
"roleName": "role1",
"tabs": {
"textTabs": [{"tabLabel": "label", "value": "val"}]
}
}
]
},
"sequence": 2
}
],
"serverTemplates": [
{
"sequence": 2,
"templateId": "templateId2"
}
]
}
],
"emailSubject": "Email subject",
"status": "sent",
"templateId": null,
"templateRoles": null
}
Information on sending an envelope from a server template can be found here.
RecipientID is used by the tab element to indicate which recipient is to sign the Document while the clientuserID specifies if the user is remote or embedded and it is recommended it be unique per signer (but not required).
I'd also suggest reading this page about composite templates, hopefully the concept will make a bit more sense but I am with you that the lack of documentation on composite templates can be troublesome.
Unfortunately, I don't have a sample with tab data included, but adding the tab section under each recipient from my sample below should work with no issues.
{
"emailSubject": "DocuSign Comp Test 1",
"emailBlurb": "Example - Composite Templates",
"status": "sent",
"compositeTemplates": [
{
"serverTemplates": [
{
"sequence": "1",
"templateId": "templateId1"
}
],
"inlineTemplates": [
{
"sequence": "1",
"recipients": {
"signers": [
{
"email": "testsigner123#gmail.com",
"name": "Test Tester",
"recipientId": "1",
"roleName": "Signer 1"
}
]
}
}
]
},
{
"serverTemplates": [
{
"sequence": "2",
"templateId": "templateId2"
}
],
"inlineTemplates": [
{
"sequence": "2",
"recipients": {
"signers": [
{
"email": "testsigner123#gmail.com",
"name": "Test Tester",
"recipientId": "1",
"roleName": "Signer 1"
}
]
}
}
]
},
{
"serverTemplates": [
{
"sequence": "3",
"templateId": "templateId3"
}
],
"inlineTemplates": [
{
"sequence": "2",
"recipients": {
"signers": [
{
"email": "testsigner123#gmail.com",
"name": "Test Tester",
"recipientId": "1",
"roleName": "Signer 1"
}
]
}
}
]
}
]
}
I'm having a problem creating an envelope from a composite template and having it not duplicate the recipient. Here is a sample of my call.
{
"emailSubject": "Please complete the following forms",
"status": "sent",
"compositeTemplates": [
{
"serverTemplates": [
{
"sequence": "1",
"templateId": "5ff1b987-dc38-49b1-b394-840f10ad08bb"
}
],
"inlineTemplates": [
{
"sequence": "2",
"recipients": {
"signers": [
{
"name": "Bob Sample",
"email": "bob.sample#example.com",
"roleName": "Client",
"clientUserId": "bob.sample#example.com",
"recipientId": "1"
}
]
}
}
]
},
{
"serverTemplates": [
{
"sequence": "1",
"templateId": "02d947aa-6320-4a6b-b4b4-79c4c733d0d0"
}
],
"inlineTemplates": [
{
"sequence": "2",
"recipients": {
"signers": [
{
"name": "Bob Sample",
"email": "bob.sample#example.com",
"roleName": "Client",
"clientUserId": "bob.sample#example.com",
"recipientId": "1"
}
]
}
}
]
}
]
}
When I look at the envelope it has Bob Sample twice in the signing flow. How do I make this call so that only one Bob Sample is required to sign?
I am creating an envelope using the RES API and have a tag on the document to capture a date (not the date signed, another recipient-supplied date). I can successfully pre-fill the value of this when the mask on the field is Text, but when I switch it to be Date it's blank. "DOBField" is the label of the tag below. Anyone know what I'm doing wrong here?
{
"accountId": "xxxxxx",
"emailSubject": "DocuSign API - Embedded Signing Example",
"compositeTemplates": [
{
"serverTemplates": [
{
"sequence": 1,
"templateId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx"
}
],
"inlineTemplates": [
{
"sequence": 1,
"recipients": {
"signers": [
{
"email": "123#456.com",
"name": "Rick James",
"clientUserId": "3",
"recipientId": 0,
"roleName": "Signer"
}
]
}
}
]
},
{
"serverTemplates": [
{
"sequence": 1,
"templateId": "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
],
"inlineTemplates": [
{
"sequence": 1,
"recipients": {
"signers": [
{
"email": "123#456.com",
"name": "Rick James",
"clientUserId": "3",
"recipientId": 0,
"roleName": "Signer",
"tabs": {
"textTabs": [
{
"tabLabel": "DOBField",
"value": "12/24/1976"
}
]
}
}
]
}
}
]
}
],
"enableWetSign": false,
"status": "sent"
}
If you've specified mask of "Date" for the field, then it's no longer a textTab -- it's now a dateTab. So, try changing textTabs to dateTabs in your API request. i.e., the tabs portion of the request will look like this:
"tabs": {
"dateTabs": [
{
"tabLabel": "DOBField",
"value": "12/24/1976"
}
]
}