Retrieves status information about all the bulk recipient batches. A bulk recipient batch is the set of envelopes sent from a single bulk recipient file. The response includes general information about each bulk recipient batch.

The response returns information about the envelopes sent with bulk recipient batches, including the batchId property, which can be used to retrieve a more detailed status of individual bulk recipient batches.

Request

HTTP request

GET /v2/accounts/{accountId}/bulk_envelopes

Parameters

Parameter NameValueDescription
Path Parameters
accountIdstring

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

Optional Query Parameters
countstring

The number of results to return. This can be 1 to 20.

includestring

Specifies which entries are included in the response. Multiple entries can be included by using commas in the query string (example: ?include="failed,queued")

Valid values:

  • all - Returns all entries. If present, overrides all other query settings. This is the default if no query string is provided.
  • failed - Entries with a failed status.
  • processing - Entries with a processing status.
  • queued - Entries with a queued status.
  • sent - Entries with a sent status.

start_positionstring

The position of the bulk envelope items in the response. This is used for repeated calls, when the number of bulk envelopes returned is too large for one return. The default value is 0.

Responses

CodeDescriptionReference
200

Successful response.

BulkEnvelopes
400

Error encountered.

errorDetails

SDK Method

BulkEnvelopes::list

Definitions

bulkEnvelope

bulkRecipientRowstring

Reserved: TBD

bulkStatusstring

Indicates the status of the bulk send operation. Returned values can be:

  • queued
  • processing
  • sent
  • failed

emailstring

envelopeIdstring

The envelope ID of the envelope status that failed to post.

envelopeUristring

Contains a URI for an endpoint that you can use to retrieve the envelope or envelopes.

errorDetailserrorDetails

namestring

submittedDateTimestring

transactionIdstring

Used to identify an envelope. The id is a sender-generated value and is valid in the DocuSign system for 7 days. It is recommended that a transaction ID is used for offline signing to ensure that an envelope is not sent multiple times. The transactionId property can be used determine an envelope's status (i.e. was it created or not) in cases where the internet connection was lost before the envelope status was returned.

bulkEnvelopeStatus

batchIdstring

Specifies an identifier which can be used to retrieve a more detailed status of individual bulk recipient batches.

batchSizestring

The number of items returned in this response.

bulkEnvelopes[bulkEnvelope]

Reserved: TBD

bulkEnvelopesBatchUristring

Reserved: TBD

endPositionstring

The last position in the result set.

failedstring

The number of entries with a status of failed.

nextUristring

The URI for the next chunk of records based on the search request. It is null if this is the last set of results for the search.

previousUristring

The URI for the prior chunk of records based on the search request. It is null if this is the first set of results for the search.

queuedstring

The number of entries with a status of queued.

resultSetSizestring

The number of results returned in this response.

sentstring

The number of entries with a status of sent.

startPositionstring

Starting position of the current result set.

submittedDatestring

totalSetSizestring

The total number of items in the search's result set. It will always be greater than or equal to the value of the resultSetSize field.

errorDetails

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

errorCodestring

An error code associated with the error.

messagestring

A short error message.

BulkEnvelopes

Bulk envelopes

bulkEnvelopeStatuses[bulkEnvelopeStatus]

Reserved: TBD

endPositionstring

The last position in the result set.

nextUristring

The URI for the next chunk of records based on the search request. It is null if this is the last set of results for the search.

previousUristring

The URI for the prior chunk of records based on the search request. It is null if this is the first set of results for the search.

resultSetSizestring

The number of results returned in this response.

startPositionstring

Starting position of the current result set.

totalSetSizestring

The total number of items in the search's result set. It will always be greater than or equal to the value of the resultSetSize field.

Examples

Generic JSON Response

Response
{
  "bulkEnvelopeStatuses": [
    {
      "batchSize": "sample string 1",
      "batchId": "sample string 2",
      "bulkEnvelopesBatchUri": "sample string 3",
      "failed": "sample string 4",
      "queued": "sample string 5",
      "sent": "sample string 6",
      "submittedDate": "sample string 7",
      "resultSetSize": "sample string 8",
      "startPosition": "sample string 9",
      "endPosition": "sample string 10",
      "totalSetSize": "sample string 11",
      "nextUri": "sample string 12",
      "previousUri": "sample string 13",
      "bulkEnvelopes": [
        {
          "transactionId": "sample string 1",
          "submittedDateTime": "sample string 2",
          "envelopeId": "sample string 3",
          "envelopeUri": "sample string 4",
          "bulkRecipientRow": "sample string 5",
          "name": "sample string 6",
          "email": "sample string 7",
          "bulkStatus": "sample string 8",
          "errorDetails": {
            "errorCode": "sample string 1",
            "message": "sample string 2"
          }
        }
      ]
    }
  ],
  "resultSetSize": "sample string 1",
  "startPosition": "sample string 2",
  "endPosition": "sample string 3",
  "totalSetSize": "sample string 4",
  "nextUri": "sample string 5",
  "previousUri": "sample string 6"
}
Generic XML Response

Response
<xml xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.docusign.com/restapi">
  <bulkEnvelopeStatuses>
    <bulkEnvelopeStatus>
      <batchId>sample string 2</batchId>
      <batchSize>sample string 1</batchSize>
      <bulkEnvelopes>
        <bulkEnvelope>
          <bulkRecipientRow>sample string 5</bulkRecipientRow>
          <bulkStatus>sample string 8</bulkStatus>
          <email>sample string 7</email>
          <envelopeId>sample string 3</envelopeId>
          <envelopeUri>sample string 4</envelopeUri>
          <errorDetails>
            <errorCode>sample string 1</errorCode>
            <message>sample string 2</message>
          </errorDetails>
          <name>sample string 6</name>
          <submittedDateTime>sample string 2</submittedDateTime>
          <transactionId>sample string 1</transactionId>
        </bulkEnvelope>
      </bulkEnvelopes>
      <bulkEnvelopesBatchUri>sample string 3</bulkEnvelopesBatchUri>
      <endPosition>sample string 10</endPosition>
      <failed>sample string 4</failed>
      <nextUri>sample string 12</nextUri>
      <previousUri>sample string 13</previousUri>
      <queued>sample string 5</queued>
      <resultSetSize>sample string 8</resultSetSize>
      <sent>sample string 6</sent>
      <startPosition>sample string 9</startPosition>
      <submittedDate>sample string 7</submittedDate>
      <totalSetSize>sample string 11</totalSetSize>
    </bulkEnvelopeStatus>
  </bulkEnvelopeStatuses>
  <endPosition>sample string 3</endPosition>
  <nextUri>sample string 5</nextUri>
  <previousUri>sample string 6</previousUri>
  <resultSetSize>sample string 1</resultSetSize>
  <startPosition>sample string 2</startPosition>
  <totalSetSize>sample string 4</totalSetSize>
</xml> 
}} />