Purging documents in an envelope

•Updated Mar 28, 2025

Summary•4 min read

See how to use the eSignature REST API to selectively purge envelope documents, metadata, and PII.

Purge limitations
Additional resources

Purge limitations
Additional resources

In the Docusign web app, Docusign eSignature account administrators can search for and purge all documents, metadata, and personally identifiable information (PII) from completed, declined, or voided envelopes that have been sent from or signed by a specific email address. Envelopes selected for purge are immediately moved into the purge queue; their documents and metadata are then purged (deleted) from Docusign systems after the purge queue period expires, which is generally 14 days later under normal purge queue processing conditions (see “Purge limitations” below for more details).

Today I'd like to show you how to purge documents associated with an envelope programmatically. But first, let’s go over how documents are purged in the Docusign web app.

Log in to your Docusign developer account and, in eSignature Admin, select the Document Retention page from the left nav. Once there, select Targeted Purge and then select one or more envelopes based on your filter criteria; then click purge. Note that only completed, declined, or voided envelopes can be put in the purge queue.

Selecting envelopes to add to the purge queue

In addition to purging documents, you can choose to remove the fields and metadata associated with the documents and choose to redact personally identifiable information.

To do this programmatically, call the Envelopes: update API; not exactly the obvious choice, but it’s pretty simple once you know where to look!

This is what the JSON request body of the PUT request looks like for the three different purge states:

PUT /restapi/v2.1/accounts/{accountId}/envelopes/{envelopeId}

{
  "envelopeId": "222e6847-xxxx-xxxx-xxxx-72a3c9c16fca",
  "purgeState": "documents_queued"
}

{
  "envelopeId": "222e6847-xxxx-xxxx-xxxx-72a3c9c16fca",
  "purgeState": "documents_and_metadata_queued"
}

{
  "envelopeId": "222e6847-xxxx-xxxx-xxxx-72a3c9c16fca",
  "purgeState": "documents_and_metadata_and_redact_queued"
}

For an example on how to call the Envelopes: update API, take a look at the Unpause a signature workflow how-to guide in the Developer Center.

For an example on how to get a set of status history data for envelopes updated within a specified range of dates, see the How to list envelope status changes how-to guide.

If you want to remove a purge request from the queue, your JSON request body for the Envelopes: update call looks like this:

{
  "envelopeId":"222e6847-xxxx-xxxx-xxxx-72a3c9c16fca",
  "purgeState": "documents_dequeued"
}

Purge limitations

You can't purge an envelope's documents that are marked as the authoritative copy. The user requesting the purge must have permission to purge documents and must be the sender or acting on behalf of the sender.

As I mentioned above, when the purge request is initiated, the items to be purged are placed in the purge queue for deletion, which generally occurs in 14 days under normal purge queue processing conditions . As a default configuration in the sender’s account, the sender and all recipients with Docusign accounts associated with the envelope get an email notification about the planned purge upon a document entering the purge queue. The notification contains a link to the documents which allows recipients to download a document before it is purged. A second email notification is additionally sent generally 7 days prior to expiration of the purge queue period as another reminder of the upcoming purge. At the end of the purge queue period the documents are deleted from the system. Recipients without Docusign accounts do not receive email notifications

If your account has a Document Retention policy, envelope documents are automatically placed in the purge queue, and notification emails are sent at the end of the retention period. Setting a Document Retention policy is the same as setting a schedule for purging documents.

Additional resources

Robert KnightSr. Programmer Writer

Robert Knight is a senior programmer writer for the Docusign Developer Content team. He writes how-tos and accompanying code for many of Docusign's products, as well as videos and blogs. His experience includes stints at Microsoft Research and Amazon Web Services.