Skip to main content

​
Overview

The Reports API provides statistical insights and analytics for church operations. It includes general dashboard stats, pastor-specific metrics, and system status monitoring.

​
Authentication

All endpoints require authentication with the church.read permission: 
Authorization: Bearer YOUR_JWT_TOKEN

​
Get Dashboard Stats

GET /api/reports

Retrieve comprehensive dashboard statistics for a church or globally
Required Permission: church.read

​
Query Parameters

​
church_id
integer
Filter stats by church ID. Required for non-super admins.
​
churchId
integer
Alternative parameter for church_id

​
Access Levels

  • Church Members: Must provide church_id, see stats for their church only
  • Super Admins: Can omit church_id to see global stats across all churches

​
Request (Church-Specific)

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

​
Response (Church-Specific)

{
  "success": true,
  "db_status": {
    "main": "online",
    "music": "online"
  },
  "data": {
    "total_members": 245,
    "active_members": 198,
    "pending_members": 12,
    "inactive_members": 35,
    "total_teams": 18,
    "total_areas": 6,
    "total_songs": 342,
    "church_songs": 28,
    "global_songs": 314,
    "total_playlists": 15,
    "upcoming_meetings": 8,
    "recent_activities": 47,
    "member_growth_30d": 12,
    "member_growth_percentage": 5.1
  }
}

​
Request (Global - Super Admin Only)

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

​
Response (Global Stats)

{
  "success": true,
  "db_status": {
    "main": "online",
    "music": "online"
  },
  "data": {
    "total_churches": 12,
    "active_churches": 11,
    "total_members_all_churches": 2847,
    "total_teams_all_churches": 186,
    "total_songs_global": 425,
    "total_playlists_all_churches": 142,
    "system_uptime": "99.8%",
    "storage_used_gb": 12.4,
    "churches": [
      {
        "id": 1,
        "name": "First Baptist Church",
        "member_count": 245,
        "active_teams": 18
      },
      {
        "id": 2,
        "name": "Grace Community Church",
        "member_count": 312,
        "active_teams": 22
      }
    ]
  }
}

​
Database Status

​
db_status.main
string
Status of main database: “online” or “error”
​
db_status.music
string
Status of music database: “online” or “error”

​
Get Pastor Stats

GET /api/reports/pastor_stats

Retrieve leadership-focused statistics and insights
Required Permission: church.read Use Case: Designed for pastors and church leaders to get high-level ministry insights.

​
Query Parameters

​
church_id
integer
Church ID to get stats for. Required for non-super admins.
​
churchId
integer
Alternative parameter for church_id

​
Request

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

​
Response

{
  "success": true,
  "stats": {
    "overview": {
      "total_members": 245,
      "active_members": 198,
      "member_retention_rate": 80.8,
      "new_members_30d": 12,
      "new_members_90d": 28
    },
    "engagement": {
      "total_teams": 18,
      "members_in_teams": 145,
      "engagement_rate": 73.2,
      "average_team_size": 8.1,
      "teams_by_area": [
        {
          "area_name": "Worship Ministry",
          "team_count": 4,
          "member_count": 32
        },
        {
          "area_name": "Youth Ministry",
          "team_count": 3,
          "member_count": 28
        }
      ]
    },
    "ministry": {
      "total_areas": 6,
      "upcoming_events": 8,
      "events_this_month": 15,
      "worship_songs_library": 342,
      "active_playlists": 15
    },
    "growth_trends": {
      "members_by_month": [
        {"month": "2024-01", "count": 221},
        {"month": "2024-02", "count": 233},
        {"month": "2024-03", "count": 245}
      ],
      "teams_by_month": [
        {"month": "2024-01", "count": 16},
        {"month": "2024-02", "count": 17},
        {"month": "2024-03", "count": 18}
      ]
    },
    "pending_actions": {
      "pending_approvals": 12,
      "pending_song_edits": 3,
      "unassigned_meetings": 2
    }
  }
}

​
Key Metrics Explained

​
member_retention_rate
number
Percentage of active members vs. total members
​
engagement_rate
number
Percentage of members actively involved in teams
​
average_team_size
number
Average number of members per team

​
Church Context Resolution

For non-super admins, church_id is resolved automatically:
  1. Query parameter: church_id or churchId
  2. User’s church: From authenticated member data
  3. Required: Returns 400 error if church cannot be determined

​
Database Status Monitoring

All report responses include database health status:

​
Status Values

StatusDescription
onlineDatabase is connected and responsive
errorDatabase connection failed or timeout

​
Example Status Check

{
  "db_status": {
    "main": "online",
    "music": "error"
  }
}
If music database shows “error”, song and playlist functionality may be degraded.

​
Report Types Comparison

ReportAudienceFocusChurch-Specific
Dashboard StatsAll rolesGeneral metricsYes
Pastor StatsLeadershipMinistry insightsYes
Global StatsSuper AdminPlatform-wideNo

​
Use Cases

​
Monthly Ministry Review

Use pastor stats to review:
  • Member growth trends
  • Team engagement rates
  • Upcoming events planning
  • Pending approvals
curl -X GET "https://your-domain.com/api/reports/pastor_stats?church_id=1" \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Platform Health Check (Admin)

Use global stats to monitor:
  • All churches status
  • System-wide metrics
  • Database health
  • Storage usage
curl -X GET https://your-domain.com/api/reports \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Dashboard Widget

Use dashboard stats for quick overview:
  • Active member count
  • Upcoming meetings
  • Recent activity
curl -X GET "https://your-domain.com/api/reports?church_id=1" \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Error Responses

Missing Church Context (400) 
{
  "success": false,
  "error": "Church ID required"
}
Forbidden Access (403) 
{
  "success": false,
  "error": "Church context required for dashboard"
}

​
Error Codes

CodeDescription
400Bad Request - Missing church_id for non-super admins
401Unauthorized - Invalid or missing token
403Forbidden - Insufficient permissions or missing church context
500Internal Server Error

​
Performance Notes

  • Reports are calculated in real-time
  • Large churches (500+ members) may see 1-2 second response times
  • Consider caching results for 5-15 minutes on the client side
  • Global stats are more expensive to compute

Churches

Manage church organizations

People

View detailed member data

Teams

Analyze team engagement

Calendar

Review upcoming events

Build docs developers (and LLMs) love

Get started for freeTalk to us