Retrieves a list of documents associated with the specified envelope.

Request

HTTP request

GET /v2.1/accounts/{accountId}/envelopes/{envelopeId}/documents

Parameters

Parameter NameValueDescription
Path Parameters
accountIdstring

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

envelopeIdstring

The envelope's GUID.

Example: 93be49ab-afa0-4adf-933c-f752070d71ec

Optional Query Parameters
documents_by_useridstring

When set to true, allows recipients to get documents by their user id. For example, if a user is included in two different routing orders with different visibilities, using this parameter returns all of the documents from both routing orders.

include_metadatastring

When set to true, the response includes metadata that indicates which properties the sender can edit.

include_tabsstring

When set to true, information about the tabs associated with the documents are included in the response.

recipient_idstring

Allows the sender to retrieve the documents as one of the recipients that they control. The documents_by_userid parameter must be set to false for this to work.

shared_user_idstring

The ID of a shared user that you want to impersonate in order to retrieve their view of the list of documents. This parameter is used in the context of a shared inbox (i.e., when you share envelopes from one user to another through the RADmin console).

Responses

CodeDescriptionReference
200

Successful response.

EnvelopeDocuments
400

Error encountered.

errorDetails

SDK Method

Envelopes::listDocuments

Definitions

envelopeDocument

This object contains details about the envelope document.

addedRecipientIds[array]

If recipients were added by converting form fields into tabs, their ids appear here. Read only.

attachmentTabIdstring

If this document is an attachment to another document in the envelope, this is the id of the attachment tab it is associated with on the other document.

authoritativeCopystring

When true, marks all of the documents in the envelope as authoritative copies.

Note: You can override this value for a specific document. For example, you can set the authoritativeCopy property to true at the envelope level, but turn it off for a single document by setting the authoritativeCopy property for the document to false.

authoritativeCopyMetadatapropertyMetadata

Metadata that indicates if the sender can edit the authoritativeCopy property. Not applicable for template documents.

availableDocumentTypes[signatureType]

containsPdfFormFieldsstring

When true, the document has editable form fields that are made available through a PDF format.

displaystring

This string sets the display and behavior properties of the document during signing. The possible values are:

  • modal
    The document is shown as a supplement action strip and can be viewed, downloaded, or printed in a modal window. This is the recommended value for supplemental documents.

  • download
    The document is shown as a supplement action strip and can be viewed, downloaded, or printed in a new browser window.

  • inline
    The document is shown in the normal signing window. This value is not used with supplemental documents, but is the default value for all other documents.

displayMetadatapropertyMetadata

Metadata that indicates if the sender can edit the display property. Not applicable for template documents.

documentFields[nameValue]

An object containing information about the custom fields on the document.

documentGroupstring

The type of group to which the document belongs. Valid values are:

  • content: This is the default value for non-certificate documents.
  • certificate: When a user makes a request to download a certificate of completion, the documents in the certificate document group are appended to the DocuSign certificate and the resulting PDF is returned. Documents returned with the DocuSign certificate are stamped or watermarked to indicate that they were not created by DocuSign.

Note: A document may only be in a single document group.

documentIdstring

The id of the document that the tab is placed on. This value must refer to the id of an existing document.

documentIdGuidstring

The GUID of the document.

errorDetailserrorDetails

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

includeInDownloadstring

When set to true, the document is included in the combined document download (documentsCombinedUri). The default value is true.

includeInDownloadMetadatapropertyMetadata

Metadata that indicates if the sender can edit the includeInDowload property. Not applicable for template documents.

namestring

The document's file name.

Example: Q1-Report.docx

nameMetadatapropertyMetadata

Metadata that indicates if the sender can edit the name property. Not applicable for template documents.

orderstring

(Optional) The order in which to sort the results.

Valid values are:

  • asc: Ascending order.
  • desc: Descending order.

pages[page]

An array of page objects that contain information about the pages in the document.

signerMustAcknowledgestring

Sets how the signer interacts with the supplemental document. The possible values are:

  • no_interaction
    No recipient action is required.

  • view
    The recipient is required to view the document.

  • accept
    The recipient is required to accept the document by selecting accept during signing, but is not required to view the document.

  • view_accept
    The recipient is required to view and accept the document.

signerMustAcknowledgeMetadatapropertyMetadata

Metadata that indicates if the sender can edit the signerMustAcknowledge property. Not applicable for template documents.

templateLockedstring

When set to true, the sender cannot change any attributes of the recipient. Used only when working with template recipients.

templateRequiredstring

When set to true, the sender may not remove the recipient. Used only when working with template recipients.

typestring

uristring

The URI for retrieving the document.

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.

nameValue

A name-value pair that describes an item and provides a value for the item.

errorDetailserrorDetails

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

namestring

The name of the item.

originalValuestring

The initial value of the item.

valuestring

The current value of the item.

page

Description of a page of a document.

dpistring

The number of dots per inch used for the page image.

errorDetailserrorDetails

If an error occurs, this property describes the error.

heightstring

The height of the page in pixels.

imageBytesstring

The number of image bytes.

mimeTypestring

The MIME type.

pageIdstring

The id of the page.

sequencestring

The sequence of the page in the document, or page number.

widthstring

The width of the page in pixels.

propertyMetadata

Metadata about a property.

options[array]

An array of option strings supported by this setting.

rightsstring

Indicates whether the property is editable. Valid values are:

  • editable
  • read_only

signatureType

This object contains information about the type of signature.

isDefaultstring

When true, the signature type is the default type.

typestring

The type of signature. Valid values are:

  • electronic: Indicates an electronic signature that is used by common law countries such as the United States, United Kingdom, and Australia. This is the default signature type that DocuSign uses.
  • universal: Indicates a digital signature that is accepted by both common law and civil law countries. To use digital signatures, you must use the DocuSign Signature Appliance.

For more information, see Standards Based Signatures.

EnvelopeDocuments

Envelope documents

envelopeDocuments[envelopeDocument]

An array of document objects.

envelopeIdstring

The envelope ID of the envelope status that failed to post.

Examples

List All Documents in an Envelope

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.1/accounts/1703061/envelopes/44efc9e6-915e-4b1d-9b54-801410d6922d/documents

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"
}
Generic JSON Response

Response
{
  "envelopeId": "sample string 1",
  "envelopeDocuments": [
    {
      "documentId": "sample string 1",
      "name": "sample string 2",
      "type": "sample string 3",
      "uri": "sample string 4",
      "order": "sample string 5",
      "pages": "sample string 6",
      "containsPdfFormFields": "sample string 7",
      "documentFields": [
        {}
      ],
      "availableDocumentTypes": [
        {
          "type": "sample string 1",
          "isDefault": "sample string 2"
        }
      ],
      "attachmentTabId": "sample string 8",
      "display": "sample string 9",
      "includeInDownload": "sample string 10",
      "signerMustAcknowledge": "sample string 11",
      "documentGroup": "sample string 12",
      "authoritativeCopy": "sample string 13",
      "errorDetails": {
        "errorCode": "sample string 1",
        "message": "sample string 2"
      }
    }
  ]
}
Generic XML Response

Response
<envelopeDocumentsResult xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.docusign.com/restapi">
  <envelopeDocuments>
    <envelopeDocument>
      <attachmentTabId>sample string 8</attachmentTabId>
      <authoritativeCopy>sample string 13</authoritativeCopy>
      <availableDocumentTypes>
        <signatureType>
          <isDefault>sample string 2</isDefault>
          <type>sample string 1</type>
        </signatureType>
      </availableDocumentTypes>
      <containsPdfFormFields>sample string 7</containsPdfFormFields>
      <display>sample string 9</display>
      <documentFields>
        <nameValue />
      </documentFields>
      <documentGroup>sample string 12</documentGroup>
      <documentId>sample string 1</documentId>
      <errorDetails>
        <errorCode>sample string 1</errorCode>
        <message>sample string 2</message>
      </errorDetails>
      <includeInDownload>sample string 10</includeInDownload>
      <name>sample string 2</name>
      <order>sample string 5</order>
      <pages>sample string 6</pages>
      <signerMustAcknowledge>sample string 11</signerMustAcknowledge>
      <type>sample string 3</type>
      <uri>sample string 4</uri>
    </envelopeDocument>
  </envelopeDocuments>
  <envelopeId>sample string 1</envelopeId>
</envelopeDocumentsResult> 
}} />