This method updates document visibility for a recipient.

Note: A document cannot be hidden from a recipient if the recipient has tabs assigned to them on the document. Carbon Copy, Certified Delivery (Needs to Sign), Editor, and Agent recipients can always see all documents.

Request

HTTP request

PUT /v2.1/accounts/{accountId}/envelopes/{envelopeId}/recipients/{recipientId}/document_visibility

Parameters

Parameter NameValueDescription
Path Parameters
accountIdstring

The external account number (int) or account ID GUID.

envelopeIdstring

The envelope's GUID.

Example: 93be49ab-afa0-4adf-933c-f752070d71ec

recipientIdstring

A local reference that senders use to map recipients to other objects, such as specific document tabs. Within an envelope, each recipientId must be unique, but there is no uniqueness requirement across envelopes. For example, many envelopes assign the first recipient a recipientId of 1.

Responses

CodeDescriptionReference
200

Successful response.

EnvelopeDocumentVisibility
400

Error encountered.

errorDetails

SDK Method

Envelopes::updateRecipientDocumentVisibility

Definitions

documentVisibility

This object configures a recipient's read/write access to a document.

documentIdstring

The documentId is set by the API client. It is an integer that falls between 1 and 2,147,483,647. The value is encoded as a string without commas. The values 1, 2, 3, and so on are typically used to identify the first few documents in an envelope. Tab definitions include a documentId property that specifies the document on which to place the tab.

errorDetailserrorDetails

This object describes errors that occur. It is only valid for responses and ignored in requests.

recipientIdstring

A local reference that senders use to map recipients to other objects, such as specific document tabs. Within an envelope, each recipientId must be unique, but there is no uniqueness requirement across envelopes. For example, many envelopes assign the first recipient a recipientId of 1.

rightsstring

Indicates whether the document is editable:

  • editable
  • read_only

visiblestring

When true, the document is visible to the recipient.

errorDetails

This object describes errors that occur. It is only valid for responses and ignored in requests.

errorCodestring

The code associated with the error condition.

messagestring

A brief message describing the error condition.

EnvelopeDocumentVisibility

Document Visibility enables senders to control the visibility of the documents in an envelope at the recipient level. For example, if the parties associated with a legal proceeding should have access to different documents, the Document Visibility feature enables you to keep all of the documents in the same envelope and set view permissions for the documents by recipient. This functionality is enabled for envelopes and templates. It is not available for PowerForms.

Note: Before you use Document Visibility, you should be aware of the following information:

  • Document Visibility must be enabled for your account by your DocuSign administrator.
  • A document cannot be hidden from a recipient if the recipient has tabs assigned to them on the document.
  • When the Document Visibility setting hides a document from a recipient, the document also does not appear in the recipient's list of envelopes, documents, or page images.
  • Carbon Copy, Certified Delivery (Needs to Sign), Editor, and Agent recipients can always see all of the documents associated with the envelope or template.

The Document Visibility feature has multiple settings that specify the options that senders have when sending documents. For more information, see Use Document Visibility to Control Recipient Access.

documentVisibility[documentVisibility]

An array of documentVisibility objects that specifies which documents are visible to which recipients.

Examples

Generic JSON Request/Response

Request
{
  "documentVisibility": [
    {
      "recipientId": "sample string 1",
      "documentId": "sample string 2",
      "visible": "sample string 3",
      "rights": "sample string 4"
    }
  ]
}
Response
{
  "documentVisibility": [
    {
      "recipientId": "sample string 1",
      "documentId": "sample string 2",
      "visible": "sample string 3",
      "rights": "sample string 4",
      "errorDetails": {
        "errorCode": "sample string 1",
        "message": "sample string 2"
      }
    }
  ]
}
Generic XML Request/Response

Request
<documentVisibilityList xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.docusign.com/restapi">
  <documentVisibility>
    <documentVisibility>
      <documentId>sample string 2</documentId>
      <recipientId>sample string 1</recipientId>
      <rights>sample string 4</rights>
      <visible>sample string 3</visible>
    </documentVisibility>
  </documentVisibility>
</documentVisibilityList> 
Response
<documentVisibilityList xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.docusign.com/restapi">
  <documentVisibility>
    <documentVisibility>
      <documentId>sample string 2</documentId>
      <errorDetails>
        <errorCode>sample string 1</errorCode>
        <message>sample string 2</message>
      </errorDetails>
      <recipientId>sample string 1</recipientId>
      <rights>sample string 4</rights>
      <visible>sample string 3</visible>
    </documentVisibility>
  </documentVisibility>
</documentVisibilityList> 
}} />