v1
latestSwagger 2.02026-07-134146194.6 MBSearch for specific sets of envelopes by using search filters.
This method lets you search for envelopes in your accounts. A large set of filters let you narrow the scope of your search by date, by envelope ID, or by status codes. Your request must include one or more of the following parameters:
- from_date
- envelope_ids
- transaction_ids
Restrictions
The number of envelopes returned is limited to 1,000 per call. To retrieve the next or previous set of envelopes, use the nextUri and previousUri parameters returned in the original call's response.
If no from_date query parameter is specified, envelopes from more than two years ago will not be returned. To fetch older envelopes, set the specific date range using the from_date and to_date parameters.
To avoid unnecessary database queries, the Docusign signature platform first checks requests to ensure that the filter set supplied does not result in a zero-size response before querying the database.
Envelope statuses
This table shows the valid current envelope statuses (status parameter) for the different status qualifiers (from_to_status parameter) in the request. If the status and status qualifiers in the API request do not contain any of the values shown in the Valid Current Statuses column, then an empty list is returned.
Client applications should check that the statuses (status parameter) they are requesting make sense for a given from_to_status parameter value.
| Status Qualifier<br>(from_to_status) | Effective Status Qualifier | Valid Current Statuses |
|---|---|---|
| any (changed) | StatusChanged | any, created, sent, delivered, signed, completed, declined, voided, deleted |
| created | Created | any, created, sent, delivered, signed, completed, declined, voided, deleted |
| sent | Sent | any, sent, delivered, signed, completed, declined, voided, deleted |
| delivered | StatusChanged | any, delivered, signed, completed, declined, voided, deleted |
| signed | StatusChanged | any, signed, completed, declined, voided, deleted |
| completed | Completed | any, completed, declined, voided, deleted |
| declined | StatusChanged | any, declined, voided, deleted |
| timedout<br>always return zero results | StatusChanged | any, voided, deleted |
| voided | Voided | any, voided, deleted |
| deleted | StatusChanged | any, deleted |
Extraneous results
In some cases, a request for a specific envelope status will include envelopes with additional statuses. For example, in a request with a from_date of 2017-01-01, a to_date of 2017-01-07 and the status qualifier (from_to_status) set to delivered, the response set might contain envelopes that were created during that time period, but not delivered during the time period. As a workaround, check the envelope status values in the result set as needed.
Related topics
- Searching for envelopes
- How to list envelope status changes
Path parameters
The external account number (int) or account ID GUID.
Query parameters
Specifies the authoritative copy status for the envelopes. Valid values:
- Unknown
- Original
- Transferred
- AuthoritativeCopy
- AuthoritativeCopyExportPending
- AuthoritativeCopyExported
- DepositPending
- Deposited
- DepositedEO
- DepositFailed
Reserved for Docusign.
Reserved for Docusign.
Reserved for Docusign.
The maximum number of results to return.
The maximum value is 1000. To get the next or previous set of envelopes, use nextUri or previousUri from the response.
Optional. Specifies an envelope custom field name and value searched for in the envelopes. Format: custom_envelope_field_name=desired_value
Example: If you have an envelope custom field named "Region" and you want to search for all envelopes where the value is "West" you would use set this parameter to Region=West.
Limit results to envelopes sent by the account user with this email address.
user_name must be given as well, and both email and user_name must refer to an existing account user.
Comma separated list of envelopeId values.
Excludes information from the response. Enter as a comma-separated list (e.g., folders,powerforms).
Valid values:
- recipients
- powerforms
- folders
Returns the envelopes from specific folders. Enter as a comma-separated list of either valid folder GUIDs or the following values:
- awaiting_my_signature
- completed
- draft
- drafts
- expiring_soon
- inbox
- out_for_signature
- recyclebin
- sentitems
- waiting_for_others
Returns the envelopes from folders of a specific type. Enter as a comma-separated list of the following values:
- normal
- inbox
- sentitems
- draft
- templates
Specifies the date and time to start looking for status changes. This parameter is required unless envelopeIds or transactionIds are set.
Although you can use any date format supported by the .NET system library's DateTime.Parse() function, Docusign recommends using ISO 8601 format dates with an explicit time zone offset. If you do not provide a time zone offset, the method uses the server's time zone.
For example, the following dates and times refer to the same instant:
- 2017-05-02T01:44Z
- 2017-05-01T21:44-04:00
- 2017-05-01T18:44-07:00
If this property is not included, envelopes from the last two years will be returned.
This is the status type checked for in the from_date/to_date period. For example, if Created is specified, then envelopes created during the period are found. If Changed is specified, then envelopes that changed status during the period are returned. The default value is Changed.
Valid values:
- Changed
- Voided
- Created
- Deleted
- Sent
- Delivered
- Signed
- Completed
- Declined
- TimedOut
- Processing
Specifies additional information to return about the envelopes. Use a comma-separated list, such as folders, recipients to specify information. Valid values are:
- custom_fields: The custom fields associated with the envelope.
- documents: The documents associated with the envelope.
- attachments: The attachments associated with the envelope.
- extensions: Information about the email settings associated with the envelope.
- folders: The folders where the envelope exists.
- recipients: The recipients associated with the envelope.
- payment_tabs: The payment tabs associated with the envelope.
When true, information about envelopes that have been deleted is included in the response.
A comma-separated list of folders from which you want to get envelopes. Valid values:
- normal
- inbox
- sentitems
- draft
- templates
Returns envelopes that were modified prior to the specified date and time.
Example: 2020-05-09T21:56:12.2500000Z
Returns envelopes in either ascending (asc) or descending (desc) order.
Sorts results according to a specific property. Valid values:
- last_modified
- action_required
- created
- completed
- envelope_name
- expire
- sent
- signer_list
- status
- subject
- user_name
- status_changed
- last_modified
A comma-separated list of PowerFormId values.
The time in seconds that the query should run before returning data.
Free text search criteria that you can use to filter the list of envelopes that is returned.
The zero-based index of the result from which to start returning results.
Use with count to limit the number of results.
The default value is 0.
A comma-separated list of current envelope statuses to be included in the response. Valid values:
- completed
- created
- declined
- deleted
- delivered
- processing
- sent
- signed
- timedout
- voided
The any value is equivalent to any status.
Specifies the date and time to stop looking for status changes. The default is the current date and time.
Although you can use any date format supported by the .NET system library's DateTime.Parse() function, Docusign recommends using ISO 8601 format dates with an explicit time zone offset If you do not provide a time zone offset, the method uses the server's time zone.
For example, the following dates and times refer to the same instant:
- 2017-05-02T01:44Z
- 2017-05-01T21:44-04:00
- 2017-05-01T18:44-07:00
A comma-separated list of envelope transaction IDs.
Getting envelope status by transaction IDs is useful for offline signing situations to determine if an envelope was created or not. It can be used for the cases where a network connection was lost before the envelope status could be returned.
Note: Transaction IDs are only valid in the Docusign system for seven days.
Returns envelopes where the current user is the recipient, the sender, or the recipient only. (For example, user_filter=sender.) Valid values are:
- sender
- recipient
- recipient_only
The ID of the user who created the envelopes to be retrieved. Note that an account can have multiple users, and any user with account access can retrieve envelopes by user_id from the account.
Limit results to envelopes sent by the account user with this user name.
email must be given as well, and both email and user_name must refer to an existing account user.
Response
Successful response.