Volunteer Serving API - TheFaithApp Documentation

Contracts

Volunteer Serving uses two authenticated contracts:

Staff administration endpoints under /api/volunteer-serving require an authenticated administrator and the permission listed for the action.
Member endpoints under /v2/volunteer require the signed-in member’s bearer token and always resolve records inside that member’s church.

These endpoints power TheFaithApp’s web dashboard and Flutter app. Existing partner apps should continue using the published v1 Volunteer Opportunity endpoints unless first-party Volunteer Hub access has been agreed for that app.

Staff Permissions

Permission	Scope
`volunteer_schedule`	Roles, teams, templates, plans, assignments, swaps, standby alerts, attendance, feedback, and recognition
`volunteer_sensitive`	Eligibility, clearances, training records, restricted wellbeing signals, and private leader notes
`worship_planning`	Songs, arrangements, preparation assets, run-of-show items, and CCLI reports

An administrator may have more than one permission. Read responses omit sensitive fields unless the token has volunteer_sensitive.

Staff Endpoints

Action	Endpoint
Load the workspace and form options	`GET /api/volunteer-serving/overview`, `GET /api/volunteer-serving/options`
Create or update a role	`POST /api/volunteer-serving/roles`, `PUT /api/volunteer-serving/roles/{uuid}`
Add or update a team member	`POST /api/volunteer-serving/memberships`, `PUT /api/volunteer-serving/memberships/{uuid}`
Review a restricted volunteer profile	`PUT /api/volunteer-serving/profiles/{memberId}`
Create or generate from a template	`POST /api/volunteer-serving/templates`, `POST /api/volunteer-serving/templates/{uuid}/generate`
Create, update, publish, or duplicate a plan	`POST /api/volunteer-serving/plans`, `PUT /api/volunteer-serving/plans/{uuid}`, `POST /api/volunteer-serving/plans/{uuid}/publish`, `POST /api/volunteer-serving/plans/{uuid}/duplicate`
Create or update an assignment	`POST /api/volunteer-serving/plans/{planUuid}/assignments`, `PUT /api/volunteer-serving/assignments/{uuid}`
Review a swap or contact standby volunteers	`PUT /api/volunteer-serving/swaps/{uuid}`, `POST /api/volunteer-serving/assignments/{uuid}/standby`
Record leader feedback or recognition	`POST /api/volunteer-serving/assignments/{uuid}/leader-feedback`, `POST /api/volunteer-serving/recognition`
Manage training	`POST /api/volunteer-serving/training/requirements`, `PUT /api/volunteer-serving/training/records/{uuid}`
Manage the run of show	`POST /api/volunteer-serving/plans/{planUuid}/items`, `PUT /api/volunteer-serving/plan-items/{uuid}`, `PUT /api/volunteer-serving/plans/{planUuid}/items/reorder`, `DELETE /api/volunteer-serving/plan-items/{uuid}`
Manage songs and preparation files	`POST /api/volunteer-serving/songs`, `POST /api/volunteer-serving/songs/{songUuid}/arrangements`, `POST /api/volunteer-serving/songs/{songUuid}/assets`
Generate a song usage report	`GET /api/volunteer-serving/reports/ccli`

Publishing a plan changes named draft assignments to invited and empty assignments to unfilled. When coverage or eligibility warnings exist, the request must explicitly send confirm_warnings: true after a human review. Safety-clearance failures cannot be overridden.

Member Endpoints

Member action	Endpoint
Load the complete Volunteer Hub	`GET /v2/volunteer/hub`
Update reminders, load, rest, recognition, or conduct	`PUT /v2/volunteer/profile`
Add/remove weekly availability	`POST /v2/volunteer/availability`, `DELETE /v2/volunteer/availability/{uuid}`
Add/remove a blockout	`POST /v2/volunteer/blockouts`, `DELETE /v2/volunteer/blockouts/{uuid}`
Confirm or decline	`POST /v2/volunteer/assignments/{uuid}/respond`
Request a swap	`POST /v2/volunteer/assignments/{uuid}/swap`
Send private wellbeing feedback	`POST /v2/volunteer/assignments/{uuid}/feedback`
Check in	`POST /v2/volunteer/assignments/{uuid}/check-in`
Claim an open role	`POST /v2/volunteer/assignments/{uuid}/claim`
Invalidate and replace the private calendar link	`POST /v2/volunteer/calendar/rotate`

The hub response includes the member’s own profile, team memberships, availability, blockouts, assignments, eligible open roles, active Volunteer Opportunities, training records, and opted-in recognition. It excludes private leader notes, eligibility notes, clearance values, health flags, and another member’s schedule.

Calendar Feed

GET /api/public/volunteer/calendar/{token}.ics returns the member’s published serving commitments as iCalendar data. Treat the random token as a secret: never log it, include it in analytics, or place it in a public page. A call to POST /v2/volunteer/calendar/rotate immediately invalidates the old URL and returns a profile containing the replacement URL.

Reminder Delivery

The scheduled volunteers:send-reminders workflow creates idempotent assignment and training reminders. It respects quiet hours, category/channel preferences, and active email or confirmed SMS consent before dispatching through existing communication providers.

​Contracts

​Staff Permissions

​Staff Endpoints

​Member Endpoints

​Calendar Feed

​Reminder Delivery