Related
I want to update all the tabs for a document at once. The document's envelope was created from a template which already has the recipients and tabs defined, and I am calling this endpoint with the following payload to update the tabs:
{
"textTabs": [
{
"validationPattern": "",
"validationMessage": "",
"shared": "false",
"requireInitialOnSharedChange": "false",
"requireAll": "false",
"value": "Some value",
"originalValue": "Original value",
"required": "false",
"locked": "true",
"concealValueOnDocument": "false",
"disableAutoSize": "false",
"maxLength": "4000",
"tabLabel": "Address",
"font": "lucidaconsole",
"fontColor": "black",
"fontSize": "size12",
"localePolicy": {},
"documentId": "1",
"recipientId": "18870af6-8c21-4e4c-934c-ac329b6f7374",
"pageNumber": "1",
"xPosition": "52",
"yPosition": "94",
"width": "132",
"height": "18",
"tabId": "032f2d80-7a93-4a7c-b969-aea2249fbd04",
"templateRequired": "false",
"tabType": "text"
}
]
}
I get the following error in response:
{
"errorCode": "INVALID_TAB_OPERATION",
"message": "The Tab specified is not valid for the requested operation. Updated tabs must all be Strikethrough or SmartSection tabs if you're not specifying a valid recipient."
}
recipientId is set to the value I received from this endpoint, but I've also tried setting it to "1" which is the recipientId I pass when creating the template.
What is the correct way to call this endpoint?
Yulian, It appears there's a bug in the UpdateDocumentTabs endpoint that is causing this issue and we're looking into it and hope to have an update soon.
As a workaround, you can use the UpdateRecipientTabs endpoint for now. I realize this would mean making additional API calls for the same purpose. If you need your API hourly quota increased - you can contact me and I can help with that.
Hi I am using Docusign rest api. I have a scenario where I have three fields that needs to be filled by the same person(2 text and 1 signature all of them optional). Is there a way to make them such that if one of the text field is filled the signature must be required?
I am trying to use "conditionalParentLabel" and "conditionalParentValue" to achieve this fuctionality but I am not sure what value to give for "conditionalParentvalue" so that the required will get activated for all text input except blank.
Here is a sample CreateEnvelope call that could work for you.
POST /v2/accounts/{accountId}/envelopes
{
"recipients": {
"signers": [
{
"email": "janedoe#yourdomain.com",
"name": "Jane Doe",
"recipientId": 1,
"tabs": {
"signHereTabs": [
{
"optional": "false",
"documentId": "1",
"pageNumber": "1",
"xPosition": "279",
"yPosition": "89",
"conditionalParentLabel": "Amount",
"conditionalParentValue": "##ANY##"
}
],
"textTabs": [
{
"height": 11,
"width": 78,
"required": "false",
"locked": "false",
"maxLength": 100,
"tabLabel": "Amount",
"documentId": "1",
"pageNumber": "1",
"xPosition": "117",
"yPosition": "119"
}
]
}
}
]
},
"emailSubject": "Requesting signature with conditional fields",
"documents": [
{
"documentId": "1",
"name": "Doc One",
"fileExtension": "txt",
"documentBase64": "RG9jIFRXTyBUV08gVFdP"
}
],
"status": "sent"
}
Wondering what I am missing or doing wrong here as the value for the tabs are not being set when creating the envelope.
In the JSON code below I am trying to default values for the text tabs for recipient 5.
{
"emailSubject":"Allowance Agreement - AK Anne Klein Footwear - ytd .doc",
"emailBlurb":"DEV - Please complete the Vendor Allowance Agreement required for your Supplier setup with Zappos.com or 6pm.com. \n\n Please reach out to your Vendor Support team member or vendorsupport#zappos.com with any questions.",
"status":"sent",
"compositeTemplates":[
{
"compositeTemplateId": "1",
"inlineTemplates":[
{
"sequence":"1",
"documents": [
{
"documentId": "1",
"name": "Allowance Agreement - AK Anne Klein Footwear - ytd .doc.doc"
}
],
"customFields": {
"textCustomFields": [
{
"name": "Node ID",
"required": "true",
"show": "true",
"value": "658824"
}
]
},
"recipients":{
"signers":[
{
"email":"email#email.com",
"name":"v",
"recipientId":1,
"roleName":"Vendor"
},
{
"email":"email#email.com",
"name":"test",
"recipientId":2,
"roleName":"Vendor Support"
},
{
"email":"email#email.com",
"name":"ap",
"recipientId":3,
"roleName":"AP"
},
{
"email":"email#email.com",
"name":"f",
"recipientId":4,
"roleName":"Finance"
},
{
"email":"email#email.com",
"name":"ap",
"recipientId":5,
"roleName":"AP2",
"tabs":{
"textTabs":[
{
"tabLabel":"txtVendorId",
"value":"100023"
},
{
"tabLabel":"txtSupplierName",
"value":"AK Anne Klein Footwear"
},
{
"tabLabel":"txtSupplierId",
"value":"253"
}
]
}}
]
}
}
],
"serverTemplates":[
{
"sequence":"2",
"templateId":"A3B4F6BB-639A-486F-8C84-826295142F21"
}
]
}
]
}
When I look at the envelope tabs here is what I get for the 5th recipient:
"textTabs": [
{
"height": 22,
"isPaymentAmount": "false",
"validationPattern": "",
"shared": "false",
"requireInitialOnSharedChange": "false",
"requireAll": "false",
"name": "Text",
"value": "",
"width": 300,
"required": "true",
"locked": "false",
"concealValueOnDocument": "false",
"disableAutoSize": "false",
"tabLabel": "txtVendorId",
"font": "lucidaconsole",
"fontColor": "black",
"fontSize": "size9",
"documentId": "1",
"recipientId": "5",
"pageNumber": "2",
"xPosition": "217",
"yPosition": "651",
"tabId": "2179efb5-9f59-4bb7-895e-da868fba9919"
},
{
"height": 22,
"isPaymentAmount": "false",
"validationPattern": "",
"shared": "false",
"requireInitialOnSharedChange": "false",
"requireAll": "false",
"name": "Text",
"value": "",
"width": 342,
"required": "true",
"locked": "false",
"concealValueOnDocument": "false",
"disableAutoSize": "false",
"tabLabel": "txtSupplierName",
"font": "lucidaconsole",
"fontColor": "black",
"fontSize": "size9",
"documentId": "1",
"recipientId": "5",
"pageNumber": "2",
"xPosition": "172",
"yPosition": "670",
"tabId": "2c6e59b1-6a4f-4f5f-a873-33398c78e408"
},
{
"height": 22,
"isPaymentAmount": "false",
"validationPattern": "",
"shared": "false",
"requireInitialOnSharedChange": "false",
"requireAll": "false",
"name": "Text",
"value": "",
"width": 354,
"required": "true",
"locked": "false",
"concealValueOnDocument": "false",
"disableAutoSize": "false",
"tabLabel": "txtSupplierId",
"font": "lucidaconsole",
"fontColor": "black",
"fontSize": "size9",
"documentId": "1",
"recipientId": "5",
"pageNumber": "2",
"xPosition": "172",
"yPosition": "690",
"tabId": "614eb20b-5536-45db-b64a-84a475cdc44d"
}
]
* EDIT *
adding final part of envelopes tabs and screen captures of recipients and one tab...
},
"isBulkRecipient": "false",
"name": "ap",
"email": "email#email.com",
"recipientId": "5",
"recipientIdGuid": "77e255d8-a6d6-47a8-98ee-0f3829631d76",
"requireIdLookup": "false",
"userId": "8d7f443b-7adf-4cfa-8368-296aee88e959",
"routingOrder": "5",
"roleName": "AP2",
"status": "created",
"totalTabCount": "5"
}
* Workaround *
Since I was not able to set the tab values at creation time I tried the following:
Tried to create a PUT request to update the tabs using the uri for the tab for the recipient /envelopeid/recipients/5/tabs and passing the JSON for the text tabs as.
{
"textTabs":[
{
"tabLabel": "txtVendorId",
"value":"123"
}
]
}
Passing the JSON above I would get a response that the tab was not found on the envelope
{
"requireAll": "false",
"concealValueOnDocument": "false",
"disableAutoSize": "false",
"recipientId": "5",
"tabId": "00000000-0000-0000-0000-000000000000",
"errorDetails": {
"errorCode": "INVALID_TAB_OPERATION",
"message": "The Tab specified is not valid for the requested operation. The Tab specified is not valid for the requested operation. Tab not found in envelope."
}
My second step was to actually get the tabId value from the created envelope instead of using the tab lable (something that I would not have before creating the envelope).
By calling /envelopeid/recipients/5/tabs with the tabId in the JSON instead like
{
"textTabs":[
{
"tabId": "57135910-fe34-417d-a4e3-fc7d6c4a42ed",
"value":"123"
}
]
}
Then the field value got updated correctly.
In conclusion, for my workaround will need three calls to DocuSign to be able to set the default values for this recipient:
Create Envelope
Get Recipient tabs (to get value of tab ids)
Update tab values using tab ids.
Are you positive you are correctly matching your recipients to valid roles you've configured on the Template?
For instance, I see that for recipient #5 you are assigning them to the "AP2" role, does that exact role exist in your template when you login to the website and view the template?
I'm sorry for the very long delay on an answer, your JSON needs one small tweek.
You need to change your sequence of your serverTemplates to 1, assigning the values to the same template.
"serverTemplates":[
{
"sequence":"1",
}
This will remove the need for the GET/PUT (although you can still do the GET to verify information if you'd like)
We are having some issue replacement documents using the docusign REST API.
The steps that we follow are, delete the documents, added the documents and adding al the tabs of the recipient for that document.
The follow ing is an example of the code that we use:
-- DELETE
https://demo.docusign.net/restapi/v2/accounts/xx/envelopes/11111222223333344444/documents
DELETE
X-DocuSign-Authentication : {"Username": "XXXXXX","Password": "YYYYY","IntegratorKey": "ZZZZZZZZZ"}
{
"documents": [
{
"documentId": "1"
},
{
"documentId": "2"
}
]
}
--ADD DOCUMENT
https://demo.docusign.net/restapi/v2/accounts/xx/envelopes/11111222223333344444/documents
PUT
X-DocuSign-Authentication : {"Username": "XXXXXX","Password": "YYYYY","IntegratorKey": "ZZZZZZZZZ"}
Content-Type ** multipart/form-data; charset=UTF-8; boundary=111222333444
Accept ** application/json
--111222333444
Content-Type: application/json; charset=UTF-8
Content-Disposition : form-data
{
"documents": [
{
"name": "446_BBB.pdf",
"documentId": "1",
"order": "1",
"documentFields": [
{
"name": "doctype",
"value": "cont"
}
]
},
{
"name": "747_BBB.pdf",
"documentId": "2",
"order": "2",
"documentFields": [
{
"name": "doctype",
"value": "cont"
}
]
}
]
}
--- doc bytes deletes
-- ADD TABS
https://demo.docusign.net/restapi/v2/accounts/xx/envelopes/11111222223333344444/recipients/1/tabs
POST
X-DocuSign-Authentication : {"Username": "XXXXXX","Password": "YYYYY","IntegratorKey": "ZZZZZZZZZ"}
{
"signHereTabs": [
{
"anchorString": "<SIGNATURE_1/>",
"anchorXOffset": "0",
"anchorYOffset": "7",
"documentId": "1",
"pageNumber": "1"
}
],
"textTabs": [
{
"documentId": "2",
"pageNumber": "1",
"xPosition": "109",
"yPosition": "656",
"tabLabel": "Name of depository",
"disableAutoSize": "true",
"name": "Name of depository",
"required": "true",
"width": "195",
"maxLength": "33"
}
],
"numberTabs": [
{
"documentId": "2",
"pageNumber": "1",
"xPosition": "420",
"yPosition": "681",
"tabLabel": "CC Account number",
"disableAutoSize": "true",
"name": "CC Account number",
"required": "true",
"width": "138",
"maxLength": "16"
}
],
"zipTabs": [
{
"documentId": "2",
"pageNumber": "1",
"xPosition": "197",
"yPosition": "690",
"tabLabel": "Depository zipcode",
"disableAutoSize": "true",
"name": "Depository zipcode",
"required": "true",
"width": "95",
"maxLength": "5"
}
]
}
The problem that we have are the following:
The documents doesn't keep the order specified
for the tabs, the process crreate 2 tabs of each type for the same recipient.
I really appreciate any help with this.
Thank you,
The documents doesn't keep the order specified
Make sure to reorder each of the existing documents as well. For example:
{
"documents": [
{
"name": "446_BBB.pdf",
"documentId": "1",
"order": "1",
"documentFields": [
{
"name": "doctype",
"value": "cont"
}
]
},
{
"name": "747_BBB.pdf",
"documentId": "2",
"order": "2",
"documentFields": [
{
"name": "doctype",
"value": "cont"
}
]
},
{
"documentId": "3",
"order": "3"
}
]
}
for the tabs, the process crreate 2 tabs of each type for the same recipient.
Seems like a bug (will let you know otherwise or when fixed). To workaround this issue you can split the last API request into two separate requests, one that contains the signHereTabs only, and another for all the other tabs.
Reading the API documentation i understood that I can edit the tabs of recipients for an envelope which is created/sent
However i am trying to undertsand can i also modify tabs for a template?
When i used the same request, as the one below i am getting error
Any reference would be appreciable.
The reason for my question is, everytime when i update the feed document for some corrections i have to redo creating the fields over it. Rather if i can send the fields through API that would save me a lot of time
Thank you
Sample JSON while updating the TABS (trying to add Tabs)
{
"signers": [
{
"tabs": {
"fullNameTabs": [
{
"name": "Full Name",
"tabLabel": "Full Name",
"bold": "false",
"italic": "false",
"underline": "false",
"documentId": "1",
"recipientId": "5b46b9dc-d40d-493d-b319-5757bf1d5cb4",
"pageNumber": "1",
"xPosition": "321",
"yPosition": "676",
"tabId": "82be754a-47c6-47fc-9793-6fdec6758060"
}
],
"dateSignedTabs": [
{
"name": "Date Signed",
"value": "",
"tabLabel": "Date Signed",
"bold": "false",
"italic": "false",
"underline": "false",
"documentId": "1",
"recipientId": "5b46b9dc-d40d-493d-b319-5757bf1d5cb4",
"pageNumber": "1",
"xPosition": "504",
"yPosition": "676",
"tabId": "1e3f16e8-77a9-4726-9876-66e6d377a0c1"
}
]
},
"signInEachLocation": "false",
"name": "",
"email": "",
"recipientId": "5b46b9dc-d40d-493d-b319-5757bf1d5cb4",
"recipientIdGuid": "5b46b9dc-d40d-493d-b319-5757bf1d5cb4",
"requireIdLookup": "false",
"routingOrder": "1",
"roleName": "ONE",
"status": "created",
"templateLocked": "false",
"templateRequired": "false",
"emailNotification": {
"emailSubject": "Subject",
"emailBody": "Body",
"supportedLanguage": "en"
}
},
{
"tabs": {
"signHereTabs": [
{
"name": "Sign Here",
"tabLabel": "Signature 3",
"scaleValue": 0.9,
"optional": "false",
"documentId": "1",
"recipientId": "d4f63c18-8ccc-4ed3-bacb-660bebf829bf",
"pageNumber": "1",
"xPosition": "106",
"yPosition": "591",
"tabId": "9b20f825-f37c-4dc6-aa57-d29b3d531d6b"
}
],
"fullNameTabs": [
{
"name": "Full Name",
"tabLabel": "Full Name",
"bold": "false",
"italic": "false",
"underline": "false",
"documentId": "1",
"recipientId": "d4f63c18-8ccc-4ed3-bacb-660bebf829bf",
"pageNumber": "1",
"xPosition": "319",
"yPosition": "622",
"tabId": "79c35daf-cada-4a57-ac82-8a2a149839e8"
}
],
"dateSignedTabs": [
{
"name": "Date Signed",
"value": "",
"tabLabel": "Date Signed",
"bold": "false",
"italic": "false",
"underline": "false",
"documentId": "1",
"recipientId": "d4f63c18-8ccc-4ed3-bacb-660bebf829bf",
"pageNumber": "1",
"xPosition": "504",
"yPosition": "622",
"tabId": "14d47f01-a911-49b9-bf04-1c4cadb2924a"
}
]
},
"signInEachLocation": "false",
"name": "",
"email": "",
"recipientId": "d4f63c18-8ccc-4ed3-bacb-660bebf829bf",
"recipientIdGuid": "d4f63c18-8ccc-4ed3-bacb-660bebf829bf",
"requireIdLookup": "false",
"routingOrder": "2",
"roleName": "TWO",
"status": "created",
"templateLocked": "false",
"templateRequired": "false",
"emailNotification": {
"emailSubject": "Subject",
"emailBody": "Body",
"supportedLanguage": "en"
}
},
{
"tabs": {
"approveTabs": [
{
"buttonText": "Approve",
"width": 60,
"height": 18,
"tabLabel": "Approve 9",
"font": "lucidaconsole",
"bold": "false",
"italic": "false",
"underline": "false",
"fontSize": "size9",
"documentId": "1",
"recipientId": "95f1d73e-df27-4f19-86ea-c921f0321d26",
"pageNumber": "1",
"xPosition": "228",
"yPosition": "718",
"tabId": "5083943e-bdf0-42fe-87ff-d92778b13be7"
}
],
"declineTabs": [
{
"buttonText": "Decline",
"width": 60,
"height": 18,
"declineReason": "",
"tabLabel": "Decline 10",
"font": "lucidaconsole",
"bold": "false",
"italic": "false",
"underline": "false",
"fontSize": "size9",
"documentId": "1",
"recipientId": "95f1d73e-df27-4f19-86ea-c921f0321d26",
"pageNumber": "1",
"xPosition": "350",
"yPosition": "718",
"tabId": "b1c1ad78-e3b9-4630-b411-09127997f7dd"
}
]
},
"signInEachLocation": "false",
"name": "",
"email": "",
"recipientId": "95f1d73e-df27-4f19-86ea-c921f0321d26",
"recipientIdGuid": "95f1d73e-df27-4f19-86ea-c921f0321d26",
"requireIdLookup": "false",
"routingOrder": "3",
"roleName": "THREE",
"status": "created",
"templateLocked": "false",
"templateRequired": "false",
"emailNotification": {
"emailSubject": "Subject",
"emailBody": "Body",
"supportedLanguage": "en"
}
}
],
"agents": [],
"editors": [],
"intermediaries": [
{
"name": "",
"email": "",
"recipientId": "fa2bffdb-81d7-4de4-a964-e543e2d1d3cf",
"recipientIdGuid": "fa2bffdb-81d7-4de4-a964-e543e2d1d3cf",
"requireIdLookup": "false",
"routingOrder": "3",
"roleName": "FOUR",
"status": "created",
"templateLocked": "false",
"templateRequired": "false",
"emailNotification": {
"emailSubject": "Subject",
"emailBody": "Body",
"supportedLanguage": "en"
}
}
],
"carbonCopies": [],
"certifiedDeliveries": [],
"inPersonSigners": [],
"recipientCount": "5"
}
URL (tried both POST/PUT)
https://DOMAIN/restapi/v2/accounts/ACCTID/envelopes/ENVELOPID/recipients
RESPONSE
{
"errorCode": "ENVELOPE_CANNOT_CORRECT_INVALID_STATE",
"message": "This account may not have 'correct' permission, or the envelope state is not 'sent' or 'delivered'."
}
I don't believe it's possible to modify the tabs in the Template itself, using the API. The "Modify or Correct Recipient Information" operation you're trying to use allows you to "modify recipients in a draft envelope or correct recipient information for an in process envelope." (from p156 of the REST API guide: https://08d1d92f490618f41c65-8fb00e97ac499a7066a18ce9c66b019b.ssl.cf2.rackcdn.com/REST_API_Guide_v2.pdf). Since a Template is neither a draft envelope nor an in-process envelope, I wouldn't expect this operation to work for modifying tags within a Template.
If you wanted to use a template to specify the document(s), and then specify fields via the "Create Envelope" API call each time you send the envelope, you could achieve this by using a technique like I describe below. (The same technique could also be applied if you're using "Composite Templates" in your Create Envelope API call.)
For example, let's say that I've created a template via the DocuSign UI that has a single recipient (Signer1) and no tags within the document(s). I could then use the following request to create an Envelope that has the document(s) and recipient(s) that the template defines, with the tag(s) that my API request specifies (in this example, just a single Text Tab):
POST https://{{env}}.docusign.net/restapi/{{version}}/accounts/{{acctId}}/envelopes
{
"emailSubject": "Please sign this",
"emailBlurb": "Please sign...thanks!",
"templateId": "TEMPLATE_ID",
"templateRoles": [
{
"roleName": "Signer1",
"name": "John Doe",
"email": "johnsemail#outlook.com",
"recipientId": "1",
"tabs":{
"textTabs":[
{
"documentId": "1",
"pageNumber": "1",
"recipientId": "1",
"xPosition": "100",
"yPosition": "400",
"tabLabel":"Address",
"name":"Address",
"value":"123 Main Street",
"locked": "false"
},
],
}
}
],
"status": "sent"
}
The example above uses templateRoles in the "Create Envelope" request. If you're instead using Composite Templates in your "Create Envelope" request, the request body would look like this:
POST https://{{env}}.docusign.net/restapi/{{version}}/accounts/{{acctId}}/envelopes
{
"emailSubject": "Please sign",
"emailBlurb": "Please sign...thanks!",
"status": "sent",
"compositeTemplates": [{
"serverTemplates": [{
"sequence": 1,
"templateId": "TEMPLATE_ID"
}],
"inlineTemplates": [{
"sequence": 2,
"recipients": {
"signers": [{
"email": "sallysemail#outlook.com",
"name": "Sally Adamson",
"recipientId": "1",
"roleName": "Signer1",
"tabs":{
"textTabs":[
{
"documentId": "1",
"pageNumber": "1",
"recipientId": "1",
"xPosition": "100",
"yPosition": "400",
"tabLabel":"Address",
"name":"Address",
"value":"123 Main Street",
"locked": "false"
},
],
}
}]
}
}]
}]
}
If you're going to implement this approach, I'd suggest that you consider using the "anchor text" technique of specify tag placement, rather than specifying x-y coordinates for each and every tag. Using "anchor text" placement technique means that you specify placement of each tag relative to some existing text within your document(s), such that the tag location will always be correct, even if the format of your document changes slightly -- as long as the anchor text string still exists in the doc and can therefore be used to place the tag. See pages 324-325 of the REST API guide for more info on using anchor text to specify tag placement.