Common API Tasks🐈: Add Reminders and Expiration to an Envelope
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.
(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.
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...
