Purging documents in an envelope
See how to use the eSignature REST API to selectively purge envelope documents, metadata, and PII.
Table of contents
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.
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 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 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.
Related posts
Discover what's new with Docusign IAM or start with eSignature for free
