Polling for envelope status


You’ve sent some documents for signing. How should your app automatically track the envelope’s (or envelopes’) progress and status changes from behind your firewall? You can poll the DocuSign platform or use DocuSign Connect to be notified whenever an event occurs. This recipe shows how to poll for status changes.

Getting ready

You’ll need a DocuSign account email and password that has access to the envelopes’ status information. You’ll also need an integration key. See Generate Your Integator Key.

How to do it

Step 1: use the login_information API end point to obtain the base url for use in subsequent API calls, and the user’s account ID. See the recipe Requesting a Signature via Email for an example of this step.

Step 2: Send the Envelopes::listStatusChanges request and use the response status object.

The Envelopes::listStatusChanges method accepts optional query parameters to specify the time period that you’d like change information on, and the types of changes and current envelope statuses that you’re interested in. See below for working within DocuSign’s polling limits. The call will return an array of information about the envelopes that meet your search criteria.



Please see our Github repo for the recipe’s source files.

How it works

You are not allowed to poll DocuSign more than once every 15 minutes. To ensure that your app has an accurate view of your envelopes’ statuses, we suggest that you poll every 17-20 minutes. Each time you poll, request information since 3 minutes before the last time you polled, to ensure that you don’t create a small window where changes can occur unnoticed.

For example, you poll on the hour, then 18 minutes later. At the second polling, request changes since 3 minutes before the hour. This technique may give you duplicates of change information, but you'll be assured of not missing any changes.

There’s more

DocuSign prefers and recommends that you use DocuSign Connect to be notified of changes. DocuSign Connect is a "web hook" service — your app will be called by the DocuSign platform whenever there is a change in your envelopes’ status. DocuSign Connect provides a modern, smooth, easy to use design pattern. But it does require that your application be open to the Internet to enable DocuSign to initiate contact to your app from the Internet when there’s a status change event.