Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: DocuSign REST Template Bulk Recipients API
description: The DocuSign REST API provides you with a powerful, convenient, and simple Web services API for interacting with DocuSign.
termsOfService: https://www.docusign.com/company/terms-and-conditions/web
contact:
name: DocuSign Developer Center
url: https://developers.docusign.com/
email: devcenter@docusign.com
version: v2
servers:
- url: https://www.docusign.net/restapi
tags:
- name: TemplateBulkRecipients
description: "The TemplateBulkRecipients resource provide methods that allow you manage the bulk recipient file for an template.\n\nThe bulk recipient CSV (Comma Separated Value) file contains the list of recipient names and email addresses that you can add to an template to send the same document to a large number of recipients.\n \nThe required and optional information that can be included the file is described in the BulkEnvelope: updateRecipients method"
paths:
/v2/accounts/{accountId}/templates/{templateId}/recipients/{recipientId}/bulk_recipients:
get:
tags:
- TemplateBulkRecipients
summary: Docusign Gets the bulk recipient file from a template.
description: Retrieves the bulk recipient file information from a template that has a bulk recipient.
operationId: Recipients_GetTemplateBulkRecipients
parameters:
- name: accountId
in: path
description: The external account number (int) or account id GUID.
required: true
schema:
type: string
- name: recipientId
in: path
description: 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`.
required: true
schema:
type: string
- name: templateId
in: path
description: The ID of the template being accessed.
required: true
schema:
type: string
- name: include_tabs
in: query
description: When set to **true**, the tab information associated with the recipient is included in the response.
schema:
type: string
- name: start_position
in: query
description: 'Reserved for DocuSign.
'
schema:
type: string
responses:
'200':
description: Successful response.
content:
'*/*':
schema:
$ref: '#/components/schemas/bulkRecipientsResponse'
'400':
description: Error encountered.
content:
'*/*':
schema:
$ref: '#/components/schemas/errorDetails'
deprecated: false
x-ds-methodname: listBulkRecipients
x-ds-method: list
x-ds-service: Templates
x-ds-in-sdk: true
put:
tags:
- TemplateBulkRecipients
summary: Docusign Adds or replaces the bulk recipients list in a template.
description: '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.'
operationId: Recipients_PutTemplateBulkRecipients
parameters:
- name: accountId
in: path
description: The external account number (int) or account id GUID.
required: true
schema:
type: string
- name: recipientId
in: path
description: 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`.
required: true
schema:
type: string
- name: templateId
in: path
description: The ID of the template being accessed.
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/bulkRecipientsRequest'
application/xml:
schema:
$ref: '#/components/schemas/bulkRecipientsRequest'
required: false
responses:
'200':
description: Successful response.
content:
'*/*':
schema:
$ref: '#/components/schemas/bulkRecipientsSummaryResponse'
'400':
description: Error encountered.
content:
'*/*':
schema:
$ref: '#/components/schemas/errorDetails'
deprecated: false
x-ds-methodname: updateBulkRecipients
x-ds-method: update
x-ds-service: Templates
x-ds-in-sdk: true
x-codegen-request-body-name: bulkRecipientsRequest
delete:
tags:
- TemplateBulkRecipients
summary: Docusign Deletes the bulk recipient list on a template.
description: Deletes the bulk recipient list on a template.
operationId: Recipients_DeleteTemplateBulkRecipientsFile
parameters:
- name: accountId
in: path
description: The external account number (int) or account id GUID.
required: true
schema:
type: string
- name: recipientId
in: path
description: 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`.
required: true
schema:
type: string
- name: templateId
in: path
description: The ID of the template being accessed.
required: true
schema:
type: string
responses:
'200':
description: Successful response.
content:
'*/*':
schema:
$ref: '#/components/schemas/bulkRecipientsUpdateResponse'
'400':
description: Error encountered.
content:
'*/*':
schema:
$ref: '#/components/schemas/errorDetails'
deprecated: false
x-ds-methodname: deleteBulkRecipients
x-ds-method: delete
x-ds-service: Templates
x-ds-in-sdk: true
components:
schemas:
radioGroup:
type: object
properties:
conditionalParentLabel:
type: string
description: For conditional fields this is the TabLabel of the parent tab that controls this tab's visibility.
conditionalParentValue:
type: string
description: 'For conditional fields, this is the value of the parent tab that controls the tab''s visibility.
If the parent tab is a Checkbox, Radio button, Optional Signature, or Optional Initial use "on" as the value to show that the parent tab is active.
'
documentId:
type: string
description: Specifies the document ID number that the tab is placed on. This must refer to an existing Document's ID attribute.
groupName:
type: string
description: The name of the group. The search_text provided in the call automatically performs a wild card search on group_name.
radios:
type: array
description: Specifies the locations and status for radio buttons that are grouped together.
items:
$ref: '#/components/schemas/radio'
recipientId:
type: string
description: Unique for the recipient. It is used by the tab element to indicate which recipient is to sign the Document.
requireAll:
type: string
description: 'When set to **true** and shared is true, information must be entered in this field to complete the envelope. '
requireInitialOnSharedChange:
type: string
description: Optional element for field markup. When set to **true**, the signer is required to initial when they modify a shared field.
shared:
type: string
description: When set to **true**, this custom tab is shared.
templateLocked:
type: string
description: 'When set to **true**, the sender cannot change any attributes of the recipient. Used only when working with template recipients. '
templateRequired:
type: string
description: When set to **true**, the sender may not remove the recipient. Used only when working with template recipients.
tooltip:
type: string
description: ''
description: 'This group tab is used to place radio buttons on a document.
The `radios` property
contains a list of
[`radio`](https://developers.docusign.com/esign-rest-api/reference/Envelopes/EnvelopeRecipientTabs/create/#/definitions/radio)
objects associated with the group. Only one radio button can
be selected in a group.
'
x-ds-definition-name: radioGroup
x-ms-summary: 'This group tab is used to place radio buttons on a document.
The `radios` property
contains a list of
[`radio`](https://developers.docusign.com/esign-rest-api/reference/Envelopes/EnvelopeRecipientTabs/create/#/definitions/radio)
objects associated with the group. Only one radio button can
be selected in a group.
'
addressInformationInput:
type: object
properties:
addressInformation:
$ref: '#/components/schemas/addressInformation'
displayLevelCode:
type: string
description: "Specifies the display level for the recipient. \nValid values are: \n\n* ReadOnly\n* Editable\n* DoNotDisplay"
receiveInResponse:
type: string
description: When set to **true**, the information needs to be returned in the response.
description: Contains address input information.
x-ds-definition-name: addressInformationInput
x-ms-summary: Contains address input information.
recipientEmailNotification:
type: object
properties:
emailBody:
type: string
description: Not applicable
emailSubject:
type: string
description: Not applicable
supportedLanguage:
type: string
description: "Specifies the language used to localize Electronic Seals UI texts such as \"Sealed by\", etc. \n \nThe supported languages, with the language value shown in parenthesis, are: Arabic (ar), Bahasa Indonesia (id), Bahasa Melayu (ms) Bulgarian (bg), Czech (cs), Chinese Simplified (zh_CN), Chinese Traditional (zh_TW), Croatian (hr), Danish (da), Dutch (nl), English US (en), English UK (en_GB), Estonian (et), Farsi (fa), Finnish (fi), French (fr), French Canada (fr_CA), German (de), Greek (el), Hebrew (he), Hindi (hi), Hungarian (hu), Italian (it), Japanese (ja), Korean (ko), Latvian (lv), Lithuanian (lt), Norwegian (no), Polish (pl), Portuguese (pt), Portuguese Brazil (pt_BR), Romanian (ro),Russian (ru), Serbian (sr), Slovak (sk), Slovenian (sl), Spanish (es),Spanish Latin America (es_MX), Swedish (sv), Thai (th), Turkish (tr), Ukrainian (uk), and Vietnamese (vi). \n \nThis parameter is optional. If not set, it defaults to the sender’s language settings at time of sealing. "
description: ''
x-ds-definition-name: recipientEmailNotification
x-ms-summary: ''
recipientPhoneAuthentication:
type: object
properties:
recipMayProvideNumber:
type: string
description: Boolean. When set to **true**, the recipient can supply a phone number their choice.
recordVoicePrint:
type: string
description: Reserved.
senderProvidedNumbers:
type: array
description: 'An Array containing a list of phone numbers the recipient may use for SMS text authentication. '
items:
type: string
validateRecipProvidedNumber:
type: string
description: ' Reserved.'
description: 'A complex type that Contains the elements:
* recipMayProvideNumber - Boolean. When set to **true**, the recipient can use whatever phone number they choose.
* senderProvidedNumbers - ArrayOfString. A list of phone numbers the recipient can use.
* recordVoicePrint - Reserved.
* validateRecipProvidedNumber - Reserved.'
x-ds-definition-name: recipientPhoneAuthentication
x-ms-summary: 'A complex type that Contains the elements:
* recipMayProvideNumber - Boolean. When set to **true**, the recipient can use whatever phone number they choose.
* senderProvidedNumbers - ArrayOfString. A list of phone numbers the recipient can use.
* recordVoicePrint - Reserved.
* validateRecipProvidedNumber - Reserved.'
signerAttachment:
type: object
properties:
anchorCaseSensitive:
type: string
description: 'Reserved for DocuSign.
<!--
When set to **true**, the anchor string does not consider case when matching strings in the document. The default value is **true**.
-->'
anchorHorizontalAlignment:
type: string
description: 'Reserved for DocuSign.
<!--
Specifies the alignment of anchor tabs with anchor strings. Possible values are **left** or **right**. The default value is **left**.
-->
'
anchorIgnoreIfNotPresent:
type: string
description: When set to **true**, this tab is ignored if anchorString is not found in the document.
anchorMatchWholeWord:
type: string
description: 'Reserved for DocuSign.
<!--
When set to **true**, the anchor string in this tab matches whole words only (strings embedded in other strings are ignored.) The default value is **true**.
-->
'
anchorString:
type: string
description: Specifies the anchor string.
anchorUnits:
type: string
description: 'Specifies units of the
`anchorXOffset` and
`anchorYOffset`.
Valid units are:
- `pixels`
- `inches`
- `mms`
- `cms`
'
anchorXOffset:
type: string
description: 'Specifies the X axis location of the tab in `anchorUnits` relative to the `anchorString`.
'
anchorYOffset:
type: string
description: 'Specifies the Y axis location of the tab in `anchorUnits` relative to the `anchorString`.
'
conditionalParentLabel:
type: string
description: For conditional fields this is the TabLabel of the parent tab that controls this tab's visibility.
conditionalParentValue:
type: string
description: 'For conditional fields, this is the value of the parent tab that controls the tab''s visibility.
If the parent tab is a Checkbox, Radio button, Optional Signature, or Optional Initial use "on" as the value to show that the parent tab is active.
'
customTabId:
type: string
description: The DocuSign generated custom tab ID for the custom tab to be applied. This can only be used when adding new tabs for a recipient. When used, the new tab inherits all the custom tab properties.
documentId:
type: string
description: Specifies the document ID number that the tab is placed on. This must refer to an existing Document's ID attribute.
errorDetails:
$ref: '#/components/schemas/errorDetails'
mergeField:
$ref: '#/components/schemas/mergeField'
name:
type: string
description: ''
optional:
type: string
description: ''
pageNumber:
type: string
description: 'Specifies the page number on which the tab is located.
Must be 1 for supplemental documents.'
recipientId:
type: string
description: Unique for the recipient. It is used by the tab element to indicate which recipient is to sign the Document.
scaleValue:
type: number
description: ''
format: float
status:
type: string
description: 'Tab status
<!-- todo -->
'
tabGroupLabels:
type: array
description: ''
items:
type: string
tabId:
type: string
description: The unique identifier for the tab.
tabLabel:
type: string
description: 'The label string associated with the tab.
The string may be the empty string.
If no value is provided, the tab type is used as the value.
Maximum of 500 characters.
'
tabOrder:
type: string
description: 'A positive integer that sets the order the tab is navigated to during signing.
Tabs on a page are navigated to in ascending order, starting with the lowest number and moving to the highest. If two or more tabs have the same `tabOrder` value, the normal auto-navigation setting behavior for the envelope is used.'
templateLocked:
type: string
description: 'When set to **true**, the sender cannot change any attributes of the recipient. Used only when working with template recipients. '
templateRequired:
type: string
description: When set to **true**, the sender may not remove the recipient. Used only when working with template recipients.
tooltip:
type: string
description: ''
xPosition:
type: string
description: 'This property indicates the horizontal offset of the object on the page.
DocuSign uses 72 DPI when determining position.
Required. May be zero.
To improve the tab''s position on the document,
DocuSign recommends
adjusting `xPosition`
and `yPosition`
coordinates
by (+0, -24)
'
yPosition:
type: string
description: 'This property indicates the vertical offset of the object on the page.
DocuSign uses 72 DPI when determining position.
Required. May be zero.
To improve the tab''s position on the document,
DocuSign recommends
adjusting `xPosition`
and `yPosition`
coordinates
by (+0, -24)
'
description: 'A tab that allows the recipient to attach supporting
documents to an envelope.
'
x-ds-definition-name: signerAttachment
x-ms-summary: 'A tab that allows the recipient to attach supporting
documents to an envelope.
'
initialHere:
type: object
properties:
anchorCaseSensitive:
type: string
description: 'Reserved for DocuSign.
<!--
When set to **true**, the anchor string does not consider case when matching strings in the document. The default value is **true**.
-->'
anchorHorizontalAlignment:
type: string
description: 'Reserved for DocuSign.
<!--
Specifies the alignment of anchor tabs with anchor strings. Possible values are **left** or **right**. The default value is **left**.
-->
'
anchorIgnoreIfNotPresent:
type: string
description: When set to **true**, this tab is ignored if anchorString is not found in the document.
anchorMatchWholeWord:
type: string
description: 'Reserved for DocuSign.
<!--
When set to **true**, the anchor string in this tab matches whole words only (strings embedded in other strings are ignored.) The default value is **true**.
-->
'
anchorString:
type: string
description: Specifies the anchor string.
anchorUnits:
type: string
description: 'Specifies units of the
`anchorXOffset` and
`anchorYOffset`.
Valid units are:
- `pixels`
- `inches`
- `mms`
- `cms`
'
anchorXOffset:
type: string
description: 'Specifies the X axis location of the tab in `anchorUnits` relative to the `anchorString`.
'
anchorYOffset:
type: string
description: 'Specifies the Y axis location of the tab in `anchorUnits` relative to the `anchorString`.
'
conditionalParentLabel:
type: string
description: For conditional fields this is the TabLabel of the parent tab that controls this tab's visibility.
conditionalParentValue:
type: string
description: 'For conditional fields, this is the value of the parent tab that controls the tab''s visibility.
If the parent tab is a Checkbox, Radio button, Optional Signature, or Optional Initial use "on" as the value to show that the parent tab is active.
'
customTabId:
type: string
description: The DocuSign generated custom tab ID for the custom tab to be applied. This can only be used when adding new tabs for a recipient. When used, the new tab inherits all the custom tab properties.
documentId:
type: string
description: Specifies the document ID number that the tab is placed on. This must refer to an existing Document's ID attribute.
errorDetails:
$ref: '#/components/schemas/errorDetails'
mergeField:
$ref: '#/components/schemas/mergeField'
name:
type: string
description: Specifies the tool tip text for the tab.
optional:
type: string
description: ''
pageNumber:
type: string
description: 'Specifies the page number on which the tab is located.
Must be 1 for supplemental documents.
'
recipientId:
type: string
description: Unique for the recipient. It is used by the tab element to indicate which recipient is to sign the Document.
scaleValue:
type: number
description: ' Sets the size for the InitialHere tab. It can be value from 0.5 to 1.0, where 1.0 represents full size and 0.5 is 50% size.'
format: float
status:
type: string
description: 'Tab status
<!-- todo -->
'
tabGroupLabels:
type: array
description: ''
items:
type: string
tabId:
type: string
description: The unique identifier for the tab.
tabLabel:
type: string
description: 'The label string associated with the tab.
The string may be the empty string.
If no value is provided, the tab type is used as the value.
Maximum of 500 characters.
'
tabOrder:
type: string
description: 'A positive integer that sets the order the tab is navigated to during signing.
Tabs on a page are navigated to in ascending order, starting with the lowest number and moving to the highest. If two or more tabs have the same `tabOrder` value, the normal auto-navigation setting behavior for the envelope is used.'
templateLocked:
type: string
description: 'When set to **true**, the sender cannot change any attributes of the recipient. Used only when working with template recipients. '
templateRequired:
type: string
description: When set to **true**, the sender may not remove the recipient. Used only when working with template recipients.
tooltip:
type: string
description: ''
xPosition:
type: string
description: 'This property indicates the horizontal offset of the object on the page.
DocuSign uses 72 DPI when determining position.
Required. May be zero.
To improve the tab''s position on the document,
DocuSign recommends
adjusting `xPosition`
and `yPosition`
coordinates
by (+2, -23)
'
yPosition:
type: string
description: 'This property indicates the vertical offset of the object on the page.
DocuSign uses 72 DPI when determining position.
Required. May be zero.
To improve the tab''s position on the document,
DocuSign recommends
adjusting `xPosition`
and `yPosition`
coordinates
by (+2, -23)
'
description: 'A tab that allows the recipient to initial the document. May
be optional.
'
x-ds-definition-name: initialHere
x-ms-summary: 'A tab that allows the recipient to initial the document. May
be optional.
'
socialAuthentication:
type: object
properties:
authentication:
type: string
description: 'Reserved: TBD'
description: ''
x-ds-definition-name: socialAuthentication
x-ms-summary: ''
fullName:
type: object
properties:
anchorCaseSensitive:
type: string
description: 'Reserved for DocuSign.
<!--
When set to **true**, the anchor string does not consider case when matching strings in the document. The default value is **true**.
-->'
anchorHorizontalAlignment:
type: string
description: 'Reserved for DocuSign.
<!--
Specifies the alignment of anchor tabs with anchor strings. Possible values are **left** or **right**. The default value is **left**.
-->
'
anchorIgnoreIfNotPresent:
type: string
description: When set to **true**, this tab is ignored if anchorString is not found in the document.
anchorMatchWholeWord:
type: string
description: 'Reserved for DocuSign.
<!--
When set to **true**, the anchor string in this tab matches whole words only (strings embedded in other strings are ignored.) The default value is **true**.
-->
'
anchorString:
type: string
description: Specifies the anchor string.
anchorUnits:
type: string
description: 'Specifies units of the
`anchorXOffset` and
`anchorYOffset`.
Valid units are:
- `pixels`
- `inches`
- `mms`
- `cms`
'
anchorXOffset:
type: string
description: 'Specifies the X axis location of the tab in `anchorUnits` relative to the `anchorString`.
'
anchorYOffset:
type: string
description: 'Specifies the Y axis location of the tab in `anchorUnits` relative to the `anchorString`.
'
bold:
type: string
description: When set to **true**, the information in the tab is bold.
conditionalParentLabel:
type: string
description: For conditional fields this is the TabLabel of the parent tab that controls this tab's visibility.
conditionalParentValue:
type: string
description: 'For conditional fields, this is the value of the parent tab that controls the tab''s visibility.
If the parent tab is a Checkbox, Radio button, Optional Signature, or Optional Initial use "on" as the value to show that the parent tab is active.
'
customTabId:
type: string
description: The DocuSign generated custom tab ID for the custom tab to be applied. This can only be used when adding new tabs for a recipient. When used, the new tab inherits all the custom tab properties.
documentId:
type: string
description: Specifies the document ID number that the tab is placed on. This must refer to an existing Document's ID attribute.
errorDetails:
$ref: '#/components/schemas/errorDetails'
font:
type: string
description: 'The font to be used for the tab value. Supported Fonts include:
- Default
- Arial
- ArialNarrow
- Calibri
- CourierNew
- Garamond
- Georgia
- Helvetica
- LucidaConsole
- MSGothic
- MSMincho
- OCR-A
- Tahoma
- TimesNewRoman
- Trebuchet
- Verdana
'
fontColor:
type: string
description: "The font color used for the information in the tab. Possible values are: \n\n- Black\n- BrightBlue\n- BrightRed\n- DarkGreen\n- DarkRed\n- Gold\n- Green\n- NavyBlue\n- Purple\n- White\n"
fontSize:
type: string
description: 'The font size used for the information in the tab. Possible values are:
- Size7
- Size8
- Size9
- Size10
- Size11
- Size12
- Size14
- Size16
- Size18
- Size20
- Size22
- Size24
- Size26
- Size28
- Size36
- Size48
- Size72'
italic:
type: string
description: When set to **true**, the information in the tab is italic.
mergeField:
$ref: '#/components/schemas/mergeField'
name:
type: string
description: ''
pageNumber:
type: string
description: 'Specifies the page number on which the tab is located.
Must be 1 for supplemental documents.
'
recipientId:
type: string
description: Unique for the recipient. It is used by the tab element to indicate which recipient is to sign the Document.
status:
type: string
description: 'Tab status
<!-- todo -->
'
tabGroupLabels:
type: array
description: ''
items:
type: string
tabId:
type: string
description: The unique identifier for the tab.
tabLabel:
type: string
description: 'The label string associated with the tab.
The string may be the empty string.
If no value is provided, the tab type is used as the value.
Maximum of 500 characters.
'
tabOrder:
type: string
description: 'A positive integer that sets the order the tab is navigated to during signing.
Tabs on a page are navigated to in ascending order, starting with the lowest number and moving to the highest. If two or more tabs have the same `tabOrder` value, the normal auto-navigation setting behavior for the envelope is used.'
templateLocked:
type: string
description: 'When set to **true**, the sender cannot change any attributes of the recipient. Used only when working with template recipients. '
templateRequired:
type: string
description: When set to **true**, the sender may not remove the recipient. Used only when working with template recipients.
tooltip:
type: string
description: ''
underline:
type: string
description: When set to **true**, the information in the tab is underlined.
value:
type: string
# --- truncated at 32 KB (317 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/docusign/refs/heads/main/openapi/docusign-templatebulkrecipients-api-openapi.yml