Vendor Guide: Building a Texting Integration

1. Authentication (v2)

• Protocol: OAuth 2.0, three-legged flow.
• Auth types:
  • System Auth — vendor-level access to an entire church's data.
• Base URLs:
  • Production: https://api.ccbchurch.com
• Getting credentials: Submit the API access request form via the Pushpay vendor portal. A church's Master Administrator must authorize the app before it can pull data.

This is unchanged in structure from v1 (same OAuth model, same host), but v2 is the actively developed surface for day-to-day church-management data — people, groups, scheduling, forms, process queues.

---

2. Native ChMS Texting Features (context, not API)

These exist in the ChMS product itself and set the boundaries any integration works around:

Text delivery for all of these depends on the individual's Communication Preferences having text messages enabled — the API cannot force delivery for someone who has opted out on their phone/carrier or in ChMS.

---

3. Integration Patterns on v2

A. Group Leader Sends → Vendor Texts Participants

Same pattern as v1: since there's no API to send a group text or to know per-person opt-in/out for group texts, a vendor watches for new leader messages and relays them as SMS.

• Poll GET /groups/{id}/messages for new messages (v2 supports leaders_only filter — narrower than v1's equivalent).
• Resolve recipients via GET /groups/{id}/members.
• Still no v2 endpoint to create/send a group message via API, and still no per-person group-text opt-in/out surfaced — same as v1. This has to be managed on the vendor's side.

B. Inbound Text → Process Queue (e.g., guest follow-up)

• Search for an existing match: POST /search/individuals/results (v2 equivalent of v1's getIndividualAdvancedSearchResults).
• If not found, create the person: POST /individuals.
• Add them to a follow-up queue: POST /queues/{queueId}/individuals.

Functionally identical to the v1 flow — just new paths.

C. Notify Schedule Volunteers of Open Requests

• Find volunteers in a category, optionally filtered by whether they've been notified: GET /categories/{id}/individuals, filters include has_mobile_phone, has_been_notified, schedule_ids, statuses (v2 adds position_ids and serving_rotation_ids — more precise targeting than v1 offered).
• v2 adds a direct send option not available in v1: POST /categories/{id}/notifications (and POST /categories/{id}/volunteers/message) let you trigger ChMS-side notifications instead of only reading recipient lists and sending externally.
• Process-queue notifications have an equivalent direct-send endpoint too: POST /queues/{queueId}/individuals/notifications.

D. New in v2: Two-Way Individual Messaging

This is the most relevant v2 addition for a texting vendor — v1 had no reply capability at all. v2 exposes message endpoints:

• GET /individual_messages/{id} — retrieve a single message
• POST /individual_messages/{id}/replies — send a reply to a message
• GET /individual_messages/{id}/replies — list replies
• PUT / DELETE on both messages and replies

---

4. v1 → v2 Endpoint Reference (ranked by most popular)