Wasanidi programu

REST API na webhooks za ChurchBright

Unganisha tovuti yako, kadi za mawasiliano, programu ya uhasibu au ghala la data na akaunti ya kanisa lako. JSON rahisi kupitia HTTPS, funguo zenye ruhusa za kina, na webhook zilizosainiwa za papo hapo.

Pata ufunguo wa APIRuka hadi endpoints

Anza haraka

  1. Katika akaunti ya kanisa lako fungua Mipangilio → API na webhooks kisha unda ufunguo. Unakili — unaonyeshwa mara moja tu.
  2. Ita API kutoka kwenye seva yako ukiweka ufunguo kwenye kichwa cha Authorization.
  3. Ongeza webhook ili kuarifiwa kuhusu mabadiliko yanapotokea badala ya kuuliza mara kwa mara.

URL ya msingi: https://churchbright.com/api/v1

export CHURCHBRIGHT_API_KEY=cb_live_your_key_here

curl "https://churchbright.com/api/v1/people?per_page=5&status=first_timer" \
  -H "Authorization: Bearer $CHURCHBRIGHT_API_KEY"

Uthibitishaji

Kila ombi linahitaji ufunguo wa API. Funguo huonekana kama cb_live_ ikifuatiwa na herufi na tarakimu 32. Utume kama tokeni ya bearer:

Authorization: Bearer cb_live_…

Kila ufunguo una ruhusa kwa kila rasilimali — kwa mfano people:read, people:write, contributions:read au messages:write — na unaweza kuwekewa kikomo kwa tawi moja na matawi yaliyo chini yake. Ufunguo uliowekewa kikomo kwa tawi huona na kuunda rekodi katika matawi hayo pekee.

Ikiwa zana yako haiwezi kuweka vichwa (headers) unaweza kutumia ?api_key=… badala yake, lakini vichwa ni salama zaidi kwa sababu URL huishia kwenye kumbukumbu. Funguo zinapaswa kuwa kwenye seva tu: kamwe si kwenye JavaScript ya kivinjari, programu za simu au hazina za umma. Batilisha ufunguo mara tu unapodhani umevuja.

Maombi na majibu

  • Tuma JSON yenye Content-Type: application/json (maudhui ya aina ya form-encoded pia yanafanya kazi).
  • Kila jibu ni JSON yenye "ok". Majibu yaliyofanikiwa yana "data" (na "meta" kwa orodha).
  • Mihuri ya muda iko katika UTC kwa ISO 8601 (2026-09-28T09:14:03Z). Tarehe za kalenda kama given_on au dob ziko katika muundo YYYY-MM-DD kwa saa za eneo la kanisa lenyewe.
  • Kiasi cha pesa ni namba kamili katika vipande vidogo vya sarafu (k.m. senti): 150050 inamaanisha 1,500.50 katika sarafu iliyotajwa. amount_base huwa katika sarafu ya kanisa kila wakati.
  • Tuma kichwa cha Idempotency-Key (mfuatano wowote wa kipekee wa hadi herufi 120) kwenye maombi ya POST. Kujaribu tena kwa ufunguo uleule hurudisha jibu la kwanza badala ya kuunda nakala — muhimu kwa michango.
{
    "ok": true,
    "data": {
        "id": 42,
        "first_name": "Ngozi",
        "…": "…"
    },
    "meta": {
        "page": 1,
        "per_page": 25,
        "total": 214,
        "total_pages": 9,
        "has_more": true
    }
}

Kurasa na vichujio

Orodha hurudisha rekodi 25 kwa kila ukurasa kwa chaguo-msingi. Tumia ?page= na ?per_page= (hadi 100). meta inakuonyesha jumla na kama kuna ukurasa mwingine.

Ili kuweka mfumo mwingine ukiwa umesawazishwa, kumbuka mara ya mwisho ulipousawazisha na uombe tu kilichobadilika tangu wakati huo kwa ?updated_since=2026-09-01T00:00:00Z. Kwa watu, ongeza include_deleted=1 ili pia ujue kuhusu walioondolewa.

curl "https://churchbright.com/api/v1/people?updated_since=2026-09-01T00:00:00Z&include_deleted=1&per_page=100&page=2" \
  -H "Authorization: Bearer $CHURCHBRIGHT_API_KEY"

Hitilafu

Hitilafu hutumia misimbo ya kawaida ya hali ya HTTP na maudhui yenye "ok": false, "error" inayosomeka na mashine na "message" inayosomeka na binadamu. Hitilafu za uthibitishaji huongeza "errors" yenye ujumbe mmoja kwa kila sehemu.

HalierrorMaana
400invalid_json, invalid_updated_since, invalid_status…Ombi lina muundo mbovu — angalia ujumbe.
401unauthorized, invalid_api_keyHakuna ufunguo, au ufunguo si sahihi au umebatilishwa.
403insufficient_scope, api_disabled, church_inactive, plan_limit_reachedUfunguo ni halali lakini hauruhusiwi kufanya hili.
404not_found, unknown_resourceRekodi haipo au iko nje ya tawi la ufunguo huu.
405method_not_allowedMbinu hiyo ya HTTP haitumiki kwenye URL hii.
409duplicate_reference, idempotency_key_reusedInagongana na ombi la awali.
422validation_failed, send_failed, recipient_skippedData si sahihi; "errors" huorodhesha kila sehemu.
429rate_limitedMaombi mengi mno — subiri sekunde zilizotajwa kwenye Retry-After.
500resource_errorKuna tatizo upande wetu. Jaribu tena baadaye.
 
{
    "ok": false,
    "error": "validation_failed",
    "message": "Baadhi ya sehemu si sahihi.",
    "errors": {
        "email": "Weka anwani sahihi ya barua pepe."
    }
}

Vikomo vya kasi

Kila ufunguo unaweza kutuma maombi 120 kwa dakika (na kila anwani ya IP maombi 600). Zaidi ya hapo utapata HTTP 429 pamoja na kichwa cha Retry-After. Tumia updated_since na webhooks badala ya kuuliza mara kwa mara (polling).

Endpoints

Ufunguo wako

GET /api/v1

Kagua ufunguo wako · inahitaji ufunguo wowote halali

Hurejesha kanisa, ruhusa za ufunguo na kila rasilimali ambayo ufunguo unaweza kufikia. Itumie kujaribu mipangilio yako.

curl "https://churchbright.com/api/v1" \
  -H "Authorization: Bearer $CHURCHBRIGHT_API_KEY"
Jibu la mfano
{
    "ok": true,
    "data": {
        "church": {
            "id": 1,
            "name": "Grace Assembly",
            "slug": "grace",
            "country": "NG",
            "currency": "NGN",
            "timezone": "Africa/Lagos"
        },
        "key": {
            "id": 3,
            "name": "Website forms",
            "prefix": "cb_live_Ab3d",
            "scopes": [
                "people:read",
                "people:write"
            ],
            "branch_id": null,
            "created_at": "2026-09-01T10:00:00Z"
        },
        "resources": [
            {
                "name": "people",
                "url": "https://churchbright.com/api/v1/people",
                "allowed": [
                    "read",
                    "write"
                ],
                "module": "core"
            }
        ]
    }
}
Watu

GET /api/v1/people

Orodhesha watu · inahitaji people:read

Washirika, wageni na wageni wa mara ya kwanza, wa zamani zaidi kwanza. Watu waliofutwa hawajumuishwi isipokuwa include_deleted=1.

Kigezo cha hoja (query parameter)Maelezo
statusHali moja au orodha iliyotenganishwa kwa koma: first_timer, visitor, new_convert, regular, member, worker, leader, inactive, transferred, deceased
branch_idTawi hili na matawi yake madogo tu
family_idFamilia hii pekee
qTafuta jina, barua pepe au namba ya mshirika
emailBarua pepe inayolingana kikamilifu
phoneNamba ya simu inayolingana kikamilifu (muundo wowote)
updated_sinceImebadilishwa wakati huu au baadaye (ISO 8601)
created_sinceImeongezwa wakati huu au baadaye
include_deleted1 kujumuisha watu walioondolewa (wenye deleted_at) — inafaa kwa kusawazisha
sortid, -id, updated_at, -updated_at, last_name
curl "https://churchbright.com/api/v1/people" \
  -H "Authorization: Bearer $CHURCHBRIGHT_API_KEY"
Jibu la mfano
{
    "ok": true,
    "data": [
        {
            "id": 42,
            "member_no": "GA-00042",
            "title": "Mrs",
            "first_name": "Ngozi",
            "middle_name": null,
            "last_name": "Okafor",
            "full_name": "Ngozi Okafor",
            "gender": "female",
            "dob": "1988-04-12",
            "marital_status": "married",
            "anniversary": "2012-11-24",
            "email": "ngozi@example.com",
            "phone": "+2348031234567",
            "phone2": null,
            "whatsapp": null,
            "address": "4 Admiralty Way",
            "city": "Lekki",
            "state": "Lagos",
            "country": "NG",
            "postal_code": null,
            "occupation": "Pharmacist",
            "employer": null,
            "status": "member",
            "branch_id": 1,
            "family_id": 7,
            "family_role": "spouse",
            "membership_date": "2019-03-03",
            "baptism_date": null,
            "salvation_date": null,
            "first_visit_date": "2018-11-11",
            "source": "invited",
            "sms_opt_in": true,
            "email_opt_in": true,
            "whatsapp_opt_in": true,
            "photo_url": null,
            "custom": {},
            "created_at": "2026-01-14T09:21:00Z",
            "updated_at": "2026-09-02T17:45:10Z",
            "deleted_at": null
        }
    ],
    "meta": {
        "page": 1,
        "per_page": 25,
        "total": 214,
        "total_pages": 9,
        "has_more": true
    }
}

GET /api/v1/people/{id}

Pata mtu · inahitaji people:read

curl "https://churchbright.com/api/v1/people/42" \
  -H "Authorization: Bearer $CHURCHBRIGHT_API_KEY"
Jibu la mfano
{
    "ok": true,
    "data": {
        "id": 42,
        "member_no": "GA-00042",
        "title": "Mrs",
        "first_name": "Ngozi",
        "middle_name": null,
        "last_name": "Okafor",
        "full_name": "Ngozi Okafor",
        "gender": "female",
        "dob": "1988-04-12",
        "marital_status": "married",
        "anniversary": "2012-11-24",
        "email": "ngozi@example.com",
        "phone": "+2348031234567",
        "phone2": null,
        "whatsapp": null,
        "address": "4 Admiralty Way",
        "city": "Lekki",
        "state": "Lagos",
        "country": "NG",
        "postal_code": null,
        "occupation": "Pharmacist",
        "employer": null,
        "status": "member",
        "branch_id": 1,
        "family_id": 7,
        "family_role": "spouse",
        "membership_date": "2019-03-03",
        "baptism_date": null,
        "salvation_date": null,
        "first_visit_date": "2018-11-11",
        "source": "invited",
        "sms_opt_in": true,
        "email_opt_in": true,
        "whatsapp_opt_in": true,
        "photo_url": null,
        "custom": {},
        "created_at": "2026-01-14T09:21:00Z",
        "updated_at": "2026-09-02T17:45:10Z",
        "deleted_at": null
    }
}

POST /api/v1/people

Unda mtu mpya · inahitaji people:write

first_name inahitajika. Tarehe hutumia muundo YYYY-MM-DD, namba za simu hubadilishwa kuwa muundo wa kimataifa kwa kutumia nchi ya kanisa. Tuma "dedupe": true ili urudishiwe mtu aliyepo (HTTP 200, meta.duplicate = true) ikiwa barua pepe au simu tayari imo kwenye kumbukumbu.

curl -X POST "https://churchbright.com/api/v1/people" \
  -H "Authorization: Bearer $CHURCHBRIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"first_name":"Ngozi","last_name":"Okafor","email":"ngozi@example.com","phone":"0803 123 4567","status":"first_timer","source":"online","dedupe":true}'
Jibu la mfano
{
    "ok": true,
    "data": {
        "id": 42,
        "member_no": "GA-00042",
        "title": "Mrs",
        "first_name": "Ngozi",
        "middle_name": null,
        "last_name": "Okafor",
        "full_name": "Ngozi Okafor",
        "gender": "female",
        "dob": "1988-04-12",
        "marital_status": "married",
        "anniversary": "2012-11-24",
        "email": "ngozi@example.com",
        "phone": "+2348031234567",
        "phone2": null,
        "whatsapp": null,
        "address": "4 Admiralty Way",
        "city": "Lekki",
        "state": "Lagos",
        "country": "NG",
        "postal_code": null,
        "occupation": "Pharmacist",
        "employer": null,
        "status": "member",
        "branch_id": 1,
        "family_id": 7,
        "family_role": "spouse",
        "membership_date": "2019-03-03",
        "baptism_date": null,
        "salvation_date": null,
        "first_visit_date": "2018-11-11",
        "source": "invited",
        "sms_opt_in": true,
        "email_opt_in": true,
        "whatsapp_opt_in": true,
        "photo_url": null,
        "custom": {},
        "created_at": "2026-01-14T09:21:00Z",
        "updated_at": "2026-09-02T17:45:10Z",
        "deleted_at": null
    }
}

PATCH /api/v1/people/{id}

Sasisha taarifa za mtu · inahitaji people:write

Tuma sehemu za kubadilisha pekee. PUT na POST kwenye URL ileile pia zinafanya kazi. Sehemu maalum huunganishwa.

curl -X PATCH "https://churchbright.com/api/v1/people/42" \
  -H "Authorization: Bearer $CHURCHBRIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"member","membership_date":"2026-09-28","custom":{"department":"Choir"}}'
Jibu la mfano
{
    "ok": true,
    "data": {
        "id": 42,
        "member_no": "GA-00042",
        "title": "Mrs",
        "first_name": "Ngozi",
        "middle_name": null,
        "last_name": "Okafor",
        "full_name": "Ngozi Okafor",
        "gender": "female",
        "dob": "1988-04-12",
        "marital_status": "married",
        "anniversary": "2012-11-24",
        "email": "ngozi@example.com",
        "phone": "+2348031234567",
        "phone2": null,
        "whatsapp": null,
        "address": "4 Admiralty Way",
        "city": "Lekki",
        "state": "Lagos",
        "country": "NG",
        "postal_code": null,
        "occupation": "Pharmacist",
        "employer": null,
        "status": "member",
        "branch_id": 1,
        "family_id": 7,
        "family_role": "spouse",
        "membership_date": "2019-03-03",
        "baptism_date": null,
        "salvation_date": null,
        "first_visit_date": "2018-11-11",
        "source": "invited",
        "sms_opt_in": true,
        "email_opt_in": true,
        "whatsapp_opt_in": true,
        "photo_url": null,
        "custom": {},
        "created_at": "2026-01-14T09:21:00Z",
        "updated_at": "2026-09-02T17:45:10Z",
        "deleted_at": null
    }
}
Familia

GET /api/v1/families

Orodhesha familia · inahitaji families:read

Kigezo cha hoja (query parameter)Maelezo
qTafuta kwa jina
branch_idTawi hili tu
updated_sinceImebadilishwa tangu
curl "https://churchbright.com/api/v1/families" \
  -H "Authorization: Bearer $CHURCHBRIGHT_API_KEY"
Jibu la mfano
{
    "ok": true,
    "data": [
        {
            "id": 7,
            "name": "The Okafor family",
            "address": "4 Admiralty Way, Lekki",
            "phone": null,
            "branch_id": 1,
            "member_count": 4,
            "created_at": "2026-01-14T09:20:00Z",
            "updated_at": null
        }
    ],
    "meta": {
        "page": 1,
        "per_page": 25,
        "total": 88,
        "total_pages": 4,
        "has_more": true
    }
}

GET /api/v1/families/{id}

Pata familia pamoja na wanafamilia wake · inahitaji families:read

curl "https://churchbright.com/api/v1/families/42" \
  -H "Authorization: Bearer $CHURCHBRIGHT_API_KEY"
Jibu la mfano
{
    "ok": true,
    "data": {
        "id": 7,
        "name": "The Okafor family",
        "address": "4 Admiralty Way, Lekki",
        "phone": null,
        "branch_id": 1,
        "member_count": 2,
        "created_at": "2026-01-14T09:20:00Z",
        "updated_at": null,
        "members": [
            {
                "id": 41,
                "first_name": "Chinedu",
                "last_name": "Okafor",
                "family_role": "head",
                "status": "worker"
            },
            {
                "id": 42,
                "first_name": "Ngozi",
                "last_name": "Okafor",
                "family_role": "spouse",
                "status": "member"
            }
        ]
    }
}

POST /api/v1/families

Unda familia · inahitaji families:write

curl -X POST "https://churchbright.com/api/v1/families" \
  -H "Authorization: Bearer $CHURCHBRIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"The Mensah family","address":"12 Allen Avenue, Ikeja","branch_id":2}'
Jibu la mfano
{
    "ok": true,
    "data": {
        "id": 89,
        "name": "The Mensah family",
        "address": "12 Allen Avenue, Ikeja",
        "phone": null,
        "branch_id": 2,
        "member_count": 0,
        "members": [],
        "created_at": "2026-09-28T08:00:00Z",
        "updated_at": "2026-09-28T08:00:00Z"
    }
}
Matawi na mifuko

GET /api/v1/branches

Orodhesha matawi · inahitaji branches:read

Mti mzima: parent_id huunganisha tawi na lile lililo juu yake.

curl "https://churchbright.com/api/v1/branches" \
  -H "Authorization: Bearer $CHURCHBRIGHT_API_KEY"
Jibu la mfano
{
    "ok": true,
    "data": [
        {
            "id": 1,
            "parent_id": null,
            "depth": 0,
            "name": "Lekki (Headquarters)",
            "code": null,
            "is_hq": true,
            "level": "Headquarters",
            "pastor_name": null,
            "email": null,
            "phone": null,
            "address": null,
            "city": "Lagos",
            "state": null,
            "country": "NG",
            "currency": "NGN",
            "timezone": "Africa/Lagos",
            "status": "active",
            "created_at": "2026-01-01T00:00:00Z",
            "updated_at": null
        }
    ],
    "meta": {
        "page": 1,
        "per_page": 25,
        "total": 4,
        "total_pages": 1,
        "has_more": false
    }
}

GET /api/v1/funds

Orodhesha mifuko · inahitaji funds:read

Kigezo cha hoja (query parameter)Maelezo
active1 = mifuko amilifu pekee, 0 = isiyo amilifu pekee
curl "https://churchbright.com/api/v1/funds" \
  -H "Authorization: Bearer $CHURCHBRIGHT_API_KEY"
Jibu la mfano
{
    "ok": true,
    "data": [
        {
            "id": 1,
            "name": "Tithe",
            "slug": "tithe",
            "description": null,
            "kind": "general",
            "target_amount": null,
            "currency": "NGN",
            "is_online": true,
            "is_default": true,
            "is_active": true,
            "created_at": "2026-01-01T00:00:00Z",
            "updated_at": null
        }
    ],
    "meta": {
        "page": 1,
        "per_page": 25,
        "total": 8,
        "total_pages": 1,
        "has_more": false
    }
}
Michango

GET /api/v1/contributions

Orodhesha michango · inahitaji contributions:read

Kiasi ni namba kamili katika vipimo vidogo vya sarafu (kobo, senti). meta.sum_amount_base hujumlisha kila mchango unaolingana kwa sarafu ya kanisa.

Kigezo cha hoja (query parameter)Maelezo
fromIlitolewa tarehe hii au baadaye (YYYY-MM-DD)
toIlitolewa tarehe hii au kabla yake
fund_idMfuko mmoja
person_idMtoaji mmoja
methodcash, bank_transfer, pos, online, ach, cheque, ussd, mobile_money, text, in_kind, other
sourcemanual, online, import, api, …
statusposted (chaguo-msingi), void au all
branch_idTawi hili na matawi yake madogo
updated_sinceImebadilishwa tangu
sortid, -id, given_on, -given_on
curl "https://churchbright.com/api/v1/contributions" \
  -H "Authorization: Bearer $CHURCHBRIGHT_API_KEY"
Jibu la mfano
{
    "ok": true,
    "data": [
        {
            "id": 981,
            "person_id": 42,
            "fund_id": 1,
            "fund_name": "Tithe",
            "branch_id": 1,
            "amount": 5000000,
            "currency": "NGN",
            "amount_display": "₦50,000.00",
            "amount_base": 5000000,
            "method": "bank_transfer",
            "given_on": "2026-09-27",
            "reference": "TRF-88213",
            "note": null,
            "source": "api",
            "payment_id": null,
            "donor_name": null,
            "donor_email": null,
            "donor_phone": null,
            "is_anonymous": false,
            "status": "posted",
            "created_at": "2026-09-27T12:02:11Z",
            "updated_at": "2026-09-27T12:02:11Z"
        }
    ],
    "meta": {
        "page": 1,
        "per_page": 25,
        "total": 1203,
        "total_pages": 49,
        "has_more": true,
        "sum_amount_base": 1843250000,
        "base_currency": "NGN"
    }
}

GET /api/v1/contributions/{id}

Pata mchango · inahitaji contributions:read

curl "https://churchbright.com/api/v1/contributions/42" \
  -H "Authorization: Bearer $CHURCHBRIGHT_API_KEY"
Jibu la mfano
{
    "ok": true,
    "data": {
        "id": 981,
        "person_id": 42,
        "fund_id": 1,
        "fund_name": "Tithe",
        "branch_id": 1,
        "amount": 5000000,
        "currency": "NGN",
        "amount_display": "₦50,000.00",
        "amount_base": 5000000,
        "method": "bank_transfer",
        "given_on": "2026-09-27",
        "reference": "TRF-88213",
        "note": null,
        "source": "api",
        "payment_id": null,
        "donor_name": null,
        "donor_email": null,
        "donor_phone": null,
        "is_anonymous": false,
        "status": "posted",
        "created_at": "2026-09-27T12:02:11Z",
        "updated_at": "2026-09-27T12:02:11Z"
    }
}

POST /api/v1/contributions

Rekodi mchango · inahitaji contributions:write

amount inahitajika, katika vipimo vidogo vya sarafu. Kwa chaguo-msingi fund_id ni mfuko chaguo-msingi wa kanisa, given_on ni leo, na method ni online. Rejea ambayo tayari imerekodiwa kupitia API hurudisha 409. Tuma kichwa cha Idempotency-Key ili majaribio ya kurudia yasirekodi mchango mara mbili.

curl -X POST "https://churchbright.com/api/v1/contributions" \
  -H "Authorization: Bearer $CHURCHBRIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount":5000000,"fund_id":1,"person_id":42,"method":"bank_transfer","given_on":"2026-09-27","reference":"TRF-88213"}'
Jibu la mfano
{
    "ok": true,
    "data": {
        "id": 981,
        "person_id": 42,
        "fund_id": 1,
        "fund_name": "Tithe",
        "branch_id": 1,
        "amount": 5000000,
        "currency": "NGN",
        "amount_display": "₦50,000.00",
        "amount_base": 5000000,
        "method": "bank_transfer",
        "given_on": "2026-09-27",
        "reference": "TRF-88213",
        "note": null,
        "source": "api",
        "payment_id": null,
        "donor_name": null,
        "donor_email": null,
        "donor_phone": null,
        "is_anonymous": false,
        "status": "posted",
        "created_at": "2026-09-27T12:02:11Z",
        "updated_at": "2026-09-27T12:02:11Z"
    }
}
Ujumbe

POST /api/v1/messages

Tuma ujumbe · inahitaji messages:write

channel ni sms, email, whatsapp au push. Tuma kwa person_id, hadi person_ids 100, au namba ya simu/barua pepe moja kwa moja katika "to". Lebo za kuunganisha kama {first_name} zinafanya kazi. Walioomba kutopokea ujumbe wanaheshimiwa na vitengo vya SMS vinatozwa kama kawaida.

curl -X POST "https://churchbright.com/api/v1/messages" \
  -H "Authorization: Bearer $CHURCHBRIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"channel":"sms","person_id":42,"body":"Hi {first_name}, thank you for worshipping with us today!"}'
Jibu la mfano
{
    "ok": true,
    "data": {
        "id": 5521,
        "person_id": 42,
        "status": "sent",
        "error": null,
        "channel": "sms"
    }
}

GET /api/v1/messages

Kumbukumbu ya ujumbe · inahitaji messages:read

Kigezo cha hoja (query parameter)Maelezo
channelsms, email, whatsapp, voice, push
statussent, delivered, failed, skipped
person_idMtu mmoja
sourceIlikotoka, k.m. api, followup
updated_sinceImebadilishwa tangu
curl "https://churchbright.com/api/v1/messages" \
  -H "Authorization: Bearer $CHURCHBRIGHT_API_KEY"
Jibu la mfano
{
    "ok": true,
    "data": [
        {
            "id": 5521,
            "channel": "sms",
            "person_id": 42,
            "to": "+2348031234567",
            "subject": null,
            "body": "Hi Ngozi, thank you for worshipping with us today!",
            "status": "delivered",
            "units": 1,
            "error": null,
            "source": "api",
            "sent_at": "2026-09-28T11:02:00Z",
            "delivered_at": "2026-09-28T11:02:09Z",
            "created_at": "2026-09-28T11:02:00Z"
        }
    ],
    "meta": {
        "page": 1,
        "per_page": 25,
        "total": 5521,
        "total_pages": 221,
        "has_more": true
    }
}
Rasilimali zaidi
Rasilimali hizi zinatokana na vipengele ambavyo kanisa lako limewasha. Zinafuata kanuni zile zile za uthibitishaji, ugawaji wa kurasa na makosa.

GET /api/v1/prayer_requests

Orodhesha Maombi ya kuombewa · inahitaji prayer_requests:read

Imetolewa na moduli ya Uangalizi na maombi.

Kigezo cha hoja (query parameter)Maelezo
pageNamba ya ukurasa
per_pageHadi 100
updated_sinceImebadilishwa tangu (inapowezekana)
curl "https://churchbright.com/api/v1/prayer_requests" \
  -H "Authorization: Bearer $CHURCHBRIGHT_API_KEY"

GET /api/v1/prayer_requests/{id}

Pata rekodi moja ya Maombi ya kuombewa · inahitaji prayer_requests:read

curl "https://churchbright.com/api/v1/prayer_requests/42" \
  -H "Authorization: Bearer $CHURCHBRIGHT_API_KEY"

POST /api/v1/prayer_requests

Unda Maombi ya kuombewa · inahitaji prayer_requests:write

curl -X POST "https://churchbright.com/api/v1/prayer_requests" \
  -H "Authorization: Bearer $CHURCHBRIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[]'

GET /api/v1/gifts

Orodhesha Michango · inahitaji gifts:read

Imetolewa na moduli ya Matoleo.

Kigezo cha hoja (query parameter)Maelezo
pageNamba ya ukurasa
per_pageHadi 100
updated_sinceImebadilishwa tangu (inapowezekana)
curl "https://churchbright.com/api/v1/gifts" \
  -H "Authorization: Bearer $CHURCHBRIGHT_API_KEY"

GET /api/v1/gifts/{id}

Pata rekodi moja ya Michango · inahitaji gifts:read

curl "https://churchbright.com/api/v1/gifts/42" \
  -H "Authorization: Bearer $CHURCHBRIGHT_API_KEY"

GET /api/v1/sermons

Orodhesha Mahubiri · inahitaji sermons:read

Imetolewa na moduli ya Media.

Kigezo cha hoja (query parameter)Maelezo
pageNamba ya ukurasa
per_pageHadi 100
updated_sinceImebadilishwa tangu (inapowezekana)
curl "https://churchbright.com/api/v1/sermons" \
  -H "Authorization: Bearer $CHURCHBRIGHT_API_KEY"

GET /api/v1/sermons/{id}

Pata rekodi moja ya Mahubiri · inahitaji sermons:read

curl "https://churchbright.com/api/v1/sermons/42" \
  -H "Authorization: Bearer $CHURCHBRIGHT_API_KEY"

Webhooks

Ongeza endpoints chini ya Mipangilio → API na webhooks → Webhooks na uchague matukio unayotaka. Moja linapotokea tunatuma HTTPS POST yenye mwili wa JSON kama huu:

{
    "id": "evt_5b1c0f3e9a7d44c2b8e1a0f2",
    "event": "person.created",
    "created_at": "2026-09-28T09:14:03Z",
    "api_version": "v1",
    "church": {
        "id": 1,
        "slug": "grace",
        "name": "Grace Assembly"
    },
    "data": {
        "id": 42,
        "member_no": "GA-00042",
        "title": "Mrs",
        "first_name": "Ngozi",
        "middle_name": null,
        "last_name": "Okafor",
        "full_name": "Ngozi Okafor",
        "gender": "female",
        "dob": "1988-04-12",
        "marital_status": "married",
        "anniversary": "2012-11-24",
        "email": "ngozi@example.com",
        "phone": "+2348031234567",
        "phone2": null,
        "whatsapp": null,
        "address": "4 Admiralty Way",
        "city": "Lekki",
        "state": "Lagos",
        "country": "NG",
        "postal_code": null,
        "occupation": "Pharmacist",
        "employer": null,
        "status": "member",
        "branch_id": 1,
        "family_id": 7,
        "family_role": "spouse",
        "membership_date": "2019-03-03",
        "baptism_date": null,
        "salvation_date": null,
        "first_visit_date": "2018-11-11",
        "source": "invited",
        "sms_opt_in": true,
        "email_opt_in": true,
        "whatsapp_opt_in": true,
        "photo_url": null,
        "custom": {},
        "created_at": "2026-01-14T09:21:00Z",
        "updated_at": "2026-09-02T17:45:10Z",
        "deleted_at": null
    }
}

"data" ina muundo sawa na rasilimali ya REST inayolingana. Matukio ya kusasisha pia yanajumuisha "previous" yenye thamani za kabla ya mabadiliko. Kila ombi hubeba vichwa (headers) hivi:

X-ChurchBright-EventJina la tukio, k.m. person.created
X-ChurchBright-Event-IdNi ya kipekee kwa kila tukio — ihifadhi ili kupuuza nakala rudufu, kwa sababu utumaji upya huitumia tena.
X-ChurchBright-DeliveryKitambulisho cha jaribio la uwasilishaji kinachoonyeshwa kwenye kumbukumbu yako ya uwasilishaji.
X-ChurchBright-Signaturet=<unix time>,v1=<HMAC-SHA256 of "<t>.<raw body>" using your signing secret, hex>
  • Jibu kwa hali yoyote ya 2xx ndani ya sekunde 10. Fanya kazi za muda mrefu baada ya kujibu.
  • Jibu lingine lolote hujaribiwa tena mara 4 zaidi kwa vipindi vinavyoongezeka (dakika 2, 4, 8 na 16). Unaweza kutuma upya tukio lolote kutoka kumbukumbu ya uwasilishaji.
  • Endpoints zinazoshindwa uwasilishaji 20 mfululizo husitishwa na wasimamizi hujulishwa. Ziwashe tena baada ya kurekebishwa.
  • Tumia “Tuma tukio la majaribio” ili kupokea tukio la ping wakati unajenga endpoint yako.

Kuthibitisha sahihi

Kokotoa HMAC-SHA256 ya muhuri wa muda, nukta na mwili ghafi wa ombi kwa kutumia siri yako ya kusaini (mfuatano wote wa whsec_…), ulinganishe na v1 kwa muda usiobadilika (constant time), na ukatae mihuri ya muda iliyopitisha dakika tano.

PHPNode.js
<?php
// Verify a ChurchBright webhook (plain PHP, no libraries needed).
$secret  = getenv('CHURCHBRIGHT_WEBHOOK_SECRET');           // whsec_… from Settings → API & webhooks
$payload = file_get_contents('php://input');                  // the raw body, before json_decode
$header  = $_SERVER['HTTP_X_CHURCHBRIGHT_SIGNATURE'] ?? '';   // "t=1727517600,v1=5f2c…"

$parts = [];
foreach (explode(',', $header) as $item) {
    [$k, $v] = array_pad(explode('=', trim($item), 2), 2, '');
    $parts[$k] = $v;
}
$t = (int)($parts['t'] ?? 0);
$expected = hash_hmac('sha256', $t . '.' . $payload, $secret);

if (!$t || abs(time() - $t) > 300 || !hash_equals($expected, $parts['v1'] ?? '')) {
    http_response_code(400);
    exit('Invalid signature');
}

$event = json_decode($payload, true);
switch ($event['event']) {
    case 'person.created':
        // $event['data'] is the person, shaped like GET /api/v1/people/{id}
        break;
    case 'contribution.recorded':
        // $event['data']['amount'] is in minor units
        break;
}
http_response_code(200); // answer quickly; do slow work in the background
Orodha ya matukio
Matukio ya msingi pamoja na matukio kutoka kwenye vipengele vilivyosakinishwa kwenye jukwaa hili. Jisajili kwa majina kamili au alama za jumla kama person.*
TukioKutokaInapotumwa
pingMsingiHutumwa tu unapobonyeza “Tuma tukio la majaribio”.
ai.output_createdBright AIBright AI wrote something in the writing studio (title and template only).
api.key_createdAPI na webhooksAn API key was created (the key itself is never included).
api.key_revokedAPI na webhooksAn API key was revoked.
api.webhook_goneAPI na webhooksHutolewa na kipengele hiki.
attendance.checkinMahudhurio na kuandikisha mahudhurioHutolewa na kipengele hiki.
attendance.children_picked_upMahudhurio na kuandikisha mahudhurioHutolewa na kipengele hiki.
attendance.pickup_flaggedMahudhurio na kuandikisha mahudhurioHutolewa na kipengele hiki.
attendance.recordedMsingiMahudhurio ya ibada au mkutano yamerekodiwa.
automations.run_completedMichakato ya kiotomatikiA person finished an automation journey (the run and the automation).
billing.downgrade_scheduledMpango na malipoHutolewa na kipengele hiki.
billing.enterprise_enquiryMpango na malipoHutolewa na kipengele hiki.
billing.extras_pausedMpango na malipoHutolewa na kipengele hiki.
billing.extras_restoredMpango na malipoHutolewa na kipengele hiki.
billing.plan_changedMpango na malipoHutolewa na kipengele hiki.
billing.plan_expiredMpango na malipoHutolewa na kipengele hiki.
billing.sms_purchasedMpango na malipoHutolewa na kipengele hiki.
billing.subscription_activatedMpango na malipoHutolewa na kipengele hiki.
care.pathway_completedUangalizi na maombiHutolewa na kipengele hiki.
care.prayer_request_createdUangalizi na maombiHutolewa na kipengele hiki.
compete.badge_awardedMashindanoHutolewa na kipengele hiki.
compete.quiz_completedMashindanoHutolewa na kipengele hiki.
contribution.recordedMsingiMchango umerekodiwa — mtandaoni, kwa mkono, kwa kuingizwa au kupitia API.
contribution.voidedMsingiMchango umebatilishwa.
dashboard.setup_completedDashibodiHutolewa na kipengele hiki.
dashboard.setup_step_doneDashibodiHutolewa na kipengele hiki.
events.checked_inMatukioHutolewa na kipengele hiki.
events.registeredMatukioHutolewa na kipengele hiki.
finance.expense_approvedFedhaHutolewa na kipengele hiki.
finance.remittance_paidFedhaHutolewa na kipengele hiki.
followup.guest_capturedWageni wa mara ya kwanza na ufuatiliajiHutolewa na kipengele hiki.
followup.stage_changedWageni wa mara ya kwanza na ufuatiliajiHutolewa na kipengele hiki.
followup.task_completedWageni wa mara ya kwanza na ufuatiliajiHutolewa na kipengele hiki.
forms.submittedFomuHutolewa na kipengele hiki.
giving.batch_depositedMatoleoHutolewa na kipengele hiki.
giving.gift_receivedMatoleoHutolewa na kipengele hiki.
giving.pledge_createdMatoleoHutolewa na kipengele hiki.
giving.recurring_cancelledMatoleoHutolewa na kipengele hiki.
giving.recurring_createdMatoleoHutolewa na kipengele hiki.
groups.join_requestedVikundi na seliHutolewa na kipengele hiki.
groups.member_addedVikundi na seliHutolewa na kipengele hiki.
groups.members_bulk_addedVikundi na seliHutolewa na kipengele hiki.
groups.message_postedVikundi na seliHutolewa na kipengele hiki.
groups.report_submittedVikundi na seliHutolewa na kipengele hiki.
imports.completedUingizajiHutolewa na kipengele hiki.
imports.undoneUingizajiHutolewa na kipengele hiki.
integrations.feed_createdMiunganishoA Google Sheets feed was created.
integrations.feed_revokedMiunganishoA Google Sheets feed was revoked.
integrations.hook_subscribedMiunganishoA Zapier or Make trigger subscribed to an event.
integrations.hook_unsubscribedMiunganishoA Zapier or Make trigger unsubscribed.
media.live_endedMediaHutolewa na kipengele hiki.
media.live_startedMediaHutolewa na kipengele hiki.
media.sermon_deletedMediaHutolewa na kipengele hiki.
media.sermon_publishedMediaHutolewa na kipengele hiki.
media.studio_publishedMediaA sermon studio section (notes, questions or devotional) was published to the sermon page.
media.studio_unpublishedMediaA sermon studio section was taken off the sermon page.
member.app_installedProgramu ya washirikaHutolewa na kipengele hiki.
member.post_publishedProgramu ya washirikaHutolewa na kipengele hiki.
member.push_sentProgramu ya washirikaHutolewa na kipengele hiki.
member.registeredProgramu ya washirikaHutolewa na kipengele hiki.
member.testimony_approvedProgramu ya washirikaHutolewa na kipengele hiki.
member.testimony_submittedProgramu ya washirikaHutolewa na kipengele hiki.
message.sentMsingiUjumbe wa SMS, barua pepe, WhatsApp, sauti au push umetumwa.
messaging.campaign_sentUjumbeHutolewa na kipengele hiki.
messaging.inbox_receivedUjumbeHutolewa na kipengele hiki.
messaging.unsubscribedUjumbeHutolewa na kipengele hiki.
nativeapp.device_registeredProgramu asiliaA phone registered for push notifications in the native app.
payment.failedMsingiMalipo ya mtandaoni yameshindikana.
payment.succeededMsingiMalipo ya mtandaoni yamefanikiwa.
people.importedWatuHutolewa na kipengele hiki.
person.createdMsingiMtu ameongezwa.
person.deletedMsingiMtu ameondolewa.
person.mergedMsingiRekodi mbili zilizojirudia ziliunganishwa ("data" imebakizwa, "previous" iliondolewa).
person.mergingWatuHutolewa na kipengele hiki.
person.status_changedMsingiHali ya mtu imebadilika, k.m. mgeni wa mara ya kwanza → mshirika.
person.tag_addedMichakato ya kiotomatikiA tag was added to a person (the person and the tag).
person.tag_removedMichakato ya kiotomatikiA tag was removed from a person (the person and the tag).
person.updatedMsingiTaarifa za mtu zimebadilika ("previous" ina thamani za zamani).
platform.announcement_publishedMsimamizi wa jukwaaHutolewa na kipengele hiki.
platform.church_plan_changedMsimamizi wa jukwaaHutolewa na kipengele hiki.
platform.church_status_changedMsimamizi wa jukwaaHutolewa na kipengele hiki.
platform.sender_id_decidedMsimamizi wa jukwaaHutolewa na kipengele hiki.
print.generatedBarua, vibandiko na bejiHutolewa na kipengele hiki.
reports.emailedRipotiAn executive summary was emailed (scheduled or on demand).
school.attendance_closedShule ya JumapiliA class closed a Sunday school session (the session and the class).
school.promotion_appliedShule ya JumapiliPromotion Sunday was applied (the promotion and how many moved).
serve.assignment_acceptedKuhudumuHutolewa na kipengele hiki.
site.lead_receivedTovuti ya masokoHutolewa na kipengele hiki.
user.invitedMsingiMwanatimu amealikwa.
ussd.pay_requestedUSSDHutolewa na kipengele hiki.
ussd.session_endedUSSDHutolewa na kipengele hiki.
website.message_receivedTovutiHutolewa na kipengele hiki.
website.page_publishedTovutiHutolewa na kipengele hiki.
website.template_appliedTovutiHutolewa na kipengele hiki.
website.translation_createdTovutiHutolewa na kipengele hiki.
x.yAPI na webhooksHutolewa na kipengele hiki.

Matoleo ya API: hili ni toleo la 1. Tunaongeza sehemu na endpoint bila taarifa, kwa hivyo puuza sehemu usizozijua; chochote kinachoweza kuvunja muunganisho kitakuja kama toleo jipya.