Envelopes with a dynamic number of signers
One of the features most widely used by DocuSign developers is composite templates. Composite templates give you the flexibility to combine one or more server templates with inline templates, documents, signer details, and more.
This post shows you how to generate an envelope for a dynamic number of signers set when the envelope is created. Every signer will see and sign a document that’s specific to them, and one of the signers will include SMS authentication.
The use case
- A server template is used for the first document in the envelope. Every signer will see it. It displays common company information.
- A carbon copy recipient will receive a completed copy of the envelope. They will see all the signed documents.
- The envelope has a dynamic number of signers.
- Every signer sees one additional document specific to themselves.
- Different documents are uploaded for the signers. The documents for the signers do not need to share anchor strings, tabs, or any other characteristics in common. This example uses a PDF for one signer and a Word document for another.
- Additional signer authentication can be added for some or all signers. In this example, SMS authentication is used for one of the signers.
Note: This example requires the document visibility feature for the account, and anchor tagging scope of Envelope.
Document visibility is used to control document access by recipients in the current envelope. For this use case, the Must sign to view, unless sender setting under Settings > Sending Settings will allow recipients to only see the documents they need to sign. Reference: the User guide section on document visibility.
By default, Anchor tagging scope is set to Envelope. It is controlled in the DocuSign back-end. If you encounter stacked tags, the reason could well be your anchor tagging scope. Please contact support to confirm your scope type.
Solution
The solution for the use case is to use multiple composite template objects.
The first compositeTemplate object (ID of 1) includes the cc recipient information and the server template (with its document) that will be visible to all recipients. This template will be visible to all recipients because it does not include any tabs (fields). See the document visibility documentation.
The second compositeTemplate object (ID of 2) includes the Agreement Summary PDF document, and its signer’s details. This document will only be visible to its signer (and the cc recipient). This compositeTemplate object does not include a server template. This compositeTemplate object’s output (the document) will be sequenced after the first compositeTemplate’s output.
The third compositeTemplate object (ID of 3) is similar to the second compositeTemplate. It includes the document for the second signer and the signer’s details. This signer includes SMS authentication.
This document will only be visible to its signer (and the cc recipient). This compositeTemplate object does not include a server template. This compositeTemplate object’s output (the document) will be sequenced after the first compositeTemplate’s output.
Additional compositeTemplate objects can be added to the request for each additional signer.
{
"compositeTemplates": [
{
"compositeTemplateId": "1",
"inlineTemplates": [
{
"recipients": {
"carbonCopies": [
{
"email": "carbon@example.com",
"name": "Signer copy",
"recipientId": "2",
"roleName": "cc",
"routingOrder": "2"
}
]
},
"sequence": "1"
}
],
"serverTemplates": [
{
"sequence": "1",
"templateId": "xxxxx-xxxxx-xxxxx-xxxxxx"
}
]
},
{
"compositeTemplateId": "2",
"document": {
"documentBase64": "base64doc",
"documentId": 1,
"fileExtension": "pdf",
"name": "Agreement Summary"
},
"inlineTemplates": [
{
"sequence": "2",
"recipients": {
"signers": [
{
"email": "signer1@example.com",
"name": "Signer One",
"recipientId": "1",
"routingOrder": "1",
"tabs": {
"dateTabs": [
{
"recipientId": "1",
"value": "2020-12-16",
"anchorXOffset": "1",
"anchorYOffset": "0",
"anchorIgnoreIfNotPresent": "false",
"anchorString": "/date/",
}
],
"signHereTabs": [
{
"recipientId": "1",
"anchorXOffset": "1",
"anchorYOffset": "0",
"anchorIgnoreIfNotPresent": "false",
"anchorString": "/signature/"
}
],
"fullNameTabs": [
{
"recipientId": "1",
"anchorXOffset": "1",
"anchorYOffset": "0",
"anchorIgnoreIfNotPresent": "false",
"anchorString": "/name/"
}
]
}
}
]
}
}
]
},
{
"compositeTemplateId": "3",
"document": {
"documentBase64": "base64doc",
"documentId": 2,
"fileExtension": "docx",
"name": "Another Agreement Summary"
},
"inlineTemplates": [
{
"sequence": "2",
"recipients": {
"signers": [
{
"email": "signer2@example.com",
"name": "Signer Two",
"recipientId": "2",
"routingOrder": "1",
"idCheckConfigurationName": "SMS Auth $",
"requireIdLookup": "true",
"smsAuthentication": {
"senderProvidedNumbers": [
"+0000000000"
]
},
"tabs": {
"dateTabs": [
{
"recipientId": "2",
"value": "2020-12-16",
"anchorXOffset": "1",
"anchorYOffset": "0",
"anchorIgnoreIfNotPresent": "false",
"anchorString": "/date2/",
}
],
"signHereTabs": [
{
"recipientId": "2",
"anchorXOffset": "1",
"anchorYOffset": "0",
"anchorIgnoreIfNotPresent": "false",
"anchorString": "/signature2/"
}
],
"fullNameTabs": [
{
"recipientId": "2",
"anchorXOffset": "1",
"anchorYOffset": "0",
"anchorIgnoreIfNotPresent": "false",
"anchorString": "/name2/"
}
]
}
}
]
}
}
]
}
],
"emailSubject": "Please sign",
"status": "sent"
}
Envelope vs document anchor string scoping
Does DocuSign search all of the documents for an anchor string or just the document specified with a documentId attribute? Accounts, by default, search all of the documents in the envelope visible to the recipient for anchor string matches, even if a documentId is supplied. This is the default Envelope Anchor String Scope.
This example works with the default settings by using different anchor strings for each document.
Summary
By using compositeTemplate objects, you can add documents and signers when your application creates envelopes.
Additional resources
- DocuSign Support: Use Document Visibility to Control Recipient Access
- DocuSign Developer Center: eSignature REST API 101: Auto-place (anchor tagging)
- DocuSign Developer Center
- @DocuSignAPI on Twitter
- DocuSign for Developers on LinkedIn
- DocuSign for Developers on YouTube
- DocuSign Developer Newsletter
