Explore our blog

Purging documents in an envelope

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 14 days later (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.

Selecting purge options

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 in 14 days. The sender and all recipients with DocuSign accounts associated with the envelope get an email notification that the documents will be deleted in 14 days. The notification contains a link to the documents. A second email notification is sent 7 days later. At the end of the 14-day 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 Knight
Author
Robert Knight
Sr. Programmer Writer
Published
Related Topics

Related Blog Posts