Updates the bulk recipients in a draft envelope 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/accounts/{accountId}/envelopes/{envelopeId}/recipients/{recipientId}/bulk_recipients

Parameters

Parameter name Value Description
Path parameters
accountId string

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

envelopeId string

The envelope's GUID. Eg 93be49ab-afa0-4adf-933c-f752070d71ec

recipientId string

The recipientId used when the envelope or template was created.

Request Body

Responses

Code Description Reference
200 OK Successful response.
400 Bad Request Error encountered.

SDK Method

BulkEnvelopes::updateRecipients

Definitions Expand All | Collapse All

bulkRecipient

accessCode string

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.

email string

Specifies the recipient's email address.

Maximum length: 100 characters.

errorDetails
[errorDetails]

Array or errors.

identification string

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.
name string

Specifies the recipient's name.

Maximum length: 50 characters.

note string

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.

phoneNumber string

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]
rowNumber string
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

name string
value string

Specifies the value of the tab.

bulkRecipientTabLabel

name string
value string

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.

bulkRecipientsCount string

The number of items returned in this response.

bulkRecipientsUri string

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

errorDetails
[errorDetails]

Array or errors.

errorDetails

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

errorCode string

An error code associated with the error.

message string

A short error message.

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>