04/08/2024 | News release | Distributed by Public on 04/08/2024 10:56
Document visibility allows senders to control which documents each recipient can see in an envelope with multiple documents. You can control document visibility in two ways: using the Docusign eSignature web UI or by calling the eSignature REST API. This post will overview each method and also cover the limitations of document visibility in a particular scenario.
Document visibility UI settings
You can control document visibility in DocuSign eSignature; select Settings > Sending Settings. In Sending Settings, you can choose from options to control document visibility :
Depending on the option selected, another setting appears in the envelope's prepare view. With so many options to choose from, it's quite difficult to understand the whole mechanism. However, each setting is created with a purpose, so I'll explain what you can expect from each setting in this section.
Before I discuss the options, note that if a tab is placed on a document, that document will always be visible to the recipient who owns the tab. It means there's no way to control document visibility on documents that include recipients' tabs. All you can control is the documents that don't have recipients' tabs.
In conclusion, you can expect the following behavior depending on which Document Visibility option is selected:
Once you apply the document visibility setting you want, I always recommend that you check the Document Visibility matrix to ensure that you set the visibility appropriately before sending the envelope.
Lastly, check the requirements and limitations of document visibility if you encounter an unexpected behavior when using document visibility.
Controlling document visibility through the eSignature REST API
To control document visibility through the DocuSign eSignature REST API, the sender must have permission to overwrite the Document Visibility account settings through an API call. This permission can be controlled by "Allow sender to specify document visibility", which must be enabled if you want to control document visibility through the API. If this setting does not appear in your Sending Settings, it means it is already enabled on your account by default.
Once this setting is enabled, you should define two properties in the request body of the Envelope: create API call to apply document visibility on your documents:
The property must be set as to apply document visibility. You also need to define the property. It is an array of the user-defined document IDs of the documents, which should be hidden from the signer when they receive the envelope. For a brief overview of how you can define these properties, refer to the JSON below for quick testing. In this example, signer 1 will be excluded from viewing the second document () and signer 2 will be excluded from viewing the first document (). Once you send the envelope with this payload, you can check the document visibility applied to a recipient via EnvelopeDocumentVisibility: get.
Refer to How to set document visibility for envelope recipients for the step-by-step code example.
Limitation 1: Document visibility with a composite template model
The composite template model provides a more flexible way to create the envelope than the direct documents or template reference model. As the composite template model is more flexible and provides more functionality, it has a more complicated internal design and some limitations on using it. One limitation of the composite template model is with document visibility. However, you'll be able to apply document visibility without issue once you understand how the composite template works internally.
The composite template model internally renumbers the document ID defined in the template. The document ID is renumbered in the order of the documents, so the first document will get the ID of 1, the second document will get the ID of 2, and so on. Then, the system processes and applies the document visibility rules defined in the property.
Therefore, if the property references the old value of the document ID, you'll run into the issue of document visibility not being applied to the envelope. This is because the system cannot find a matching document, as it was updated to the new number.
To prevent this behavior, I recommend you follow one of the options below based on your use case:
While creating the template, specify the document ID sequentially in order starting from 1. As the document ID in the template is already specified with the order number (1, 2, …), the new number will be the same as the one you already assigned to the document ID. In this case, follow the API call described in the above "eSignature REST API" section to send the envelope with document visibility.
If you create the template on the DocuSign Portal, the document ID will be assigned random eight digits, such as 18265009 or 34723248, which is different from the renumbered document ID (1,2, ...). In this case, call the APIs below sequentially to apply the document visibility settings to the envelope. I recommend following this option as it covers every possible scenario.
Limitation 2: Document visibility with supplemental documents
You can also apply document visibility to supplemental documents attached to your envelope. However, it's only possible through the eSignature REST API. Check the sample payload below to apply document visibility to supplemental documents. The will be excluded from viewing the supplemental document in this example.
Additional resources