can i modify tabs of a template using API in docusign

Question

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'."
}

Are you simply trying to update the x/y positioning of each tag, or are there other tag properties you're trying to update as well? — Kim Brandl, Apr 14 '14 at 16:23
This is my actual scenario. I created a template through UI console. I added one document and fields are added on top of it. I downloaded the complete recipients and their fields. I had a situtation where i need to replace the document. I know i can go and replace the document in UI and again i have add the fields i have created before. But i thought i can replace the document and then through API add the tabs. That way I can save time in drag/drop the fields. As i have to change the document in 4 different templates. — linux developer, Apr 14 '14 at 16:28

Kim Brandl · Accepted Answer · 2014-04-14T17:13:01.917

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.

You are correct Kim, there is no way to currently edit the tags in the template itself via the API. +1 for this approach. — Andrew, Apr 14 '14 at 17:01

can i modify tabs of a template using API in docusign

1 Answers1