Common API Tasks🐈: Retrieve Tab Data

Inbar Gazit

Sr. Manager, Developer Content

•

Summary•4 min read

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

Table of contents

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

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#

Java

Node.js

PHP

Python

Ruby

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