Spreadsheet imports

Bring members, children, collections, expenses, department members and pledges in from Excel or CSV. Upload once; the imports worker reads the file row by row and reports every row it could not take.

Route	Permission	Purpose
GET/v1/imports	the permission of any kind	Import jobs (kind, status, page, page_size).
POST/v1/imports	the permission of the kind	Upload a file (multipart) and queue the job.
GET/v1/imports/options	the permission of any kind	Collection account or department choices for the upload form (type, q).
GET/v1/imports/templates/{kind}.xlsx	the permission of any kind	The template for a kind, with the expected headings.
GET/v1/imports/{uuid}	the permission of any kind	One job: progress, counts and the rejected rows with their reasons.

Head office and staff may read jobs with head_office:churches:view or system:churches:view.

Kinds

kind

Field	Type	Required	Description
members	church:members:import	No	Columns: Member Number, Name, Primary Phone (Name and Primary Phone required), Physical Address, Gender, Email, Marital Status, Date Of Birth, Baptism Date, Date Joined, Family Name And Christian Name, Parents Name, Minister.
children	church:children:create	No	Name (required), Parent Phone, Gender, Date Of Birth, Baptism Date, Family Name And Christian Name, Minister. The parent is found by phone.
collections	church:collections:manage	No	Member No, Name, Phone, then one column per collection account headed with its account number. With account_uuid, a single Amount column is read instead.
expenses	church:expenses:create	No	Name and Amount required, Account No, Date, Reference, Description.
department_members	church:departments:edit	No	Name and Phone, both required; needs department_uuid.
pledges	church:pledges:create	No	Phone and Amount Pledged required, Amount Paid; needs account_uuid.

Headings are normalised before matching and common variants are accepted (Phone or Phone Number for Primary Phone, DOB for Date Of Birth). Download the template to be sure.

Upload

multipart/form-data

Field	Type	Required	Description
kind	string	Yes	One of the kinds above.
file	file	Yes	.xlsx or .csv, at most 20 MB. Old .xls files are refused: save as .xlsx first.
account_uuid	uuid	No	collections (one account) and pledges: the collection account.
department_uuid	uuid	No	department_members: the department.
date	date	No	collections: the date to record when a row has no Date column, YYYY-MM-DD (default today).
member_type	string	No	members: the member type to give everyone imported.
message	string	No	collections: a receipt SMS to each payer with a phone. Placeholders: [name] [payments] [church_name].

bash

curl -X POST https://uat-api.mychurch.co.ke/v1/imports \
  -H "Authorization: Bearer $MYCHURCH_TOKEN" \
  -F kind=members \
  -F [email protected]

GET /v1/imports/{uuid} when finished

{
  "success": true,
  "data": {
    "uuid": "4d8a6f02-0000-4000-8000-0000000000b1",
    "kind": "members",
    "status": "done",
    "file_name": "members.xlsx",
    "size_bytes": 48211,
    "params": {},
    "total_rows": 412,
    "imported": 409,
    "skipped": 3,
    "processed": 412,
    "errors": [
      { "row": 17, "message": "phone number is not valid" },
      { "row": 88, "message": "another member already has this phone number" },
      { "row": 301, "message": "name is required" }
    ],
    "error_count": 3,
    "error": null,
    "created_by": "Jane Wanjiku",
    "started_at": "2026-11-01T09:40:02Z",
    "finished_at": "2026-11-01T09:40:31Z",
    "created_at": "2026-11-01T09:40:00Z"
  }
}

Row numbers

errors[].row is the row number as Excel shows it, heading row included, so you can fix the file and upload only those rows again.

Imported collections are recorded with payment mode import and appear in the ledger and reports; they never move M-Pesa money. See Giving for statement reconciliation, which matches rather than imports.