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"}
My goal is to make SignHereTab location and size the same as one of my Pdf Form Field. Docusign guide
tells me that I can transform Pdf Form fields into DocuSign tabs. And according to the guide I shoud use CompositeTempates.
I have two recipients and two Pdfs. One pdf should be signed by both recipients, the second pdf should be signed by the first. Here is JSON example of envelop. I'm usign CreateEnvelop method from Docusign.eSign.dll (https://www.nuget.org/packages/DocuSign.eSign.dll/)
{
"compositeTemplates": [
{
"document": {
"documentBase64": "base64 data",
"documentId": "1",
"name": "MainPart.pdf",
"transformPdfFields": "True"
},
"inlineTemplates": [
{
"recipients": {
"signers": [
{
"accessCode": "1239",
"email": "insured#gmail.com",
"name": "Insured ",
"recipientId": "1",
"routingOrder": "1",
"tabs": {
"signHereTabs": [
{
"recipientId": "1",
"tabLabel": "insured_sign_parta\\*"
}
]
}
},
{
"accessCode": "1212",
"email": "owner#gmail.com",
"name": "Owner",
"recipientId": "2",
"routingOrder": "2",
"tabs": {
"signHereTabs": [
{
"recipientId": "2",
"tabLabel": "owner_sign_parta\\*"
}
]
}
}
]
},
"sequence": "1"
}
]
},
{
"document": {
"documentBase64": "base64 data",
"documentId": "2",
"name": "AdditionalPart.pdf",
"transformPdfFields": "True"
},
"inlineTemplates": [
{
"recipients": {
"signers": [
{
"accessCode": "1239",
"email": "insured#gmail.com",
"name": "Insured",
"recipientId": "1",
"routingOrder": "1",
"tabs": {
"signHereTabs": [
{
"recipientId": "1",
"tabLabel": "insured_sign_parta\\*"
}
]
}
}
]
},
"sequence": "2"
}
]
}
],
"emailBlurb": "Email Text",
"emailSubject": "Subject",
"status": "sent"
}
When I open documents SignHereTabs doesn't appear :(
Could anybody help me, please? What am I doing wrong?
I have seen tutorials from Docusign website and all related issues on StackOverflow, but still it didn't help. I've been investigating this issue for almost two days and I got nothing...
tabs should have a documentId as well as a recipientId so that they can refer to both the recipient that needs to sign them and the specific document that they should be in.
see here for full reference - https://developers.docusign.com/esign-rest-api/reference/Envelopes/EnvelopeDocumentTabs
Many questions address portions of my request, but I cannot seem to make a complete solution work. I have created a template on my site (it has various text fields, initial fields, and signature block). Single recipient, using anchor tags for the fields. When I take a .docx file, create an envelope via the api, I want to apply the template previously mentioned, and then prefill 4 text fields on the document/template.
Anchor tags are not placing the fields appropriately.
Any advise/suggestions?
Working request call is:
{
"documents":
[
{
"documentBase64":"<BASE64STREAM>",
"documentId":"3",
"fileExtension":"docx",
"name":"10001000_20170803_FILE"
}
],
"emailSubject": "TEST - Group Audit - 10001000",
"templateId": "TEMPLATE_ID",
"templateRoles" :
[
{
"email": "JDOE#email.com",
"name": "JOHN DOE",
"roleName": "signer1",
"tabs":
{
"textTabs":
[
{
"documentId": "3",
"recipientId": "1",
"tabLabel": "groupname",
"value": "TEST GROUP ONE"
},
{
"documentId": "3",
"recipientId": "1",
"tabLabel": "groupnumber",
"value": "10001000"
},
{
"documentId": "3",
"recipientId": "1",
"tabLabel": "txt",
"value": "my#email.com"
},
{
"documentId": "3",
"recipientId": "1",
"tabLabel": "fein",
"value": "870142380"
},
{
"documentId": "3",
"recipientId": "1",
"tabLabel": "physicaladdress",
"value": "1 STREET WAY, , MY CITY, CA, 98001"
}
]
}
}
],
"status":"sent"
}
Based on the information you've provided, I understand your scenario to be as follows:
You've created a template via the DocuSign UI; that template contains a 'placeholder' document (which you will replace at run-time via your Create/Send Envlope API call) and defines the recipient(s) and tabs for that document.
When you create/send the envelope via API, you want to specify the document as part of the API request (i.e., to be used instead of the 'placeholder' document that the DocuSign template contains) and also auto-populate some of the tabs that the template defines.
If that's an accurate description of what you're trying to achieve, then you need to use Composite Templates in the API request structure. Here's an example of a Create/Send Envelope JSON request that uses composite templates (and contains data based upon the information you provided in your question):
{
"compositeTemplates": [
{
"serverTemplates": [
{
"sequence": "1",
"templateId": "TEMPLATE_ID"
}
],
"inlineTemplates": [
{
"sequence": "2",
"recipients": {
"signers": [
{
"name": "JOHN DOE",
"email": "JDOE#email.com",
"roleName": "signer1",
"tabs":
{
"textTabs":[
{
"tabLabel" : "groupname",
"value" : "TEST GROUP ONE"
},
{
"tabLabel" : "groupnumber",
"value" : "10001000"
},
{
"tabLabel" : "txt",
"value" : "my#email.com"
},
{
"tabLabel" : "fein",
"value" : "870142380"
},
{
"tabLabel" : "physicaladdress",
"value" : "1 STREET WAY, , MY CITY, CA, 98001"
}
]
}
}
]
}
}
],
"document": {
"documentId": "3",
"name": "10001000_20170803_FILE.docx",
"fileExtension": "docx",
"documentBase64": "BASE64STREAM"
}
}
],
"status": "sent",
"emailSubject": "TEST - Group Audit - 10001000"
}
I am trying to develop the following workflow in DocuSign:
There are two documents to be signed. The first is a template with 4 signatures required by 4 roles. The second document is uploaded, docx or pdf, and will be signed after the first document is complete.In the first document the first two signers need to be provided to the template and I could make this work when all I had in the envelope was the template document. After converting this to a compositeTemplate I don't see a place to add the roles to the template document. I am also unsure how to add the signature to the second document to the workflow for the template document.
The following is the json I am generating:
{
"templateRoles": [
{
"email": "EMAIL1",
"roleName": "ROLE1",
"name": "NAME1"
},
{
"email": "EMAIL2",
"roleName": "ROLE2",
"name": "NAME2"
}
],
"compositeTemplates": [
{
"serverTemplates": [
{
"sequence": "1",
"templateId": "TEMPLATE-ID"
}
]
},
{
"inlineTemplates": [
{
"sequence": "2",
"documents": [
{
"documentId": "1",
"name": "Contract",
"documentBase64": <DOC DATA>
}
]
}
]
}
],
"emailSubject": "[DocuSign C# SDK] - Sample Signature Request"
}
The template roles aren't picked up by the servertemplate and the documents are sent to the third person in the workflow.
Any help with this will be much appreciated.
You will have to use multiple composite templates to add a new document.
The templateRoles specified at the root level are ignored when your envelope definition contains composite templates. The templateRoles have to be spcified within the inlineTemplate.
The tabs can be added in the second composite template.
{
"compositeTemplates": [
{
"serverTemplates": [
{
"sequence": "1",
"templateId": "<Specify the serverTemplateId here>"
}
],
"inlineTemplates": [
{
"sequence": "1",
"recipients": {
"signers": [
{
"name": "NAME1",
"email": "EMAIL1",
"roleName": "ROLE1",
"recipientId": "1"
},
{
"name": "NAME2",
"email": "EMAIL2",
"roleName": "ROLE2",
"recipientId": "2"
}
]
}
}
]
},
{
"inlineTemplates": [
{
"sequence": "2",
"recipients": {
"signers": [
{
"name": "NAME1",
"email": "EMAIL1",
"roleName": "ROLE1",
"recipientId": "1",
"tabs": {
"signHereTabs": [
{
"documentId": "2",
"pageNumber": "1",
"xPosition": "50",
"yPosition": "50"
}
]
}
}
]
}
}
],
"document": {
"documentId": "2",
"name": "DocumentName",
"fileExtension": "docx",
"documentBase64": "<Specify document bytes here>"
}
}
],
"emailSubject": "[DocuSign C# SDK] - Sample Signature Request",
"status": "sent"
}
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"
}
]
}
}
]
}
]
}