Envelopes

Gets envelope statuses for a set of envelopes.

Retrieves envelope statuses for a set of envelopes. Envelopes: listStatus has both a GET and a PUT implementation:

  • PUT /restapi/v2.1/accounts/{accountId}/envelopes/status is passed a set of envelope IDs in the request body. This version of the method returns a smaller subset of envelope information.
  • GET /restapi/v2.1/accounts/{accountId}/envelopes/status is passed a list of envelope IDs in a query string.
<ds-inlinemessage> To search for envelopes using a broad range of filters, use <a href="/docs/esign-rest-api/reference/envelopes/envelopes/liststatuschanges/">Envelopes: listStatusChanges</a> instead of this method. </ds-inlinemessage>

You must specify exactly one of the following query parameters:

ParameterDescription
from_datea valid UTC DateTime: 2016-01-01
envelope_ids<ul><li>For the <code>GET</code> implementation of this method, include the envelope IDs in a comma-separated list. </li><li>For the <code>PUT</code> version of this method, you should use the <code>request_body</code> value for this parameter and include the list of envelope IDs in the request body.</li></ul>
transaction_idsA comma-separated list of transaction IDs<br>or the special value <code>request_body</code>

When you use the special value request_body, the request body looks like this:

{
  "envelopeIds": [
    "44c5ad6c-xxxx-xxxx-xxxx-ebda5e2dfe15",
    "8e26040d-xxxx-xxxx-xxxx-1e29b924d237",
    "c8b40a2d-xxxx-xxxx-xxxx-4fe56fe10f95"
  ]
}
<ds-inlinemessage kind="warning"> Omitting the request body altogether causes the endpoint to return an error. The request body must be at least <code>{}</code>. </ds-inlinemessage>

Related topics

  • Searching for envelopes
  • How to list envelope status changes
put/v2.1/accounts/{accountId}/envelopes/status

Request

  • Base URL
    https://www.docusign.net/restapi
  • URL
    https://www.docusign.net/restapi/v2.1/accounts/{accountId}/envelopes/status
  • Auth
    none declared

Path parameters

accountIdstring required

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

Query parameters

ac_statusstring

Specifies the Authoritative Copy Status for the envelopes. Valid values:

  • Unknown
  • Original
  • Transferred
  • AuthoritativeCopy
  • AuthoritativeCopyExportPending
  • AuthoritativeCopyExported
  • DepositPending
  • Deposited
  • DepositedEO
  • DepositFailed
blockstring

When true, removes any results that match one of the provided transaction_ids.

countstring

The maximum number of results to return.

Use start_position to specify the number of results to skip.

emailstring

The email address of the sender.

envelope_idsstring

The envelope IDs to include in the results.

The value of this property can be:

  • For the GET implementation of this method, use a comma-separated list of envelope IDs.
  • For the PUT implementation of this method, use the request_body value, and include the envelope IDs in the request body.
from_datestring

The date/time setting that specifies when the request begins checking for status changes for envelopes in the account. This is required unless parameters envelope_ids and/or transaction_Ids are provided.

Note: This parameter must be set to a valid DateTime, or envelope_ids and/or transaction_ids must be specified.

from_to_statusstring

The envelope status that you are checking for. Possible values are:

  • Changed (default)
  • Completed
  • Created
  • Declined
  • Deleted
  • Delivered
  • Processing
  • Sent
  • Signed
  • TimedOut
  • Voided

For example, if you specify Changed, this method returns a list of envelopes that changed status during the from_date to to_date time period.

start_positionstring

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.

statusstring

A comma-separated list of envelope status to search for. Possible values are:

  • completed
  • created
  • declined
  • deleted
  • delivered
  • processing
  • sent
  • signed
  • template
  • voided
to_datestring

Optional date/time setting that specifies the last date/time or envelope status changes in the result set.

The default value is the time that you call the method.

transaction_idsstring

The transaction IDs to include in the results. Note that transaction IDs are valid for seven days.

The value of this property can be:

  • A list of comma-separated transaction IDs
  • The special value request_body. In this case, this method uses the transaction IDs in the request body.
user_namestring

Limits 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.

Request body

envelopeIdsstring[]

A comma-separated list of envelope IDs to include in the results.

transactionIdsstring[]

A comma-separated list of transaction IDs to include in the results. Note that transaction IDs are valid for seven days.

Response

Successful response.

Changes

No recorded changes to this operation across all 39 revisions of this API.