Blog
Home/

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

Byungjae Chung
Byungjae ChungDeveloper Support Engineer
Summary3 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

    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.

    1. useAccountDefaults: true : When true, the account default notification settings defined on Docusign eSignature in  Settings > Reminders and Expiration are used for the envelope.

    2. 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

    Byungjae Chung
    Byungjae ChungDeveloper Support Engineer

    Byungjae Chung has been a Developer Support Engineer for Docusign since 2022. He specializes in helping developers resolve issues they encounter when developing applications using Docusign APIs. You can reach Byungjae on LinkedIn.

    More posts from this author

    Related posts

    • Developer Support Articles

      From the Trenches: Reminders and Expiration

      Drew Martin
      Drew Martin
    • Common API Tasks

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

      Inbar Gazit
      Inbar Gazit
    • From the Trenches: Automate resending email notifications after updates

      Byungjae Chung
      Byungjae Chung

    From the Trenches: Reminders and Expiration

    Drew Martin
    Drew Martin
    Common API Tasks

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

    Inbar Gazit
    Inbar Gazit

    From the Trenches: Automate resending email notifications after updates

    Byungjae Chung
    Byungjae Chung

    Discover what's new with Docusign IAM or start with eSignature for free

    Explore Docusign IAMTry eSignature for Free
    Person smiling while presenting