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. (For 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

addedRecipientIds[array]

If recipients were added by converting form fields into tabs, their ids will 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

Specifies whether all documents in this envelope are authoritative copies. A document can set its own authoritativeCopy property to override this value. For example you can set the authoritativeCopy on an envelope level to true but can turn it off for a specific document.

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]

The custom fields on the document.

documentGroupstring

The type of group the document belongs to (certificate or content).

documentIdstring

Specifies the document ID number that the tab is placed on. This must refer to an existing Document's ID attribute.

documentIdGuidstring

The Guid of the document.

errorDetailserrorDetails

If an error occurs, this property describes the error.

includeInDownloadstring

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

includeInDownloadMetadatapropertyMetadata

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

namestring

The name of the document.

nameMetadatapropertyMetadata

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

orderstring

An optional value that sets the direction order used to sort the item list.

Valid values are:

  • asc = ascending sort order
  • desc = descending sort order

pages[page]

An array of page objects that contain information about the pages in a 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

Type of user:

  • type_owner
  • type_participant

uristring

URI containing the user ID.

errorDetails

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

errorCodestring

A code associated with the error condition.

messagestring

A brief message describing the error condition.

nameValue

errorDetailserrorDetails

Object that describes errors that occur. Only valid for responses; ignored in requests.

namestring

The name or key of a name/value pair.

originalValuestring

The initial value of the tab when it was sent to the recipient.

valuestring

The value field of a name/value pair.

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 unique 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

isDefaultstring

Indicates if the signature type is the default type.

typestring

Type of user:

  • type_owner
  • type_participant

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> 
}} />