Account administrators can use this method to perform the following tasks:

  • Customize values in the default disclosure.
  • Switch to a custom disclosure that uses your own text and HTML formatting.
  • Change values in your existing consumer disclosure.

To specify the signer language version of the disclosure that you are updating, use the optional langCode query parameter.

Note: Only account administrators can use this method. Each time you change the disclosure content, all unsigned recipients of outstanding documents will be required to accept a new version.

Updating the default disclosure

When you update the default disclosure, you can edit all properties except for the following ones:

  • accountEsignId: This property is read only.
  • custom: The default value is false. Editing this property causes the default disclosure to switch to a custom disclosure.
  • esignAgreement: This property is read only.
  • esignText: You cannot edit this property when custom is set to false. The API returns a 200 OK HTTP response, but does not update the esignText.
  • Metadata properties: These properties are read only.

Note: The text of the default disclosure is always in English.

Switching to a custom disclosure

To switch to a custom disclosure, set the custom property to true and customize the value for the eSignText property.

You can also edit all of the other properties except for the following ones:

  • accountEsignId: This property is read only.
  • esignAgreement: This property is read only.
  • Metadata properties: These properties are read only.

Note: When you use a custom disclosure, you can create versions of it in different signer languages and se the langCode parameter to specify the signer language version that you are updating.

Important: When you switch from a default to a custom disclosure, note the following information:

  • You will not be able to return to using the default disclosure.
  • Only the disclosure for the currently selected signer language is saved. DocuSign will not automatically translate your custom disclosure. You must create a disclosure for each language that your signers use.

Updating a custom disclosure

When you update a custom disclosure, you can update all of the properties except for the following ones:

  • accountEsignId: This property is read only.
  • esignAgreement: This property is read only.
  • Metadata properties: These properties are read only.

Important: Only the disclosure for the currently selected signer language is saved. DocuSign will not automatically translate your custom disclosure. You must create a disclosure for each language that your signers use.

Request

HTTP request

PUT /v2.1/accounts/{accountId}/consumer_disclosure/{langCode}

Parameters

Parameter NameValueDescription
Path Parameters
accountIdstring

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

langCodestring

(Optional) The code for the signer language version of the disclosure that you want to update. The following languages are supported:

  • Arabic (ar)
  • Bulgarian (bg)
  • Czech (cs)
  • Chinese Simplified (zh_CN)
  • Chinese Traditional (zh_TW)
  • Croatian (hr)
  • Danish (da)
  • Dutch (nl)
  • English US (en)
  • English UK (en_GB)
  • Estonian (et)
  • Farsi (fa)
  • Finnish (fi)
  • French (fr)
  • French Canadian (fr_CA)
  • German (de)
  • Greek (el)
  • Hebrew (he)
  • Hindi (hi)
  • Hungarian (hu)
  • Bahasa Indonesian (id)
  • Italian (it)
  • Japanese (ja)
  • Korean (ko)
  • Latvian (lv)
  • Lithuanian (lt)
  • Bahasa Melayu (ms)
  • Norwegian (no)
  • Polish (pl)
  • Portuguese (pt)
  • Portuguese Brazil (pt_BR)
  • Romanian (ro)
  • Russian (ru)
  • Serbian (sr)
  • Slovak (sk)
  • Slovenian (sl)
  • Spanish (es)
  • Spanish Latin America (es_MX)
  • Swedish (sv)
  • Thai (th)
  • Turkish (tr)
  • Ukrainian (uk)
  • Vietnamese (vi)

Additionally, you can automatically detect the browser language being used by the viewer and display the disclosure in that language by setting the value to browser.

Optional Query Parameters
include_metadatastring

(Optional) When set to true, the response includes metadata indicating which properties are editable.

Responses

CodeDescriptionReference
200

Successful response.

EnvelopeConsumerDisclosures
400

Error encountered.

errorDetails

SDK Method

Accounts::updateConsumerDisclosure

Definitions

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.

settingsMetadata

Metadata that indicates whether a property is editable and describes setting-specific options.

is21CFRPart11string

When true, indicates compliance with United States Food and Drug Administration (FDA) regulations on electronic records and electronic signatures (ERES).

options[array]

An array of option strings supported by this setting.

rightsstring

Indicates whether the property is editable. Valid values are:

  • editable
  • read_only

uiHintstring

Reserved for DocuSign.

uiOrderstring

Reserved for DocuSign.

uiTypestring

Reserved for DocuSign.

EnvelopeConsumerDisclosures

Details about envelope consumer disclosures.

accountEsignIdstring

The GUID of the account associated with the consumer disclosure.

allowCDWithdrawstring

When set to true, indicates that the customer can withdraw their consent to the consumer disclosure when they decline to sign documents. If these recipients sign documents sent to them from your account in the future, they will be required to agree to the terms in the disclosure. The default value is false. Note: Only Admin users can change this setting.

allowCDWithdrawMetadatasettingsMetadata

Metadata that indicates whether the allowCDWithdraw property is editable.

changeEmailstring

If the customer needs to change their email address, this is the email address to which they should the change request.

changeEmailOtherstring

Other information about the requirements for the user to change their email address.

Example:

We do not require any other information from you to change your email address.

companyNamestring

Specifies the company name used in the disclosure. The default value is the account name.

However, if your account uses signing brands that specify a company name, you can substitute the brand's company name by setting the useBrand property to true. Whenever an envelope is sent from the account that uses a signing brand with a specified companyName, that value is used in email notifications and in the signing experience.

Note: This substitution only works if you use the default legal disclosure or if you apply the companyName to the merge fields in a custom ERSD. You must also set the value of the useBrand property to true.

companyPhonestring

The phone number of the company associated with the consumer disclosure, as a free-formatted string.

copyCostPerPagestring

The cost per page if the customer requests paper copies.

Example:

0.0000

copyFeeCollectionMethodstring

Specifies the fee collection method for cases in which the customer requires paper copies of the document.

Maximum length: 255 characters.

Example:

We will bill you for any fees at that time, if any.

copyRequestEmailstring

The email address to which the customer should send a request for copies of a document.

Maximum length: 100 characters.

customstring

When set to true, the consumer disclosure is a custom disclosure. The default is false.

enableEsignstring

When set to true (default), indicates that eSign is enabled.

esignAgreementstring

The final, assembled text of the Electronic Record and Signature Disclosure that includes the appropriate companyName and other specifics. It also includes the HTML tags used for formatting.

esignTextstring

The template for the Electronic Record and Signature Disclosure, which contains placeholders for information such as the companyName. It also includes the HTML tags used for formatting.

Note: If you are switching to or updating a custom disclosure, you can edit both the text and the HTML formatting.

languageCodestring

The simple type enumeration for the language to use when displaying the disclosure. The following languages are supported:

  • Arabic (ar)
  • Bulgarian (bg)
  • Czech (cs)
  • Chinese Simplified (zh_CN)
  • Chinese Traditional (zh_TW)
  • Croatian (hr)
  • Danish (da)
  • Dutch (nl)
  • English US (en)
  • English UK (en_GB)
  • Estonian (et)
  • Farsi (fa)
  • Finnish (fi)
  • French (fr)
  • French Canadian (fr_CA)
  • German (de)
  • Greek (el)
  • Hebrew (he)
  • Hindi (hi)
  • Hungarian (hu)
  • Bahasa Indonesian (id)
  • Italian (it)
  • Japanese (ja)
  • Korean (ko)
  • Latvian (lv)
  • Lithuanian (lt)
  • Bahasa Melayu (ms)
  • Norwegian (no)
  • Polish (pl)
  • Portuguese (pt)
  • Portuguese Brazil (pt_BR)
  • Romanian (ro)
  • Russian (ru)
  • Serbian (sr)
  • Slovak (sk)
  • Slovenian (sl)
  • Spanish (es)
  • Spanish Latin America (es_MX)
  • Swedish (sv)
  • Thai (th)
  • Turkish (tr)
  • Ukrainian (uk)
  • Vietnamese (vi)

Additionally, you can automatically detect the browser language being used by the viewer and display the disclosure in that language by setting the value to browser.

mustAgreeToEsignstring

When set to true, the recipient must agree to the consumer disclosure. This is a calculated field.

pdfIdstring

Deprecated.

The pdfId property in the consumer_disclosure PUT request is deprecated. For security reasons going forward, any value provided in the request packet must be ignored.

useBrandstring

When set to true, specifies that the company name in the signing brand is used for the disclosure. Whenever an envelope is sent from the account that uses a signing brand with a specified company name, that value is used in email notifications and in the signing experience.

When set to false (default), or if the signing brand does not specify a company name, the account name is used instead.

Note: This substitution only works if you use the default legal disclosure or if you apply the companyName to the merge fields in a custom ERSD.

useConsumerDisclosureWithinAccountstring

When set to true, specifies that recipients in the same account as the sender must agree to eSign an Electronic Record and Signature Disclosure Statement.

useConsumerDisclosureWithinAccountMetadatasettingsMetadata

Metadata that indicates whether the useConsumerDisclosureWithinAccount property is editable.

withdrawAddressLine1string

Contains the first address line of the postal address to which a customer can send a consent withdrawal notification.

Maximum length: 100 characters.

withdrawAddressLine2string

Contains the second address line of the postal address to which a customer can send a consent withdrawal notification.

Maximum length: 100 characters.

withdrawByEmailstring

When set to true (default), indicates that the customer can withdraw consent by email.

withdrawByMailstring

When set to true, indicates that the customer can withdraw consent by postal mail. The default is false.

withdrawByPhonestring

When set to true, indicates that the customer can withdraw consent by phone. The default is false.

withdrawCitystring

Contains the city of the postal address to which a customer can send a consent withdrawal notification.

Maximum length: 50 characters.

withdrawConsequencesstring

Text indicating the consequences of withdrawing consent.

Maximum length: 255 characters.

withdrawEmailstring

Contains the email address to which a customer can send a consent withdrawal notification.

Maximum length: 100 characters.

withdrawOtherstring

Contains any other information needed to withdraw consent.

Maximum length: 255 characters.

Example:

We do not need any other information from you to withdraw consent.

withdrawPhonestring

Contains the phone number that a customer can call to register consent withdrawal notification as a free-formatted string.

Maximum length: 20 characters.

withdrawPostalCodestring

Contains the postal code of the postal address to which a customer can send a consent withdrawal notification.

Maximum length: 20 characters.

withdrawStatestring

Contains the state of the postal address to which a customer can send a consent withdrawal notification.

Example: PA

Examples

Generic JSON Request/Response

Request
{
  "companyName": "sample string 1",
  "companyPhone": "sample string 2",
  "withdrawEmail": "sample string 3",
  "withdrawByEmail": "sample string 4",
  "withdrawByPhone": "sample string 5",
  "withdrawByMail": "sample string 6",
  "withdrawAddressLine1": "sample string 7",
  "withdrawAddressLine2": "sample string 8",
  "withdrawCity": "sample string 9",
  "withdrawState": "sample string 10",
  "withdrawPostalCode": "sample string 11",
  "withdrawConsequences": "sample string 12",
  "withdrawOther": "sample string 13",
  "withdrawPhone": "sample string 14",
  "changeEmail": "sample string 15",
  "changeEmailOther": "sample string 16",
  "copyCostPerPage": "sample string 17",
  "copyRequestEmail": "sample string 18",
  "copyFeeCollectionMethod": "sample string 19",
  "custom": "sample string 20",
  "pdfId": "sample string 21",
  "enableEsign": "sample string 22",
  "useBrand": "sample string 23",
  "esignAgreement": "sample string 24",
  "esignText": "sample string 25",
  "allowCDWithdraw": "sample string 26",
  "mustAgreeToEsign": "sample string 27",
  "useConsumerDisclosureWithinAccount": "sample string 28"
}
Response
{
  "accountEsignId": "sample string 1",
  "companyName": "sample string 2",
  "companyPhone": "sample string 3",
  "withdrawEmail": "sample string 4",
  "withdrawByEmail": "sample string 5",
  "withdrawByPhone": "sample string 6",
  "withdrawByMail": "sample string 7",
  "withdrawAddressLine1": "sample string 8",
  "withdrawAddressLine2": "sample string 9",
  "withdrawCity": "sample string 10",
  "withdrawState": "sample string 11",
  "withdrawPostalCode": "sample string 12",
  "withdrawConsequences": "sample string 13",
  "withdrawOther": "sample string 14",
  "withdrawPhone": "sample string 15",
  "changeEmail": "sample string 16",
  "changeEmailOther": "sample string 17",
  "copyCostPerPage": "sample string 18",
  "copyRequestEmail": "sample string 19",
  "copyFeeCollectionMethod": "sample string 20",
  "custom": "sample string 21",
  "pdfId": "sample string 22",
  "enableEsign": "sample string 23",
  "languageCode": "sample string 24",
  "useBrand": "sample string 25",
  "esignAgreement": "sample string 26",
  "esignText": "sample string 27",
  "allowCDWithdraw": "sample string 28",
  "allowCDWithdrawMetadata": {
    "rights": "sample string 1",
    "uiHint": "sample string 2",
    "uiType": "sample string 3",
    "uiOrder": "sample string 4",
    "is21CFRPart11": "sample string 5",
    "options": [
      "sample string 1"
    ]
  },
  "mustAgreeToEsign": "sample string 29",
  "useConsumerDisclosureWithinAccount": "sample string 30",
  "useConsumerDisclosureWithinAccountMetadata": {}
}
Generic XML Request/Response

Request
<consumerDisclosure xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.docusign.com/restapi">
  <allowCDWithdraw>sample string 26</allowCDWithdraw>
  <changeEmail>sample string 15</changeEmail>
  <changeEmailOther>sample string 16</changeEmailOther>
  <companyName>sample string 1</companyName>
  <companyPhone>sample string 2</companyPhone>
  <copyCostPerPage>sample string 17</copyCostPerPage>
  <copyFeeCollectionMethod>sample string 19</copyFeeCollectionMethod>
  <copyRequestEmail>sample string 18</copyRequestEmail>
  <custom>sample string 20</custom>
  <enableEsign>sample string 22</enableEsign>
  <esignAgreement>sample string 24</esignAgreement>
  <esignText>sample string 25</esignText>
  <mustAgreeToEsign>sample string 27</mustAgreeToEsign>
  <pdfId>sample string 21</pdfId>
  <useBrand>sample string 23</useBrand>
  <useConsumerDisclosureWithinAccount>sample string 28</useConsumerDisclosureWithinAccount>
  <withdrawAddressLine1>sample string 7</withdrawAddressLine1>
  <withdrawAddressLine2>sample string 8</withdrawAddressLine2>
  <withdrawByEmail>sample string 4</withdrawByEmail>
  <withdrawByMail>sample string 6</withdrawByMail>
  <withdrawByPhone>sample string 5</withdrawByPhone>
  <withdrawCity>sample string 9</withdrawCity>
  <withdrawConsequences>sample string 12</withdrawConsequences>
  <withdrawEmail>sample string 3</withdrawEmail>
  <withdrawOther>sample string 13</withdrawOther>
  <withdrawPhone>sample string 14</withdrawPhone>
  <withdrawPostalCode>sample string 11</withdrawPostalCode>
  <withdrawState>sample string 10</withdrawState>
</consumerDisclosure> 
Response
<consumerDisclosure xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.docusign.com/restapi">
  <accountEsignId>sample string 1</accountEsignId>
  <allowCDWithdraw>sample string 28</allowCDWithdraw>
  <allowCDWithdrawMetadata>
    <is21CFRPart11>sample string 5</is21CFRPart11>
    <options>
      <string>sample string 1</string>
    </options>
    <rights>sample string 1</rights>
    <uiHint>sample string 2</uiHint>
    <uiOrder>sample string 4</uiOrder>
    <uiType>sample string 3</uiType>
  </allowCDWithdrawMetadata>
  <changeEmail>sample string 16</changeEmail>
  <changeEmailOther>sample string 17</changeEmailOther>
  <companyName>sample string 2</companyName>
  <companyPhone>sample string 3</companyPhone>
  <copyCostPerPage>sample string 18</copyCostPerPage>
  <copyFeeCollectionMethod>sample string 20</copyFeeCollectionMethod>
  <copyRequestEmail>sample string 19</copyRequestEmail>
  <custom>sample string 21</custom>
  <enableEsign>sample string 23</enableEsign>
  <esignAgreement>sample string 26</esignAgreement>
  <esignText>sample string 27</esignText>
  <languageCode>sample string 24</languageCode>
  <mustAgreeToEsign>sample string 29</mustAgreeToEsign>
  <pdfId>sample string 22</pdfId>
  <useBrand>sample string 25</useBrand>
  <useConsumerDisclosureWithinAccount>sample string 30</useConsumerDisclosureWithinAccount>
  <useConsumerDisclosureWithinAccountMetadata />
  <withdrawAddressLine1>sample string 8</withdrawAddressLine1>
  <withdrawAddressLine2>sample string 9</withdrawAddressLine2>
  <withdrawByEmail>sample string 5</withdrawByEmail>
  <withdrawByMail>sample string 7</withdrawByMail>
  <withdrawByPhone>sample string 6</withdrawByPhone>
  <withdrawCity>sample string 10</withdrawCity>
  <withdrawConsequences>sample string 13</withdrawConsequences>
  <withdrawEmail>sample string 4</withdrawEmail>
  <withdrawOther>sample string 14</withdrawOther>
  <withdrawPhone>sample string 15</withdrawPhone>
  <withdrawPostalCode>sample string 12</withdrawPostalCode>
  <withdrawState>sample string 11</withdrawState>
</consumerDisclosure> 
}} />