Common API Tasks🐈: Purging envelopes from your DocuSign account
Welcome to a wonderful new edition of the CAT🐈 (Common API Tasks) blog series. The CAT blogs provide all you need to complete small, specific, SDK-supported tasks using one of our APIs. You can find all articles in this series on the DocuSign Developer Blog.
Generally speaking, DocuSign stores all of your production environment envelope data in the cloud permanently (in the developer environment, your envelopes are removed after 30 days.) However, you can define your own document retention policy to have DocuSign purge envelopes automatically at a given time. You can also manually purge envelopes from the DocuSign eSignature Admin Settings menu by selecting Document Retention in the left menu and selecting TARGETED PURGE, then picking the envelopes to be purged (only completed or voided envelopes can be purged).
If you can do something manually from the DocuSign web app, you can also do it using one of the DocuSign APIs. This is where I come in. Let’s see how you can write code to purge a specific envelope. To be clear, you don’t get to purge an envelope immediately, but instead you add it to a purge queue for up to 14 days. DocuSign will purge this envelope when it gets to the top of the queue. You’ll need your envelope’s
envelopeID (a unique GUID identifying it in the system) and you need to choose which parts of the envelope to purge and which to keep. This is decided by the purgeState parameter, which you can set to one of the following string values:
documents_queued: Only the documents in the envelope will be removed
documents_and_metadata_queued: Documents and any metadata such as tabs or custom fields will be removed
documents_and_metadata_and_redact_queued: Documents and any metadata such as tabs or custom fields will be removed. In addition, any PII (Personal Identifiable Information) such as names, or email addresses will be redacted
documents_dequeued: This value is used to undo one of the previous three actions and remove the envelope from the queue. As long as the envelope hasn’t been purged yet, you can use this action to restore it
The code snippets presented here are very simple. They will add a single envelope to the purge queue (adding multiple envelopes requires multiple API calls). I choose to use
documents_and_metadata_and_redact_queued for this example, but you can change this value as needed. Note that the envelope you’re trying to purge must be in either completed or void status and the user account authenticated to make API calls must be the sender of the envelope or has permission to this envelope exclipicly granted.
var apiClient = new ApiClient(basePath); // You will need to obtain an access token using your chosen authentication method apiClient.Configuration.DefaultHeader.Add("Authorization", "Bearer " + accessToken); EnvelopesApi envelopesApi = new EnvelopesApi(apiClient); string envId = "0e3b78b9-xxxx-xxxx-xxxx-dbf35ba8f58a"; Envelope env = new Envelope(); env.EnvelopeId = envId; env.PurgeState = "documents_and_metadata_and_redact_queued"; envelopesApi.Update(accountId, envId, env);
// You will need to obtain an access token using your chosen authentication flow Configuration config = new Configuration(new ApiClient(basePath)); config.addDefaultHeader("Authorization", "Bearer " + accessToken); EnvelopesApi envelopesApi = new EnvelopesApi(config); String envId = "0e3b78b9-xxxx-xxxx-xxxx-dbf35ba8f58a"; Envelope env = new Envelope(); env.setEnvelopeId(envId); env.setPurgeState("documents_and_metadata_and_redact_queued"); envelopesApi.Update(accountId, envId, env);
// You will need to obtain an access token using your chosen authentication flow let dsApiClient = new docusign.ApiClient(); dsApiClient.setBasePath(basePath); dsApiClient.addDefaultHeader('Authorization', 'Bearer ' + accessToken); let envelopesApi = new docusign.EnvelopesApi(apiClient); let envId = '0e3b78b9-xxxx-xxxx-xxxx-dbf35ba8f58a'; let env = new docusign.Envelope(); env.envelopeId = envId; env.purgeState = 'documents_and_metadata_and_redact_queued'; envelopesApi.update(accountId, envId, env);
# You will need to obtain an access token using your chosen authentication flow $api_client = new \DocuSign\eSign\client\ApiClient($base_path); $config = new \DocuSign\eSign\Model\Configuration($api_client); $config->addDefaultHeader('Authorization', 'Bearer ' + $access_token); $envelopes_api = new \DocuSign\eSign\Api\EnvelopesApi($api_client); $env_id = '0e3b78b9-xxxx-xxxx-xxxx-dbf35ba8f58a'; $env = new \DocuSign\eSign\Model\Envelope(); $env->setEnvelopeId($env_id); $env->setPurgeState('documents_and_metadata_and_redact_queued'); $envelopes_api->update($account_id, $env_id, $env);
# You will need to obtain an access token using your chosen authentication flow api_client = ApiClient() api_client.set_default_header('Authorization', 'Bearer ' + access_token) envelopes_api = EnvelopesApi(api_client) env_id = '0e3b78b9-xxxx-xxxx-xxxx-dbf35ba8f58a' env = Envelope() env.envelope_id = env_id env.purge_state = 'documents_and_metadata_and_redact_queued' envelopes_api.update(account_id, env_id, env)
# You will need to obtain an access token using your chosen authentication flow config = DocuSign_eSign::Configuration.new config.host = base_path api_client = DocuSign_eSign::ApiClient.new config api_client.DefaultHeader['Authorization'] = 'Bearer ' + access_token envelopes_api = DocuSign_eSign::EnvelopesApi.new api_client env_id = '0e3b78b9-xxxx-xxxx-xxxx-dbf35ba8f58a' env = Envelope.new env.envelope_id = env_id env.purge_state = 'documents_and_metadata_and_redact_queued' envelopes_api.update(account_id, env_id, env)
That’s all folks! I hope you found it useful. If you have any questions, comments, or suggestions for topics for future Common API Tasks posts, feel free to email me. Until next time...