---
title: "Update the reminder lead times"
method: PUT
path: "/api/v1/reminder-settings"
tags: ["Reminders"]
---

# Update the reminder lead times

`PUT /api/v1/reminder-settings`

## Request

- Base URL: `https://volunteerreminder.com`
- URL: `https://volunteerreminder.com/api/v1/reminder-settings`
- Auth: HTTP bearer

Set the account-wide default lead time and/or a per-job override. Requires the `reminders:write` scope. Fails validation (no writes performed) if neither `global_default` nor `job_override` is provided, if a lead time leaves all three fields at zero, if `job_override.job_id` is not a job on this account, or if `channels.require_sms` is true on a plan without SMS.

## Request body

- PutReminderSettingsRequest
  - `extra_sentence` string, nullable: Optional extra sentence appended to every reminder (max 80 chars). Null or empty clears it.
  - `global_defaults` object[]: Replace the account-wide default lead set. Length is capped by the plan.
    - `days_before` integer, required: Whole days before the shift to send this reminder.
    - `hours_before` integer, required: Additional whole hours before the shift.
    - `minutes_before` integer, required: Additional whole minutes before the shift.
  - `global_default` object: Set (or replace) the account-wide default with ONE lead. Ignored when global_defaults is provided.
    - `days_before` integer, required: Whole days before the shift to send this reminder.
    - `hours_before` integer, required: Additional whole hours before the shift.
    - `minutes_before` integer, required: Additional whole minutes before the shift.
  - `job_override` object: Create or replace the lead-time override for one job. Pass `leads` for multiple reminders; otherwise the three singular fields set one lead.
    - `job_id` integer, required: The job this override applies to. Must belong to this account.
    - `leads` object[]
      - `days_before` integer, required: Whole days before the shift to send this reminder.
      - `hours_before` integer, required: Additional whole hours before the shift.
      - `minutes_before` integer, required: Additional whole minutes before the shift.
    - `days_before` integer
    - `hours_before` integer
    - `minutes_before` integer
  - `channels` object
    - `require_sms` boolean, required: Assert that SMS/text reminders should be used. There is no separate stored channel preference to persist — SMS eligibility is always computed at send time from plan entitlement plus whether each contact has a mobile number. Setting this to `true` is a guard: the whole request is REJECTED (no fields are saved) if the account's plan does not include SMS, so an agent gets an actionable upgrade-hint error instead of a silent no-op. Omit it, or set it to `false`, to make no assertion.

## Response `200`

The updated reminder configuration.

- ReminderSettingsResponse
  - `global_default` ReminderGlobalDefault, nullable, required: The first account-wide default lead time, or null if never configured. Prefer `global_defaults` when reading more than one reminder per shift.
    - `id` number, required: reminder_schedule_item id.
    - `days_before` integer, required: Whole days before the shift to send this reminder.
    - `hours_before` integer, required: Additional whole hours before the shift.
    - `minutes_before` integer, required: Additional whole minutes before the shift.
  - `global_defaults` ReminderGlobalDefault[], required: Every account-wide default lead time (longest first).
    - `id` number, required: reminder_schedule_item id.
    - `days_before` integer, required: Whole days before the shift to send this reminder.
    - `hours_before` integer, required: Additional whole hours before the shift.
    - `minutes_before` integer, required: Additional whole minutes before the shift.
  - `extra_sentence` string, nullable, required: Optional extra sentence appended to the fixed reminder wording, or null.
  - `reminder_cap` integer, required: How many reminders per shift this plan allows (1 / 2 / 3).
  - `job_overrides` ReminderJobOverride[], required: Per-job lead-time overrides. A job may have more than one row — one per lead. A live override set replaces the account defaults for that job.
    - `id` number, required: reminder_schedule_item id.
    - `job_id` number, required
    - `job_name` string, nullable, required
    - `days_before` integer, required: Whole days before the shift to send this reminder.
    - `hours_before` integer, required: Additional whole hours before the shift.
    - `minutes_before` integer, required: Additional whole minutes before the shift.
  - `channels` ReminderChannels, required
    - `email` object, required
      - `available` boolean, required: Email reminders are always available.
    - `sms` object, required
      - `available` boolean, required: Whether this account can actually send SMS/text reminders right now. This is the FULL gate the send loop applies (domain/smsGate via domain/reminderSelection): the plan must include SMS AND, for accounts created from 2026-08-10 on, a coordinator must have a verified mobile. See `reason` for which one is missing.
      - `reason` string, nullable, required: Why SMS is unavailable, or null when it is available.

## Other responses

- `400`: The request failed schema validation (`validation_error`). On the import endpoints, also when the text is UTF-16 (Excel "Unicode Text"; `unsupported_encoding`): resend it as CSV UTF-8.
- `401`: Missing or invalid API key.
- `403`: The API key lacks a scope required by this endpoint.
- `404`: The requested resource does not exist.

---

[API](https://skmtc.dev/volunteerreminder/apis/volunteerreminder-api.md) · [All operations](https://skmtc.dev/volunteerreminder/apis/volunteerreminder-api/llms.txt) · [OpenAPI document](https://skmtc.dev/volunteerreminder/apis/volunteerreminder-api/revisions/f8e7e26ba96f?raw)