Reports

Ask for a report as PDF or XLSX, let the reports worker build it, then download it. Large periods never time out a request.

Generation is asynchronous: POST /v1/reports answers at once with a download row in status queued; the reports worker moves it to running and then ready (or failed with an error). Poll the row, or set email: true to have the link emailed when it is done. Files are kept for 7 days by default (expires_on) and then removed. The download route answers only for a ready row.

Route	Permission	Purpose
GET/v1/reports/catalog	church:reports:view	Every report the caller may run, with its filters, columns and formats.
GET/v1/reports/options	church:reports:view	Choices for an entity filter: type (account, money_account, service, member, cell_group, department, fundraiser, event, vote_head) and q.
GET/v1/reports	church:reports:view	Downloads requested in the church (status, report, page, page_size).
POST/v1/reports	church:reports:generate	Queue a report.
GET/v1/reports/{uuid}	church:reports:view	One download row: status, row count, size, download_url.
GET/v1/reports/{uuid}/download	church:reports:view	The file itself.
DELETE/v1/reports/{uuid}	church:reports:generate	Remove a download and its file.

Read routes accept church:reports:view, church:reports:generate, head_office:reports:view, head_office:reports:generate or system:churches:view; generating takes church:reports:generate or head_office:reports:generate. On top of that each report checks the permission for its data: a collections report also needs church:transactions:view, an expenses report church:expenses:view, and so on. Premium reports answer 402 for a basic plan church.

Queue a report

Parameters

Field	Type	Required	Description
report	string	Yes	A name from the catalog, for example collections_summary.
format	string	Yes	xlsx or pdf.
filters	object	No	The report's filters as strings: from and to (YYYY-MM-DD) on most, plus account, mode, member, service and others as the catalog lists.
email	boolean	No	Email the requester the link when it is ready.

# Paste your token once (it starts with mc_):
export MYCHURCH_TOKEN="mc_your_token_here"

curl -X POST https://uat-api.mychurch.co.ke/v1/reports \
  -H "Authorization: Bearer $MYCHURCH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "report": "collections_summary",
    "format": "xlsx",
    "filters": {
      "from": "2026-10-01",
      "to": "2026-10-31"
    },
    "email": true
  }'

200 OK

{
  "success": true,
  "data": {
    "uuid": "9b3e1c55-0000-4000-8000-0000000000a1",
    "report": "collections_summary",
    "title": "Collections summary",
    "kind": "church",
    "format": "xlsx",
    "status": "queued",
    "filters": { "from": "2026-10-01", "to": "2026-10-31" },
    "row_count": 0,
    "size_bytes": 0,
    "error": null,
    "email_to": "[email protected]",
    "expires_on": "2026-11-08T00:00:00Z",
    "requested_by": "Jane Wanjiku",
    "member_name": null,
    "download_url": "",
    "created_at": "2026-11-01T09:30:00Z",
    "finished_at": null
  }
}

Download when ready

curl -L -o collections.xlsx \
  "https://uat-api.mychurch.co.ke/v1/reports/9b3e1c55-0000-4000-8000-0000000000a1/download" \
  -H "Authorization: Bearer $MYCHURCH_TOKEN"

Head offices

A head office user can run church reports for any church in its tree with X-Church, using head_office:reports:generate.

The catalog

GET /v1/reports/catalog is the authority (it lists only what the caller may run, with each filter and column); today it holds:

report	Area	Contents
collections_by_account	giving	Every collection in the period, optionally for one account and one payment mode.
collections_summary	giving	Totals per account split by M-Pesa, cash, cheque, bank and other.
member_statement	giving	One member's giving in the period.
cell_group_contributions	giving	Giving per member through cell group accounts.
members_not_giving	giving	Members with no collection in the period.
pledges	giving	Pledges with paid amounts and balances.
fundraiser_summary	fundraising	Target, raised and pledged per fundraiser.
fundraiser_contributions	fundraising	Contributions to one fundraiser.
attendance_by_service	attendance	Every check-in, by service.
attendance_summary	attendance	Attendance totals per service.
member_directory	members	The member register.
inactive_members	members	Members marked inactive.
birthdays	members	Birthdays this month.
expenses	finance	Expenses in the period.
expenses_by_vote_head	finance	Expenses totalled per vote head.
income_statement	finance	Income against expenses, with the net surplus.
account_statement	finance	One money account's ledger.
sms_usage	messaging	SMS sent and their delivery.
event_attendance	events	Event attendants and payments (premium).

Quick CSV exports without the queue exist for the collection ledger and expenses; see Giving and Finance.