--- title: "Updates a bulk send list." method: PUT path: "/v2.1/accounts/{accountId}/bulk_send_lists/{bulkSendListId}" tags: ["BulkSend"] --- # Updates a bulk send list. `PUT /v2.1/accounts/{accountId}/bulk_send_lists/{bulkSendListId}` This method replaces the definition of an existing bulk send list. ## Path parameters - `accountId` string, required - `bulkSendListId` string, required ## Request body - BulkSendingList — This object contains the details for the bulk send list. - `bulkCopies` BulkSendingCopy[] — An array of `bulkCopy` objects. Each object represents an instance or copy of an envelope and contains details such as the recipient, custom fields, tabs, and other information. - `customFields` BulkSendingCopyCustomField[] — The custom fields for this copy of the envelope. **Note:** These custom fields must also be included in the original envelope or template that you want to send. - `name` string — The name of the custom field. - `value` string — The value of the custom field. - `docGenFormFields` BulksendingCopyDocGenFormField[] - `name` string - `rowValues` BulkSendingCopyDocGenFormFieldRowValue[] - `docGenFormFieldList` BulksendingCopyDocGenFormField[] - `value` string — Specifies the value of the tab. - `emailBlurb` string — The email body for this copy of the envelope. - `emailSubject` string — The email subject line for this copy of the envelope. For information about adding merge field information to the email subject, see [Template Email Subject Merge Fields](/docs/esign-rest-api/reference/templates/templates/create/). **Note:** The subject line is limited to 100 characters, including any merged fields.It is not truncated. It is an error if the text is longer than 100 characters. - `prefillTabs` BulkSendingCopyPrefillTab[] — Prefill tabs are tabs that the sender can fill in before the envelope is sent. They are sometimes called sender tags or pre-fill fields. [Pre-Fill Your Own Document Fields][app] describes how prefill tabs work in the web application. [Customize your envelopes with pre-fill fields][catblog] shows how to use prefill tabs in your application using the eSignature SDKs. [app]: https://support.docusign.com/s/document-item?bundleId=gbo1643332197980&topicId=nwo1611173513994.html [catblog]: https://www.docusign.com/blog/developers/common-api-tasks-customize-your-envelopes-pre-fill-fields - `initialValue` string — The original value of the tab. - `tabLabel` string — The label associated with the tab. This value may be an empty string. If no value is provided, the tab type is used as the value. Maximum Length: 500 characters. - `recipients` BulkSendingCopyRecipient[] — Information about the recipients associated with this copy of the envelope. - `accessCode` string — If a value is provided, the recipient must enter the value as the access code to view and sign the envelope. Maximum Length: 50 characters and it must conform to the account's access code format setting. If blank, but the signer `accessCode` property is set in the envelope, then that value is used. If blank and the signer `accessCode` property is not set, then the access code is not required. - `clientUserId` string — Specifies whether the recipient is embedded or remote. If the `clientUserId` property is not null then the recipient is embedded. Use this field to associate the signer with their userId in your app. Authenticating the user is the responsibility of your app when you use embedded signing. If the `clientUserId` property is set and either `SignerMustHaveAccount` or `SignerMustLoginToSign` property of the account settings is set to **true,** an error is generated on sending. **Note:** This property is not returned by the [listStatusChanges](/docs/esign-rest-api/reference/envelopes/envelopes/liststatuschanges/) endpoint. Maximum length: 100 characters. - `customFields` string[] — An optional array of strings that allows the sender to provide custom data about the recipient. This information is returned in the envelope status but otherwise not used by Docusign. Each customField string can be a maximum of 100 characters. - `deliveryMethod` string — The delivery method. One of: - `email` - `fax` - `SMS` - `WhatsApp` - `offline` The `SMS` and `WhatsApp` delivery methods are limited to `signer`, `carbonCopy`, and `certifiedDelivery` recipients. **Related topics** - [Using SMS delivery with the eSignature API][smsconcept] - [How to request a signature by SMS or WhatsApp delivery][howto] [smsconcept]: /docs/esign-rest-api/esign101/concepts/sms-delivery/using-sms-esignature/ [howto]: /docs/esign-rest-api/how-to/request-signature-sms-whatsapp/ - `email` string — The recipient's email address. - `emailNotification` RecipientEmailNotification — Sets custom email subject and email body for individual recipients. **Note:** You must explicitly set `supportedLanguage` if you use this feature. - `emailBody` string — The body of the email message. - `emailBodyMetadata` PropertyMetadata — Metadata about a property. - `options` string[] — An array of option strings supported by this setting. - `rights` string — Indicates whether the property is editable. Valid values are: - `editable` - `read_only` - `emailSubject` string — The subject line for the email notification. - `emailSubjectMetadata` PropertyMetadata — Metadata about a property. - `options` string[] — An array of option strings supported by this setting. - `rights` string — Indicates whether the property is editable. Valid values are: - `editable` - `read_only` - `supportedLanguage` string — The language to use for the standard email format and signing view for a recipient. For example, this setting determines the language of the recipient's email notification message. It also determines the language used for buttons and tabs in both the email notification and the signing experience. **Note:** This setting affects only Docusign standard text. Any custom text that you enter for the `emailBody` and `emailSubject` of the notification is not translated, and appears exactly as you enter it. To retrieve the possible values, use the [Accounts::listSupportedLanguages][ListLang] method. [ListLang]: /docs/esign-rest-api/reference/accounts/accounts/listsupportedlanguages/ - `supportedLanguageMetadata` PropertyMetadata — Metadata about a property. - `options` string[] — An array of option strings supported by this setting. - `rights` string — Indicates whether the property is editable. Valid values are: - `editable` - `read_only` - `embeddedRecipientStartURL` string — Specifies a sender-provided valid URL string for redirecting an embedded recipient. When using this option, the embedded recipient still receives an email from Docusign, just as a remote recipient would. When the document link in the email is clicked the recipient is redirected, through Docusign, to the supplied URL to complete their actions. When routing to the URL, the sender's system (the server responding to the URL) must request a recipient token to launch a signing session. When `SIGN_AT_DOCUSIGN`, the recipient is directed to an embedded signing or viewing process directly at Docusign. The signing or viewing action is initiated by the Docusign system and the transaction activity and Certificate of Completion records will reflect this. In all other ways the process is identical to an embedded signing or viewing operation launched by a partner. It is important to understand that in a typical embedded workflow, the authentication of an embedded recipient is the responsibility of the sending application. Docusign expects that senders will follow their own processes for establishing the recipient's identity. In this workflow the recipient goes through the sending application before the embedded signing or viewing process is initiated. However, when the sending application sets `EmbeddedRecipientStartURL=SIGN_AT_DOCUSIGN`, the recipient goes directly to the embedded signing or viewing process, bypassing the sending application and any authentication steps the sending application would use. In this case, Docusign recommends that you use one of the normal Docusign authentication features (Access Code, Phone Authentication, SMS Authentication, etc.) to verify the identity of the recipient. If the `clientUserId` property is NOT set, and the `embeddedRecipientStartURL` is set, Docusign will ignore the redirect URL and launch the standard signing process for the email recipient. Information can be appended to the embedded recipient start URL using merge fields. The available merge fields items are: `envelopeId`, `recipientId`, `recipientName`, `recipientEmail`, and `customFields`. The `customFields` property must be set for the recipient or envelope. The merge fields are enclosed in double brackets. *Example*: `http://senderHost/[[mergeField1]]/ beginSigningSession? [[mergeField2]]&[[mergeField3]]` - `faxNumber` string — Reserved for Docusign. - `hostEmail` string — The email address of the signing host. This is the Docusign user that is hosting the in-person signing session. Required when `inPersonSigningType` is `inPersonSigner`. For eNotary flow, use `email` instead. Maximum Length: 100 characters. - `hostName` string — The name of the signing host. This is the Docusign user that is hosting the in-person signing session. Required when `inPersonSigningType` is `inPersonSigner`. For eNotary flow, use `name` instead. Maximum Length: 100 characters. - `idCheckConfigurationName` string — The name of the authentication check to use. This value must match one of the authentication types that the account uses. The names of these authentication types appear in the web console sending interface in the Identify list for a recipient. This setting overrides any default authentication setting. Valid values are: - `Phone Auth $`: The recipient must authenticate by using two-factor authentication (2FA). You provide the phone number to use for 2FA in the `phoneAuthentication` object. - `SMS Auth $`: The recipient must authenticate via SMS. You provide the phone number to use in the `smsAuthentication` object. - `ID Check $`: The recipient must answer detailed security questions. **Example:** Your account has ID Check and SMS Authentication available. In the web console Identify list, these appear as ID Check $ and SMS Auth $. To use ID Check in an envelope, the idCheckConfigurationName should be ID Check $. For SMS, you would use SMS Auth $, and you would also need to add a phone number to the smsAuthentication node. - `idCheckInformationInput` IdCheckInformationInput — A complex element that contains input information related to a recipient ID check. - `addressInformationInput` AddressInformationInput — Contains address input information. - `addressInformation` AddressInformation — Contains address information. - `address1` string — The first line of the user's address. Maximum length: 100 characters. - `address2` string — The second line of the user's address. Maximum length: 100 characters. - `city` string — The user's city. Maximum length: 40 characters. - `country` string — The user's country. Maximum length: 50 characters. - `fax` string — A fax number associated with the address, if one is available. - `phone` string — A phone number associated with the address. - `postalCode` string — The user's postal code. Maximum length: 20 characters. - `stateOrProvince` string — The user's state or province. Maximum length: 40 characters. - `zipPlus4` string - `displayLevelCode` string — Specifies the display level for the recipient. Valid values are: * `ReadOnly` * `Editable` * `DoNotDisplay` - `receiveInResponse` string — A Boolean value that specifies whether the information must be returned in the response. - `dobInformationInput` DobInformationInput — Complex type containing: * dateOfBirth * displayLevelCode * receiveInResponse - `dateOfBirth` string — Specifies the recipient's date, month, and year of birth. - `displayLevelCode` string — Specifies the display level for the recipient. Valid values are: * `ReadOnly` * `Editable` * `DoNotDisplay` - `receiveInResponse` string — A Boolean value that specifies whether the information must be returned in the response. - `ssn4InformationInput` Ssn4InformationInput - `displayLevelCode` string — Specifies the display level for the recipient. Valid values are: * `ReadOnly` * `Editable` * `DoNotDisplay` - `receiveInResponse` string — A Boolean value that specifies whether the information must be returned in the response. - `ssn4` string — The last four digits of the recipient's Social Security Number (SSN). - `ssn9InformationInput` Ssn9InformationInput - `displayLevelCode` string — Specifies the display level for the recipient. Valid values are: * `ReadOnly` * `Editable` * `DoNotDisplay` - `ssn9` string — The recipient's full Social Security Number (SSN). - `identificationMethod` string - `identityVerification` RecipientIdentityVerification — Specifies ID Verification applied on an envelope by workflow ID. See the [list](/docs/esign-rest-api/reference/accounts/identityverifications/list/) method in the [IdentityVerifications](/docs/esign-rest-api/reference/accounts/identityverifications/) resource for more information on how to retrieve workflow IDs available for an account. This can be used in addition to other [recipient authentication](https://support.docusign.com/s/document-item?bundleId=gav1643676262430&topicId=kzp1578456318101.html) methods. - `inputOptions` RecipientIdentityInputOption[] - `name` string - `phoneNumberList` RecipientIdentityPhoneNumber[] - `countryCode` string — The numeric country calling code for the phone number. For example, the country calling code for the US and Canada is 1. For the UK, the country calling code is 44. Do not include the + symbol. - `countryCodeLock` string - `countryCodeMetadata` PropertyMetadata — Metadata about a property. - … - `extension` string — The telephone extension, if any. - `extensionMetadata` PropertyMetadata — Metadata about a property. - … - `number` string — The telephone number. Use only the digits `0`-`9`. Remove any non-numeric characters. Do not include the `countryCode`. For US, Canada, and other [North American Numbering Plan](https://en.wikipedia.org/wiki/North_American_Numbering_Plan) countries, do not include a leading `1` or `0`. - `numberMetadata` PropertyMetadata — Metadata about a property. - … - `stringValue` string - `valueType` string - `workflowId` string — ID of the Identity Verification worklow used to verify recipients' identity. This ID must match one of the [workflowId](/docs/esign-rest-api/reference/accounts/identityverifications/list/) available to your account. - `workflowIdMetadata` PropertyMetadata — Metadata about a property. - `options` string[] — An array of option strings supported by this setting. - `rights` string — Indicates whether the property is editable. Valid values are: - `editable` - `read_only` - `workflowLabel` string - `name` string - `note` string — A note sent to the recipient in the signing email. This note is unique to this recipient. In the user interface, it appears near the upper left corner of the document on the signing screen. Maximum Length: 1000 characters. - `phoneAuthentication` RecipientPhoneAuthentication — A complex type that contains the elements: * `recipMayProvideNumber`: A Boolean value that specifies whether the recipient can use the phone number of their choice. * `senderProvidedNumbers`: A list of phone numbers that the recipient can use. * `recordVoicePrint`: Reserved for Docusign. * `validateRecipProvidedNumber`: Reserved for Docusign. - `recipMayProvideNumber` string — Boolean. When **true,** the recipient can supply a phone number their choice. - `recipMayProvideNumberMetadata` PropertyMetadata — Metadata about a property. - `options` string[] — An array of option strings supported by this setting. - `rights` string — Indicates whether the property is editable. Valid values are: - `editable` - `read_only` - `recordVoicePrint` string — Reserved for Docusign. - `recordVoicePrintMetadata` PropertyMetadata — Metadata about a property. - `options` string[] — An array of option strings supported by this setting. - `rights` string — Indicates whether the property is editable. Valid values are: - `editable` - `read_only` - `senderProvidedNumbers` string[] — An array containing a list of phone numbers that the recipient can use for SMS text authentication. - `senderProvidedNumbersMetadata` PropertyMetadata — Metadata about a property. - `options` string[] — An array of option strings supported by this setting. - `rights` string — Indicates whether the property is editable. Valid values are: - `editable` - `read_only` - `validateRecipProvidedNumber` string — Reserved for Docusign. - `validateRecipProvidedNumberMetadata` PropertyMetadata — Metadata about a property. - `options` string[] — An array of option strings supported by this setting. - `rights` string — Indicates whether the property is editable. Valid values are: - `editable` - `read_only` - `recipientId` string — A local reference used to map recipients to other objects, such as specific document tabs. A `recipientId` must be either an integer or a GUID, and the `recipientId` must be unique within an envelope. For example, many envelopes assign the first recipient a `recipientId` of `1`. - `recipientSignatureProviders` RecipientSignatureProvider[] — The default signature provider is the Docusign Electronic signature system. This parameter is used to specify one or more Standards Based Signature (digital signature) providers for the signer to use. [More information.](/docs/esign-rest-api/esign101/concepts/standards-based-signatures/) - `sealDocumentsWithTabsOnly` string — By default, electronic seals apply on all documents in an envelope. If any of the documents has a `signHere` tab, then a visual representation of the electronic seal will show up in the final document. If not, the electronic seal will be visible in the metadata but not in the content of the document. To apply electronic seals on specific documents only, you must enable the `sealDocumentsWithTabsOnly` parameter. In this case, Electronic Seal applies only on documents that have `signHere` tabs set for the Electronic Seal recipient. Other documents won't be sealed. - `sealName` string — Indicates the name of the electronic seal to apply on documents. - `signatureProviderName` string — The name of an Electronic or Standards Based Signature (digital signature) provider for the signer to use. For details, see [the current provider list](/docs/esign-rest-api/esign101/concepts/standards-based-signatures/). You can also retrieve the list by using the [AccountSignatureProviders: List](/docs/esign-rest-api/reference/accounts/accountsignatureproviders/list/) method. Example: `universalsignaturepen_default` - `signatureProviderNameMetadata` PropertyMetadata — Metadata about a property. - `options` string[] — An array of option strings supported by this setting. - `rights` string — Indicates whether the property is editable. Valid values are: - `editable` - `read_only` - `signatureProviderOptions` RecipientSignatureProviderOptions — Option settings for the signature provider. Different providers require or use different options. [The current provider list and the options they require.](/docs/esign-rest-api/esign101/concepts/standards-based-signatures/) - `cpfNumber` string — Reserved for Docusign. - `cpfNumberMetadata` PropertyMetadata — Metadata about a property. - `options` string[] — An array of option strings supported by this setting. - `rights` string — Indicates whether the property is editable. Valid values are: - `editable` - `read_only` - `oneTimePassword` string — A pre-shared secret that the signer must enter to complete the signing process. Eg last six digits of the signer's government ID or Social Security number. Or a newly created pre-shared secret for the transaction. Note: some signature providers may require an exact (case-sensitive) match if alphabetic characters are included in the field. - `oneTimePasswordMetadata` PropertyMetadata — Metadata about a property. - `options` string[] — An array of option strings supported by this setting. - `rights` string — Indicates whether the property is editable. Valid values are: - `editable` - `read_only` - `signerRole` string — The role or capacity of the signing recipient. Examples: Manager, Approver, etc. - `signerRoleMetadata` PropertyMetadata — Metadata about a property. - `options` string[] — An array of option strings supported by this setting. - `rights` string — Indicates whether the property is editable. Valid values are: - `editable` - `read_only` - `sms` string — The mobile phone number used to send the recipient an access code for the signing ceremony. Format: a string starting with +, then the country code followed by the full mobile phone number without any spaces or special characters. Omit leading zeroes before a city code. Examples: +14155551234, +97235551234, +33505551234. - `smsMetadata` PropertyMetadata — Metadata about a property. - `options` string[] — An array of option strings supported by this setting. - `rights` string — Indicates whether the property is editable. Valid values are: - `editable` - `read_only` - `roleName` string — The name of the role associated with the recipient. **Note:** Every recipient must be assigned either a `recipientId` or a `roleName` but not both. You cannot use `roleName` and `recipientId` in the same list. - `signerName` string — The in-person signer's full legal name. Required when `inPersonSigningType` is `inPersonSigner`. For eNotary flow, use `name` instead. Maximum Length: 100 characters. - `signingGroupId` string — The ID of the [signing group](https://support.docusign.com/s/document-item?bundleId=gav1643676262430&topicId=zgn1578456447934.html). - `smsAuthentication` RecipientSMSAuthentication — Contains the element senderProvidedNumbers which is an Array of phone numbers the recipient can use for SMS text authentication. - `senderProvidedNumbers` string[] — An array containing a list of phone numbers that the recipient can use for SMS text authentication. - `senderProvidedNumbersMetadata` PropertyMetadata — Metadata about a property. - `options` string[] — An array of option strings supported by this setting. - `rights` string — Indicates whether the property is editable. Valid values are: - `editable` - `read_only` - `socialAuthentications` SocialAuthentication[] — Deprecated. - `authentication` string — Reserved for Docusign. - `tabs` BulkSendingCopyTab[] — A list of tabs associated with the recipient. In a bulk send request, each of these recipient tabs must match a recipient tab on the envelope or template that you want to send. To match up, the `tabLabel` for this tab and the `tabLabel` for the corresponding tab on the envelope or template must be the same. For example, if the envelope has a placeholder text tab with the `tabLabel` `childName`, you must assign the same `tabLabel` `childName` to the tab here that you are populating with that information. You can use the following types of tabs to match bulk send recipients to an envelope: - Text tabs - Radio group tabs (where the name of the `radioGroup` on the envelope is used as the `tabLabel` in the bulk send list) - List tabs - `initialValue` string — The initial value that you want to assign to the tab. - `tabLabel` string — The label associated with the recipient tab. In a bulk send request, the `tabLabel` for this tab and the `tabLabel` for the corresponding tab on the envelope or template must be the same. Maximum Length: 500 characters. - `listId` string — The GUID of the bulk send list. - `name` string — The name of the bulk send list. ## Response `200` Successful response. ## Other responses - `400` — Error encountered. --- [API](https://skmtc.net/docusign/apis/docusign-esignature-rest-api.md) · [All operations](https://skmtc.net/docusign/apis/docusign-esignature-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/docusign/docusign-esignature-rest-api/versions/77f1998c313d/schema)