Searching for envelopes | Docusign

Expanded by eSignature REST API 2.1

You can search precisely and flexibly for specific sets of envelopes by setting search filters and using the Envelopes:listStatusChanges endpoint or the listStatusChanges SDK method.

You can retrieve envelopes using their specific ID or search by using any combination of the following filters:

Important: to_date and from_date are required parameters and must be included in every envelope search operation. They can be combined with any other search parameters or used alone for a date-range search.

Filter	Search parameters	Description
Parent folder	`folder_ids, folder_types, intersecting_folder_ids`	Inclusion by association with a specific folder (multiple folders can be specified by comma-separated list) or by folder type. The `folder_ids` parameter allows you to specify any combination of IDs and folder types. Valid types are: `awaiting_my_signature` `completed` `draft` `drafts` `expiring_soon` `inbox` `out_for_signature` `recyclebin` `sentitems` `waiting_for_others` The `folder_types` parameter allows you to specify a subset of commonly used folder types: `inbox` `sentitems` `draft` `templates` `normal` The `intersecting_folder_ids` parameter enables you to search for envelopes that are within two folders simultaneously. For example, an envelope might be in the `awaiting_my_signature` and `inbox` folders at once; this parameter lets you filter results to return only these envelopes, rather than all envelopes in both folders. You can specify any folder type, just as with `folder_ids`.
Contains text	`search_text`	Text strings that must be present in the email subject, email address, user name, email body, and/or the custom fields of returned envelopes.
Parent PowerForm	`power_form_ids`	Inclusion by association with a specific PowerForm ID or a comma-separated list of PowerForm IDs.
Current user	`user_filter`	Includes envelopes where the current user is the recipient, the sender, or is exclusively a recipient and not also the sender. Possible values are: `sender` `recipient` `recipient_only`
User ID	`user_id`	Inclusion by association with the ID of a user in your account. All envelopes where the specified user is a recipient or sender will be included in the search.
Date range when the envelope status was changed	`from_date, to_date`	A range of dates within which the status of the returned envelopes was changed.

You can also include or exclude additional metadata, including:

Recipients, PowerForms and/or folders associated with the returned envelopes.
Data on purged or deleted information associated with the returned envelopes.

Search results may also be ordered in ascending or descending order by any envelope property.

For details on these query parameters, see Envelopes:listStatusChanges.

Excluding result data

You can specifically exclude categories of data from being returned using an exclude request parameter and specifying recipients, PowerForms, or folders.

Searching for envelopes in a specific folder

You can filter your envelope search to search only in specific folders by specifying a folder_ids request parameter and providing a comma-separated list of folder GUIDs (to search within only those folders) and/or a list of the following valid folder categories:

awaiting_my_signature
completed
draft
drafts
expiring_soon
inbox
out_for_signature
recyclebin
sentitems
waiting_for_others

Searching for envelopes in a folder type

You can filter your envelope search to search only in folders of a specified type by providing a folder_types request parameter and providing a comma-separated list of the following valid folder categories:

normal
inbox
draft
sentitems
templates

Searching for specific text

You can search for envelopes that contain specific text strings using a search_text request parameter and specifying a string that all returned envelope text must contain. The envelope’s email subject, recipient user names, email addresses, and custom fields are all searched for the strings.

Searching for envelopes associated with specific users

You can search for envelopes that are associated with a specific user ID (who may be a recipient or a sender) using the user_id request parameter and specifying the ID of a user within your account. All envelopes where that user is a recipient or sender will be searched.

Next steps

See How to list envelope status changes for a code example demonstrating how search for envelopes.
See the MyAPICalls sample app scenario Envelope Search with Resend, which walks you through a sequence of API calls that search for envelopes and resend an envelope returned in the results.