![](https://images.ctfassets.net/9pvazpst9iwl/7u82G0iax7C8ucnYSsTR1K/8ee0ad3ecdb463094846db53c537203f/illustration-isometric_expanded-cube_inkwell.png)
From the Trenches: API call defaults for reminders and expiration settings
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.
![](https://images.ctfassets.net/9pvazpst9iwl/Wftxkn4hDmua0eidzd4zY/62657acbfb4f2765f88d0f752282938b/illustration-isometric_cubes-surrounding-circle_inkwell.png)
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 = 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
: Whentrue
, the account default notification settings defined on Docusign eSignature in Settings > Reminders and Expiration are used for the envelope.useAccountDefaults
: false
: Whenfalse
, the reminders and expirations settings specified in the API call are used. The default value isfalse
.
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
Byungjae Chung
Developer Support Engineer
Related posts