Stick-eTabs

 

Stick-eTabs (aka tabs or tags)

Signature and Initial tabs are the most common types of tabs however DocuSign offers a wide variety of tabs for you to tag your envelopes with. Remember that tabs are always specific to recipients, so when you are tagging your documents you specify which recipient each tab is designated for. Some tabs require action from the recipient (i.e. enter data, select drop downs or checkboxes, sign or initial) while other tabs simply contain reviewable information (i.e. display a date, company name, calculated price, etc). For a full list of tab types, their corresponding names in JSON format, and their required and optional parameters review the online REST API Guide.

Adding Stick-eTabs to your Envelopes

To configure Stick-eTabs for your envelope recipients use the tabs request body property.

"tabs": {
              "signHereTabs": [
                { ... }
              ],
              "initialHereTabs": [
                { ... }
              ],
              "dateSignedTabs": [
                { ... }
              ],
                    ...
            }
            

Remember that tabs can only be added in relation to recipients as the recipients page explains, which means the tabs property will be nested under recipients in your request body.

For instance, to add a signature and an initial tab for John Doe in the sample signature request found in the Quick Start section you could use the following (JSON formatted) request body:

{
            "emailBlurb": "Email body goes here",
            "emailSubject": "Email subject goes here",
            "documents": [
                {
                    "documentId": "1",
                    "name": "test.pdf"
                }
            ],
            "recipients": {
                "signers": [
                    {
                        "email": "test@email.com",
                        "name": "John Doe",
                        "recipientId": "1",
                        "tabs": {
                            "signHereTabs": [
                                {
                                    "xPosition": "100",
                                    "yPosition": "100",
                                    "documentId": "1",
                                    "pageNumber": "1"
                                }
                            ],
                            "initialHereTabs": [
                                {
                                    "xPosition": "200",
                                    "yPosition": "100",
                                    "documentId": "1",
                                    "pageNumber": "1"
                                }
                            ]
                        }
                    }
                ]
            },
            "status": "sent"
        }

Notice how under the recipients element the first node is signers, and since John Doe is a signer his recipient information is entered as the first object in the signers array. Also notice how the tabs property is a child of the signers array, indicating that the following tabs are designated for the parent recipient, John Doe.

The above request places a signature tab for signer John Doe at a location 100 units to the right and 100 units down from the top left of page 1 of test.pdf. It also places an initial tab 100 units further to the right of that signature tab. The default X and Y units is pixels but mms, cms, or inches can be used as well. The position (0, 0) represents the top left of each document's coordinate system with X increasing to the right and Y increasing downward.

Tab Positioning

There are two ways of specifying the location of Stick-eTabs in your envelopes: absolute positioning or relative positioning. The sample JSON above uses absolute positioning because it specifies xPosition and yPosition values (default units is pixels). To use relative positioning instead you can use what's called Anchor Tagging. With anchor tagging you can specify the location of your tabs based on content or other "markers" contained within your documents.

For instance, let's say we have a document that ends with the text "Please Sign Here:". If we want to place a signature tab 1 inch to the right of the text "Please Sign Here:" wherever it is found in the document then we could use the following JSON:

"tabs": {
              "signHereTabs": [
                {
                "anchorString": "Please Sign Here:",
                "anchorXOffset": "1",
                "anchorYOffset": "0",
                "anchorIgnoreIfNotPresent": "false",
                "anchorUnits": "inches"
                }
              ]
            }

Since we set the anchorString element to the value "Please Sign Here:" a signHere tab will be placed wherever that string is found in the document. And since anchorXOffset is set to "1" and anchorUnits is set to "inches" the signature tabs will be placed 1 inch to the right of "Please Sign Here:" wherever it is found. Note that if anchorIgnoreIfNotPresent is set to false then an error will be returned if the text "Please Sign Here:" is not found in the document.

One common approach towards anchor tagging is to put unique tags or character sequences in the document that aren't normally found in the document's content, and make them invisible by setting them to the same color as the background (white in most cases). For instance, the string "\s1\" could be used to indicate where signature tabs for the first recipient should be placed, and "\i2\" could be used to indicate where initial tabs for the second recipient go, etc. And by setting their font color to the same color as the background the recipients will only see the tabs at those locations in the documents.

For more information about anchor tagging rules and exceptions please see refer to the REST API Guide.

Data Fields

Data fields, also known as form fields or text fields, have a variety of uses. Most tabs types, including data fields, can be made editable by setting their locked property to false. When your data fields are editable they can be used to gather information from your recipients. You can also dynamically populate the information contained in your data fields and make them read-only by setting locked to true, if you want your recipients to simply review and not be able to modify them.

In the API data field tabs are called textTabs and if we wanted to add two editable data fields to our document we could use the following sample JSON in our request body:

"tabs": {
            "textTabs": [
             {
                "tabLabel": "Data Field 1",
                "locked": "false",
                "xPosition": "200",
                "yPosition": "200",
                "documentId": "1",
                "pageNumber": "1"
            },
            {
                "tabLabel": "Data Field 2",
                "locked": "true",
                "xPosition": "300",
                "yPosition": "200",
                "documentId": "1",
                "pageNumber": "1"
            }]
        }

Note that if not specified the locked property defaults to false, so we could have not specified it in the example above and both fields would still have been editable. If you instead simply want to display information in your data fields and make them read-only you can use the value property. For instance, to set the first data field in our example to the value foo and the second data field to the value bar and make them read-only, we could use the following JSON:

"tabs": {
        "textTabs": [
         {
            "tabLabel": "Data Field 1",
            "value": "foo",
            "locked": "true",
            "xPosition": "200",
            "yPosition": "200",
            "documentId": "1",
            "pageNumber": "1"
        },
        {
            "tabLabel": "Data Field 2",
            "value": "bar",
            "locked": "true",
            "xPosition": "300",
            "yPosition": "200",
            "documentId": "1",
            "pageNumber": "1"
        }]
    }

Data Fields are especially useful when you want to obtain or display information that is not easily set through the other default tab types, such as Company Name, Full Name, or Date Signed for example . They can be used to gather information from your recipients or they can be used to display data for their review. For instance you could have a button trigger an API call where the only difference between each API call is the value of the data fields and possibly the recipients. That way you could automate the tailoring of your documents you commonly send out and do things like say "Dear Bob" or "Dear Sally" at the start of your document while the rest of the document is the same. Or you could populate a unique product name, display calculated fields, or have other types of custom data.

Shared Tab Labels

When adding Stick-eTabs to your envelopes if you give tabs of the same type the same tabLabel then when a recipient updates one tab it will update all the others with the same data, in real time. For instance, let's say you create an envelope with a 3 page document and with the following (partial) JSON body:

"tabs": {
    "textTabs": [
     {
        "tabLabel": "SharedDataField",
        "xPosition": "100",
        "yPosition": "100",
        "documentId": "1",
        "pageNumber": "1"
    },
    {
        "tabLabel": "SharedDataField",
        "xPosition": "100",
        "yPosition": "100",
        "documentId": "1",
        "pageNumber": "2"
    },
    {
        "tabLabel": "SharedDataField",
        "xPosition": "300",
        "yPosition": "200",
        "documentId": "1",
        "pageNumber": "3"
    }]
}

Even though we have 3 individual tabs each added to a different page on the document, all these fields will update with the same recipient data (as it's typed in by the recipient) since they all have "SharedDataField" set for their tabLabels. This will update all fields simultaneously if data is entered into any one of the fields, however if you'd like to start all 3 fields with the same initial data then you need to use wildcard matching.

Free Form Signing

If you do not add any Stick-eTabs to an envelope then it becomes what's known as a Free-Form signing experience. With free-form signing the recipients decide which tabs to place on the document(s) as well as the location of those tabs (instead of the sender controlling those aspects). When recipients open documents sent for free-form signing they can place tags in the document as needed using the Add menu at the top of the signing page. From this menu they can access the default tab types (Signature, Initial, My Name, Company, Title, Date Signed, Text, or Checkbox) and add them to the documents in the envelope.

Creating free-form signing workflows is easy- simply do not specify any tabs sections for your recipients in the request body and it will automatically become a free-form signing experience for them.

Sample Request Body

The following JSON body sends out a request to two unique recipients. Both recipients are of type signers with the first recipient having a signature tab and a couple of radio buttons configured for them (note that the first radio button is checked by default). The second recipient has an initial tab and a signature tab assigned to them. Note that there is no routingOrder element defined for either of the recipients- which means they both inherit a routingOrder of 1 and will therefore receive the request at the same time.

{
      "emailBlurb": "-- Email Body --",
      "emailSubject": "Email Subject",
      "status": "sent",
      "documents": [{
          "documentId": "1",
          "name": "test.pdf"
      }],
      "recipients": {
      "signers": [
      {
        "email": "test_1@email.com",
        "name": "Recipient Name 1",
        "recipientId": "1",
        "tabs": {
        "signHereTabs": [
          {
            "xPosition": "100",
            "yPosition": "200",
            "documentId": "1",
            "pageNumber": "1"
          }],
        "radioGroupTabs": [
          {
          "documentId": "1",
          "groupName": "RadioGroup1",
          "radios": [
          {
            "pageNumber": "1",
            "selected": "true",
            "value": "X",
            "xPosition": "300",
            "yPosition": "75"
          },
          {
            "pageNumber": "1",
            "selected": "false",
            "xPosition": "350",
            "yPosition": "75"
          }
          ]
          }]}
      },
      {
        "email": "test_2@email.com",
        "name": "Recipient Name 2",
        "recipientId": "2",
        "tabs": {
        "signHereTabs": [
          {
            "xPosition": "100",
            "yPosition": "300",
            "documentId": "1",
            "pageNumber": "1"
          }
          ],
          "initialHereTabs": [
          {
            "xPosition": "200",
            "yPosition": "300",
            "documentId": "1",
            "pageNumber": "1"
          }
          ]
        }
        }
      ]
      }
    }

For more information please refer to the online REST API Guide.