Common API Tasks🐈: Void an Envelope

Inbar Gazit

Sr. Manager, Developer Content

•

Summary•3 min read

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

Table of contents

C#
Java
Node.js
PHP
Python
Ruby
Additional resources

Common API Tasks

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#

Java

Node.js

PHP

Python

Ruby

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