Explore our blog

Tabs deep dive: Custom tabs

This is the Tabs deep dive series, where I walk you through some of the countless ways that you can customize your documents with tabs using the eSignature REST API. I’ve written before about the many different types of tabs that you can include in your documents. Each of those tab types comes with numerous properties that can be used to customize your tabs. For example, the text tab has font, fontColor, and fontSize properties, among others, that can be used to change the appearance of the text in the tab. In this post I’ll be introducing you to custom tabs, which let you save your customization of a tab and reuse it as a new tab type in your account. Rather than copying the same large blocks of JSON to apply the same properties across multiple tabs, you can define a custom tab from which new tabs can inherit their properties. Let’s get into more detail about how this works.

To create a custom tab, first you’ll need to define your request body. In this example I’m creating a custom tab that can be used to collect a student ID. This request body will look similar to the JSON for a tab that you would define when creating a tab in an envelope. The JSON snippet below gives an example of a request body for a custom text tab with bold green text in the font Arial. In this example, student IDs are alphanumeric and contain 10 characters. The API reference has full details on the allowed values for font and fontColor.

{
    "type": "text",
    "tabLabel": "StudentId",
    "validationPattern": "^[a-zA-Z0-9]{10,}$",
    "validationMessage": "Please enter a valid Student Id",
    "width": "100",
    "fontColor": "Green",
    "bold": "true",
    "font": "Arial"
}

In the JSON above I defined the properties that I want my custom tab to have. Most importantly, I defined the type of my custom tab by setting the type property to text. This property is required when creating a custom tab. I set the tabLabel property to a descriptive string so that I can easily differentiate this tab from other custom tabs in my account. The rest of the properties in my request body are used to define the tab’s size and the style of the text that will appear in the tab. I also set the validationPattern property to a regular expression that will require that text input in the tab matches the correct pattern of a student ID number. The validationMessage property is set with a message that will be displayed if the user enters a student ID that does not follow the pattern. You can find a full list of allowed properties in the API reference.

After constructing the request body, the next step is to make a POST request to the CustomTabs:create endpoint. Using curl, this might look something like the snippet below, where request_data represents a temporary file containing your request body and response represents a temporary file that will store the response.

curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
     --header "Content-Type: application/json" \
     --data-binary @${request_data} \
     --request POST ${base_path}/v2.1/accounts/${ACCOUNT_ID}/tab_definitions \
     --output ${response}

After making this API call, the new custom tab will be available in your account. The response will contain a customTabId GUID that you will need to store so that you can use your new tab. You can also get the value at any time by making a call to the CustomTabs:list endpoint. When you want to use your custom tab, create a tab of the same type and set the customTabId property to your custom tab’s GUID. The JSON snippet below demonstrates how to do this when defining a text tab. 

"tabs": {
    "textTabs": [
        {
            "documentId": "1",
            "pageNumber": "1",
            "xPosition": "200",
            "yPosition": "300",
            "customTabId": "b52c75d2-xxxx-xxxx-xxxx-0e9bfb1d84e9"
        }
    ]
}

The tab definition above includes the required properties that will determine where it will be placed in a document. It’s important that the tab you create has the same type as the custom tab that you created before. This tab will have bold green text in Arial font, just as the custom tab has that I defined previously. I don’t need to use any of those properties that enforce text validation or set the tab’s color or font, because setting the customTabId property causes this tab to inherit those values from my custom tab. I can set the customTabId property across multiple tabs to apply the same properties easily across all of them. The image below shows what this tab will look like when a valid student ID is entered in it.

The custom tab viewed in a document

This example demonstrates how to create a custom text tab, but you can create custom tabs of other types as well. If you find that you are repeatedly creating tabs with the same properties, custom tabs are a great solution to save you some time and help reduce errors. Also, any custom tabs that you create through the API can be placed as well in documents using the DocuSign web UI; so they can benefit all users in your account, regardless of whether they are a developer or not. Try it out for yourself and learn how custom tabs can improve your sending experience.

Additional resources

Paige Rossi
Author
Paige Rossi
Sr. Programmer Writer
Published
Related Topics

Related Blog Posts