Skip to navigation
How-to guidesUse envelopes and templates

How to list envelope status changes

View as Markdown

This topic demonstrates how to get a set of status history data for all of your envelopes updated within a specified range of dates.

Required data

Running the code in this how-to requires this data:

Data elementDescription
{API_ACCOUNT_ID}A GUID value that identifies your account. This value is automatically generated by Docusign for any account you create. Copy the value from the API Account ID field on the Apps and Keys page.
{BASE_PATH}A string value that forms the root of the URL required to make API calls. The base path value in the example code is set to target the developer environment at
https://<domain>/restapi
Where <domain> is demo.docusign.net for the developer environment and is the result of the GetUserInfo call in production.
{FROM_DATE}A filter for the query in the format YYYY-MM-DD. Only envelopes whose status has changed beginning with the date specified by from_date will be returned.

Step 1. Obtain your OAuth token

To make the API call shown in this how-to, you need a valid OAuth access token. Docusign supports access tokens for three different recommended OAuth grant types: Public Authorization Code Grant, Confidential Authorization Code Grant, and JSON Web Token (JWT) Grant. Choose the OAuth grant type appropriate for your scenario.

See Confidential Authorization Code Grant for guidance on your options to get an Confidential Authorization Code Grant OAuth token.

Three icons that represent the three methods a user can use to obtain an OAuth token: JSON Web Token (JWT), Public Authorization Code Grant (ACG), and Confidential Authorization Code grant

Step 2. List envelope status

Call the envelopes.listStatusChanges method to get a list of envelopes and their statuses during a specified range of time. To get the list, you must specify either a from date or provide a list of envelope IDs or transaction IDs in the request. Otherwise, an error will be returned. This example uses the from date to get an array of envelopes created within the last 30 days. Use the following steps to make this method call and obtain the list of envelopes and statuses:

  1. Instantiate the Docusign API client.

  2. Set the following default request header to add your access token. "Authorization" : "Bearer {ACCESS_TOKEN}"

  3. Initialize the Envelopes API.

  4. Create a filter that specifies the set of envelope statuses that you want to return. Your request must include one or more of the following filter parameters: from_date, envelope_ids, or transaction_ids. Each of these parameters can accept a comma-delimited list.

    The example documented here uses the from_date filter, which returns all envelope status changes made since the specified date. Docusign recommends using ISO 8601 format dates with an explicit time zone offset.

    Note: The status and from_to_status options are very useful for search filtering. The former enables filtering by way of a comma-delimited list of statuses, whereas the latter will enable you to filter by a specific status for a given from_date and to_date time range. You can learn about more optional query filtering parameters by consulting Envelopes:listStatusChanges in the API Reference.

  5. After calling the envelopes.listStatusChanges method to obtain the envelope status data, you will receive both data on the status of each document within the envelope (sent vs draft, for instance) and status change dates as well as resource locators such as the documents combined URI, the attachments URI, and the recipients URI.

View the source code for this example on GitHub: Bash, C#, Java, Node.js, PHP, PowerShell, Python, or Ruby.

# Calculate the from_date query parameter and use the ISO 8601 format.
# Example:
# from_date=2018-09-30T07:43:12+03:00
# For a Mac, 10 days in the past:
if date -v -10d &> /dev/null ; then
    # Mac
    from_date=`date -v -10d '+%Y-%m-%dT%H:%M:%S%z'`
else
    # Not a Mac
    from_date=`date --date='-10 days' '+%Y-%m-%dT%H:%M:%S%z'`
fi
curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
     --header "Content-Type: application/json" \
     --get \
     --data-urlencode "from_date=${from_date}" \
     --request GET ${base_path}/v2.1/accounts/${account_id}/envelopes

Expected response

If you run this code example from our Quickstart or launcher projects, you should see a JSON response similar to the code shown.

Sample response
{
  "resultSetSize": "4",
  "startPosition": "0",
  "endPosition": "3",
  "totalSetSize": "4",
  "nextUri": "",
  "previousUri": "",
  "envelopes":
  [
    {
      "status": "sent",
      "documentsUri": "/envelopes/d9457cd7-xxxx-xxxx-xxxx-b5847d53092e/documents",
      "recipientsUri": "/envelopes/d9457cd7-xxxx-xxxx-xxxx-b5847d53092e/recipients",
      "attachmentsUri": "/envelopes/d9457cd7-xxxx-xxxx-xxxx-b5847d53092e/attachments",
      "envelopeUri": "/envelopes/d9457cd7-xxxx-xxxx-xxxx-b5847d53092e",
      "emailSubject": "Please sign this document",
      "envelopeId": "d9457cd7-xxxx-xxxx-xxxx-b5847d53092e",
      "signingLocation": "online",
      "customFieldsUri": "/envelopes/d9457cd7-xxxx-xxxx-xxxx-b5847d53092e/custom_fields",
      "notificationUri": "/envelopes/d9457cd7-xxxx-xxxx-xxxx-b5847d53092e/notification",
      "allowMarkup": "false",
      "createdDateTime": "2020-08-19T00:37:17.6570000Z",
      "lastModifiedDateTime": "2020-08-19T00:37:17.6570000Z",
      "sentDateTime": "2020-08-19T00:37:18.3600000Z",
      "statusChangedDateTime": "2020-08-19T00:37:18.3600000Z",
      "documentsCombinedUri": "/envelopes/d9457cd7-xxxx-xxxx-xxxx-b5847d53092e/documents/combined",
      "certificateUri": "/envelopes/d9457cd7-xxxx-xxxx-xxxx-b5847d53092e/documents/certificate",
      "templatesUri": "/envelopes/d9457cd7-xxxx-xxxx-xxxx-b5847d53092e/templates",
      "expireEnabled": "true",
      "expireAfter": "120",
      "sender":
      {
        "userName": "Admin One",
        "userId": "c1c4ca80-xxxx-xxxx-xxxx-32a3a9b13925",
        "accountId": "a56df5fc-xxxx-xxxx-xxxx-f64dc8ab421e",
        "email": "admin1@anyemail.com"
      },
      "purgeState": "unpurged",
      "envelopeIdStamping": "true",
      "autoNavigation": "true",
      "isSignatureProviderEnvelope": "false",
      "anySigner": null,
      "envelopeLocation": "not_specified"
    }
  ]
}

Next steps