Envelope’s status via polling


You’ve sent some documents for signing. How should your app automatically track the envelope’s (or envelopes’) progress and status changes? You can set a webhook and DocuSign will notify your app when a change occurs. This is the recommended technique. Or your app can poll the DocuSign platform to check for changes to your envelopes. This recipe covers the polling pattern.

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


Source files

The recipe source files are available on Github: Java, C#, Objective-C, Python, PHP, and Node-JS

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

Instead of polling, DocuSign recommends that you use envelope eventNotifications or DocuSign Connect to be notified of changes. These are “webhook” services–your app will be called by the DocuSign platform whenever there is a change in your envelopes’ status.