Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: DocuSign REST Folders 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: Folders
description: The Folders resource provides methods that allow you to view contents of folders on the account and move envelopes between folders.
paths:
/v2/accounts/{accountId}/folders:
get:
tags:
- Folders
summary: Docusign Gets a list of the folders for the account.
description: Retrieves a list of the folders for the account, including the folder hierarchy. You can specify whether to return just the template folder or template folder and normal folders by setting the `template` query string parameter.
operationId: Folders_GetFolders
parameters:
- name: accountId
in: path
description: The external account number (int) or account id GUID.
required: true
schema:
type: string
- name: include
in: query
description: 'Reserved for DocuSign.
'
schema:
type: string
- name: start_position
in: query
description: 'Reserved for DocuSign.
'
schema:
type: string
- name: template
in: query
description: "Specifies the items that are returned. Valid values are: \n\n* include - The folder list will return normal folders plus template folders. \n* only - Only the list of template folders are returned."
schema:
type: string
- name: user_filter
in: query
description: 'Reserved for DocuSign.
'
schema:
type: string
responses:
'200':
description: Successful response.
content:
'*/*':
schema:
$ref: '#/components/schemas/foldersResponse'
'400':
description: Error encountered.
content:
'*/*':
schema:
$ref: '#/components/schemas/errorDetails'
deprecated: false
x-ds-methodname: list
x-ds-method: list
x-ds-service: Folders
x-ds-in-sdk: true
/v2/accounts/{accountId}/folders/{folderId}:
get:
tags:
- Folders
summary: Docusign Gets a list of the envelopes in the specified folder.
description: Retrieves a list of the envelopes in the specified folder. You can narrow the query by specifying search criteria in the query string parameters.
operationId: Folders_GetFolderItems
parameters:
- name: accountId
in: path
description: The external account number (int) or account id GUID.
required: true
schema:
type: string
- name: folderId
in: path
description: The ID of the folder being accessed.
required: true
schema:
type: string
- name: from_date
in: query
description: ' Only return items on or after this date. If no value is provided, the default search is the previous 30 days. '
schema:
type: string
- name: owner_email
in: query
description: ' The email of the folder owner. '
schema:
type: string
- name: owner_name
in: query
description: ' The name of the folder owner. '
schema:
type: string
- name: search_text
in: query
description: ' The search text used to search the items of the envelope. The search looks at recipient names and emails, envelope custom fields, sender name, and subject. '
schema:
type: string
- name: start_position
in: query
description: The position of the folder items to return. This is used for repeated calls, when the number of envelopes returned is too much for one return (calls return 100 envelopes at a time). The default value is 0.
schema:
type: string
- name: status
in: query
description: 'A comma-separated list of current envelope statuses to included in the response. Possible values are:
* completed
* created
* declined
* deleted
* delivered
* processing
* sent
* signed
* timedout
* voided
The `any` value is equivalent to any status.
'
schema:
type: string
- name: to_date
in: query
description: Only return items up to this date. If no value is provided, the default search is to the current date.
schema:
type: string
responses:
'200':
description: Successful response.
content:
'*/*':
schema:
$ref: '#/components/schemas/folderItemsResponse'
'400':
description: Error encountered.
content:
'*/*':
schema:
$ref: '#/components/schemas/errorDetails'
deprecated: false
x-ds-methodname: listItems
x-ds-method: listItems
x-ds-service: Folders
x-ds-in-sdk: true
put:
tags:
- Folders
summary: Docusign Moves an envelope from its current folder to the specified folder.
description: 'Moves an envelope from its current folder to the specified folder.
###### Note: You can use this endpoint to delete envelopes by specifying `recyclebin` in the `folderId` parameter of the endpoint. Placing an in process envelope (envelope status of `sent` or `delivered`) in the recycle bin voids the envelope. You can also use this endpoint to delete templates by specifying a template ID instead of an envelope ID in the ''envelopeIds'' property and specifying `recyclebin` in the `folderId` parameter. '
operationId: Folders_PutFolderById
parameters:
- name: accountId
in: path
description: The external account number (int) or account id GUID.
required: true
schema:
type: string
- name: folderId
in: path
description: The ID of the folder being accessed.
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/foldersRequest'
application/xml:
schema:
$ref: '#/components/schemas/foldersRequest'
required: false
responses:
'200':
description: Successful response.
content: {}
'400':
description: Error encountered.
content:
'*/*':
schema:
$ref: '#/components/schemas/errorDetails'
deprecated: false
x-ds-methodname: moveEnvelopes
x-ds-method: moveEnvelopes
x-ds-service: Folders
x-ds-in-sdk: true
x-codegen-request-body-name: foldersRequest
/v2/accounts/{accountId}/search_folders/{searchFolderId}:
get:
tags:
- Folders
summary: Docusign Gets a list of envelopes in folders matching the specified criteria.
description: 'Retrieves a list of envelopes that match the criteria specified in the query.
If the user ID of the user making the call is the same as the user ID for any returned recipient, then the userId property is added to the returned information for those recipients.'
operationId: SearchFolders_GetSearchFolderContents
parameters:
- name: accountId
in: path
description: The external account number (int) or account id GUID.
required: true
schema:
type: string
- name: searchFolderId
in: path
description: 'Specifies the envelope group that is searched by the request. These are logical groupings, not actual folder names. Valid values are: drafts, awaiting_my_signature, completed, out_for_signature.'
required: true
schema:
type: string
- name: all
in: query
description: Specifies that all envelopes that match the criteria are returned.
schema:
type: string
- name: count
in: query
description: Specifies the number of records returned in the cache. The number must be greater than 0 and less than or equal to 100.
schema:
type: string
- name: from_date
in: query
description: Specifies the start of the date range to return. If no value is provided, the default search is the previous 30 days.
schema:
type: string
- name: include_recipients
in: query
description: When set to **true**, the recipient information is returned in the response.
schema:
type: string
- name: order
in: query
description: 'Specifies the order in which the list is returned. Valid values are: `asc` for ascending order, and `desc` for descending order.'
schema:
type: string
- name: order_by
in: query
description: 'Specifies the property used to sort the list. Valid values are: `action_required`, `created`, `completed`, `sent`, `signer_list`, `status`, or `subject`.'
schema:
type: string
- name: start_position
in: query
description: Specifies the the starting location in the result set of the items that are returned.
schema:
type: string
- name: to_date
in: query
description: Specifies the end of the date range to return.
schema:
type: string
responses:
'200':
description: Successful response.
content:
'*/*':
schema:
$ref: '#/components/schemas/folderItemResponse'
'400':
description: Error encountered.
content:
'*/*':
schema:
$ref: '#/components/schemas/errorDetails'
deprecated: false
x-ds-methodname: search
x-ds-method: search
x-ds-service: Folders
x-ds-in-sdk: true
components:
schemas:
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.
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.'
recipientIdentityPhoneNumber:
type: object
properties:
countryCode:
type: string
description: ''
extension:
type: string
description: ''
number:
type: string
description: ''
description: ''
x-ds-definition-name: recipientIdentityPhoneNumber
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
description: 'Specifies the value of the tab. '
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 (-3, -2)
'
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 (-3, -2)
'
description: 'A tab that displays the recipient''s full name.
'
x-ds-definition-name: fullName
x-ms-summary: 'A tab that displays the recipient''s full name.
'
foldersResponse:
type: object
properties:
folders:
type: array
description: A collection of folder objects returned in a response.
items:
$ref: '#/components/schemas/folder'
description: ''
x-ds-definition-name: foldersResponse
x-ms-summary: ''
number:
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.
concealValueOnDocument:
type: string
description: 'When set to **true**, the field appears normally while the recipient is adding or modifying the information in the field, but the data is not visible (the characters are hidden by asterisks) to any other signer or the sender.
When an envelope is completed the information is available to the sender through the Form Data link in the DocuSign Console.
This setting applies only to text boxes and does not affect list boxes, radio buttons, or check boxes.'
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.
disableAutoSize:
type: string
description: When set to **true**, disables the auto sizing of single line text boxes in the signing screen when the signer enters data. If disabled users will only be able enter as much data as the text box can hold. By default this is false. This property only affects single line text boxes.
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'
formula:
type: string
description: 'Contains the formula
for calculating the value of
this tab.
Use a tab''s `tabLabel`,
enclosed in brackets,
to refer to it.
For example,
you want to present the total cost
of two items, tax included.
The cost of each item is stored
in number tabs labeled Item1 and Item2.
The tax rate is in a number tab
labeled TaxRate.
The formula string for this property
would be:
`([Item1] + [Item2]) * (1 + [TaxRate])`
See [Calculated Fields][calculatedfields]
in the DocuSign Support Center
to learn more about formulas.
Maximum Length: 2000 characters
[calculatedfields]: https://support.docusign.com/en/guides/ndse-user-guide-calculated-fields
'
isPaymentAmount:
type: string
description: 'When set to **true**, sets this as a payment tab. Can only be used with Text, Number, Formula, or List tabs. The value of the tab must be a number. '
italic:
type: string
description: When set to **true**, the information in the tab is italic.
locked:
type: string
description: When set to **true**, the signer cannot change the data of the custom tab.
maxLength:
type: integer
description: An optional value that describes the maximum length of the property when the property is a string.
format: int32
mergeField:
$ref: '#/components/schemas/mergeField'
name:
type: string
description: Specifies the tool tip text for the tab.
originalValue:
type: string
description: 'The initial value of the tab when it was sent to the recipient. '
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.
requireAll:
type: string
description: 'When set to **true** and shared is true, information must be entered in this field to complete the envelope. '
required:
type: string
description: When set to **true**, the signer is required to fill out this tab
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.
senderRequired:
type: string
description: "When set to **true**, the sender must populate the tab before an envelope can be sent using the template. \n\nThis value tab can only be changed by modifying (PUT) the template. \n\nTabs with a `senderRequired` value of true cannot be deleted from an envelope."
shared:
type: string
description: When set to **true**, this custom tab is shared.
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.
validationMessage:
type: string
description: The message displayed if the custom tab fails input validation (either custom of embedded).
validationPattern:
type: string
description: A regular expressionn used to validate input for the tab.
value:
type: string
description: 'Specifies the value of the tab. '
width:
type: integer
description: Width of the tab in pixels.
format: int32
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 (-3, -2)
'
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 (-3, -2)
'
description: 'A tab that allows the recipient to enter numbers and decimal
(.) points.
'
x-ds-definition-name: number
x-ms-summary: 'A tab that allows the recipient to enter numbers and decimal
(.)
# --- truncated at 32 KB (447 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/docusign/refs/heads/main/openapi/docusign-folders-api-openapi.yml