Calendar API - MinistryHub

Overview

The Calendar API manages church meetings, events, and services. It includes functionality for creating events, viewing schedules, assigning team members, and managing playlists for worship services.

Authentication

All endpoints require authentication with specific permissions:

Read: calendar.read
Create: meeting.create
Update/Assign: meeting.update

Authorization: Bearer YOUR_JWT_TOKEN

List Events

GET /api/calendar/events

Retrieve all meetings and events for a church

Required Permission: calendar.read

Query Parameters

church_id

integer

Filter events by church ID. Defaults to authenticated user’s church.

churchId

integer

Alternative parameter for church_id

start

string

Filter events starting from this date (ISO 8601 format: YYYY-MM-DD)

end

string

Filter events ending before this date (ISO 8601 format: YYYY-MM-DD)

Request

# All events for a church
curl -X GET "https://your-domain.com/api/calendar/events?church_id=1" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Events in a date range
curl -X GET "https://your-domain.com/api/calendar/events?church_id=1&start=2024-03-01&end=2024-03-31" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

success

boolean

Indicates if the request was successful

instances

array

Array of meeting/event objects

{
  "success": true,
  "instances": [
    {
      "id": 15,
      "calendar_id": 1,
      "title": "Sunday Morning Service",
      "description": "Regular Sunday worship service",
      "start_at": "2024-03-17 10:00:00",
      "end_at": "2024-03-17 12:00:00",
      "location": "Main Sanctuary",
      "created_by_member_id": 5,
      "created_at": "2024-03-01 14:30:00"
    },
    {
      "id": 18,
      "calendar_id": 1,
      "title": "Worship Team Rehearsal",
      "description": "Prepare for Sunday service",
      "start_at": "2024-03-15 19:00:00",
      "end_at": "2024-03-15 21:00:00",
      "location": "Fellowship Hall",
      "created_by_member_id": 5,
      "created_at": "2024-03-10 09:15:00"
    }
  ]
}

Get Event Details

GET /api/calendar/{id}

Retrieve detailed information about a specific event

Required Permission: calendar.read

Request Parameters

integer

required

The unique identifier of the meeting/event

Request

curl -X GET https://your-domain.com/api/calendar/15 \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

{
  "success": true,
  "details": {
    "id": 15,
    "calendar_id": 1,
    "church_id": 1,
    "title": "Sunday Morning Service",
    "description": "Regular Sunday worship service",
    "start_at": "2024-03-17 10:00:00",
    "end_at": "2024-03-17 12:00:00",
    "location": "Main Sanctuary",
    "created_by_member_id": 5,
    "created_by_name": "John Smith",
    "playlist_id": 3,
    "assignments": [
      {
        "member_id": 5,
        "member_name": "John Smith",
        "role": "Worship Leader",
        "instrument_id": 5,
        "instrument_name": "Acoustic Guitar"
      },
      {
        "member_id": 12,
        "member_name": "Emily Davis",
        "role": "Vocals",
        "instrument_id": null,
        "instrument_name": null
      }
    ]
  }
}

Error Response

Not Found (404)

{
  "success": false,
  "error": "Event not found"
}

Create Event

POST /api/calendar

Create a new meeting or event

Required Permission: meeting.create

Request Body

title

string

required

The title of the event

church_id

integer

The church ID (uses authenticated user’s church if omitted)

churchId

integer

Alternative parameter for church_id

description

string

Description of the event

start_at

string

Start date/time (ISO 8601: YYYY-MM-DD HH:MM:SS)

date

string

Alternative parameter for start_at

end_at

string

End date/time (ISO 8601: YYYY-MM-DD HH:MM:SS)

location

string

Physical location of the event

Request

curl -X POST https://your-domain.com/api/calendar \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Easter Sunday Service",
    "description": "Special Easter celebration service",
    "start_at": "2024-03-31 10:00:00",
    "end_at": "2024-03-31 12:30:00",
    "location": "Main Sanctuary",
    "church_id": 1
  }'

Response

{
  "success": true,
  "id": 22
}

Process Details

Ensures a default calendar exists for the church
Creates the meeting record
Logs activity in the system
Returns the new meeting ID

Error Response

Missing Church Context (400)

{
  "success": false,
  "error": "Church ID required for meeting creation"
}

Get Assignment Data

GET /api/calendar/assignment-data

Retrieve data needed for creating assignments (members, instruments, playlists)

Required Permission: calendar.read

Request

curl -X GET https://your-domain.com/api/calendar/assignment-data \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

{
  "success": true,
  "members": [
    {
      "id": 5,
      "name": "John Smith",
      "email": "[email protected]",
      "role_id": 2
    },
    {
      "id": 12,
      "name": "Emily Davis",
      "email": "[email protected]",
      "role_id": 5
    }
  ],
  "instruments": [
    {
      "id": 1,
      "name": "Acoustic Guitar"
    },
    {
      "id": 2,
      "name": "Electric Guitar"
    },
    {
      "id": 3,
      "name": "Piano/Keys"
    },
    {
      "id": 4,
      "name": "Drums"
    },
    {
      "id": 5,
      "name": "Bass"
    }
  ],
  "playlists": [
    {
      "id": 3,
      "name": "Sunday Service - March 17",
      "song_count": 6
    },
    {
      "id": 5,
      "name": "Easter Sunday Set",
      "song_count": 8
    }
  ]
}

Assign Member to Event

POST /api/calendar/assignment

Assign a team member to a meeting with a specific role and instrument

Required Permission: meeting.update

Request Body

meetingId

integer

required

The ID of the meeting to assign to

instanceId

integer

Alternative parameter for meetingId

memberId

integer

required

The ID of the member to assign

role

string

The role for this assignment (e.g., “Worship Leader”, “Vocals”, “Tech”)

instrumentId

integer

The instrument ID if applicable

Request

curl -X POST https://your-domain.com/api/calendar/assignment \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "meetingId": 15,
    "memberId": 12,
    "role": "Vocals",
    "instrumentId": null
  }'

Response

{
  "success": true
}

Process Details

Creates the assignment record
Logs activity for tracking
Creates a notification for the assigned member
Notification includes meeting title and link

Error Response

Missing Required Fields (400)

{
  "success": false,
  "error": "Meeting ID and Member ID required"
}

Notifications

When a member is assigned to an event, they receive a notification:

Notification Object

{
  "member_id": 12,
  "type": "assignment",
  "title": "Nueva asignación",
  "message": "Has sido asignado a la reunión: Sunday Morning Service",
  "link": "/mainhub/calendar"
}

Church Context Resolution

The API resolves church context in the following order:

Request body church_id or churchId
Query parameter church_id or churchId
User’s church from authenticated member data
Super admin fallback uses first available church

Date Filtering

When using date filters:

Use ISO 8601 format: YYYY-MM-DD
start parameter: Events starting on or after this date
end parameter: Events starting before this date
Both parameters are optional
Omitting both returns all future events

Example: Get March 2024 events

start=2024-03-01&end=2024-04-01

Activity Logging

Event Creation

{
  "church_id": 1,
  "member_id": 5,
  "action": "created",
  "entity_type": "meeting",
  "entity_id": 22,
  "details": {"name": "Easter Sunday Service"}
}

Member Assignment

{
  "church_id": 1,
  "member_id": 5,
  "action": "assigned",
  "entity_type": "meeting",
  "entity_id": 15,
  "details": {
    "target_name": "Emily Davis",
    "meeting_title": "Sunday Morning Service"
  }
}

Error Codes

Code	Description
400	Bad Request - Missing required fields or invalid church context
401	Unauthorized - Invalid or missing token
403	Forbidden - Insufficient permissions
404	Not Found - Event doesn’t exist
500	Internal Server Error

Common Assignment Roles

Worship Leader - Leads the worship team
Vocals - Singer
Tech - Audio/video operator
Member - General team member
Coordinator - Service coordinator

Playlists

Manage song playlists for services

Teams

Manage worship teams

People

Manage church members

Authentication

Endpoints

​Overview

​Authentication

​List Events

GET /api/calendar/events

​Query Parameters

​Request

​Response

​Get Event Details

GET /api/calendar/{id}

​Request Parameters

​Request

​Response

​Error Response

​Create Event

POST /api/calendar

​Request Body

​Request

​Response

​Process Details

​Error Response

​Get Assignment Data

GET /api/calendar/assignment-data

​Request

​Response

​Assign Member to Event

POST /api/calendar/assignment

​Request Body

​Request

​Response

​Process Details

​Error Response

​Notifications

​Notification Object

​Church Context Resolution

​Date Filtering

​Activity Logging

​Event Creation

​Member Assignment

​Error Codes

​Common Assignment Roles

​Related APIs

Playlists

Teams

People

Build docs developers (and LLMs) love

Overview

Authentication

List Events

Query Parameters

Request

Response

Get Event Details

Request Parameters

Request

Response

Error Response

Create Event

Request Body

Request

Response

Process Details

Error Response

Get Assignment Data

Request

Response

Assign Member to Event

Request Body

Request

Response

Process Details

Error Response

Notifications

Notification Object

Church Context Resolution

Date Filtering

Activity Logging

Event Creation

Member Assignment

Error Codes

Common Assignment Roles

Related APIs