Updates the bulk recipients in a template using a file upload. The Content-Type supported for uploading a bulk recipient file is CSV (text/csv).

The REST API does not support modifying individual rows or values in the bulk recipients file. It only allows the entire file to be added or replaced with a new file.

Request

HTTP request

PUT /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

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.

templateIdstring

The id of the template.

Responses

CodeDescriptionReference
200

Successful response.

bulkRecipientsSummaryResponse
400

Error encountered.

errorDetails

SDK Method

Templates::updateBulkRecipients

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.

bulkRecipientsRequest

bulkRecipients[bulkRecipient]

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

bulkRecipientsSummaryResponse

bulkRecipients[bulkRecipient]

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

bulkRecipientsCountstring

The number of items returned in this response.

bulkRecipientsUristring

Contains a URI for an endpoint that allows you to easily retrieve bulk recipient information.

errorDetails[errorDetails]

Array or errors.

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

The code associated with the error condition.

messagestring

A brief message describing the error condition.

Examples

Generic JSON Request/Response

Request
{
  "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"
        }
      ]
    }
  ]
}
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"
        }
      ]
    }
  ],
  "errorDetails": [
    {
      "errorCode": "SUCCESS",
      "message": ""
    }
  ],
  "bulkRecipientsCount": "sample string 1",
  "bulkRecipientsUri": "sample string 2"
}
Generic XML Request/Response

Request
<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>
      <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>
</xml> 
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>
  <bulkRecipientsCount>sample string 1</bulkRecipientsCount>
  <bulkRecipientsUri>sample string 2</bulkRecipientsUri>
  <errorDetails>
    <errorDetails>
      <errorCode>SUCCESS</errorCode>
      <message></message>
    </errorDetails>
  </errorDetails>
</xml> 
}} />