Related
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.
Case details
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.
Each signerAttachmentTab specified in each compositeTemplate has specified the same document for placement - "documentId": "3", so each of your composites is placing a new signer attachment tab to the same document, ID 3. If you only want one signer attachment, only specify it in the requisite composite. For documentId = 3, that would be your third composite. If you want an attachment tab on each document, then make sure you specify the correct documentId.
I am seeing a weird behavior with this test eSign transaction:
{
"compositeTemplates": [
{
"inlineTemplates": [
{
"documents": [
{
"documentBase64": "BASE64STRING",
"documentId": "7",
"fileExtension": "PDF",
"name": "DOCUMENT7"
}, {
"documentBase64": "BASE64STRING",
"documentId": "10",
"fileExtension": "PDF",
"name": "DOCUMENT10"
}, {
"documentBase64": "BASE64STRING",
"documentId": "12",
"fileExtension": "PDF",
"name": "DOCUMENT12"
}, {
"documentBase64": "BASE64STRING",
"documentId": "17",
"fileExtension": "PDF",
"name": "DOCUMENT17"
}, {
"documentBase64": "BASE64STRING",
"documentId": "18",
"fileExtension": "PDF",
"name": "DOCUMENT18"
}, {
"documentBase64": "BASE64STRING",
"documentId": "19",
"fileExtension": "PDF",
"name": "DOCUMENT19"
}, {
"documentBase64": "BASE64STRING",
"documentId": "20",
"fileExtension": "PDF",
"name": "DOCUMENT20"
}
],
"recipients": {
"signers": [
{
"email": "SIGNER1#mailinator.com",
"excludedDocuments": [
"20"
],
"name": "SIGNER1",
"recipientId": "2",
"tabs": {
"signHereTabs": [
{
"documentId": "7",
"pageNumber": "1",
"recipientId": "2",
"xPosition": "45",
"yPosition": "628"
}
]
}
}, {
"email": "SIGNER2#mailinator.com",
"excludedDocuments": [
"7"
],
"name": "SIGNER2",
"recipientId": "3",
"tabs": {
"signHereTabs": [
{
"documentId": "20",
"pageNumber": "1",
"recipientId": "3",
"xPosition": "45",
"yPosition": "628"
}
]
}
}
]
},
"sequence": "1"
}
]
}, {
"serverTemplates": [
{
"sequence": "1",
"templateId": "f7e03095-8fd0-4c0a-9ec4-50d8fcee9b17"
}
]
}
],
"emailSubject": "Test eSign",
"enforceSignerVisibility": "True",
"status": "sent"
}
When I send it to the DocuSign v2.1 api {{baseUrl}}/v2.1/accounts/{{accountId}}/envelopes
I receive the following error:
{
"errorCode": "CANNOT_EXCLUDE_DOCUMENT",
"message": "This document cannot be excluded for this recipient. Recipient: SIGNER2 cannot be excluded from Document:DOCUMENT20"
}
However, as you can see in the recipient "SIGNER2", the list of excluded documents doesn't contain the document 20 but this one :
"excludedDocuments": [
"7"
],
If I remove the document "7" from the list of excludedDocuments, then the transaction will go through.
I have tested with any templates and it fails just the same.
If I don't use the CompositeTemplate structure, it succeeds.
Anything I am missing or not seeing ?
Thanks in advance
After more than 4 months since I have created a DocuSign case, it was finally reviewed and considered a bug on the DocuSign API.
This bug has been announced as something that will be fixed in the future.
This issue is currently open and in the hands of our engineering team
that have come with a workaround. This issue is due to the
compositeTemplate call re-generated document Ids, so instead of
honoring the values provided for document id the documents are
renumbered, in the created envelope DOCUMENT20 does have an ID of 7,
so that's where the error is coming from. To remove DOCUMENT20 you
would have to send exclude document 7 in your call body.
Go to Settings > Sending Settings > Document Visibility
And change Document Visibility to "Must sign to view, unless sender"
If this does not work, open a case and make sure to include the API request logs.
I have my Json working for single document and transforms the PDF fields, but when I try to add second document. I Get JSON Parse error.
This works
"document": {
"documentId": "1",
"name": "Test Contract With Fields.pdf",
"transformPdfFields": "true",
"documentBase64": "'.$documentHashpdf.'"
}
this also works but doesn't transforms the PDFFields.
"inlineTemplates": [
{
"documents": [
{
"documentBase64": "<Base64BytesHere>",
"documentId": "1",
"name": "test",
"transformPdfFields": "true"
},
{
"documentBase64": "<Base64BytesHere>",
"documentId": "2",
"name": "test 2",
"order": "2"
}
],
Adding Square [] and second document breaks. Tried making Documents
"document": [{
"documentId": "1",
"name": "Test Contract With Fields.pdf",
"transformPdfFields": "true",
"documentBase64": "'.$documentHashpdf.'"
},
{
"documentId": "2",
"name": "Test Contract With Fields 2.pdf",
"transformPdfFields": "true",
"documentBase64": "'.$documentHashpdf.'"
}]
**Update: Complete JSON
Looking to add a second **document****
{
"emailBlurb": "Test Blurb",
"emailSubject": "Test subject",
"status": "sent",
"compositeTemplates": [
{
"compositeTemplateId": "1",
"inlineTemplates": [
{
"sequence": "1","documents": [
{
"documentBase64": "'.$documentHashpdf.'",
"documentId": "2",
"name": "Not working", "order": "2"
}
],
"recipients": {
"signers": [
{
"email": "*******",
"name": "********e",
"recipientId": "1",
"smsAuthentication": {
"senderProvidedNumbers": ["******"]
},
"idCheckConfigurationName": "SMS Auth $",
"requireIdLookup": "true",
"clientUserId": "1001",
"defaultRecipient": "true",
"tabs": {
"signHereTabs": [
{
"pageNumber": "1",
"documentId": "1",
"tabLabel": "text 1",
"recipientId": "1"
}
],
"fullNameTabs": [
{
"pageNumber": "1",
"documentId": "1",
"xPosition": "20",
"yPosition": "20",
"height": "10",
"width": "20",
"tabLabel": "Text 2",
"recipientId": "1"
}
],
"dateSignedTabs": [
{
"pageNumber": "1",
"documentId": "1",
"xPosition": "20",
"yPosition": "30",
"height": "10",
"width": "20",
"tabLabel": "text 3",
"recipientId": "1"
}
]
}
}
]
}
}
],
"document": {
"documentId": "1",
"name": "Working",
"transformPdfFields": "true",
"documentBase64": "'.$documentHashpdf.'"
} }
]
There are 3 "models" for constructing envelopes. I recommend using composite templates in the intended way, where you manage each document contribution to the envelope by enclosing within separate compositeTemplate elements. I reworked your JSON like this:
{
"emailBlurb": "Test Blurb",
"emailSubject": "Test subject",
"status": "sent",
"compositeTemplates": [{
"compositeTemplateId": "1",
"document": {
"documentId": "1",
"name": "Working",
"transformPdfFields": "true",
"documentBase64": "'.$documentHashpdf.'"
},
"inlineTemplates": [{
"sequence": "1",
"recipients": {
"signers": [{
"email": "*******",
"name": "********e",
"recipientId": "1",
"smsAuthentication": {
"senderProvidedNumbers": ["******"]
},
"idCheckConfigurationName": "SMS Auth $",
"requireIdLookup": "true",
"clientUserId": "1001",
"defaultRecipient": "true"
}]
}
}]
},
{
"compositeTemplateId": "2",
"document": {
"documentBase64": "'.$documentHashpdf.'",
"documentId": "2",
"name": "Not working",
"transformPdfFields": "true"
},
"inlineTemplates": [{
"sequence": "1",
"recipients": {
"signers": [{
"email": "*******",
"name": "********e",
"recipientId": "1",
"smsAuthentication": {
"senderProvidedNumbers": ["******"]
},
"idCheckConfigurationName": "SMS Auth $",
"requireIdLookup": "true",
"clientUserId": "1001",
"defaultRecipient": "true"
}]
}
}]
}
]
}
In this fashion, any number of additional documents you wish to add would simply be another compositeTemplate element added to the array. This works for additional documents regardless of whether you wish to transform PDF fields, documents sourced from DocuSign templates, or any additional document for which you want to apply a template to overlay.
Note that the use of compositeTemplateId is only needed to relate multipart form attachments, which is a cleaner way to handle your documents rather than base64 encoding them in documentBase64 elements.
Here is the fixed JSON:
{
"emailBlurb": "Test Blurb",
"emailSubject": "Test subject",
"status": "sent",
"compositeTemplates": [
{
"compositeTemplateId": "1",
"inlineTemplates": [
{
"sequence": "1","documents": [
{
"documentBase64": "'.$documentHashpdf.'",
"documentId": "2",
"name": "Not working", "order": "2"
}
],
"recipients": {
"signers": [
{
"email": "*******",
"name": "********e",
"recipientId": "1",
"smsAuthentication": {
"senderProvidedNumbers": ["******"]
},
"idCheckConfigurationName": "SMS Auth $",
"requireIdLookup": "true",
"clientUserId": "1001",
"defaultRecipient": "true",
"tabs": {
"signHereTabs": [
{
"pageNumber": "1",
"documentId": "1",
"tabLabel": "text 1",
"recipientId": "1"
}
],
"fullNameTabs": [
{
"pageNumber": "1",
"documentId": "1",
"xPosition": "20",
"yPosition": "20",
"height": "10",
"width": "20",
"tabLabel": "Text 2",
"recipientId": "1"
}
],
"dateSignedTabs": [
{
"pageNumber": "1",
"documentId": "1",
"xPosition": "20",
"yPosition": "30",
"height": "10",
"width": "20",
"tabLabel": "text 3",
"recipientId": "1"
}
]
}
}
]
}
},
{
"documentId": "1",
"name": "Working",
"transformPdfFields": "true",
"documentBase64": "'.$documentHashpdf.'"
}
]}
]
}
How do I make signatures in docusign behave like radio buttons (so that the user can only initial "Accept" or "Decline" on a form, for example, but not both?) Alternatively, we'd like to add a condition so only one signature is enabled at a time (that is, the user would have the choice of where to sign made for them).
You can use a Radio button group and have conditional Signature fields on a document to accomplish your use case.
Here is a sample CreateEnvelope Call.
{
"recipients": {
"signers": [
{
"email": "SignerEmail#acme.com",
"name": "Signer One",
"recipientId": 1,
"tabs":
{
"signHereTabs": [
{
"tabLabel": "ApproveSignature",
"documentId": "1",
"pageNumber": "1",
"xPosition": "159",
"yPosition": "340",
"conditionalParentLabel": "RadioGroup_1",
"conditionalParentValue": "Approve",
"tabOrder": "0",
},
{
"tabLabel": "DeclineSignature",
"documentId": "1",
"pageNumber": "1",
"xPosition": "360",
"yPosition": "339",
"conditionalParentLabel": "RadioGroup_1",
"conditionalParentValue": "Decline",
}
],
"radioGroupTabs": [
{
"documentId": "1",
"recipientId": "1",
"groupName": "RadioGroup_1",
"radios": [
{
"pageNumber": "1",
"xPosition": "119",
"yPosition": "199",
"value": "Approve",
"selected": "false",
"required": "true",
},
{
"pageNumber": "1",
"xPosition": "356",
"yPosition": "199",
"value": "Decline",
"selected": "false",
"required": "true",
}
],
}
]
}
}
]
},
"emailSubject": "Please approve or deny my document",
"documents": [
{
"documentId": "1",
"name": "Approve or Deny",
"fileExtension" : "pdf",
"documentBase64": "[Intentionally Left out]"
}
],
"status": "sent"
}
Is there any REST API call to add a attachment tab while sending envelopes? For this I am referring to this link, but I don't know how to use this. Can you please tel me the full API call?
It's just like any other DocuSign tab, you just need to reference the name properly and set its parameters. Here's an example that would send one signature tab and one signer attachment tab:
POST v2/accounts/{accountId}/envelopes
{
"emailSubject": "Please sign this document",
"documents": [
{
"name": "test.pdf",
"documentId": "1"
}
],
"recipients": {
"signers": [
{
"tabs": {
"signHereTabs": [
{
"pageNumber": "1",
"documentId": "1",
"yPosition": "100",
"xPosition": "100",
"tabLabel": "Signature Tab",
}
],
"signerAttachmentTabs": [
{
"pageNumber": "1",
"documentId": "1",
"yPosition": "100",
"xPosition": "200",
"required": "true",
"tabLabel": "Signer Attachment Tab",
}
]
},
"routingOrder": "1",
"recipientId": "1",
"name": "Jon Dough",
"email": "jon.dough#email.com"
}
]
},
"status": "sent"
}