Folders: listItems

Retrieves a list of the envelopes in the specified folder. You can narrow the query by specifying search criteria in the query string parameters.

Request

HTTP request

GET /v2/accounts/{accountId}/folders/{folderId}

Parameters

Parameter NameValueDescription
Path Parameters
accountIdstring

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

folderIdstring

The ID of the folder being accessed.

Optional Query Parameters
from_datestring

Only return items on or after this date. If no value is provided, the default search is the previous 30 days.

owner_emailstring

The email of the folder owner.

owner_namestring

The name of the folder owner.

search_textstring

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.

start_positionstring

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.

statusstring

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.

to_datestring

Only return items up to this date. If no value is provided, the default search is to the current date.

Responses

CodeDescriptionReference
200

Successful response.

folderItemsResponse
400

Error encountered.

errorDetails

SDK Method

Folders::listItems

Definitions

customField_v2

configurationTypestring

If merge field's are being used, specifies the type of the merge field. The only supported value is salesforce.

errorDetailserrorDetails

fieldIdstring

An ID used to specify a custom field.

namestring

requiredstring

When set to true, the signer is required to fill out this tab

showstring

A boolean indicating if the value should be displayed. If this value is set to true, the custom field is displayed at the top of the certificate of completion. If this value is left blank/ or set to false, then it does not appear in the certificate of completion.

valuestring

The value of the custom field.

errorDetails

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

errorCodestring

An error code associated with the error.

messagestring

A short error message.

folderItem

completedDateTimestring

Specifies the date and time this item was completed.

createdDateTimestring

Indicates the date and time the item was created.

customFields[customField_v2]

An optional array of strings that allows the sender to provide custom data about the recipient. This information is returned in the envelope status but otherwise not used by DocuSign. Each customField string can be a maximum of 100 characters.

descriptionstring

A sender-defined description of the line item.

envelopeIdstring

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

envelopeUristring

Contains a URI for an endpoint that you can use to retrieve the envelope or envelopes.

is21CFRPart11string

When set to true, indicates that this module is enabled on the account.

isSignatureProviderEnvelopestring

lastModifiedstring

Utc date and time the comment was last updated (can only be done by creator.)

namestring

ownerNamestring

Name of the envelope owner.

pageCountinteger

passwordstring

senderEmailstring

senderNamestring

Name of the envelope sender.

sentDateTimestring

The date and time the envelope was sent.

sharedstring

When set to true, this custom tab is shared.

statusstring

Item status.

subjectstring

templateIdstring

The unique identifier of the template. If this is not provided, DocuSign will generate a value.

uristring

folderItemsResponse

endPositionstring

The last position in the result set.

folderItems[folderItem]

A list of the envelopes in the specified folder or folders.

nextUristring

The URI for the next chunk of records based on the search request. It is null if this is the last set of results for the search.

previousUristring

The URI for the prior chunk of records based on the search request. It is null if this is the first set of results for the search.

resultSetSizestring

The number of results returned in this response.

startPositionstring

Starting position of the current result set.

totalSetSizestring

The total number of items in the search's result set. It will always be greater than or equal to the value of the resultSetSize field.

Examples

Generic JSON Response

Response
{
  "resultSetSize": "sample string 1",
  "startPosition": "sample string 2",
  "endPosition": "sample string 3",
  "totalSetSize": "sample string 4",
  "previousUri": "sample string 5",
  "nextUri": "sample string 6",
  "folderItems": [
    {
      "ownerName": "sample string 1",
      "envelopeId": "sample string 2",
      "envelopeUri": "sample string 3",
      "status": "sample string 4",
      "senderName": "sample string 5",
      "senderEmail": "sample string 6",
      "createdDateTime": "sample string 7",
      "sentDateTime": "sample string 8",
      "completedDateTime": "sample string 9",
      "subject": "sample string 10",
      "templateId": "sample string 11",
      "name": "sample string 12",
      "shared": "sample string 13",
      "password": "sample string 14",
      "description": "sample string 15",
      "lastModified": "sample string 16",
      "pageCount": 17,
      "uri": "sample string 18",
      "is21CFRPart11": "sample string 19",
      "isSignatureProviderEnvelope": "sample string 20",
      "customFields": [
        {
          "fieldId": "sample string 1",
          "name": "sample string 2",
          "show": "sample string 3",
          "required": "sample string 4",
          "value": "sample string 5",
          "configurationType": "sample string 6",
          "errorDetails": {
            "errorCode": "sample string 1",
            "message": "sample string 2"
          }
        }
      ]
    }
  ]
}
Generic XML Response

Response
<folderItemsResponse xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.docusign.com/restapi">
  <endPosition>sample string 3</endPosition>
  <folderItems>
    <folderItem>
      <completedDateTime>sample string 9</completedDateTime>
      <createdDateTime>sample string 7</createdDateTime>
      <customFields>
        <customField>
          <configurationType>sample string 6</configurationType>
          <errorDetails>
            <errorCode>sample string 1</errorCode>
            <message>sample string 2</message>
          </errorDetails>
          <fieldId>sample string 1</fieldId>
          <name>sample string 2</name>
          <required>sample string 4</required>
          <show>sample string 3</show>
          <value>sample string 5</value>
        </customField>
      </customFields>
      <description>sample string 15</description>
      <envelopeId>sample string 2</envelopeId>
      <envelopeUri>sample string 3</envelopeUri>
      <is21CFRPart11>sample string 19</is21CFRPart11>
      <isSignatureProviderEnvelope>sample string 20</isSignatureProviderEnvelope>
      <lastModified>sample string 16</lastModified>
      <name>sample string 12</name>
      <ownerName>sample string 1</ownerName>
      <pageCount>17</pageCount>
      <password>sample string 14</password>
      <senderEmail>sample string 6</senderEmail>
      <senderName>sample string 5</senderName>
      <sentDateTime>sample string 8</sentDateTime>
      <shared>sample string 13</shared>
      <status>sample string 4</status>
      <subject>sample string 10</subject>
      <templateId>sample string 11</templateId>
      <uri>sample string 18</uri>
    </folderItem>
  </folderItems>
  <nextUri>sample string 6</nextUri>
  <previousUri>sample string 5</previousUri>
  <resultSetSize>sample string 1</resultSetSize>
  <startPosition>sample string 2</startPosition>
  <totalSetSize>sample string 4</totalSetSize>
</folderItemsResponse> 
}} />