Skip to main content

​
Overview

The People API manages church members throughout their lifecycle: invitation, approval, profile management, and deletion. It supports both individual and bulk invitation workflows.

​
Authentication

All endpoints require authentication with specific permissions:
  • List/View: church.update
  • Invite: users.invite
  • Approve: users.approve
  • Delete: users.delete
Authorization: Bearer YOUR_JWT_TOKEN

​
List People

GET /api/people

Retrieve all members for a church
Required Permission: church.update

​
Query Parameters

​
church_id
integer
Filter by church ID. Defaults to authenticated user’s church for non-super admins
​
churchId
integer
Alternative parameter for church_id

​
Request

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

​
Response

{
  "success": true,
  "users": [
    {
      "id": 5,
      "name": "John Smith",
      "email": "[email protected]",
      "church_id": 1,
      "role_id": 2,
      "role_name": "Leader",
      "status": "active",
      "created_at": "2024-01-15 10:30:00"
    },
    {
      "id": 8,
      "name": "Sarah Johnson",
      "email": "[email protected]",
      "church_id": 1,
      "role_id": 5,
      "role_name": "Member",
      "status": "pending",
      "created_at": "2024-02-20 14:15:00"
    }
  ]
}

​
Get Member Details

GET /api/people/{id}

Retrieve detailed information about a specific member
Required Permission: church.update

​
Request Parameters

​
id
integer
required
The unique identifier of the member

​
Request

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

​
Response

{
  "success": true,
  "user": {
    "id": 5,
    "name": "John Smith",
    "email": "[email protected]",
    "church_id": 1,
    "role_id": 2,
    "status": "active",
    "phone": "+1-555-0123",
    "address": "123 Main St",
    "created_at": "2024-01-15 10:30:00",
    "updated_at": "2024-03-01 09:20:00"
  }
}

​
Get Member’s Areas

GET /api/people/{id}/areas

Retrieve all areas a member is assigned to
Required Permission: church.update

​
Request

curl -X GET https://your-domain.com/api/people/5/areas \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Response

{
  "success": true,
  "areaIds": [1, 2, 5]
}

​
Get Member’s Groups

GET /api/people/{id}/groups

Retrieve all teams/groups a member belongs to
Required Permission: church.update

​
Request

curl -X GET https://your-domain.com/api/people/5/groups \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Response

{
  "success": true,
  "groupIds": [3, 7, 12]
}

​
Invite Member

POST /api/people/invite

Invite a new member to join the church
Required Permission: users.invite

​
Request Body

​
name
string
required
Full name of the person to invite
​
email
string
required
Email address for the invitation
​
church_id
integer
required
The church ID to invite them to
​
churchId
integer
Alternative parameter for church_id
​
role_id
integer
The role ID to assign (defaults to Member role)
​
roleId
integer
Alternative parameter for role_id

​
Request

curl -X POST https://your-domain.com/api/people/invite \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Emily Davis",
    "email": "[email protected]",
    "church_id": 1,
    "role_id": 5
  }'

​
Response

{
  "success": true,
  "message": "Member invited successfully",
  "id": 23
}

​
Process Details

  1. Creates a member record with status: pending
  2. Generates a secure invitation token (valid for 48 hours)
  3. Assigns the specified role
  4. Sends invitation email with registration link
  5. Logs activity in the system

​
Error Responses

Missing Required Fields (400) 
{
  "success": false,
  "error": "Name, email and church ID are required"
}
Duplicate Email (400) 
{
  "success": false,
  "error": "Member already exists with this email"
}
Server Error (500) 
{
  "success": false,
  "error": "Error al invitar al integrante. Intente nuevamente."
}

​
Bulk Invite Members

POST /api/people/invite/bulk

Invite multiple members at once
Required Permission: users.invite

​
Request Body

​
emails
array
required
Array of email addresses to invite
​
church_id
integer
required
The church ID to invite them to
​
churchId
integer
Alternative parameter for church_id

​
Request

curl -X POST https://your-domain.com/api/people/invite/bulk \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "emails": [
      "[email protected]",
      "[email protected]",
      "[email protected]"
    ],
    "church_id": 1
  }'

​
Response

{
  "success": 2,
  "failed": 1,
  "message": "Process completed: 2 successful, 1 failed"
}

​
Behavior

  • Validates each email address
  • Skips emails that already exist in the system
  • Creates member names from email prefixes
  • Assigns default Member role (ID: 5)
  • Sends individual invitation emails
  • Returns count of successful and failed invitations

​
Approve Member

POST /api/people/approve

Approve a pending member and activate their account
Required Permission: users.approve

​
Request Body

​
role_id
integer
required
The role ID to assign upon approval
​
roleId
integer
Alternative parameter for role_id
The member ID should be included in the query string (e.g., /api/people/approve?action=5)

​
Request

curl -X POST https://your-domain.com/api/people/approve?action=8 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "role_id": 5
  }'

​
Response

{
  "success": true,
  "message": "Member approved successfully"
}

​
Process

  1. Changes member status from pending to active
  2. Assigns the specified role
  3. Creates service role assignment for Church Center
  4. Logs approval activity

​
Error Responses

Missing Parameters (400) 
{
  "success": false,
  "error": "Member ID and Role ID are required"
}
Member Not Found (404) 
{
  "success": false,
  "error": "Member not found"
}

​
Update Member Role

PUT /api/people/{id}/role

Update a member’s role
Required Permission: users.approve

​
Request Parameters

​
id
integer
required
The member ID
​
role_id
integer
required
The new role ID
​
roleId
integer
Alternative parameter for role_id

​
Request

curl -X PUT https://your-domain.com/api/people/5/role \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "role_id": 2
  }'

​
Response

{
  "success": true
}

​
Update Member Status

PUT /api/people/{id}/status

Update a member’s status (active, inactive, pending)
Required Permission: users.approve

​
Request Parameters

​
id
integer
required
The member ID
​
status_id
integer
required
Status ID: 1 = active, 2 = inactive, 3 = pending
​
statusId
integer
Alternative parameter for status_id

​
Request

curl -X PUT https://your-domain.com/api/people/5/status \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status_id": 1
  }'

​
Response

{
  "success": true
}

​
Update Member Profile

PUT /api/people/{id}/profile

Update a member’s profile information
Authorization: Members can update their own profile, or admins can update any profile

​
Request Parameters

​
id
integer
required
The member ID
​
name
string
Updated name
​
email
string
Updated email
​
phone
string
Updated phone number
​
address
string
Updated address

​
Request

curl -X PUT https://your-domain.com/api/people/5/profile \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Michael Smith",
    "phone": "+1-555-0199",
    "address": "456 Oak Avenue"
  }'

​
Response

{
  "success": true
}

​
Error Responses

Unauthorized (403) 
{
  "success": false,
  "error": "Unauthorized"
}

​
Delete Invitation

DELETE /api/people/invite

Delete a pending invitation by email
Required Permission: users.invite

​
Request Body

​
email
string
required
Email address of the invitation to delete

​
Request

curl -X DELETE https://your-domain.com/api/people/invite \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]"
  }'

​
Response

{
  "success": true
}

​
Delete Member

DELETE /api/people/{id}

Permanently delete a member
Required Permission: users.delete
This is a hard delete operation. The member and all associated data will be permanently removed.

​
Request Parameters

​
id
integer
required
The member ID to delete

​
Request

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

​
Response

{
  "success": true
}

​
Member Statuses

StatusDescription
pendingInvited but hasn’t completed registration
activeApproved and active member
inactiveTemporarily deactivated

​
Error Codes

CodeDescription
400Bad Request - Missing or invalid parameters
401Unauthorized - Invalid or missing token
403Forbidden - Insufficient permissions or unauthorized profile access
404Not Found - Member doesn’t exist
500Internal Server Error

Teams

Manage team memberships

Areas

Manage area assignments

Build docs developers (and LLMs) love

Get started for freeTalk to us