Retrieves the bulk recipient file information from a template that has a bulk recipient.

Request

HTTP request

GET /v2.1/accounts/{accountId}/templates/{templateId}/recipients/{recipientId}/bulk_recipients

Parameters

Parameter NameValueDescription
Path Parameters
accountIdstring

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

recipientIdstring

The recipientId used when the envelope or template was created.

templateIdstring

The ID of the template.

Optional Query Parameters
include_tabsstring

When set to true, the tab information associated with the recipient is included in the response. If you do not specify this parameter, the effect is the default behavior (false).

start_positionstring

Reserved for DocuSign.

Responses

CodeDescriptionReference
200

Successful response.

TemplateBulkRecipients
400

Error encountered.

errorDetails

SDK Method

Templates::listBulkRecipients

Definitions

bulkRecipient

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.

emailstring

Specifies the recipient's email address.

Maximum length: 100 characters.

errorDetails[errorDetails]

Array or errors.

identificationstring

Specifies the authentication check used for the signer. If blank then no authentication check is required for the signer. Only one value can be used in this field.

The acceptable values are:

  • KBA: Enables the normal ID check authentication set up for your account.
  • Phone: Enables phone authentication.
  • SMS: Enables SMS authentication.

namestring

Specifies the recipient's name.

Maximum length: 50 characters.

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.

phoneNumberstring

This is only used if the Identification field value is Phone or SMS. The value for this field can be a valid telephone number or, if Phone, usersupplied (SMS authentication cannot use a user supplied number). Parenthesis and dashes can be used in the telephone number.

If usersupplied is used, the signer supplies his or her own telephone number.

recipientSignatureProviderInfo[bulkRecipientSignatureProvider]

rowNumberstring

tabLabels[bulkRecipientTabLabel]

Specifies values used to populate recipient tabs with information. This allows each bulk recipient signer to have different values for their associated tabs. Any number of tabLabel columns can be added to the bulk recipient file.

The information used in the bulk recipient file header must be the same as the tabLabel for the tab.

The values entered in this column are automatically inserted into the corresponding tab for the recipient in the same row.

Note that this option cannot be used for tabs that do not have data or that are automatically populated data such as Signature, Full Name, Email Address, Company, Title, and Date Signed tabs.

bulkRecipientSignatureProvider

namestring

valuestring

Specifies the value of the tab.

bulkRecipientTabLabel

namestring

valuestring

Specifies the value of the tab.

errorDetails

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

errorCodestring

A code associated with the error condition.

messagestring

A brief message describing the error condition.

TemplateBulkRecipients

Template bulk recipients

bulkRecipients[bulkRecipient]

A complex type containing information about the bulk recipients in the response.

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
{
  "bulkRecipients": [
    {
      "rowNumber": "sample string 1",
      "email": "sample string 2",
      "name": "sample string 3",
      "note": "sample string 4",
      "accessCode": "sample string 5",
      "identification": "sample string 6",
      "phoneNumber": "sample string 7",
      "tabLabels": [
        {
          "name": "sample string 1",
          "value": "sample string 2"
        }
      ],
      "recipientSignatureProviderInfo": [
        {
          "name": "sample string 1",
          "value": "sample string 2"
        }
      ],
      "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">
  <bulkRecipients>
    <bulkRecipient>
      <accessCode>sample string 5</accessCode>
      <email>sample string 2</email>
      <errorDetails>
        <errorDetails>
          <errorCode>sample string 1</errorCode>
          <message>sample string 2</message>
        </errorDetails>
      </errorDetails>
      <identification>sample string 6</identification>
      <name>sample string 3</name>
      <note>sample string 4</note>
      <phoneNumber>sample string 7</phoneNumber>
      <recipientSignatureProviderInfo>
        <bulkRecipientSignatureProvider>
          <name>sample string 1</name>
          <value>sample string 2</value>
        </bulkRecipientSignatureProvider>
      </recipientSignatureProviderInfo>
      <rowNumber>sample string 1</rowNumber>
      <tabLabels>
        <bulkRecipientTabLabel>
          <name>sample string 1</name>
          <value>sample string 2</value>
        </bulkRecipientTabLabel>
      </tabLabels>
    </bulkRecipient>
  </bulkRecipients>
  <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> 
}} />