Common API Tasksđ: Retrieve Tab Data
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
Â
