Common API Tasks🐈: Void an Envelope

If you are, like me, keeping score, you know this is the fifth blog post in the Common API Tasks series. This series is all about helping you complete simple API tasks that you may need for your integration. The first blog post in this series is about how to modify the email message that is sent to envelope recipients. The second post discusses how to retrieve tab information from envelopes. The third post in the series is about how to set up DocuSign Connect webhooks; and the fourth post in this series shows you how you can set reminders and expiration for an envelope using the DocuSign eSignature REST API. In this post, I’m going to tackle yet another common scenario that many of you may be interested in: voiding an envelope.

First, let’s explain what "voiding" actually means. Sometimes you wish to void, or cancel, an envelope that’s already in progress. You've decided you don’t want to correct it and it’s not a transaction you wish to complete for any reason.

It’s important to note a few things here:

1. You can only void envelopes that you sent or that were shared with you. You have to have the permission to void the envelope based on the specific account from which the envelope was sent.
2. You can only void envelopes that are in process; you cannot void draft or completed envelopes.
3. Voiding is a one-way action. Once voided, an envelope is voided forever: there’s no way to “unvoid” it or do anything else with it at that point. So it’s important to be very careful when using the void command in your application.
4. You should offer the user the option to confirm before proceeding to avoid any lost information that would be associated with the envelope you are voiding.

OK, now let’s get to business: how do you do that using the eSignature REST API?

Before I show you the code, I’d like to point out the specific API endpoint that I’ll be using. The endpoint is called Envelopes::update, and it is a PUT call to /v2.1/accounts/{accountId}/envelopes/{envelopeId}. (There’s an equivalent endpoint in the v2 API as well.) The body of the call includes the following information:

{
  "status": "voided",
  "voidedReason": "The reason for voiding the envelope"
}

Note that voidedReason is a required field, as you have to provide a textual explanation why you chose to void that envelope. Why? Because when you void an envelope, an email message will be sent to all the recipients letting them know that the envelope was voided.

Now here is how to code this with our six SDK languages:

 

C#

// You would need to obtain an accessToken using your chosen auth flow 
var apiClient = new ApiClient(basePath);
apiClient.Configuration.DefaultHeader.Add("Authorization", "Bearer " + accessToken);
EnvelopesApi envelopesApi = new EnvelopesApi(apiClient); 
var env = new Envelope();
env.Status = "voided";
env.VoidedReason = "changed my mind";
envelopesApi.Update(accountId, envelopeId, env);

Java

// You would need to obtain an accessToken using your chosen auth flow 
Configuration config = new Configuration(new ApiClient(basePath));
config.addDefaultHeader("Authorization", "Bearer " + accessToken);
EnvelopesApi envelopesApi = new EnvelopesApi(config); 
Envelope env = new Envelope();
env.status = "voided";
env.voidedReason = "changed my mind";
envelopesApi.update(accountId, envelopeId, env);

Node.js

// You would need to obtain an accessToken using your chosen auth flow 
let dsApiClient = new docusign.ApiClient();
dsApiClient.setBasePath(basePath);
dsApiClient.addDefaultHeader('Authorization', 'Bearer ' + accessToken);
let envelopesApi = new docusign.EnvelopesApi(dsApiClient);
let env = new docusign.Envelope();
env.status = 'voided';
env.voidedReason = 'changed my mind';
envelopesApi.update(accountId, envelopeId, env);

 

PHP

# You would need to obtain an accessToken using your chosen auth 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\Api\EnvelopesApi($config); 
$env = new \DocuSign\Envelope();
$env->setStatus('voided');
$env->setVoidedReason('changed my mind');
$envelopes_api->update($account_id, $envelope_id, $env);

 

Python

# You would need to obtain an accessToken using your chosen auth flow 
api_client = ApiClient()
api_client.host = base_path
api_client.set_default_header('Authorization', 'Bearer ' + access_token)
envelopes_api = EnvelopesApi(api_client)
env = Envelope()
env.status = 'voided'
env.voided_reason = 'changed my mind'
envelopes_api.update(account_id, envelope_id, env)

Ruby

# You would need to obtain an accessToken using your chosen auth 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 = DocuSign_eSign::Envelope().new
env.status = 'voided'
env.voided_reason = 'changed my mind'
envelopes_api.update(account_id, envelope_id, env)

And as usual, if you have any questions, comments, or suggestions for topics for future Common API blogs posts, feel free to email me. Until next time...

 

Additional resources

 

• Void envelopes on NDSE Guide
• DocuSign Developer Center
• @DocuSignAPI on Twitter
• DocuSign for Developers on LinkedIn
• DocuSign Developer Newsletter