Tabs deep dive: Collaborative tabs

Welcome back to the Tabs deep dive series, where I’m giving you all the information you need to customize your documents with tabs using the eSignature REST API. In my last post I discussed custom tabs. In this post I’ll be teaching you all about collaborative tabs.

Most of the time, when you’re adding tabs to an envelope, you choose to assign them to a single recipient. But sometimes you may want multiple recipients to be able to edit the same tab. Collaborative tabs solve this problem by enabling recipients to collaborate on a tab’s value. This means that recipients can make changes to the tab after other recipients have entered information in that tab. The contents of a collaborative tab can be input and edited by multiple recipients, regardless of which recipient the tab is assigned to. All of the changes and approvals are managed and tracked by DocuSign. 

To create a collaborative tab with the eSignature REST API, start by creating a tab and assigning it to a recipient as you normally would. It doesn’t matter which recipient you choose; you can assign the tab to any recipient who will be collaborating on the tab. Only the following tab types can be collaborative: text, radio button, drop-down, and checkbox. Once you have created your tab with all of the desired properties, add the shared property to the tab and set its value to true. This indicates that your tab will be shared across all recipients. The requireAll property can also be set to true to require that information is entered in the collaborative tab for the envelope to be completed. The JSON snippet below demonstrates what this should look like in your request body.

"textTabs": [
    {
        "documentId": "1",
        "pageNumber": "1",
        "xPosition": "200",
        "yPosition": "300",
        "width": "200",
        "shared": "true",
        "requireAll": "true"
    }
]

If you don’t want all of the recipients to collaborate on a tab, you can specify which recipients can edit the tab with the shareToRecipients property. The JSON snippet below shows an example of a text tab that is shared between two of an envelope’s recipients.

"textTabs": [
    {
        "documentId": "1",
        "pageNumber": "1",
        "xPosition": "200",
        "yPosition": "300",
        "width": "200",
        "shared": "false",
        "shareToRecipients": "1,3",
        "requireAll": "true"
    }
]

In the above snippet the shareToRecipients property has a value of 1,3. This means that the tab should be shared between the recipients with the recipient IDs 1 and 3. Any other recipients of the envelope will not be able to edit the text tab. The shared property is set to false because when shared is set to true, it overrides the shareToRecipients property. Setting shared to true causes the tab to be shared across all recipients, regardless of the value of shareToRecipients.

With the shared and shareToRecipients properties, you can enable multiple recipients (or all of an envelope’s recipients) to collaborate on a tab’s contents. But how will recipients know that a change has been made after they’ve signed the document? You can use the requireInitialOnSharedChange property to ensure that all recipients are aware of any changes made to collaborative tabs. When a recipient who appears later in the routing order makes a change to a collaborative tab and requireInitialOnSharedChange is set to true, the envelope will be routed back to any recipients who have already signed the document. Those prior recipients will need to complete an initialHere tab to approve the change. The image below shows the initialHere tab that will be automatically added to the right margin of the document when a change is made to the tab. The envelope will only be complete once all recipients have approved the change. On the other hand, if requireInitialOnSharedChange is set to false, any recipient can make changes to the tab and the last change is preserved as the final value of the tab. The envelope will be complete after the last recipient in the routing order has completed it.

With collaborative tabs, the information in an envelope doesn’t have to be defined by a single recipient. Instead, tabs can be shared across multiple recipients, ensuring that all relevant stakeholders have a say in the tab’s value. This is just one of the ways that you can use tabs to create envelopes that meet your needs. Check out the list of resources below to see my previous blog posts on the many other ways that you can use tabs to customize your envelopes.

Additional resources

• Tabs deep dive: custom tabs
• Tabs deep dive: conditional tabs
• Tabs deep dive: anatomy of a tab
• Tabs deep dive: checkboxes and radio groups
• Tabs deep dive: placing tabs in documents
• Tabs deep dive: tab types
• DocuSign Developer Center
• @DocuSignAPI on X
• DocuSign for Developers on LinkedIn
• DocuSign for Developers on YouTube
• DocuSign Developer Newsletter