BulkSend: createBulkSendTestRequest

This method tests a bulk send list for compatibility with the envelope or template that you want to send. For example, a template that has three roles is not compatible with a bulk send list that has only two recipients. For this reason, you might want to test compatibility first.

A successful test result returns true for the canBeSent property. An unsuccessful test returns a JSON response that contains information about the errors that occurred.

If the test is successful, you can then send the envelope or template by using the BulkSend::createBulkSendRequest method.

Envelope Compatibility Checks

This section describes the envelope compatibility checks that the system performs.

Top-Level Issues

  • Envelopes must be in a sendable state.
  • The bulk send list must contain at least one copy (instance of an envelope), and no more than the maximum number of copies allowed for the account.
  • The envelope must not be null and must be visible to the current user.
  • The account cannot have more queued envelopes than the maximum number configured for the account.
  • The bulk send list must exist.


  • The envelope must have recipients.
  • If you are using an envelope, all of the recipients defined in the bulk send list must have corresponding recipient IDs in the envelope definition. If you are using a template, you must either match the recipient IDs or role IDs.
  • The envelope cannot contain a bulk recipient (an artifact of the legacy version of DocuSign's bulk send functionality).

Recipient Tabs

  • Every recipient ID, tab label pair in the bulk send list must correspond to a tab in the envelope.

Custom Fields

  • Each envelope-level custom field in the bulk send list must correspond to the name of a customField in the envelope definition. You do not have to match the recipient-level custom fields.


HTTP request

POST /restapi/v2.1/accounts/{accountId}/bulk_send_lists/{bulkSendListId}/test


Parameter NameValueDescription
Path Parameters

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


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

Request Body




Successful response.


Error encountered.


SDK Method




This object contains information about the envelope or template that you want to send in bulk.


The GUID of the envelope or template that you want to send in bulk.


This object contains the results of a bulk send test.


When true, the envelope or template is compatible with the bulk send list and can be sent by using the BulkSend::createBulkSendRequest method.

Note: This property is only returned in responses and ignored in requests.


Human-readable details about any validation errors that occurred.


A list of validation errors that were encountered during the bulk send test.

Note: This information is intended to be parsed by machine.


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


The code associated with the error condition.


A brief message describing the error condition.

}} />