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.
In this blog post I'm going to discuss document retention and the ability to remove unwanted envelopes (along with the documents and data they contain) from your DocuSign account permanently.
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 removeddocuments_and_metadata_queued: Documents and any metadata such as tabs or custom fields will be removeddocuments_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 redacteddocuments_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.
C#
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);
Java
// 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);
Node.js
// 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);
PHP
# 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);
Python
# 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)
Ruby
# 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...
