BulkSend: updateBulkSendList

This method replaces the definition of an existing bulk send list.

Request

HTTP request

PUT /v2.1/accounts/{accountId}/bulk_send_lists/{bulkSendListId}

Parameters

Parameter NameValueDescription
Path Parameters
accountIdstring

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

bulkSendListIdstring

The GUID of the bulk send list. This property is created after you post a new bulk send list.

Request Body

BulkSend

Responses

CodeDescriptionReference
200

Successful response.

BulkSend
400

Error encountered.

errorDetails

SDK Method

BulkEnvelopes::updateBulkSendList

Definitions

addressInformation

Contains address information.

address1string

The first line of the user's address. Maximum length: 100 characters.

address2string

The second line of the user's address. Maximum length: 100 characters.

citystring

The user's city.

countrystring

The user's country.

faxstring

A fax number associated with the address, if one is available.

phonestring

A phone number associated with the address.

postalCodestring

The user's postal code.

stateOrProvincestring

The user's state or province.

addressInformationInput

addressInformationaddressInformation

A complex type that contains the following information for the new account: address1, address2, city, country, fax, phone, postalCode and stateOrProvince.

The maximum characters for the strings are:

  • address1, address2, city, country and stateOrProvince: 100 characters
  • postalCode, phone, and fax: 20 characters

Note: If country is US (United States), stateOrProvince codes are validated. Otherwise, stateOrProvince is treated as a non-validated string used to specify a state, province, or region.

displayLevelCodestring

Specifies the display level for the recipient. Valid values are:

  • ReadOnly
  • Editable
  • DoNotDisplay

receiveInResponsestring

A Boolean value that specifies whether the information must be returned in the response.

bulkSendingCopy

This object contains the details to use for a specific copy, or instance, of the envelope. When you send an envelope by using a bulk send list, you can customize these properties for each instance.

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.

emailBlurbstring

The email body for this copy of the envelope.

emailSubjectstring

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.

recipients[bulkSendingCopyRecipient]

Information about the recipients associated with this copy of the envelope.

bulkSendingCopyCustomField

This object contains details about a custom field for a bulk send copy. In a bulk send request, each custom field in the bulk send list must match a custom field in the envelope or template that you want to send.

namestring

The name of the custom field.

valuestring

The value of the custom field.

bulkSendingCopyRecipient

This object contains details about a bulk send recipient.

accessCodestring

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.

clientUserIdstring

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.

Note: 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.

Maximum length: 100 characters.

customFields[array]

An optional array of strings that enables 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.

deliveryMethodstring

Reserved for DocuSign.

emailstring

The recipient's email address.

emailNotificationrecipientEmailNotification

An optional complex type that sets a specific email subject and body for this recipient's notification email.

Note: You can set the emailNotification property separately for each recipient. If you set the value only for certain recipients, the other recipients will inherit the this value from the top-level emailSubject and emailBlurb.

embeddedRecipientStartURLstring

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.

If set to 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]]

faxNumberstring

Reserved for DocuSign.

idCheckConfigurationNamestring

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.

idCheckInformationInputidCheckInformationInput

An object that contains input information related to a recipient ID check.

identificationMethodstring

namestring

notestring

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.

phoneAuthenticationrecipientPhoneAuthentication

When idCheckConfigurationName is set to Phone Auth $, you use this complex type to provide the recipient authentication method details. It contains the following elements:

  • recipMayProvideNumber: Boolean. When set to true, the recipient can use whatever phone number they choose.
  • senderProvidedNumbers: ArrayOfStrings. A list of phone numbers the recipient can use.
  • recordVoicePrint: Reserved for DocuSign.
  • validateRecipProvidedNumber: Reserved for DocuSign.

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.

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.

roleNamestring

The name of the role associated with the recipient. This property is optional and is only used in place of a recipientId.

smsAuthenticationrecipientSMSAuthentication

When idCheckConfigurationName is set to SMS Auth $, you use this complex type to provide the recipient authentication method details. It contains the element senderProvidedNumbers, which is an array of phone numbers that the recipient can use for SMS text authentication.

socialAuthentications[socialAuthentication]

Deprecated.

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

bulkSendingCopyTab

A tab associated with the bulk send recipient. In a bulk send request, each recipient tab 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.

initialValuestring

The initial value that you want to assign to the tab.

tabLabelstring

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.

dobInformationInput

dateOfBirthstring

Specifies the recipient's date, month, and year of birth.

displayLevelCodestring

Specifies the display level for the recipient. Valid values are:

  • ReadOnly
  • Editable
  • DoNotDisplay

receiveInResponsestring

A Boolean value that specifies whether the information must be returned in the response.

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.

idCheckInformationInput

A complex element that contains input information related to a recipient ID check.

addressInformationInputaddressInformationInput

An object that specifies recipient address information and how it is displayed.

dobInformationInputdobInformationInput

An object that specifies recipient date of birth information and how it is displayed.

ssn4InformationInputssn4InformationInput

An object that specifies the last four digits of the recipient's Social Security Number (SSN).

ssn9InformationInputssn9InformationInput

An object that specifies the recipient's Social Security Number (SSN) information. Note that ssn9 information cannot be returned in a response.

propertyMetadata

Metadata about a property.

options[array]

An array of option strings supported by this setting.

rightsstring

Indicates whether the property is editable. Valid values are:

  • editable
  • read_only

recipientEmailNotification

emailBodystring

The body of the email message.

emailBodyMetadatapropertyMetadata

Metadata that indicates whether the emailBody property can be edited.

emailSubjectstring

The subject line for the email notification.

emailSubjectMetadatapropertyMetadata

Metadata that indicates whether the emailSubject property can be edited.

supportedLanguagestring

The language to use for the standard email format and signing view for a recipient.

For example, in the recipient's email notification, this setting affects elements such as the standard introductory text describing the request to sign. 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 method.

supportedLanguageMetadatapropertyMetadata

Metadata that indicates whether the supportedLanguage property can be edited.

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.

recipMayProvideNumberstring

Boolean. When set to true, the recipient can supply a phone number their choice.

recipMayProvideNumberMetadatapropertyMetadata

Metadata that indicates whether the recipMayProvideNumber property can be edited.

recordVoicePrintstring

Reserved for DocuSign.

recordVoicePrintMetadatapropertyMetadata

Reserved for DocuSign.

senderProvidedNumbers[array]

An array containing a list of phone numbers that the recipient can use for SMS text authentication.

senderProvidedNumbersMetadatapropertyMetadata

Metadata that indicates whether the senderProvidedNumbers property can be edited.

validateRecipProvidedNumberstring

Reserved for DocuSign.

validateRecipProvidedNumberMetadatapropertyMetadata

Reserved for DocuSign.

recipientSignatureProvider

An Electronic or Standards Based Signature (digital signature) provider for the signer to use. More information.

sealDocumentsWithTabsOnlystring

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.

sealNamestring

Indicates the name of the electronic seal to apply on documents.

signatureProviderNamestring

The name of an Electronic or Standards Based Signature (digital signature) provider for the signer to use. For details, see the current provider list. You can also retrieve the list by using the AccountSignatureProviders::List method.

Example: universalsignaturepen_default

signatureProviderNameMetadatapropertyMetadata

Metadata that indicates whether the signatureProviderName property is editable.

signatureProviderOptionsrecipientSignatureProviderOptions

Not applicable for this object.

recipientSignatureProviderOptions

Option settings for the signature provider. Different providers require or use different options. The current provider list and the options they require.

cpfNumberstring

Reserved for DocuSign.

cpfNumberMetadatapropertyMetadata

Reserved for DocuSign.

oneTimePasswordstring

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.

oneTimePasswordMetadatapropertyMetadata

Metadata that indicates whether the oneTimePassword property is editable.

signerRolestring

The role or capacity of the signing recipient. Examples: Manager, Approver, etc.

signerRoleMetadatapropertyMetadata

Metadata that indicates whether the signerRole property is editable.

smsstring

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.

smsMetadatapropertyMetadata

Metadata that indicates whether the sms property is editable.

recipientSMSAuthentication

Contains the element senderProvidedNumbers which is an Array of phone numbers the recipient can use for SMS text authentication.

senderProvidedNumbers[array]

An array containing a list of phone numbers that the recipient can use for SMS text authentication.

senderProvidedNumbersMetadatapropertyMetadata

Metadata that indicates whether the senderProvidedNumbers property can be edited.

socialAuthentication

authenticationstring

Reserved for DocuSign.

ssn4InformationInput

displayLevelCodestring

Specifies the display level for the recipient. Valid values are:

  • ReadOnly
  • Editable
  • DoNotDisplay

receiveInResponsestring

A Boolean value that specifies whether the information must be returned in the response.

ssn4string

The last four digits of the recipient's Social Security Number (SSN).

ssn9InformationInput

displayLevelCodestring

Specifies the display level for the recipient. Valid values are:

  • ReadOnly
  • Editable
  • DoNotDisplay

ssn9string

The recipient's full Social Security Number (SSN).

BulkSend

The bulk send list resource provides methods that enable you to create and manage bulk sending lists, which you can use to send multiple copies of an envelope in a single batch.

Note: The Bulk Send feature is only available on Business Pro plans that are using EasySign.

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.

listIdstring

The GUID of the bulk send list. This property is created after you post a new bulk send list.

namestring

The name of the bulk send list.

}} />