I'm trying to create an envelope using DocuSign REST API. The signature tabs are generated by converting the PDF signature fields, and a signerAttachment tab is added manually.
In the final envelope, there is (as expected) only one signHere tab, but three overlapping signerAttachment tabs, which must be acted upon (read: upload a file) before the envelope can be effectively signed.
The envelope has 2 documents, one of which has signature tabs generated by transforming PDF fields. There are two recipients, one signer and one "Carbon Copy". The signer, before completing the envelope, must upload an additional document, so I added a signerAttachmentTab.
The JSON sent to the API endpoint /restapi/v2.1/accounts/{accountId}/envelopes follows (null values omitted and sensitive information redacted):
{
"compositeTemplates": [
{
"compositeTemplateId": "0",
"document": {
"documentBase64": "(redacted)",
"documentId": "1",
"fileExtension": "pdf",
"name": "Summary",
"transformPdfFields": "true"
},
"inlineTemplates": [
{
"envelope": {
"emailBlurb": "Just a test for development. Ignore this message",
"emailSubject": "from unit-test 01"
},
"recipients": {
"carbonCopies": [
{
"email": "john.doe@company.com",
"name": "John Doe",
"recipientId": "00283187",
"roleName": "CCOPY",
"routingOrder": "1"
}
],
"signers": [
{
"email": "jane.dee@company.com",
"name": "Jane Dee",
"recipientId": "00283183",
"recipientSignatureProviders": [
{
"signatureProviderName": "(redacted)",
"signatureProviderOptions": {
"sms": "+000-000-000"
}
}
],
"roleName": "SIGNER",
"routingOrder": "1",
"tabs": {
"signerAttachmentTabs": [
{
"xposition": "10",
"yposition": "10",
"documentId": "3",
"name": "Attachment",
"pageNumber": "1",
"recipientId": "00283183",
"tabLabel": "Attach-document",
"tooltip": "SignerAttachment",
"xPosition": "10",
"yPosition": "10"
}
],
"signHereTabs": [
{
"anchorAllowWhiteSpaceInCharacters": "true",
"recipientId": "00283183",
"tabLabel": "firmatario_00283183\\*"
}
]
},
"userId": "00283183"
}
]
},
"sequence": "1"
}
]
},
{
"compositeTemplateId": "1",
"document": {
"documentBase64": "(redacted)",
"documentId": "2",
"fileExtension": "pdf",
"name": "sample0",
"transformPdfFields": "true"
},
"inlineTemplates": [
{
"customFields": {
},
"envelope": {
"emailBlurb": "Just a test for development. Ignore this message",
"emailSubject": "from unit-test 01"
},
"recipients": {
"carbonCopies": [
{
"email": "john.doe@company.com",
"name": "John Doe",
"recipientId": "00283187",
"roleName": "CCOPY",
"routingOrder": "1"
}
],
"signers": [
{
"email": "jane.dee@company.com",
"name": "Jane Dee",
"recipientId": "00283183",
"recipientSignatureProviders": [
{
"signatureProviderName": "(redacted)",
"signatureProviderOptions": {
"sms": "+000-000-000"
}
}
],
"roleName": "SIGNER",
"routingOrder": "1",
"tabs": {
"signerAttachmentTabs": [
{
"xposition": "10",
"yposition": "10",
"documentId": "3",
"name": "Attachment",
"pageNumber": "1",
"recipientId": "00283183",
"tabLabel": "Attach-document",
"tooltip": "SignerAttachment",
"xPosition": "10",
"yPosition": "10"
}
],
"signHereTabs": [
{
"anchorAllowWhiteSpaceInCharacters": "true",
"recipientId": "00283183",
"tabLabel": "firmatario_00283183\\*"
}
]
},
"userId": "00283183"
}
]
},
"sequence": "2"
}
]
},
{
"compositeTemplateId": "2",
"document": {
"documentBase64": "(redacted)",
"documentId": "3",
"fileExtension": "pdf",
"name": "sample1",
"transformPdfFields": "true"
},
"inlineTemplates": [
{
"envelope": {
"emailBlurb": "Just a test for development. Ignore this message",
"emailSubject": "from unit-test 01"
},
"recipients": {
"carbonCopies": [
{
"email": "john.doe@company.com",
"name": "John Doe",
"recipientId": "00283187",
"roleName": "CCOPY",
"routingOrder": "1"
}
],
"signers": [
{
"email": "jane.dee@company.com",
"name": "Jane Dee",
"recipientId": "00283183",
"recipientSignatureProviders": [
{
"signatureProviderName": "(redacted)",
"signatureProviderOptions": {
"sms": "+000-000-000"
}
}
],
"roleName": "SIGNER",
"routingOrder": "1",
"tabs": {
"signerAttachmentTabs": [
{
"xposition": "10",
"yposition": "10",
"documentId": "3",
"name": "Attachment",
"pageNumber": "1",
"recipientId": "00283183",
"tabLabel": "Attach-document",
"tooltip": "SignerAttachment",
"xPosition": "10",
"yPosition": "10"
}
],
"signHereTabs": [
{
"anchorAllowWhiteSpaceInCharacters": "true",
"recipientId": "00283183",
"tabLabel": "firmatario_00283183\\*"
}
]
},
"userId": "00283183"
}
]
},
"sequence": "3"
}
]
}
],
"notification": {
"expirations": {
"expireAfter": "2",
"expireEnabled": "true"
}
},
"status": "sent",
"transactionId": "55909b0d-b54f-454e-b966-e58ca5fb4e7e"
}
The envelope definition has been written following the guidelines by DocuSign, namely by inserting a composite template for each document and assigning the recipients to each one of them.
Now, I expect that, despite the same recipients being declared three times (one for each document), they will be merged in the final envelopes, as per this quote from the same page:
When you use multiple templates to create an envelope, two or more templates may define the same recipient (a recipient with the same role or even the same name as other recipients), creating duplicate recipients. You can automatically merge these duplicate recipients by making sure that each of these duplicate recipients has the same email, user name, and routing order. In this case, any duplicate recipients are merged together after all template overlays have been applied.
What I observe is that, in the final envelope, there is -- as expected -- only one signature field, but three overlapping signerAttachment field. Therefore, the signer has to upload the same file three times to complete the envelope.
A call to the endpoint /restapi/v2.1/accounts/{accountId}/envelopes/{envelopeId}/recipients/{recipientId}/tabs confirms the presence of three similar tabs:
{
"signHereTabs": [
{
"stampType": "signature",
"isSealSignTab": "false",
"name": "SignHere",
"tabLabel": "firmatario_00283183_Firma consulenza_001",
"scaleValue": "1",
"optional": "false",
"documentId": "3",
"recipientId": "1",
"pageNumber": "1",
"xPosition": "391",
"yPosition": "719",
"width": "0",
"height": "0",
"tabId": "2cee0f3e-a2bb-4aae-a5b4-82c66b177c0a",
"tabType": "signhere"
}
],
"signerAttachmentTabs": [
{
"name": "Attachment",
"tabLabel": "Attach-document",
"scaleValue": "1",
"optional": "false",
"documentId": "3",
"recipientId": "1",
"pageNumber": "1",
"xPosition": "10",
"yPosition": "10",
"width": "0",
"height": "0",
"tabId": "a67c3071-6ac4-4c3b-a20c-0197cda091ed",
"tabType": "signerattachment",
"tooltip": "SignerAttachment"
},
{
"name": "Attachment",
"tabLabel": "Attach-document",
"scaleValue": "1",
"optional": "false",
"documentId": "3",
"recipientId": "1",
"pageNumber": "1",
"xPosition": "10",
"yPosition": "10",
"width": "0",
"height": "0",
"tabId": "c20809de-3792-4ff7-ab31-6f09a13f3fbc",
"tabType": "signerattachment",
"tooltip": "SignerAttachment"
},
{
"name": "Attachment",
"tabLabel": "Attach-document",
"scaleValue": "1",
"optional": "false",
"documentId": "3",
"recipientId": "1",
"pageNumber": "1",
"xPosition": "10",
"yPosition": "10",
"width": "0",
"height": "0",
"tabId": "1d0c84cd-6511-47c2-a75f-73721ac2fb0f",
"tabType": "signerattachment",
"tooltip": "SignerAttachment"
}
]
}
Why the signerAttachment tabs are not merged like the signHere tabs and what can be done to merge them in the resulting envelope?
I believe the issue is that in the case of the SignHere tab, your InLineTemplate is not creating the SignHere tabs, it is providing/updating the settings for the existing tab where the tabLabel is "firmatario_00283183"
(The tab is existing because it was created as part of the PDF transformation.)
In contrast, your three definitions for the SignerAttachment tabs are each creating new tabs. So you're seeing the three new SignerAttachment tabs on the document.
Solution: only create as many SignerAttachment tabs as you want. There is no merging (supression) of tabs, just merging of the Recipients.
I will admit that I'm not a gonzo expert on CompositeTemplates. But I think I'm on reasonably firm ground here.