Blog
Home/

Common API Tasks🐈: Retrieve Tab Data

Author Inbar Gazit
Inbar GazitSr. Manager, Developer Content
•
Summary•5 min read

Learn how to use the eSignature REST API to extract information from envelope tabs

    • Background
    • Types of data collected
    • OK, so now what?
    • Show me some code!
    • Additional Resources

    Table of contents

    Common API Tasks

    Last month, I started writing a new series of blog posts to help you all with popular and useful tasks you may want to complete using our APIs. In our inaugural post, I showed you how to set the email subject and content individually for each recipient in your envelope using the Docusign eSignature API. In the second installment of this series, I’m going to show you how to retrieve envelope data—specifically, information stored in tabs. Happy coding!

    Background

    Docusign’s strength is not just allowing users to sign documents. Docusign can automate your entire business process. To that end, you need to have information flow from system to system, and this is where tab data gets into play.

    Envelopes in the Docusign system are routed to recipients. Each recipient has to act on a set of tabs. These tabs may allow the sender to request information be provided by the recipient. Processing this information programatically is a vital part of any system that collects and manipulates data from customers.

    Types of data collected

    The short answer to this question is, you can use Docusign to collect any data you want from your customers. If you can imagine it, Docusign can provide the tools to get this information from the envelope and into your backend systems.

    Let’s review some of the common tabs and what you may want to use them for:

    Text tabs

    The most common and easy tabs to explain is are text tabs. They allow the user to enter any information, and that information is then stored in the envelope. They are also visible as part of the document, of course.

    Number tabs

    Number tabs are a special case for text tabs. These hold numeric data only. You can even have rules about which numbers are valid and which are not. These are also extremely useful for business applications.

    Calculated fields

    These special tabs use a formula to calculate their value based on other information and tabs in the envelope. Recipients of the envelope cannot modify them directly, but they can see their value if the underlying information needed for the calculation is already in the envelope.

    Date tab

    Date tabs hold the date that the recipient completed the envelope. You can retrieve this information if needed for further processing.

    List tabs

    List tabs enable the sender to define a set of options for the signer to choose from. Each option has a description text that shows in the drop-down control in the visible part of the envelope as well as a value that can be obtained by the API for further processing.

    Custom tabs

    Custom tabs enable you to modify one of the existing predefined tabs and use it repeatedly without the need to define it again and again. Think of them as “tab templates”.  A common way to create custom tabs is by using a list tab. If you have a specific type of information that repeats frequently, in many envelopes, you can create the list tab once and save it as a custom tab to be used later.

    OK, so now what?

    By now you have an envelope that you are using as part of your business process. You have one or more recipients to whom you send this envelope, and there are one or more tabs for them to complete. Once these envelopes are complete, how do you get all the information back so you can use it for further processing?

    First, you need to know that your envelope is complete. You can use Connect for that. See these resources for more information about Docusign Connect webhook technology.

    Second, you need to know which envelope, which document, and which page in the document you are looking for. This is necessary because our GetTabs API requires all this information in order to return all the tab data back to the caller.

    Let’s look at a real-world example. Our envelope is a registration form for a wrestling tournament. Anyone who wants to sign up can click this PowerForm link and fill out the form. In the process they have to provide a bit of information in order to sign up for the event. I’m asking for their name, date of birth, weight (in pounds) and t-shirt size so we can give them our complimentary “I wrestled in the Docusign wrestling championship” shirt. They also need to sign the form, and voila: they’re registered! (I skipped over the portion where they have to pay using our Docusign Payment feature; that will be covered in a later blog post.)

    Show me some code!

    OK, enough talking, you guys want to see how to do this with the Docusign eSignature APIs. Here are code snippets for the various languages:

    C#

    // Set up our envelopes API with the appropriate token
    var config = new Configuration(new ApiClient(basePath));
    config.AddDefaultHeader("Authorization", "Bearer " + accessToken);
    EnvelopesApi envelopesApi = new EnvelopesApi(config);
    // Get all the tabs for page 1 of the first document in the envelope
    Tabs tabs = envelopesApi.GetPageTabs(accountId, envelopeId, "1", "1");
    // In our simple example, we only have a single number tab.
    // Get its value and parse it into an integer for the weight in pounds
    int lbs = int.Parse(tabs.NumberTabs[0].Value);
    // Again, we have a single list tab in this envelope, get the value
    string shirt = tabs.ListTabs[0].Value;
    // Parse out the date of birth from the text tab
    DateTime dob = DateTime.Parse(tabs.TextTabs[0].Value);
    

    Java

    // Set up our envelopes API with the appropriate token
    ApiClient apiClient = new ApiClient(basePath);
    apiClient.addDefaultHeader("Authorization", "Bearer " + accessToken);
    EnvelopesApi envelopesApi = new EnvelopesApi(apiClient);
    // Get all the tabs for page 1 of the first document in the envelope
    Tabs tabs = envelopesApi.getPageTabs(accountId, envelopeId, "1", "1");
    // In our simple example, we only have a single number tab.
    // Get its value and parse it into an integer for the weight in pounds
    int lbs = Integer.parseInt(tabs.numberTabs.get(0).value);
    // Again, we have a single list tab in this envelope, get the value
    String shirt = tabs.listTabs.get(0).value;
    // Parse out the date of birth from the text tab
    Date dob = new SimpleDateFormat("dd/MM/yyyy").parse(tabs.textTabs.get(0).value);
    

    Node.js

    // Set up our envelopes API with the appropriate token
    let dsApiClient = new docusign.ApiClient();
    dsApiClient.setBasePath(basePath);
    dsApiClient.addDefaultHeader('Authorization', 'Bearer ' + accessToken);
    let envelopesApi = new docusign.EnvelopesApi(dsApiClient)
    // Get all the tabs for page 1 of the first document in the envelope
    var tabs = await envelopesApi.getPageTabs(accountId, envelopeId, '1', '1', null);
    // In our simple example, we only have a single number tab.
    // Get its value and parse it into an integer for the weight in pounds
    var lbs = parseInt(tabs.numberTabs[0].value, 10);
    // Again, we have a single list tab in this envelope, get the value
    var shirt = tabs.listTabs[0].value;
    // Parse out the date of birth from the text tab (method stringToDate converts strings to Date objects)
    var dob = stringToDate(tabs.textTabs[0].value);
    

    PHP

    # Set up our envelopes API with the appropriate token
    $config = new \Docusign\eSign\Configuration();
    $config->setHost($args['base_path']);
    $config->addDefaultHeader('Authorization', 'Bearer ' . $args['ds_access_token']);
    $api_client = new \Docusign\eSign\Client\ApiClient($config);
    $envelope_api = new \Docusign\eSign\Api\EnvelopesApi($api_client);
    # Get all the tabs for page 1 of the first document in the envelope
    $tabs = envelopesApi->getPageTabs(accountId, envelopeId, '1', '1');
    # In our simple example, we only have a single number tab.
    # Get its value and cast it into an integer for the weight in pounds
    $lbs = (int)tabs->numberTabs[0]->value;
    # Again, we have a single list tab in this envelope, get the value
    $shirt = tabs->listTabs[0]->value;
    # Parse out the date of birth from the text tab (method strtotime converts strings to DateTime objects)
    $dob = strtotime(tabs->textTabs[0]->value);
    

    Python

    # Set up our envelopes API with the appropriate token
    api_client = ApiClient()
    api_client.host = base_path
    api_client.set_default_header('Authorization', 'Bearer ' + args['ds_access_token'])
    envelope_api = EnvelopesApi(api_client)
    # Get all the tabs for page 1 of the first document in the envelope
    tabs = envelope_api.get_page_tabs(accountId, envelopeId, '1', '1')
    # In our simple example, we only have a single number tab.
    # Get its value and parse it into an integer for the weight in pounds
    lbs = int(tabs.number_tabs[0].value)
    # Again, we have a single list tab in this envelope, get the value
    shirt = tabs.list_tabs[0].value
    # Parse out the date of birth from the text tab (method strptime converts strings to DateTime objects)
    dob = datetime.strptime(tabs.text_tabs[0].value, '%m/%d/%Y')
    

    Ruby

    # Set up our envelopes API with the appropriate token
    configuration = DocuSign_eSign::Configuration.new
    configuration.host = args['base_path']
    api_client = DocuSign_eSign::ApiClient.new configuration
    api_client.default_headers["Authorization"] = "Bearer #{args['access_token']}"
    envelopesApi = DocuSign_eSign::EnvelopesApi.new api_client
    # Get all the tabs for page 1 of the first document in the envelope
    tabs = envelopeApi.get_page_tabs( (accountId, envelopeId, '1', '1')
    # In our simple example, we only have a single number tab.
    # Get its value and parse it into an integer for the weight in pounds
    lbs = tabs.number_tabs[0].value.to_i
    # Again, we have a single list tab in this envelope, get the value
    shirt = tabs.list_tabs[0].value
    # Parse out the date of birth from the text tab
    dob = Date.parse(tabs.text_tabs[0].value)
    

    Note that if you have many tabs in your document, you may need to find the relevant tab by searching for it using the TabId or TabLabel fields by iterating through the tabs in the list and comparing this field to the value you need.

    OK, that’s it folks. I hope you found this useful! I would love to get your feedback about this blog post. Feel free to email me at inbar.gazit@docusign.com with any questions.

    In the next blog post in this series, I’ll show how you can use the eSignature API add Connect web-hooks for your app. Stay tuned...

    Additional Resources

    Author Inbar Gazit
    Inbar GazitSr. Manager, Developer Content

    Inbar Gazit has been with Docusign since 2013 in various engineering roles. Since 2019 he has focused on developer content. Inbar works on code examples including the launchers, available on GitHub in eight languages, and helps build sample apps showcasing the various Docusign APIs. He is also active on StackOverflow, answering your questions. Inbar can be reached at inbar.gazit@docusign.com.

    More posts from this author

    Related posts

    • Accelerating Intelligent Agreement Management with a New “Docusign for Developers”
      Intelligent Agreement Management

      Accelerating Intelligent Agreement Management with a New “Docusign for Developers”

      Dmitri Krakovsky
    • Event Notifications using JSON SIM and HMAC

      Event Notifications using JSON SIM and HMAC

      Author Jonathan Sammons
      Jonathan Sammons
    • Streamline End-to-End Agreement Management with Docusign: A Developer Overview

      Streamline End-to-End Agreement Management with Docusign: A Developer Overview

      Author Larry Jin
      Larry Jin
    Event Notifications using JSON SIM and HMAC

    Event Notifications using JSON SIM and HMAC

    Author Jonathan Sammons
    Jonathan Sammons
    Streamline End-to-End Agreement Management with Docusign: A Developer Overview

    Streamline End-to-End Agreement Management with Docusign: A Developer Overview

    Author Larry Jin
    Larry Jin

    Discover what's new with Docusign IAM or start with eSignature for free

    Explore Docusign IAMTry eSignature for Free
    Person smiling while presenting