Schedules

Create a schedule

Creates a schedule and materializes its upcoming occurrences. Validation mirrors the dashboard's add-schedule form. Requires the schedules:write scope.

post/api/v1/schedules

Request

Base URL: https://volunteerreminder.com
URL: https://volunteerreminder.com/api/v1/schedules
Auth: HTTP bearer

Request body

descriptionstring required

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

job_namestring required

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

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.

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.

contact_idsinteger[]

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

notesstring nullable

Free-text internal notes.

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"
  ],
  "contact_ids": [
    101,
    102
  ]
}

Response

The created 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.

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.

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

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.