Teams API - MinistryHub

Overview

Teams (also called groups) represent ministry groups within a church. Each team belongs to a church and optionally to an area. Teams have members with specific roles (leader, member, etc.).

Authentication

All endpoints require authentication. Permissions vary by operation:

Read: team.read
Create: team.create
Update: team.update

Authorization: Bearer YOUR_JWT_TOKEN

List Teams

GET /api/teams

Retrieve all teams for a church

Required Permission: team.read

Query Parameters

church_id

integer

Filter teams by church ID

churchId

integer

Alternative parameter for church_id

area_id

integer

Filter teams by area ID

areaId

integer

Alternative parameter for area_id

Request

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

# Teams in a specific area
curl -X GET "https://your-domain.com/api/teams?church_id=1&area_id=2" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

success

boolean

Indicates if the request was successful

groups

array

Array of team objects (note: the response uses “groups” as the key)

{
  "success": true,
  "groups": [
    {
      "id": 1,
      "church_id": 1,
      "area_id": 2,
      "name": "Worship Band",
      "description": "Sunday morning worship team",
      "leader_id": 5,
      "leader_name": "John Smith",
      "created_at": "2024-01-15 10:30:00"
    },
    {
      "id": 2,
      "church_id": 1,
      "area_id": 2,
      "name": "Tech Team",
      "description": "Audio and video production",
      "leader_id": 8,
      "leader_name": "Sarah Johnson",
      "created_at": "2024-02-01 14:20:00"
    }
  ]
}

List Team Members

GET /api/teams/{id}/members

Retrieve all members of a specific team

Required Permission: team.read

Request Parameters

integer

required

The ID of the team

Request

curl -X GET https://your-domain.com/api/teams/1/members \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

success

boolean

Indicates if the request was successful

users

array

Array of team member objects

{
  "success": true,
  "users": [
    {
      "id": 5,
      "name": "John Smith",
      "email": "[email protected]",
      "role_in_group": "leader",
      "joined_at": "2024-01-15 10:30:00"
    },
    {
      "id": 12,
      "name": "Emily Davis",
      "email": "[email protected]",
      "role_in_group": "member",
      "joined_at": "2024-02-10 09:15:00"
    }
  ]
}

Create Team

POST /api/teams

Create a new team within a church

Required Permission: team.create

Request Body

name

string

required

The name of the team

church_id

integer

required

The ID of the church this team belongs to

churchId

integer

Alternative parameter for church_id

area_id

integer

The ID of the area this team belongs to (optional)

areaId

integer

Alternative parameter for area_id

description

string

Description of the team’s purpose

leaderId

integer

Member ID to assign as team leader

Request

curl -X POST https://your-domain.com/api/teams \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Worship Band",
    "church_id": 1,
    "area_id": 2,
    "description": "Sunday morning worship team",
    "leaderId": 5
  }'

Response

{
  "success": true,
  "message": "Team created",
  "id": 3
}

Error Responses

Missing Required Fields (400)

{
  "success": false,
  "error": "Name and Church ID required"
}

Creation Failed

{
  "success": false,
  "message": "Failed to create team"
}

Update Team

PUT /api/teams/{id}

Update team details and/or leader

Required Permission: team.update

Request Parameters

integer

required

The ID of the team to update

name

string

Updated team name

description

string

Updated description

area_id

integer

Updated area ID

leaderId

integer

New leader member ID

Request

curl -X PUT https://your-domain.com/api/teams/1 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Worship & Creative Arts Team",
    "description": "Expanded worship and media team",
    "leaderId": 8
  }'

Response

{
  "success": true,
  "message": "Team updated"
}

Assign Member to Team

POST /api/teams/{id}/members

Add a member to a team with a specific role

Required Permission: team.create

Request Parameters

integer

required

The ID of the team

memberId

integer

required

The ID of the member to assign

roleInGroup

string

The role for this member (default: “member”)

Request

curl -X POST https://your-domain.com/api/teams/1/members \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "memberId": 12,
    "roleInGroup": "member"
  }'

Response

{
  "success": true
}

Error Responses

Missing Member ID (400)

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

Bulk Assign Members

POST /api/teams/{id}/members/bulk

Assign multiple members to a team at once

Required Permission: team.create

Request Parameters

integer

required

The ID of the team

memberIds

array

required

Array of member IDs to assign

Request

curl -X POST https://your-domain.com/api/teams/1/members/bulk \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "memberIds": [12, 15, 18, 22]
  }'

Response

{
  "success": true
}

Join Team (Self-Service)

POST /api/teams/{id}/join

Allow authenticated user to join a team

Required Permission: team.create

Request Parameters

integer

required

The ID of the team to join

Request

curl -X POST https://your-domain.com/api/teams/1/join \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

{
  "success": true
}

Delete Team

DELETE /api/teams/{id}

Delete a team

Required Permission: team.update

Deleting a team will remove all member assignments. This action may be irreversible depending on your database configuration.

Request Parameters

integer

required

The ID of the team to delete

Request

curl -X DELETE https://your-domain.com/api/teams/1 \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

{
  "success": true
}

Church Context Resolution

The API resolves the church context in the following order:

Query parameter: church_id or churchId
Request body: For POST/PUT requests
User’s church: For non-super admins without explicit church_id
Required: Returns 400 error if church context cannot be determined

Activity Logging

Team operations automatically log activities: Team Creation:

{
  "church_id": 1,
  "member_id": 5,
  "action": "created",
  "entity_type": "team",
  "entity_id": 3,
  "details": {"name": "Worship Band"}
}

Error Codes

Code	Description
400	Bad Request - Missing church_id, invalid parameters
401	Unauthorized - Invalid or missing token
403	Forbidden - Insufficient permissions
404	Not Found - Team doesn’t exist
500	Internal Server Error

Areas

Manage areas that contain teams

People

Manage church members

Calendar

Schedule team meetings and events

Authentication

Endpoints

​Overview

​Authentication

​List Teams

GET /api/teams

​Query Parameters

​Request

​Response

​List Team Members

GET /api/teams/{id}/members

​Request Parameters

​Request

​Response

​Create Team

POST /api/teams

​Request Body

​Request

​Response

​Error Responses

​Update Team

PUT /api/teams/{id}

​Request Parameters

​Request

​Response

​Assign Member to Team

POST /api/teams/{id}/members

​Request Parameters

​Request

​Response

​Error Responses

​Bulk Assign Members

POST /api/teams/{id}/members/bulk

​Request Parameters

​Request

​Response

​Join Team (Self-Service)

POST /api/teams/{id}/join

​Request Parameters

​Request

​Response

​Delete Team

DELETE /api/teams/{id}

​Request Parameters

​Request

​Response

​Church Context Resolution

​Activity Logging

​Error Codes

​Related APIs

Areas

People

Calendar

Build docs developers (and LLMs) love

Overview

Authentication

List Teams

Query Parameters

Request

Response

List Team Members

Request Parameters

Request

Response

Create Team

Request Body

Request

Response

Error Responses

Update Team

Request Parameters

Request

Response

Assign Member to Team

Request Parameters

Request

Response

Error Responses

Bulk Assign Members

Request Parameters

Request

Response

Join Team (Self-Service)

Request Parameters

Request

Response

Delete Team

Request Parameters

Request

Response

Church Context Resolution

Activity Logging

Error Codes

Related APIs