REST API Recipe: Getting an Envelope's Recipient Status


This recipe retrieves an envelope’s current recipient status. Envelopes have statuses and so do Recipients. For example, an envelope has two recipients, the first has signed the document, but the second recipient has declined to sign. In this case the first recipient’s status would be signed, the second recipient’s status would be declined, and the envelope’s status is declined (since one recipient has declined).

Getting ready

You’ll need a DocuSign account email and password that has access to the envelope’s status information. You’ll also need an integration key. See Generate Your Integrator Key. And you’ll need an envelope ID. You can send an envelope via the API to get an envelope ID. Or you can send an envelope via the web UI and then request the envelope’s summary or certificate information from the web UI. The summary document includes the envelope ID.

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 Request a Signature via Email for an example of this step.

Step 2: Send the Recipients::envelopeList request and use the response status object.


Source files

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

How it works

A key part of this recipe is to use the right username/password. Depending on your Use Case, you can use the sender’s information, or a “System Account” that has access to all envelope information within the account. You can also use an SSO token as a proxy for the sender’s credentials.

There’s more

DocuSign tracks the status of each envelope and of each recipient within envelopes. This recipe covers the recipients’ statuses. Use method Envelope::get to retrieve the envelope’s status. A recipe is available.