Overview The Churches API allows super admins to manage church organizations within the MinistryHub platform. Each church is a separate tenant with its own data, members, and settings.
Authentication All endpoints require authentication via Bearer token:
Authorization: Bearer YOUR_JWT_TOKEN
Most operations require the church.update permission. Only super admins can create, update, or delete churches.
List All Churches
GET /api/churches Retrieve all churches in the system
Required Permission: church.readRequest curl -X GET https://your-domain.com/api/churches \ -H "Authorization: Bearer YOUR_TOKEN"
Response { "success" : true , "churches" : [ { "id" : 1 , "name" : "First Baptist Church" , "slug" : "first-baptist" , "is_active" : true , "created_at" : "2024-01-15 10:30:00" }, { "id" : 2 , "name" : "Grace Community Church" , "slug" : "grace-community" , "is_active" : true , "created_at" : "2024-02-20 14:45:00" } ] }
Get My Churches
GET /api/churches/my_churches Retrieve churches associated with the authenticated user
Required Permission: church.readBehavior:
Super admins see all churches
Regular users see only their assigned church
Request curl -X GET https://your-domain.com/api/churches/my_churches \ -H "Authorization: Bearer YOUR_TOKEN"
Response { "success" : true , "churches" : [ { "id" : 1 , "name" : "First Baptist Church" , "slug" : "first-baptist" , "is_active" : true } ] }
Get Church by ID
GET /api/churches/{id} Retrieve details of a specific church
Required Permission: church.readRequest The unique identifier of the church
curl -X GET https://your-domain.com/api/churches/1 \ -H "Authorization: Bearer YOUR_TOKEN"
Response { "success" : true , "church" : { "id" : 1 , "name" : "First Baptist Church" , "slug" : "first-baptist" , "is_active" : true , "created_at" : "2024-01-15 10:30:00" , "updated_at" : "2024-03-01 09:15:00" } }
Error Response { "success" : false , "error" : "Iglesia no encontrada" }
Create Church
POST /api/churches Create a new church organization
Required Permission: church.update (Super admin only)Request Body The full name of the church
URL-friendly identifier for the church (must be unique)
Request curl -X POST https://your-domain.com/api/churches \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "New Hope Church", "slug": "new-hope" }'
Response Indicates if the church was created successfully
The ID of the newly created church
{ "success" : true , "id" : 3 , "message" : "Iglesia creada correctamente" }
Error Responses Missing Data (400) { "success" : false , "error" : "Datos incompletos" }
Creation Failed (500) { "success" : false , "error" : "No se pudo crear la iglesia" }
Update Church
PUT /api/churches/{id} Update an existing church
Required Permission: church.update (Super admin only)Request Parameters The ID of the church to update
The updated name of the church
The updated slug for the church
Request curl -X PUT https://your-domain.com/api/churches/1 \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "First Baptist Church - Downtown", "slug": "first-baptist-downtown" }'
Response { "success" : true , "message" : "Iglesia actualizada" }
Error Responses Unauthorized (403) { "success" : false , "error" : "No tienes permisos para editar iglesias" }
Invalid ID (400) { "success" : false , "error" : "ID de iglesia inválido" }
Delete Church
DELETE /api/churches/{id} Delete a church (two-stage process)
Required Permission: church.update (Super admin only)Deletion Process:
First DELETE: Deactivates the church (is_active = false)
Second DELETE: Permanently removes the church and all associated data
Request The ID of the church to delete
# First call - deactivates curl -X DELETE https://your-domain.com/api/churches/1 \ -H "Authorization: Bearer YOUR_TOKEN" # Second call - permanently deletes curl -X DELETE https://your-domain.com/api/churches/1 \ -H "Authorization: Bearer YOUR_TOKEN"
Response (Stage 1: Deactivate) { "success" : true , "message" : "Iglesia desactivada correctamente" }
Response (Stage 2: Hard Delete) { "success" : true , "message" : "Iglesia y todos sus datos han sido eliminados permanentemente" }
Error Responses Not Found (404) { "success" : false , "error" : "Iglesia no encontrada" }
Unauthorized (403) { "success" : false , "error" : "No tienes permisos para borrar iglesias" }
Restore Church
POST /api/churches/restore Restore a deactivated church
Required Permission: church.updateRequest Body The ID of the church to restore
Request curl -X POST https://your-domain.com/api/churches/restore \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{"id": 1}'
Response { "success" : true , "message" : "Iglesia restaurada correctamente" }
Error Codes Code Description 400 Bad Request - Invalid or missing parameters 401 Unauthorized - Invalid or missing authentication token 403 Forbidden - Insufficient permissions 404 Not Found - Church doesn’t exist 500 Internal Server Error - Database or server error
Areas Manage ministry areas within churches
Teams Manage teams and groups
People Manage church members
Reports View church statistics and reports