From the Trenches: API call defaults for reminders and expiration settings

Byungjae Chung

Developer Support Engineer

•

Summary•3 min read

Docusign offers fine-grained control over the settings applied to your envelopes that affect reminders and envelope expiration, depending on the combination of settings in your account and those in your envelope or template. See how to set the combination that results in the settings you want applied.

- Additional resources

Table of contents

Additional resources

Reminders and expiration enable you to remind recipients that the envelope is waiting for their signature and notify them before the envelope expires. The account default behaviors for reminders and expirations are defined in Docusign eSignature on the Settings > Reminders and Expiration page. These settings for reminders and expiration are automatically applied to your envelope if you send it through the Docusign eSignature portal. If you want to apply different reminders or expiration settings to an individual envelope, you can do it with Advanced Options before sending the envelope.

As you may notice, reminders and expiration behavior is quite simple when you send the envelope through Docusign eSignature. However, it becomes more complex when you send the envelope through the eSignature REST API. Since multiple different results can occur, it’s important to be aware of what behavior you can expect based on the properties of the Envelopes: Create API call and template usage. I’ll cover these possibilities in detail in this post.

The tables below outline what reminders and expiration settings are applied to the envelope depending on the properties of the API call.

When the notification object is not supplied:

Create envelope without template	system default
Create envelope with template	template default

When the notification object is supplied:

	`notification.useAccountDefaults = true`	notification.useAccountDefaults = false
Create envelope without template	account default	reminders/expiration specified in the request
Create envelope with template	account default	reminders/expiration specified in the request

When the notification object is not supplied

If you create the envelope without a template, the system default setting is applied. This will result in an envelope with no reminders, no expiration warning, and a 120 day expiration timer. However, if you create the envelope with a template, it defaults to what's stored in the template—that is, the reminders and expiration settings defined in the template will be applied to the envelope.

Note that if you create the envelope with multiple templates, the last template’s reminders and expiration settings are applied to the envelope. For example, if you create the envelope with template A and then apply template B via the subsequent EnvelopeTemplates: apply API call, the reminders and expiration settings of template B will eventually be applied to the envelope. If you use a composite template model, the reminders and expiration settings of the template defined in the last object of the compositeTemplates array will be applied to the envelope.

When the notification object is supplied

When the notification object is supplied, the behavior of reminders and expirations changes based on the value of the useAccountDefaults property.

useAccountDefaults: true : When true, the account default notification settings defined on Docusign eSignature in Settings > Reminders and Expiration are used for the envelope.
useAccountDefaults: false : When false, the reminders and expirations settings specified in the API call are used. The default value is false.

The sample payload below shows useAccountDefaults: false, which means the reminders and expiration settings defined in the request will be applied to the envelope.

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

If you want to know more about reminders and expiration, check our previous blog post by Drew Martin, From the Trenches: Reminders and Expiration, where he explains its characteristics in more detail. Check the post by Inbar Gazit, Common API Tasks🐈: Add Reminders and Expiration to an Envelope, if you want to see a code example.

Additional resources