From the Trenches: Deep dive into document visibility

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.

• First method: Document visibility UI setting

• Second method: eSignature REST API

  • excludedDocuments property

  • enforceSignerVisibility property

• Limitation 1: Document visibility with a composite template model

• Limitation 2: Document Visibility with supplemental documents

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: 

• Off

• Must sign to view, unless a member of sender's account

• Must sign to view, unless sender

• Sender can set “must sign to view, unless a member of sender's account”

• Sender can set “must sign to view, unless sender”

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.

• Must sign to view means that the recipient can only see the documents that include their tabs. If a particular document doesn't have a particular recipient's tab, it will not be visible to this recipient. It doesn't have to be only the signHere tab or the initial tab. The document will be visible if other tabs, such as the text or date tab, are placed on it.

• Unless a member of sender's account or unless sender defines the target user range being applied to this option.

• Sender can set option allows senders to turn document visibility entirely on or off on a given envelope or template. If a "Sender can set" option is enabled, users will be able to see and toggle Recipients must be signers to view signed documents under Advanced Options > Recipient Privileges in the envelope’s or template’s prepare page. If this setting is not enabled (checked), it’s the same as the document visibility being selected with “Off”. In other words, the document visibility will not be applied to the documents. Thus, every recipient can see all the documents in the envelope. So, if you want to use document visibility, enable Recipients must be signers to view signed documents when creating your envelope or template.

• Allow sender to specify document visibility is available only when an option other than Off is selected. If this option is selected, the sender can adjust document visibility through the Document Visibility matrix (envelope prepare page > Gear icon > Document Visibility). If the setting Allow sender to specify document visibility does not appear in your Sending Settings, it usually means this setting is already enabled on your account by default.

In conclusion, you can expect the following behavior depending on which Document Visibility option is selected:

1. Off: Document visibility is not active for the account.

2. Options without “Sender can set”: The document visibility setting applies immediately to all the envelopes your account will send.

3. Options with “Sender can set”: The document visibility setting does not apply to the envelope unless the sender enables “Recipients must be signers to view signed documents” in the envelope prepare screen. It means you as an administrator of the account completely permit the sender to control the document visibility on every envelope they send.

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:

1. enforceSignerVisibility

2. excludedDocuments

The enforceSignerVisibility property must be set as true to apply document visibility. You also need to define the excludedDocuments 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 ("documentId": "2") and signer 2 will be excluded from viewing the first document ("documentId": "1"). 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.

{
    "documents": [
        {
            "documentBase64": "[DOUCMENT_BASE_64]",
            "documentId": "1",
            "fileExtension": "pdf",
            "name": "Test"
        },
        {
            "documentBase64": "[DOUCMENT_BASE_64]",
            "documentId": "2",
            "fileExtension": "pdf",
            "name": "Test2"
        }
    ],
    "enforceSignerVisibility": true,
    "emailSubject": "Please Sign this Envelope",
    "expireAfter": "1",
    "expireEnabled": "true",
    "recipients": {
        "signers": [
            {
                "routingOrder": 1,
                "name": "[SIGNER1_NAME]",
                "email": "[SIGNER1_EMAIL]",
                "status": "created",
                "deliveryMethod": "email",
                "recipientId": "1",
                "excludedDocuments": [
                    2
                ],
                "tabs": {
                    "signHereTabs": [
                        {
                            "optional": "false",
                            "pageNumber": "1",
                            "recipientId": "1",
                            "scaleValue": ".5",
                            "xPosition": "144",
                            "documentId": "1",
                            "yPosition": "144"
                        }
                    ]
                }
            },
            {
                "routingOrder": 1,
                "name": "[SIGNER2_NAME]",
                "email": "[SIGNER2_EMAIL]",
                "status": "created",
                "deliveryMethod": "email",
                "recipientId": "2",
                "excludedDocuments": [
                    1
                ],
                "tabs": {
                    "signHereTabs": [
                        {
                            "optional": "false",
                            "pageNumber": "1",
                            "recipientId": "2",
                            "scaleValue": ".5",
                            "xPosition": "204",
                            "documentId": "2",
                            "yPosition": "144"
                        }
                    ]
                }
            }
        ]
    },
    "status": "sent"
}

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 excludedDocuments property.

Therefore, if the excludedDocuments 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:

• Use case 1: You always create the template through the API

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.

• Use case 2: You create the template on the Docusign Portal or don’t know how it was created.

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.

1. Create the envelope as a draft without setting document visibility (enforceSignerVisibility, excludedDocuments).

2. Use EnvelopeRecipients: list to get the recipient ID.

3. Use EnvelopeDocuments: list to get "new" document ID.

4. Use EnvelopeDocumentVisibility: get to get the current document visibility settings.

5. Use EnvelopeDocumentVisibility: updateRecipientsDocumentVisibility to update the document visibility settings.

6. Use Envelopes: update to send a draft envelope.

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 SIGNER2 will be excluded from viewing the supplemental document in this example.

{
    "documents": [
        {
            "documentBase64": "[DOC_BASE_64]",
            "documentId": "1",
            "fileExtension": "pdf",
            "name": "Test.pdf"
        },
        {
            "display": "modal",
            "documentBase64": "[DOC_BASE_64]",
            "documentId": "2",
            "includeInDownload": "True",
            "name": "Supplemental Document",
            "signerMustAcknowledge": "view",
            "templateRequired": "False"
        }
    ],
    "emailSubject": "Please Sign this Envelope",
    "expireAfter": "1",
    "expireEnabled": "true",
    "enforceSignerVisibility": true,
    "recipients": {
        "signers": [
            {
                "email": "[SIGNER1_EMAIL]",
                "name": "[SIGNER1_NAME]",
                "recipientId": "1",
                "tabs": {
                    "signHereTabs": [
                        {
                            "documentId": "1",
                            "pageNumber": "1",
                            "recipientId": "2",
                            "xPosition": "200",
                            "yPosition": "200"
                        }
                    ]
                },
            },
            {
                "email": "[SIGNER2_EMAIL]",
                "name": "[SIGNER2_NAME]",
                "recipientId": "2",
                "tabs": {
                    "signHereTabs": [
                        {
                            "documentId": "1",
                            "pageNumber": "1",
                            "recipientId": "2",
                            "xPosition": "300",
                            "yPosition": "300"
                        }
                    ]
                },
                "excludedDocuments": [
                    2
                ]
            }
        ]
    },
    "status": "sent"
}

Additional resources

• Docusign Developer Center

• @DocuSignAPI on Twitter

• Docusign for Developers on LinkedIn

• Docusign for Developers on YouTube

• Docusign Developer Newsletter