openapi: 3.0.1
info:
title: DocuSign Admin AccountBrands EnvelopeDocuments API
description: An API for an organization administrator to manage organizations, accounts and users
termsOfService: https://www.docusign.com/company/terms-and-conditions/developers
contact:
name: DocuSign Developer Center
url: https://developers.docusign.com
email: devcenter@docusign.com
version: v2.1
servers:
- url: https://api.docusign.net/Management
tags:
- name: EnvelopeDocuments
description: Manage documents within envelopes including adding, retrieving, and deleting documents attached to envelopes.
externalDocs:
url: https://developers.docusign.com/docs/esign-rest-api/reference/envelopes/envelopedocuments/
paths:
/accounts/{accountId}/envelopes/{envelopeId}/documents:
get:
operationId: EnvelopeDocuments_ListDocuments
summary: Docusign List Envelope Documents
description: Retrieves a list of documents associated with the specified envelope. Returns metadata about each document including the document ID, name, type, and order.
tags:
- EnvelopeDocuments
parameters:
- $ref: '#/components/parameters/accountId'
- $ref: '#/components/parameters/envelopeId'
responses:
'200':
description: Successfully retrieved document list.
content:
application/json:
schema:
$ref: '#/components/schemas/EnvelopeDocumentsResult'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/accounts/{accountId}/envelopes/{envelopeId}/documents/{documentId}:
get:
operationId: EnvelopeDocuments_GetDocument
summary: Docusign Get an Envelope Document
description: Retrieves the specified document from the envelope. Returns the document content as a PDF or other supported format.
tags:
- EnvelopeDocuments
parameters:
- $ref: '#/components/parameters/accountId'
- $ref: '#/components/parameters/envelopeId'
- name: documentId
in: path
required: true
description: The unique identifier of the document within the envelope. Use "combined" to retrieve all documents as a single PDF.
schema:
type: string
responses:
'200':
description: Successfully retrieved the document.
content:
application/pdf:
schema:
type: string
format: binary
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/v2/accounts/{accountId}/envelopes/{envelopeId}/documents:
get:
tags:
- EnvelopeDocuments
summary: Docusign Gets a list of envelope documents.
description: Retrieves a list of documents associated with the specified envelope.
operationId: Documents_GetDocuments
parameters:
- name: accountId
in: path
description: The external account number (int) or account id GUID.
required: true
schema:
type: string
- name: envelopeId
in: path
description: 'The envelope''s GUID. Eg 93be49ab-afa0-4adf-933c-f752070d71ec '
required: true
schema:
type: string
- name: include_document_size
in: query
schema:
type: string
responses:
'200':
description: Successful response.
content:
'*/*':
schema:
$ref: '#/components/schemas/envelopeDocumentsResult'
'400':
description: Error encountered.
content:
'*/*':
schema:
$ref: '#/components/schemas/errorDetails'
deprecated: false
x-ds-methodname: listDocuments
x-ds-method: list
x-ds-service: Envelopes
x-ds-in-sdk: true
x-ds-examples:
- description: 'This example shows how
to get a list
of all the documents in an envelope.
The request for this endpoint has no payload.
### Request
```
GET /restapi/v2/accounts/1703061/envelopes/44efc9e6-915e-4b1d-9b54-801410d6922d/documents
```
'
direction: response
format: json
response:
envelopeDocuments:
- availableDocumentTypes:
- isDefault: 'true'
type: electronic
display: inline
documentId: '1'
includeInDownload: 'true'
name: NDA.pdf
order: '1'
pages: '3'
signerMustAcknowledge: no_interaction
type: content
uri: /envelopes/44efc9e6-915e-4b1d-9b54-801410d6922d/documents/1
- availableDocumentTypes:
- isDefault: 'true'
type: electronic
display: inline
documentId: '2'
includeInDownload: 'true'
name: House.pdf
order: '2'
pages: '1'
signerMustAcknowledge: no_interaction
type: content
uri: /envelopes/44efc9e6-915e-4b1d-9b54-801410d6922d/documents/2
- availableDocumentTypes:
- isDefault: 'true'
type: electronic
display: inline
documentId: '3'
includeInDownload: 'true'
name: contractor_agreement.docx
order: '3'
pages: '2'
signerMustAcknowledge: no_interaction
type: content
uri: /envelopes/44efc9e6-915e-4b1d-9b54-801410d6922d/documents/3
- availableDocumentTypes:
- isDefault: 'true'
type: electronic
display: inline
documentId: certificate
includeInDownload: 'true'
name: Summary
order: '999'
pages: '4'
signerMustAcknowledge: no_interaction
type: summary
uri: /envelopes/44efc9e6-915e-4b1d-9b54-801410d6922d/documents/certificate
envelopeId: 44efc9e6-915e-4b1d-9b54-801410d6922d
style: custom
title: List All Documents in an Envelope
put:
tags:
- EnvelopeDocuments
summary: Docusign Adds one or more documents to an existing envelope document.
description: 'Adds one or more documents to an existing envelope document.
<p>**Note**: When adding or modifying documents for an in-process envelope, DocuSign recommends locking the envelope prior to making any changes.'
operationId: Documents_PutDocuments
parameters:
- name: accountId
in: path
description: The external account number (int) or account id GUID.
required: true
schema:
type: string
- name: envelopeId
in: path
description: 'The envelope''s GUID. Eg 93be49ab-afa0-4adf-933c-f752070d71ec '
required: true
schema:
type: string
- name: apply_document_fields
in: query
description: 'When **true**, document fields
can be added or modified
while adding or modifying envelope documents.
'
schema:
type: string
- name: persist_tabs
in: query
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/envelopeDefinition'
application/xml:
schema:
$ref: '#/components/schemas/envelopeDefinition'
required: false
responses:
'200':
description: Successful response.
content:
'*/*':
schema:
$ref: '#/components/schemas/envelopeDocumentsResult'
'400':
description: Error encountered.
content:
'*/*':
schema:
$ref: '#/components/schemas/errorDetails'
deprecated: false
x-ds-methodname: updateDocuments
x-ds-method: updateList
x-ds-service: Envelopes
x-ds-in-sdk: true
x-codegen-request-body-name: envelopeDefinition
delete:
tags:
- EnvelopeDocuments
summary: Docusign Deletes documents from a draft envelope.
description: "Deletes one or more documents from an existing envelope that has not yet been completed.\n\nTo delete a document, use only the relevant parts of the [`envelopeDefinition`](#envelopeDefinition).\nFor example, this request body specifies that you want to delete the document whose `documentId` is \"1\".\n\n\n```text\n{\n \"documents\": [\n {\n \"documentId\": \"1\"\n }\n ]\n}\n```\n\nThe envelope status must be one of:\n\n- `created`\n- `sent`\n- `delivered`\n\n\n"
operationId: Documents_DeleteDocuments
parameters:
- name: accountId
in: path
description: The external account number (int) or account id GUID.
required: true
schema:
type: string
- name: envelopeId
in: path
description: 'The envelope''s GUID. Eg 93be49ab-afa0-4adf-933c-f752070d71ec '
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/envelopeDefinition'
application/xml:
schema:
$ref: '#/components/schemas/envelopeDefinition'
required: false
responses:
'200':
description: Successful response.
content:
'*/*':
schema:
$ref: '#/components/schemas/envelopeDocumentsResult'
'400':
description: Error encountered.
content:
'*/*':
schema:
$ref: '#/components/schemas/errorDetails'
deprecated: false
x-ds-methodname: deleteDocuments
x-ds-method: delete
x-ds-service: Envelopes
x-ds-in-sdk: true
x-codegen-request-body-name: envelopeDefinition
/v2/accounts/{accountId}/envelopes/{envelopeId}/documents/{documentId}:
get:
tags:
- EnvelopeDocuments
summary: Docusign Gets a document from an envelope.
description: 'Retrieves the specified document from the envelope. If the account has the Highlight Data Changes feature enabled, there is an option to request that any changes in the envelope be highlighted.
The `{documentID}` parameter takes two special values:
| Value | Description |
| :--- | :--- |
| `combined` | Retrieve a PDF that contains the combined content of all documents and the certificate. |
| `archive` | Retrieve a ZIP archive that contains all of the PDF documents, the certificate, and any .WAV files used for voice authentication. |
'
operationId: Documents_GetDocument
parameters:
- name: accountId
in: path
description: The external account number (int) or account id GUID.
required: true
schema:
type: string
- name: documentId
in: path
description: The ID of the document being accessed.
required: true
schema:
type: string
- name: envelopeId
in: path
description: 'The envelope''s GUID. Eg 93be49ab-afa0-4adf-933c-f752070d71ec '
required: true
schema:
type: string
- name: certificate
in: query
description: When set to **false**, the envelope signing certificate is removed from the download.
schema:
type: string
- name: encoding
in: query
schema:
type: string
- name: encrypt
in: query
description: When set to **true**, the PDF bytes returned in the response are encrypted for all the key managers configured on your DocuSign account. The documents can be decrypted with the KeyManager Decrypt Document API.
schema:
type: string
- name: language
in: query
description: 'Specifies the language for the Certificate of Completion in the response. The supported languages, with the language value shown in parenthesis, are: Chinese Simplified (zh_CN), , Chinese Traditional (zh_TW), Dutch (nl), English US (en), French (fr), German (de), Italian (it), Japanese (ja), Korean (ko), Portuguese (pt), Portuguese (Brazil) (pt_BR), Russian (ru), Spanish (es). '
schema:
type: string
- name: recipient_id
in: query
schema:
type: string
- name: show_changes
in: query
description: 'When set to **true**, any changed fields for the returned PDF are highlighted in yellow and optional signatures or initials outlined in red. '
schema:
type: string
- name: watermark
in: query
description: 'When set to **true**, the account has the watermark feature enabled, and the envelope is not complete, the watermark for the account is added to the PDF documents. This option can remove the watermark. '
schema:
type: string
responses:
'200':
description: Successful response.
content:
application/pdf:
schema:
type: string
format: binary
'400':
description: Error encountered.
content:
application/pdf:
schema:
$ref: '#/components/schemas/errorDetails'
deprecated: false
x-ds-methodname: getDocument
x-ds-method: get
x-ds-service: Envelopes
x-ds-in-sdk: true
x-ds-examples:
- description: 'This example shows how to retrieve
a single document from an envelope
as a PDF file.
The request for this endpoint has no payload.
### Request
```
GET /restapi/v2/accounts/1703061/envelopes/44efc9e6-915e-4b1d-9b54-801410d6922d/documents/3
```
'
direction: response
format: json
response: PDF File
style: custom
title: Get a Single Document as a PDF File
- description: 'If you use `combined` instead of a document id
the response is a PDF file that contains
all of the documents in the specified envelope.
The request for this endpoint has no payload.
### Request
```
GET /restapi/v2/accounts/1703061/envelopes/44efc9e6-915e-4b1d-9b54-801410d6922d/documents/combined
```
'
direction: response
format: json
response: PDF File
style: custom
title: Get All Documents as a Single PDF File
- description: 'This example shows how
to get a list
of all the documents in an envelope.
The request for this endpoint has no payload.
### Request
```
GET /restapi/v2/accounts/1703061/envelopes/44efc9e6-915e-4b1d-9b54-801410d6922d/documents
```
'
direction: response
format: json
response:
envelopeDocuments:
- availableDocumentTypes:
- isDefault: 'true'
type: electronic
display: inline
documentId: '1'
includeInDownload: 'true'
name: NDA.pdf
order: '1'
pages: '3'
signerMustAcknowledge: no_interaction
type: content
uri: /envelopes/44efc9e6-915e-4b1d-9b54-801410d6922d/documents/1
- availableDocumentTypes:
- isDefault: 'true'
type: electronic
display: inline
documentId: '2'
includeInDownload: 'true'
name: House.pdf
order: '2'
pages: '1'
signerMustAcknowledge: no_interaction
type: content
uri: /envelopes/44efc9e6-915e-4b1d-9b54-801410d6922d/documents/2
- availableDocumentTypes:
- isDefault: 'true'
type: electronic
display: inline
documentId: '3'
includeInDownload: 'true'
name: contractor_agreement.docx
order: '3'
pages: '2'
signerMustAcknowledge: no_interaction
type: content
uri: /envelopes/44efc9e6-915e-4b1d-9b54-801410d6922d/documents/3
- availableDocumentTypes:
- isDefault: 'true'
type: electronic
display: inline
documentId: certificate
includeInDownload: 'true'
name: Summary
order: '999'
pages: '4'
signerMustAcknowledge: no_interaction
type: summary
uri: /envelopes/44efc9e6-915e-4b1d-9b54-801410d6922d/documents/certificate
envelopeId: 44efc9e6-915e-4b1d-9b54-801410d6922d
style: custom
title: List All Documents in an Envelope
put:
tags:
- EnvelopeDocuments
summary: Docusign Adds a document to an existing draft envelope.
description: 'Adds a document to an existing draft envelope.
<p>**Note**: When adding or modifying documents for an in-process envelope, DocuSign recommends locking the envelope prior to making any changes.'
operationId: Documents_PutDocument
parameters:
- name: accountId
in: path
description: The external account number (int) or account id GUID.
required: true
schema:
type: string
- name: documentId
in: path
description: The ID of the document being accessed.
required: true
schema:
type: string
- name: envelopeId
in: path
description: 'The envelope''s GUID. Eg 93be49ab-afa0-4adf-933c-f752070d71ec '
required: true
schema:
type: string
- name: apply_document_fields
in: query
description: 'When **true**, document fields
can be added or modified
while adding or modifying envelope documents.
'
schema:
type: string
responses:
'200':
description: Successful response.
content: {}
'400':
description: Error encountered.
content:
'*/*':
schema:
$ref: '#/components/schemas/errorDetails'
deprecated: false
x-ds-methodname: updateDocument
x-ds-method: update
x-ds-service: Envelopes
x-ds-in-sdk: true
components:
schemas:
samlAssertionAttribute:
type: object
properties:
errorDetails:
$ref: '#/components/schemas/errorDetails'
name:
type: string
description: ''
originalValue:
type: string
description: 'The initial value of the tab when it was sent to the recipient. '
value:
type: string
description: The value associated with the named SAML assertion attribute
description: ''
x-ds-definition-name: samlAssertionAttribute
x-ms-summary: ''
signatureType:
type: object
properties:
isDefault:
type: string
description: ''
type:
type: string
description: 'Type of the user. Valid values: type_owner, type_participant.'
description: ''
x-ds-definition-name: signatureType
x-ms-summary: ''
company:
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'
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.
required:
type: string
description: When set to **true**, the signer is required to fill out this tab
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. '
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 displays the recipient''s company name.
'
x-ds-definition-name: company
x-ms-summary: 'A tab that displays the recipient''s company name.
'
serverTemplate:
type: object
properties:
sequence:
type: string
description: ''
templateId:
type: string
description: 'The unique identifier of the template. If this is not provided, DocuSign will generate a value. '
description: ''
x-ds-definition-name: serverTemplate
x-ms-summary: ''
recipientProofFile:
type: object
properties:
isInProofFile:
type: string
description: ''
description: ''
x-ds-definition-name: recipientProofFile
x-ms-summary: ''
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
# --- truncated at 32 KB (505 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/docusign/refs/heads/main/openapi/docusign-envelopedocuments-api-openapi.yml