Skip to main content

​
Overview

Areas represent organizational units within a church (e.g., Worship, Youth, Children’s Ministry). Each area belongs to a specific church and can contain multiple teams.

​
Authentication

All endpoints require authentication and the church.read or church.update permission depending on the operation. 
Authorization: Bearer YOUR_JWT_TOKEN

​
List Areas

GET /api/areas

Retrieve all areas for a church
Required Permission: church.read

​
Query Parameters

​
church_id
integer
Filter areas by church ID. If omitted, uses the authenticated user’s church (non-super admins)
​
churchId
integer
Alternative parameter name for church_id

​
Request

curl -X GET "https://your-domain.com/api/areas?church_id=1" \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Response

​
success
boolean
Indicates if the request was successful
​
areas
array
Array of area objects
{
  "success": true,
  "areas": [
    {
      "id": 1,
      "church_id": 1,
      "name": "Worship Ministry",
      "description": "Music and worship team coordination",
      "created_at": "2024-01-15 10:30:00"
    },
    {
      "id": 2,
      "church_id": 1,
      "name": "Youth Ministry",
      "description": "Programs for teenagers and young adults",
      "created_at": "2024-01-20 14:15:00"
    }
  ]
}
Super Admin Response: When a super admin queries without a church_id, results include church names: 
{
  "success": true,
  "areas": [
    {
      "id": 1,
      "church_id": 1,
      "church_name": "First Baptist Church",
      "name": "Worship Ministry",
      "description": "Music and worship team coordination"
    }
  ]
}

​
Create Area

POST /api/areas

Create a new area within a church
Required Permission: church.update

​
Request Body

​
name
string
required
The name of the area
​
church_id
integer
required
The ID of the church this area belongs to
​
churchId
integer
Alternative parameter name for church_id
​
description
string
Optional description of the area’s purpose

​
Request

curl -X POST https://your-domain.com/api/areas \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Children Ministry",
    "church_id": 1,
    "description": "Programs for kids ages 0-12"
  }'

​
Alternative with Query Parameter

curl -X POST "https://your-domain.com/api/areas?church_id=1" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Children Ministry"
  }'

​
Response

{
  "success": true,
  "message": "Area created"
}

​
Error Responses

Missing Required Fields (400) 
{
  "success": false,
  "error": "Name and Church ID required"
}

​
Update Area

PUT /api/areas/{id}

Update an existing area
Required Permission: church.update

​
Request Parameters

​
id
integer
required
The ID of the area to update
​
name
string
required
The updated name of the area
​
description
string
Updated description (optional)

​
Request

curl -X PUT https://your-domain.com/api/areas/1 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Worship & Creative Arts",
    "description": "Music, media, and creative ministries"
  }'

​
Response

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

​
Error Responses

Invalid ID (400) 
{
  "success": false,
  "error": "Invalid ID"
}
Missing Name (400) 
{
  "success": false,
  "error": "Name is required"
}

​
Delete Area

DELETE /api/areas/{id}

Delete an area
Required Permission: church.update
Deleting an area may affect associated teams. Ensure teams are reassigned or deleted first.

​
Request Parameters

​
id
integer
required
The ID of the area to delete

​
Request

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

​
Response

{
  "success": true,
  "message": "Area deleted"
}

​
Error Responses

Invalid ID (400) 
{
  "success": false,
  "error": "Invalid ID"
}
Deletion Failed (200) 
{
  "success": false,
  "message": "Error deleting area"
}

​
Permission Context

​
Church ID Resolution

The API automatically resolves the church context based on:
  1. Query parameter: church_id or churchId
  2. Request body: For POST/PUT requests
  3. User context: For non-super admins, uses their assigned church
  4. Super admin: Can access all churches or specify a church_id

​
Permission Checks

  • Read operations: Require church.read permission for the specified church
  • Write operations: Require church.update permission for the specified church
  • Super admins: Can perform operations across all churches

​
Activity Logging

Area creation automatically logs an activity entry: 
{
  "church_id": 1,
  "member_id": 5,
  "action": "created",
  "entity_type": "area",
  "entity_id": 3,
  "details": {
    "name": "Children Ministry"
  }
}

​
Error Codes

CodeDescription
400Bad Request - Invalid or missing parameters
401Unauthorized - Invalid or missing token
403Forbidden - Insufficient permissions for the church
404Not Found - Area doesn’t exist
500Internal Server Error

Churches

Manage church organizations

Teams

Manage teams within areas

Build docs developers (and LLMs) love

Get started for freeTalk to us