Common API Tasks🐈: Add Reminders and Expiration to an Envelope

Inbar GazitSr. Manager, Developer Content

•

Summary•3 min read

Learn all about Docusign reminders and expiration of an envelope and how you can use the eSignature REST API to set them programmatically

It’s not a perfect world, is it now?
First things first
Less talking, more coding
Additional resources

It’s not a perfect world, is it now?
First things first
Less talking, more coding
Additional resources

Hello everyone! If you haven’t had the pleasure of reading one of my Common API Tasks blog posts, I would love for you to explore them. 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, and the third post in the series is about how to set up Docusign Connect webhooks. In this fourth post in the series, I’m going to show you how to use the Docusign eSignature REST API to set up reminders and expiration for your envelopes.

It’s not a perfect world, is it now?

In a perfect world, every envelope sent for signing would be complete within minutes. That would make life very easy for the sender, as they could complete their workflow faster. However, as we all know, this is not a perfect world. Many times we have to remind our recipients that we are waiting on them to sign something. In some cases, the envelope and agreement it contains are time-sensitive: if the contract is not signed by a certain date and time, it may not be valid anymore. This is what we call an envelope expiration. Docusign supports these useful features (sending automatic reminders and setting an expiration for the envelope) directly from the web app as well as from the eSignature API. This blog post is intended to show you how you can easily use one of our six SDKs to complete this task for the envelopes you send from your integration.

First things first

Docusign only allows a user to customize their envelopes’ reminders and expirations in the Docusign web app, if the administrator of the Docusign account specifically enabled this setting. To do that, you can go to your Developer Sandbox account (demo) and log into Docusign eSignature Admin. Then, under the SIGNING AND SENDING section on the left, find the Reminders and Expiration menu and select it. Make sure to check the “Allow senders to override account defaults” checkbox and click SAVE to enable custom reminders and expiration for envelopes sent in this Docusign account.

Reminders and Expiration on the DocuSign web app

Figure 1: Configuring the Reminders and Expiration in the Docusign eSignature Admin Page

(You can still override these values using the eSignature API, even if the checkbox is not set.)

Also, note that this page includes the reminders and expiration default values for all envelopes in the account. The useAccountDefaults flag you will see in the code snippets below refers to these values.

Less talking, more coding

The following six code snippets show how to customize envelope reminders to be sent three days after the envelope is sent and continued every two days until it is signed. In addition, this envelope would expire after 30 days and a warning about its imminent expiration would be sent two days before it is set to expire.

Envelope's advanced options on the DocuSign web app

Figure 2: Envelope’s Advanced Options page showing its Reminders and Expiration

C#

EnvelopeDefinition envelopeDefinition = new EnvelopeDefinition();
var notification = new Notification();
notification.UseAccountDefaults = "false"; // customize the notification for this envelope
notification.Reminders = new Reminders
{
  ReminderEnabled = "true",
  ReminderDelay = "3", // first reminder to be sent three days after envelope was sent
  ReminderFrequency = "2" // keep sending reminders every two days
};
notification.Expirations = new Expirations
{
  ExpireEnabled = "true",
  ExpireAfter = "30", // envelope will expire after 30 days
  ExpireWarn = "2"  // expiration reminder would be sent two days before expiration
};
envelopeDefinition.Notification = notification;

Java

EnvelopeDefinition envelopeDefinition = new EnvelopeDefinition();
Notification notification = new Notification();
notification.setUseAccountDefaults("false"); // customize the notification for this envelope
Reminders reminders = new Reminders();
reminders.setReminderEnabled("true");
reminders.setReminderDelay("3");  // first reminder to be sent three days after envelope was sent
reminders.setReminderFrequency("2"); // keep sending reminders every two days
Expirations expirations = new Expirations();
expirations.setExpireEnabled("true");
expirations.setExpireAfter("30");  // envelope will expire after 30 days
expirations.setExpireWarn("2");  // expiration reminder would be sent two days before expiration
notification.setExpirations(expirations);
notification.setReminders(reminders);
envelopeDefinition.setNotification(notification);

Node.js

let envelopeDefinition = new docusign.EnvelopeDefinition();
let notification = new docusign.Notification();
notification.useAccountDefaults = 'false'; // customize the notification for this envelope
let reminders = new docusign.Reminders();
reminders.reminderEnabled = 'true';
reminders.reminderDelay = '3';  // first reminder to be sent three days after envelope was sent
reminders.reminderFrequency = '2'; // keep sending reminders every two days
let expirations = new docusign.Expirations();
expirations.expireEnabled = 'true';
expirations.expireAfter = '30';  // envelope will expire after 30 days
expirations.expireWarn = '2';  // expiration reminder would be sent two days before expiration
notification.expirations = expirations;
notifications.reminders = reminders;
envelopeDefinition.notification = notification;

PHP

$envelopeDefinition = new \Docusign\eSign\Model\EnvelopeDefinition();
$notification = new \Docusign\eSign\Model\Notification();
$notification->setUseAccountDefaults('false'); # customize the notification for this envelope
$reminders = new \Docusign\eSign\Model\Reminders();
$reminders->setReminderEnabled('true');
$reminders->setReminderDelay('3');  # first reminder to be sent three days after envelope was sent
$reminders->setReminderFrequency('2'); # keep sending reminders every two days
$expirations = new \Docusign\eSign\Model\Expirations();
$expirations->setExpireEnabled('true');
$expirations->setExpireAfter('30');  # envelope will expire after 30 days
$expirations->setExpireWarn('2');  # expiration reminder would be sent two days before expiration
$notification->setExpirations($expirations);
$notification->setReminders($reminders);
$envelopeDefinition->setNotification($notification);

Python

envelope_definition = EnvelopeDefinition()
notification = Notification()
notification.use_account_defaults = 'false' # customize the notification for this envelope
reminders = Reminders()
reminders.reminder_enabled = 'true'
reminders.reminder_delay =  '3'  # first reminder to be sent three days after envelope was sent
reminders.reminder_frequency =  '2' # keep sending reminders every two days
expirations = Expirations()
expirations.expire_enabled = 'true'
expirations.expire_after = '30'  # envelope will expire after 30 days
expirations.expire_warn = '2'  # expiration reminder would be sent two days before expiration
notification.expirations = expirations
notification.reminders = reminders
envelope_definition.notification = notification

Ruby

envelope_definition = DocuSign_eSign::EnvelopeDefinition.new
notification = DocuSign_eSign::Notification.new
notification.use_account_defaults = 'false' # customize the notification for this envelope
reminders = DocuSign_eSign::Reminders.new
reminders.reminder_enabled = 'true'
reminders.reminder_delay =  '3'  # first reminder to be sent three days after envelope was sent
reminders.reminder_frequency =  '2' # keep sending reminders every two days
expirations = DocuSign_eSign::Expirations.new
expirations.expire_enabled = 'true'
expirations.expire_after = '30'  # envelope will expire after 30 days
expirations.expire_warn = '2'  # expiration reminder would be sent two days before expiration
notification.expirations = expirations
notification.reminders = reminders
envelope_definition.notification = notification

Of course, to run the code snippets above, make sure to add the rest of the code that creates an envelope and sends it for signature. 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.