From the Trenches: Reminders and Expiration

When creating an envelope, it's important to consider how often the recipient should receive reminder emails, and when the envelope should expire. Default reminders and expiration are set in your account’s Admin section. When you’re creating integrations, you can specify reminders and expiration under the notification parameter in the envelope definition, and retrieve them from an existing envelope by making a GET call to: /accounts/{account_id}/envelopes/{envelope_id}/notification (as documented in the Developer Center).

If no notifications are defined, system defaults will be used instead of account defaults. This will result in an envelope with no reminders, no expiration warning, and a 120 day expiration timer.

If you will not be defining custom reminders or expiration on an envelope, the UseAccountDefaults parameter should be set to "true."

Here’s an example set of default values from my account:

ReminderDelay: 44
ReminderFrequency: 33
ExpireAfter: 22
ExpireWarn: 11

Also, if the UseAccountDefaults parameter is set to true, the account's default settings (defined in Go to Admin > Reminders and Expiration) will be used. This is the case regardless of other parameters being defined:

"notification": {
	"useAccountDefaults": "true",
	"reminders": {
        "reminderEnabled": "true",
        "reminderDelay": "2",
        "reminderFrequency": "1"
	},
	"expirations": {
        "expireEnabled": "True",
        "expireAfter": "250",
        "expireWarn": "5"
	}
}

This results in the account's defaults being used, regardless of the other parameters set:

ReminderDelay: 44
ReminderFrequency: 33
ExpireAfter: 22
ExpireWarn: 11

If your goal is to set custom settings in the envelope, set UseAccountDefaults to false, ReminderEnabled and ExpireEnabled to true, and then set the remaining parameters as you wish:

"notification": {
	"useAccountDefaults": "false",
	"reminders": {
        "reminderEnabled": "true",
        "reminderDelay": "2",
        "reminderFrequency": "1"
	},
	"expirations": {
        "expireEnabled": "true",
        "expireAfter": "250",
        "expireWarn": "5"
	}
}

This results in what you would expect:

ReminderDelay: 2
ReminderFrequency: 1
ExpireAfter: 250
ExpireWarn: 5

Setting both ReminderEnabled and ExpireEnabled to false results in the related parameters being discarded and the account defaults being used:

"notification": {
	"useAccountDefaults": "false",
	"reminders": {
        "reminderEnabled": "false",
        "reminderDelay": "2",
        "reminderFrequency": "1"
	},
	"expirations": {
        "expireEnabled": "false",
        "expireAfter": "250",
        "expireWarn": "5"
	}
}

This produces the following results:

ReminderDelay: 44
ReminderFrequency: 33
ExpireAfter: 22
ExpireWarn: 11

Note that all Docusign envelopes expire at some point. If you want an extended expiration period, use an ExpireAfter value of 999.

If you want either custom reminders or custom expirations, you should define both. Defining one without the other results in the undefined values being set to 0, not the account defaults:

	"notification": {
		{
		"expirations": {
		"expireAfter": "250",
		"expireEnabled": "true",
		"expireWarn": "5"
	},
	"useAccountDefaults": "false"
	}
}

This produces the following results:

ReminderDelay: 0
ReminderFrequency: 0
ExpireAfter: 250
ExpireWarn: 5

Likewise, when reminders are defined without expirations:

"notification": {
	"reminders": {
		"reminderDelay": "2",
		"reminderEnabled": "true",
		"reminderFrequency": "1"
  	},
  	"useAccountDefaults": "false"
}

This produces the following results:

ReminderDelay: 2
ReminderFrequency: 1
ExpireAfter: 0
ExpireWarn: 0

Note that an envelope with ExpireAfter set to 0 will expire the next day.

All of this holds true whether you are calling the API directly or through an SDK. In fact, when I was testing to confirm, I used the C# SDK for ease of repetition. Adding notifications to the envelope definition can look like this:

Expirations expirations = new Expirations("250", "false", "5"); //ExpireAfter, Enabled, Warning
Reminders reminders = new Reminders("2", "true", "1");  //ReminderDelay, Enabled, Frequency
envelopeDefinition.Notification = new Notification(expirations, reminders, "false"); //Expirations, Reminders, UseDefaults

Pulling the notifications on a live envelope can be done like this:

Notification activeNotification = envelopesApi.GetNotificationSettings(accountId, envelopeId);

Docusign gives you, through the Admin controls and the API, the power and flexibility to manage reminders and expirations as you wish. Be sure to set defaults in the Admin section that meet the largest proportion of your needs, and use the API to specify custom settings as needed.

Make sure to signup for our Developer Newsletter to stay up-do-date with the latest Docusign developer news.