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][BulkSendRequest] 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.

Recipients

  • 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.

Request

HTTP request

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

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

bulkSendRequest

Responses

CodeDescriptionReference
201

Successful response.

bulkSendTestResponse
400

Error encountered.

errorDetails

SDK Method

BulkEnvelopes::createBulkSendTestRequest

Definitions

bulkSendRequest

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

envelopeOrTemplateIdstring

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

bulkSendTestResponse

This object contains the results of a bulk send test.

canBeSentboolean

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.

validationErrorDetails[array]

Human-readable details about any validation errors that occurred.

validationErrors[array]

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

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

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.

}} />