From the Trenches: Tabs and Custom Fields
It can be tough to find the documentation you're looking for if you don't know the correct verbiage. Furthermore, while reviewing Docusign's Support documentation, you may have noticed some discrepancies between terms in API-related documentation and guides related to the Web Console. While web console vocabulary has been changed over time to clarify the intended purpose of various features, API terminology has remained static in order to support existing integrations. For reference, here is an overview of various areas where data can be stored in an envelope.
Tabs:
Note that Tabs are referred to as 'Tags', 'Fields' or 'Document Custom Fields' in the web console and in Support documentation. Tab values are also referred to as 'form data'.
Description: Tabs are the only object that allows a recipient to interact with and enter data of their own. They are documented in-depth in the Developer Center.
Use case: If it's appropriate to collect data from a signer, or if there is a need to prepopulate data to be burned into the completed PDF, Tabs should be used.
Visible through web console reporting: No
Visible through the API: Yes. When using v2.1 by making an Envelopes::GetEnvelope call with the include parameter containing recipients,tabs can be used. In either v2 or v2.1, the Envelopes::ListTabs method can be used, or Envelopes::ListRecipients with include_tabs=true set.
Visible through Connect: Yes, under the Recipient to which they are assigned.
Envelope Custom Fields:
Description: Envelope Custom Fields are the most common way to store metadata about an envelope. While they aren't directly visible to a recipient during a signing session, if the show parameter is true, they will be included in the Certificate of Completion. Envelope Custom Field values can be searched in both the web console and the API to easily reference a specific envelope or set of envelopes
Example use case: Storing an Order Number so that the completed envelope can be associated with a particular record in an external CRM system
Visible through web console reporting: Yes
Visible through the API: Yes. In v2.1, the Envelopes::GetEnvelope call can add include=custom_fields to show these. In either v2 or v2.1, the Envelopes::ListCustomFields method can be used.
Visible through Connect: Yes
Document Custom Fields:
Description: Document Custom Fields are name/value pairs that can be used to store metadata about an individual file. Most commonly used when a static filename must be used in the envelope and there is a need to distinguish between files after download.
Example use case: The same file is added to an envelope multiple times, but each copy is filled out by a particular signer.
Visible through web console reporting: No, Document Custom Fields cannot be viewed through the web console in any capacity.
Visible through the API: Yes. The Envelopes::ListDocumentFields method must be called individually. There is no way to pull Document Custom Fields in bulk.
Visible through Connect: Yes, if Document Fields are enabled on the Connect configuration.
Recipient Custom Fields:
Description: Recipient Custom Fields are strings that can be assigned to individuals to store metadata, up to 100 characters.
Example use case: Multiple envelopes are sent to multiple parties. Recipient Custom Fields are used to store record IDs so each one can be associated appropriately in an external system.
Visible through web console reporting: No, Recipient Custom Fields cannot be viewed through the web console in any capacity.
Visible through the API: Yes. Envelopes::GetRecipients will return these, as well as a v2.1 Envelopes::GetEnvelope method with include=recipients set
Visible through Connect: Yes.
Additional resources
