Common API Tasks🐈: Void an Envelope

Inbar GazitSr. Manager, Developer Content

•

Summary•3 min read

Learn how to use the eSignature REST API to void an envelope

C#
Java
Node.js
PHP
Python
Ruby
Additional resources

C#
Java
Node.js
PHP
Python
Ruby
Additional resources

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:

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.
You can only void envelopes that are in process; you cannot void draft or completed envelopes.
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.
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, {'envelope' : 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

Inbar GazitSr. Manager, Developer Content

Inbar Gazit has been with Docusign since 2013 in various engineering roles. Since 2019 he has focused on developer content. Inbar works on code examples including the launchers, available on GitHub in eight languages, and helps build sample apps showcasing the various Docusign APIs. He is also active on StackOverflow, answering your questions. Inbar can be reached at inbar.gazit@docusign.com.