Schedules

Update a schedule

Partial update — only send the fields you want to change. Unset fields keep their current value. Recomputes and re-materializes future occurrences when recurrence fields change. An edit that would remove upcoming shifts saves nothing and answers 409 confirm_remove_required with the removed days and a confirm_token; once the user agrees, resend the same edit with confirm_remove: true and that confirm_token. Does NOT change the roster: use POST /schedules/{id}/roster for that. Requires the schedules:write scope.

patch/api/v1/schedules/{id}

Request

  • Base URL: https://volunteerreminder.com
  • URL: https://volunteerreminder.com/api/v1/schedules/{id}
  • Auth: HTTP bearer

Path parameters

idstring required

The schedule's numeric id.

Example:42

Request body

descriptionstring

Short label shown on the schedule list and in reminder messages, e.g. "Sunday morning greeters".

job_namestring

The role/task volunteers are reminded about. Matched case-insensitively against this account's existing jobs and created if new.

group_idinteger nullable

Id of an existing volunteer group to attach, or null. An id not owned by this account is silently ignored (treated as null).

schedule_type'weekly' | 'biweekly' | 'monthly_fixed' | 'monthly_nth' | 'bimonthly_fixed' | 'bimonthly_nth' | 'custom'

Recurrence shape. 'weekly' recurs on one or more days of the week; 'biweekly' is the same weekday mask every 14 days (start_date picks which week — it is not BiMonthly, which is every other MONTH); 'monthly_fixed' / 'bimonthly_fixed' recur on a fixed day of the month; 'monthly_nth' / 'bimonthly_nth' recur on the Nth weekday of the month; the 'bimonthly_*' variants additionally alternate months starting from start_month; 'custom' uses an explicit list of dates.

days_of_weekstring[]

Days of the week this recurs on. Required (non-empty) when schedule_type is 'weekly' or 'biweekly'; ignored for every other schedule_type.

nth_weekday'sunday' | 'monday' | 'tuesday' | 'wednesday' | 'thursday' | 'friday' | 'saturday' | 'null' nullable

The weekday that recurs. Used by schedule_type 'monthly_nth' / 'bimonthly_nth'; defaults to Sunday if omitted for those types.

week_of_monthinteger

Which occurrence of the weekday in the month (1st through 5th). Used by 'monthly_nth' / 'bimonthly_nth'; defaults to 1.

day_of_monthinteger

Fixed day of the month. Used by 'monthly_fixed' / 'bimonthly_fixed'; defaults to 1. Clamped to the last day of shorter months (e.g. 31 in February becomes the 28th/29th).

start_monthinteger

Anchor month (1=January .. 12=December) the every-other-month cadence steps from. Used by 'bimonthly_fixed' / 'bimonthly_nth'; defaults to the account's current month.

timestring nullable

Wall-clock time of day "HH:mm" (24h) in the account's timezone, or null for no specific time (midnight).

start_datestring nullable

"yyyy-MM-dd" in the account's timezone before which no occurrences materialize, or null for no lower bound. For 'biweekly' this date also picks which week the 14-day rotation lands on (Sunday-week of this day is an on-week). When omitted for biweekly, the server stores the first selected weekday with a shift still ahead (today if it is selected and its start time hasn't passed, else the next selected weekday; the first shift), and the rotation counts from there. On PATCH of an existing biweekly schedule, null keeps the stored date (the rotation only moves when you send a new date).

end_datestring nullable

"yyyy-MM-dd" in the account's timezone after which occurrence materialization stops, or null for no end date.

custom_datesstring[]

Explicit list of "yyyy-MM-dd" dates. Required (non-empty) when schedule_type is 'custom'; ignored otherwise.

notesstring nullable

Free-text internal notes.

confirm_removeboolean

Set true, together with confirm_token, to apply an edit that removes upcoming shifts (e.g. a new start_month or fewer weekdays). Without both, such an edit saves nothing and answers 409 confirm_remove_required listing the shifts; resend only once the user has agreed to drop them.

confirm_tokenstring

The confirm_token from the 409 confirm_remove_required for this same edit. It only matches while the edit and the shifts it removes are unchanged; otherwise you get a fresh 409 to review.

Example request

{
  "description": "Sunday morning greeters",
  "job_name": "Greeter",
  "schedule_type": "weekly",
  "days_of_week": [
    "sunday"
  ],
  "nth_weekday": "tuesday",
  "week_of_month": 2,
  "day_of_month": 15,
  "start_month": 1,
  "time": "09:00",
  "custom_dates": [
    "2026-08-01",
    "2026-09-05"
  ],
  "confirm_remove": true,
  "confirm_token": "crm_3f2a9c1e5b7d4a608e1f2c3b4a5d6e7f"
}

Response

The updated schedule.

idnumber required

Schedule id.

descriptionstring required

Short label shown on the schedule list and in reminder messages, e.g. "Sunday morning greeters".

job_idnumber required

Job/role id (use for per-job reminder overrides).

job_namestring nullable required

Resolved job/role name.

group_idinteger nullable required

Id of an existing volunteer group to attach, or null. An id not owned by this account is silently ignored (treated as null).

group_namestring nullable required

Resolved group name, or null.

schedule_type'weekly' | 'biweekly' | 'monthly_fixed' | 'monthly_nth' | 'bimonthly_fixed' | 'bimonthly_nth' | 'custom' required

Recurrence shape. 'weekly' recurs on one or more days of the week; 'biweekly' is the same weekday mask every 14 days (start_date picks which week — it is not BiMonthly, which is every other MONTH); 'monthly_fixed' / 'bimonthly_fixed' recur on a fixed day of the month; 'monthly_nth' / 'bimonthly_nth' recur on the Nth weekday of the month; the 'bimonthly_*' variants additionally alternate months starting from start_month; 'custom' uses an explicit list of dates.

days_of_weekstring[] required

Days of the week this recurs on. Required (non-empty) when schedule_type is 'weekly' or 'biweekly'; ignored for every other schedule_type.

nth_weekday'sunday' | 'monday' | 'tuesday' | 'wednesday' | 'thursday' | 'friday' | 'saturday' | 'null' nullable required

The weekday that recurs. Used by schedule_type 'monthly_nth' / 'bimonthly_nth'; defaults to Sunday if omitted for those types.

week_of_monthnumber nullable required

Nth-weekday occurrence (1-5), or null when schedule_type doesn't use it.

day_of_monthnumber nullable required

Fixed day of month, or null when schedule_type doesn't use it.

start_monthnumber nullable required

Bimonthly anchor month (1-12), or null when schedule_type doesn't use it.

timestring nullable required

Wall-clock time of day "HH:mm" (24h) in the account's timezone, or null for no specific time (midnight).

start_datestring nullable required

"yyyy-MM-dd" in the account's timezone before which no occurrences materialize, or null for no lower bound. For 'biweekly' this date also picks which week the 14-day rotation lands on (Sunday-week of this day is an on-week). When omitted for biweekly, the server stores the first selected weekday with a shift still ahead (today if it is selected and its start time hasn't passed, else the next selected weekday; the first shift), and the rotation counts from there. On PATCH of an existing biweekly schedule, null keeps the stored date (the rotation only moves when you send a new date).

end_datestring nullable required

"yyyy-MM-dd" in the account's timezone after which occurrence materialization stops, or null for no end date.

custom_datesstring[] required

Explicit list of "yyyy-MM-dd" dates. Required (non-empty) when schedule_type is 'custom'; ignored otherwise.

contact_idsinteger[] required

Volunteer roster for this schedule. Ids not owned by this account are silently dropped.

notesstring nullable required

Free-text internal notes.

next_occurrence_atnumber nullable required

Epoch ms (UTC) of the next upcoming, attendable occurrence, or null.

is_mutedboolean required

Whether reminders for this schedule are muted.

created_atnumber required

Epoch ms (UTC) this schedule was created.

Example response

{
  "id": 42,
  "description": "Sunday morning greeters",
  "schedule_type": "weekly",
  "days_of_week": [
    "sunday"
  ],
  "nth_weekday": "tuesday",
  "time": "09:00",
  "custom_dates": [
    "2026-08-01",
    "2026-09-05"
  ],
  "contact_ids": [
    101,
    102
  ]
}

Changes

No recorded changes to this operation across all 1 revision of this API.