Développeurs — API REST et webhooks

Démarrage rapide

Dans le compte de votre église, ouvrez Paramètres → API et webhooks et créez une clé. Copiez-la — elle n’est affichée qu’une seule fois.
Appelez l’API depuis votre serveur avec la clé dans l’en-tête Authorization.
Ajoutez un webhook pour être informé des changements en temps réel au lieu d’interroger régulièrement l’API.

URL de base: 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"

Authentification

Chaque requête nécessite une clé API. Les clés ressemblent à cb_live_ suivi de 32 lettres et chiffres. Envoyez-la comme jeton bearer :

Authorization: Bearer cb_live_…

Chaque clé dispose d’autorisations par ressource — par exemple people:read, people:write, contributions:read ou messages:write — et peut être limitée à une branche et aux branches qui en dépendent. Une clé limitée à une branche ne voit et ne crée des enregistrements que dans ces branches.

Si votre outil ne peut pas définir d’en-têtes, vous pouvez passer ?api_key=… à la place, mais les en-têtes sont plus sûrs car les URL finissent dans les journaux. Les clés doivent rester uniquement sur les serveurs : jamais dans du JavaScript de navigateur, des applications mobiles ou des dépôts publics. Révoquez une clé dès que vous pensez qu’elle a fuité.

Requêtes et réponses

Envoyez du JSON avec Content-Type: application/json (les corps encodés en formulaire fonctionnent aussi).
Chaque réponse est au format JSON avec "ok". Les réponses réussies contiennent "data" (et "meta" pour les listes).
Les horodatages sont en UTC au format ISO 8601 (2026-09-28T09:14:03Z). Les dates de calendrier comme given_on ou dob sont au format YYYY-MM-DD dans le fuseau horaire propre à l’église.
Les montants sont des entiers en unités mineures : 150050 signifie 1,500.50 dans la devise indiquée. amount_base est toujours dans la devise de l’église.
Envoyez un en-tête Idempotency-Key (toute chaîne unique de 120 caractères maximum) avec les requêtes POST. Une nouvelle tentative avec la même clé renvoie la première réponse au lieu de créer un doublon — important pour les dons.

{
    "ok": true,
    "data": {
        "id": 42,
        "first_name": "Ngozi",
        "…": "…"
    },
    "meta": {
        "page": 1,
        "per_page": 25,
        "total": 214,
        "total_pages": 9,
        "has_more": true
    }
}

Pagination et filtres

Les listes renvoient 25 enregistrements par page par défaut. Utilisez ?page= et ?per_page= (jusqu’à 100). meta indique le total et s’il existe une autre page.

Pour garder un autre système synchronisé, notez la date de votre dernière synchronisation et demandez uniquement ce qui a changé depuis avec ?updated_since=2026-09-01T00:00:00Z. Pour les personnes, ajoutez include_deleted=1 afin d’être aussi informé des suppressions.

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"

Erreurs

Les erreurs utilisent les codes de statut HTTP habituels et un corps contenant "ok": false, un "error" lisible par une machine et un "message" lisible par un humain. Les erreurs de validation ajoutent "errors" avec un message par champ.

Statut	error	Signification
400	`invalid_json, invalid_updated_since, invalid_status…`	La requête est mal formée — vérifiez le message.
401	`unauthorized, invalid_api_key`	Aucune clé, ou la clé est incorrecte ou révoquée.
403	`insufficient_scope, api_disabled, church_inactive, plan_limit_reached`	La clé est valide mais n’est pas autorisée à effectuer cette action.
404	`not_found, unknown_resource`	L’enregistrement n’existe pas ou se trouve hors de la branche de la clé.
405	`method_not_allowed`	Cette méthode HTTP n’est pas prise en charge sur cette URL.
409	`duplicate_reference, idempotency_key_reused`	Entre en conflit avec une demande antérieure.
422	`validation_failed, send_failed, recipient_skipped`	Les données ne sont pas valides ; "errors" liste chaque champ.
429	`rate_limited`	Trop de requêtes — attendez le nombre de secondes indiqué par Retry-After.
500	`resource_error`	Un problème est survenu de notre côté. Réessayez plus tard.

{
    "ok": false,
    "error": "validation_failed",
    "message": "Certains champs ne sont pas valides.",
    "errors": {
        "email": "Saisissez une adresse e-mail valide."
    }
}

Limites de débit

Chaque clé peut effectuer 120 requêtes par minute (et chaque adresse IP 600). Au-delà, vous recevez une réponse HTTP 429 avec un en-tête Retry-After. Utilisez updated_since et les webhooks plutôt que des interrogations répétées.

Votre clé

GET `/api/v1`

Vérifiez votre clé · nécessite toute clé valide

Renvoie l’église, les autorisations de la clé et toutes les ressources auxquelles elle a accès. Utilisez-le pour tester votre configuration.

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

Exemple de réponse

{
    "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"
            }
        ]
    }
}

Personnes

GET `/api/v1/people`

Lister les personnes · nécessite people:read

Membres, visiteurs et nouveaux venus, les plus anciens en premier. Les personnes supprimées sont exclues sauf si include_deleted=1.

Paramètre de requête	Description
`status`	Un statut ou une liste séparée par des virgules : first_timer, visitor, new_convert, regular, member, worker, leader, inactive, transferred, deceased
`branch_id`	Cette branche et ses sous-branches uniquement
`family_id`	Ce foyer uniquement
`q`	Rechercher un nom, un e-mail ou un numéro de membre
`email`	Correspondance exacte de l’e-mail
`phone`	Correspondance exacte du téléphone (tout format)
`updated_since`	Modifié à cette heure ou après (ISO 8601)
`created_since`	Ajouté à cette heure ou après
`include_deleted`	1 pour inclure les personnes retirées (avec deleted_at renseigné) — utile pour la synchronisation
`sort`	id, -id, updated_at, -updated_at, last_name

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

Exemple de réponse

{
    "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}`

Obtenir une personne · nécessite people:read

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

Exemple de réponse

{
    "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`

Créer une personne · nécessite people:write

first_name est obligatoire. Les dates utilisent le format YYYY-MM-DD ; les numéros de téléphone sont convertis au format international selon le pays de l’église. Envoyez "dedupe": true pour récupérer la personne existante (HTTP 200, meta.duplicate = true) lorsque l’e-mail ou le téléphone est déjà enregistré.

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}'

Exemple de réponse

{
    "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}`

Mettre à jour une personne · nécessite people:write

Envoyez uniquement les champs à modifier. PUT et POST sur la même URL fonctionnent aussi. Les champs personnalisés sont fusionnés.

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"}}'

Exemple de réponse

{
    "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
    }
}

Familles

GET `/api/v1/families`

Lister les familles · nécessite families:read

Paramètre de requête	Description
`q`	Rechercher par nom
`branch_id`	Cette branche uniquement
`updated_since`	Modifié depuis

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

Exemple de réponse

{
    "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}`

Obtenir une famille avec ses membres · nécessite families:read

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

Exemple de réponse

{
    "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`

Créer une famille · nécessite 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}'

Exemple de réponse

{
    "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"
    }
}

Branches et fonds

GET `/api/v1/branches`

Lister les branches · nécessite branches:read

L’arborescence complète : parent_id relie une branche à celle qui se trouve au-dessus.

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

Exemple de réponse

{
    "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`

Lister les fonds · nécessite funds:read

Paramètre de requête	Description
`active`	1 = fonds actifs uniquement, 0 = fonds inactifs uniquement

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

Exemple de réponse

{
    "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
    }
}

Contributions

GET `/api/v1/contributions`

Lister les contributions · nécessite contributions:read

Les montants sont des entiers en unités mineures (kobo, centimes). meta.sum_amount_base totalise tous les dons correspondants dans la devise de l’église.

Paramètre de requête	Description
`from`	Donné à partir du (YYYY-MM-DD)
`to`	Donné jusqu’au
`fund_id`	Un seul fonds
`person_id`	Un donateur
`method`	cash, bank_transfer, pos, online, ach, cheque, ussd, mobile_money, text, in_kind, other
`source`	manual, online, import, api, …
`status`	posted (par défaut), void ou all
`branch_id`	Cette branche et ses sous-branches
`updated_since`	Modifié depuis
`sort`	id, -id, given_on, -given_on

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

Exemple de réponse

{
    "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}`

Obtenir un don · nécessite contributions:read

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

Exemple de réponse

{
    "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`

Enregistrer une contribution · nécessite contributions:write

amount est obligatoire, en unités mineures. Par défaut, fund_id correspond au fonds par défaut de l’église, given_on à la date du jour et method à online. Une référence déjà enregistrée via l’API renvoie 409. Envoyez un en-tête Idempotency-Key pour que les nouvelles tentatives n’enregistrent jamais un don deux fois.

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"}'

Exemple de réponse

{
    "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"
    }
}

Messages

POST `/api/v1/messages`

Envoyer un message · nécessite messages:write

channel vaut sms, email, whatsapp ou push. Envoyez à un person_id, jusqu’à 100 person_ids, ou directement à un numéro de téléphone ou e-mail via "to". Les balises de fusion comme {first_name} fonctionnent. Les désinscriptions sont respectées et les unités SMS sont décomptées comme d’habitude.

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!"}'

Exemple de réponse

{
    "ok": true,
    "data": {
        "id": 5521,
        "person_id": 42,
        "status": "sent",
        "error": null,
        "channel": "sms"
    }
}

GET `/api/v1/messages`

Journal des messages · nécessite messages:read

Paramètre de requête	Description
`channel`	sms, email, whatsapp, voice, push
`status`	sent, delivered, failed, skipped
`person_id`	Une personne
`source`	Provenance, p. ex. api, followup
`updated_since`	Modifié depuis

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

Exemple de réponse

{
    "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
    }
}

Plus de ressources

Ces ressources proviennent des fonctionnalités activées par votre église. Elles suivent les mêmes règles d’authentification, de pagination et d’erreurs.

GET `/api/v1/prayer_requests`

Lister Sujets de prière · nécessite prayer_requests:read

Fourni par le module Accompagnement et prière.

Paramètre de requête	Description
`page`	Numéro de page
`per_page`	Jusqu’à 100
`updated_since`	Modifié depuis (si pris en charge)

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

GET `/api/v1/prayer_requests/{id}`

Obtenir un enregistrement Sujets de prière · nécessite prayer_requests:read

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

POST `/api/v1/prayer_requests`

Créer Sujets de prière · nécessite 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`

Lister Dons · nécessite gifts:read

Fourni par le module Dons.

Paramètre de requête	Description
`page`	Numéro de page
`per_page`	Jusqu’à 100
`updated_since`	Modifié depuis (si pris en charge)

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

GET `/api/v1/gifts/{id}`

Obtenir un enregistrement Dons · nécessite gifts:read

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

GET `/api/v1/sermons`

Lister Prédications · nécessite sermons:read

Fourni par le module Médias.

Paramètre de requête	Description
`page`	Numéro de page
`per_page`	Jusqu’à 100
`updated_since`	Modifié depuis (si pris en charge)

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

GET `/api/v1/sermons/{id}`

Obtenir un enregistrement Prédications · nécessite sermons:read

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

Ajoutez des points de terminaison dans Paramètres → API et webhooks → Webhooks et choisissez les événements souhaités. Lorsqu’un événement se produit, nous envoyons un POST HTTPS avec un corps JSON comme celui-ci :

{
    "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" a la même structure que la ressource REST correspondante. Les événements de mise à jour incluent aussi "previous" avec les valeurs d’avant la modification. Chaque requête comporte ces en-têtes :

`X-ChurchBright-Event`	Le nom de l’événement, p. ex. person.created
`X-ChurchBright-Event-Id`	Unique par événement — conservez-le pour ignorer les doublons, car un renvoi le réutilise.
`X-ChurchBright-Delivery`	L’identifiant de la tentative de livraison affiché dans votre journal de livraison.
`X-ChurchBright-Signature`	t=<unix time>,v1=<HMAC-SHA256 de "<t>.<raw body>" avec votre secret de signature, en hex>

Répondez avec un statut 2xx dans les 10 secondes. Effectuez les traitements longs après avoir répondu.
Toute autre réponse entraîne 4 nouvelles tentatives à intervalles croissants (2, 4, 8 et 16 minutes). Vous pouvez renvoyer n’importe quel événement depuis le journal des envois.
Les points de terminaison qui échouent 20 envois d’affilée sont mis en pause et les administrateurs sont prévenus. Réactivez-les une fois le problème corrigé.
Utilisez « Envoyer un événement de test » pour recevoir un événement ping pendant que vous développez votre point de terminaison.

Vérification des signatures

Calculez le HMAC-SHA256 de l’horodatage, d’un point et du corps brut de la requête avec votre secret de signature (toute la chaîne whsec_…), comparez-le avec v1 en temps constant, et rejetez les horodatages de plus de cinq minutes.

PHP Node.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

Catalogue des événements

Événements de base et événements des fonctionnalités installées sur cette plateforme. Abonnez-vous avec des noms exacts ou des caractères génériques comme person.*

Événement	De	Moment de l’envoi
`ping`	Base	Envoyé uniquement lorsque vous appuyez sur « Envoyer un événement de test ».
`ai.output_created`	Bright AI	Bright AI wrote something in the writing studio (title and template only).
`api.key_created`	API et webhooks	An API key was created (the key itself is never included).
`api.key_revoked`	API et webhooks	An API key was revoked.
`api.webhook_gone`	API et webhooks	Émis par cette fonctionnalité.
`attendance.checkin`	Présences et pointage	Émis par cette fonctionnalité.
`attendance.children_picked_up`	Présences et pointage	Émis par cette fonctionnalité.
`attendance.pickup_flagged`	Présences et pointage	Émis par cette fonctionnalité.
`attendance.recorded`	Base	Les présences d’un culte ou d’une réunion ont été enregistrées.
`automations.run_completed`	Automatisations	A person finished an automation journey (the run and the automation).
`billing.downgrade_scheduled`	Forfait et facturation	Émis par cette fonctionnalité.
`billing.enterprise_enquiry`	Forfait et facturation	Émis par cette fonctionnalité.
`billing.extras_paused`	Forfait et facturation	Émis par cette fonctionnalité.
`billing.extras_restored`	Forfait et facturation	Émis par cette fonctionnalité.
`billing.plan_changed`	Forfait et facturation	Émis par cette fonctionnalité.
`billing.plan_expired`	Forfait et facturation	Émis par cette fonctionnalité.
`billing.sms_purchased`	Forfait et facturation	Émis par cette fonctionnalité.
`billing.subscription_activated`	Forfait et facturation	Émis par cette fonctionnalité.
`care.pathway_completed`	Accompagnement et prière	Émis par cette fonctionnalité.
`care.prayer_request_created`	Accompagnement et prière	Émis par cette fonctionnalité.
`compete.badge_awarded`	Compétitions	Émis par cette fonctionnalité.
`compete.quiz_completed`	Compétitions	Émis par cette fonctionnalité.
`contribution.recorded`	Base	Un don a été enregistré — en ligne, manuellement, par importation ou via l’API.
`contribution.voided`	Base	Un don a été annulé.
`dashboard.setup_completed`	Tableau de bord	Émis par cette fonctionnalité.
`dashboard.setup_step_done`	Tableau de bord	Émis par cette fonctionnalité.
`events.checked_in`	Événements	Émis par cette fonctionnalité.
`events.registered`	Événements	Émis par cette fonctionnalité.
`finance.expense_approved`	Finances	Émis par cette fonctionnalité.
`finance.remittance_paid`	Finances	Émis par cette fonctionnalité.
`followup.guest_captured`	Nouveaux venus et suivi	Émis par cette fonctionnalité.
`followup.stage_changed`	Nouveaux venus et suivi	Émis par cette fonctionnalité.
`followup.task_completed`	Nouveaux venus et suivi	Émis par cette fonctionnalité.
`forms.submitted`	Formulaires	Émis par cette fonctionnalité.
`giving.batch_deposited`	Dons	Émis par cette fonctionnalité.
`giving.gift_received`	Dons	Émis par cette fonctionnalité.
`giving.pledge_created`	Dons	Émis par cette fonctionnalité.
`giving.recurring_cancelled`	Dons	Émis par cette fonctionnalité.
`giving.recurring_created`	Dons	Émis par cette fonctionnalité.
`groups.join_requested`	Groupes et cellules	Émis par cette fonctionnalité.
`groups.member_added`	Groupes et cellules	Émis par cette fonctionnalité.
`groups.members_bulk_added`	Groupes et cellules	Émis par cette fonctionnalité.
`groups.message_posted`	Groupes et cellules	Émis par cette fonctionnalité.
`groups.report_submitted`	Groupes et cellules	Émis par cette fonctionnalité.
`imports.completed`	Importations	Émis par cette fonctionnalité.
`imports.undone`	Importations	Émis par cette fonctionnalité.
`integrations.feed_created`	Intégrations	A Google Sheets feed was created.
`integrations.feed_revoked`	Intégrations	A Google Sheets feed was revoked.
`integrations.hook_subscribed`	Intégrations	A Zapier or Make trigger subscribed to an event.
`integrations.hook_unsubscribed`	Intégrations	A Zapier or Make trigger unsubscribed.
`media.live_ended`	Médias	Émis par cette fonctionnalité.
`media.live_started`	Médias	Émis par cette fonctionnalité.
`media.sermon_deleted`	Médias	Émis par cette fonctionnalité.
`media.sermon_published`	Médias	Émis par cette fonctionnalité.
`media.studio_published`	Médias	A sermon studio section (notes, questions or devotional) was published to the sermon page.
`media.studio_unpublished`	Médias	A sermon studio section was taken off the sermon page.
`member.app_installed`	Application membre	Émis par cette fonctionnalité.
`member.post_published`	Application membre	Émis par cette fonctionnalité.
`member.push_sent`	Application membre	Émis par cette fonctionnalité.
`member.registered`	Application membre	Émis par cette fonctionnalité.
`member.testimony_approved`	Application membre	Émis par cette fonctionnalité.
`member.testimony_submitted`	Application membre	Émis par cette fonctionnalité.
`message.sent`	Base	Un SMS, un e-mail, un message WhatsApp, vocal ou push a été envoyé.
`messaging.campaign_sent`	Messages	Émis par cette fonctionnalité.
`messaging.inbox_received`	Messages	Émis par cette fonctionnalité.
`messaging.unsubscribed`	Messages	Émis par cette fonctionnalité.
`nativeapp.device_registered`	Applications natives	A phone registered for push notifications in the native app.
`payment.failed`	Base	Un paiement en ligne a échoué.
`payment.succeeded`	Base	Un paiement en ligne a réussi.
`people.imported`	Personnes	Émis par cette fonctionnalité.
`person.created`	Base	Une personne a été ajoutée.
`person.deleted`	Base	Une personne a été retirée.
`person.merged`	Base	Deux enregistrements en double ont été fusionnés ("data" est conservé, "previous" a été supprimé).
`person.merging`	Personnes	Émis par cette fonctionnalité.
`person.status_changed`	Base	Le statut d’une personne a changé, p. ex. nouveau venu → membre.
`person.tag_added`	Automatisations	A tag was added to a person (the person and the tag).
`person.tag_removed`	Automatisations	A tag was removed from a person (the person and the tag).
`person.updated`	Base	Les informations d’une personne ont changé ("previous" contient les anciennes valeurs).
`platform.announcement_published`	Administration de la plateforme	Émis par cette fonctionnalité.
`platform.church_plan_changed`	Administration de la plateforme	Émis par cette fonctionnalité.
`platform.church_status_changed`	Administration de la plateforme	Émis par cette fonctionnalité.
`platform.sender_id_decided`	Administration de la plateforme	Émis par cette fonctionnalité.
`print.generated`	Lettres, étiquettes et badges	Émis par cette fonctionnalité.
`reports.emailed`	Rapports	An executive summary was emailed (scheduled or on demand).
`school.attendance_closed`	École du dimanche	A class closed a Sunday school session (the session and the class).
`school.promotion_applied`	École du dimanche	Promotion Sunday was applied (the promotion and how many moved).
`serve.assignment_accepted`	Servir	Émis par cette fonctionnalité.
`site.lead_received`	Site vitrine	Émis par cette fonctionnalité.
`user.invited`	Base	Un membre de l’équipe a été invité.
`ussd.pay_requested`	USSD	Émis par cette fonctionnalité.
`ussd.session_ended`	USSD	Émis par cette fonctionnalité.
`website.message_received`	Site web	Émis par cette fonctionnalité.
`website.page_published`	Site web	Émis par cette fonctionnalité.
`website.template_applied`	Site web	Émis par cette fonctionnalité.
`website.translation_created`	Site web	Émis par cette fonctionnalité.
`x.y`	API et webhooks	Émis par cette fonctionnalité.

API REST et webhooks ChurchBright

Démarrage rapide

Authentification

Requêtes et réponses

Erreurs

Limites de débit

Points de terminaison

GET `/api/v1`

GET `/api/v1/people`

GET `/api/v1/people/{id}`

POST `/api/v1/people`

PATCH `/api/v1/people/{id}`

GET `/api/v1/families`

GET `/api/v1/families/{id}`

POST `/api/v1/families`

GET `/api/v1/branches`

GET `/api/v1/funds`

GET `/api/v1/contributions`

GET `/api/v1/contributions/{id}`

POST `/api/v1/contributions`

POST `/api/v1/messages`

GET `/api/v1/messages`

GET `/api/v1/prayer_requests`

GET `/api/v1/prayer_requests/{id}`

POST `/api/v1/prayer_requests`

GET `/api/v1/gifts`

GET `/api/v1/gifts/{id}`

GET `/api/v1/sermons`

GET `/api/v1/sermons/{id}`

Webhooks

Vérification des signatures

Démarrage rapide

Authentification

Requêtes et réponses

Pagination et filtres

Erreurs

Limites de débit

Points de terminaison

GET /api/v1

GET /api/v1/people

GET /api/v1/people/{id}

POST /api/v1/people

PATCH /api/v1/people/{id}

GET /api/v1/families

GET /api/v1/families/{id}

POST /api/v1/families

GET /api/v1/branches

GET /api/v1/funds

GET /api/v1/contributions

GET /api/v1/contributions/{id}

POST /api/v1/contributions

POST /api/v1/messages

GET /api/v1/messages

GET /api/v1/prayer_requests

GET /api/v1/prayer_requests/{id}

POST /api/v1/prayer_requests

GET /api/v1/gifts

GET /api/v1/gifts/{id}

GET /api/v1/sermons

GET /api/v1/sermons/{id}

Webhooks

Vérification des signatures

GET `/api/v1`

GET `/api/v1/people`

GET `/api/v1/people/{id}`

POST `/api/v1/people`

PATCH `/api/v1/people/{id}`

GET `/api/v1/families`

GET `/api/v1/families/{id}`

POST `/api/v1/families`

GET `/api/v1/branches`

GET `/api/v1/funds`

GET `/api/v1/contributions`

GET `/api/v1/contributions/{id}`

POST `/api/v1/contributions`

POST `/api/v1/messages`

GET `/api/v1/messages`

GET `/api/v1/prayer_requests`

GET `/api/v1/prayer_requests/{id}`

POST `/api/v1/prayer_requests`

GET `/api/v1/gifts`

GET `/api/v1/gifts/{id}`

GET `/api/v1/sermons`

GET `/api/v1/sermons/{id}`