Developer Guide

Key Terms

For Provider and Member, see Basic Terminology. The terms below are specific to this API.

Setup

1. Receive from CCA: the environment base URL and your Bearer token. This is the only credential you will handle — everything else CCA needs to identify you and your organization is resolved internally from the token.
2. Store the Bearer token in your server-side secrets manager. Treat it as a production credential. This token must be attached to the Authorization: Bearer <token> HTTP header for all requests.
3. Call the provider-regions endpoint to discover valid region_id values, then search availability and create a booking.
4. Complete the sandbox testing checklist before production cutover.

What CCA Provisions (Before Go-Live)

Making Requests

Every endpoint uses the same authentication — no separate login or token-exchange step:

Authorization: Bearer <token>

There is no request body signing, no claims to construct, and nothing to generate. The token CCA gives you is used exactly as received, on every call, until it is rotated.

The Four Endpoints

Full parameter and response documentation for each endpoint lives in the API Docs section.

Booking Example

A full walkthrough of the real sequence, from discovering a region through confirming the booking. Every call below sends the same Authorization: Bearer <token> header.

1. Discover a Region

GET /partners/v1/provider-regions/?country_code=US

[
  { "id": 1, "countryCode": "US", "stateProvinceCode": "US-NY", "stateProvinceNameLocal": "New York", "stateProvinceLabel": "State" },
  { "id": 2, "countryCode": "US", "stateProvinceCode": "US-CA", "stateProvinceNameLocal": "California", "stateProvinceLabel": "State" },
  { "id": 3, "countryCode": "US", "stateProvinceCode": "US-TX", "stateProvinceNameLocal": "Texas", "stateProvinceLabel": "State" }
]

This is one page of results — one entry per active region in the country, paginated (page/page_size, same as described above). Take the id you want — that is the region_id the next call expects.

2. Search Provider Booking Availability

GET /partners/v1/providers/?region_id=1

Send at least one of region_id/country_code — region_id is required for a country if the provider-regions endpoint returns more than one region for it. Full parameter rules, error cases, and filter options (modality, language, pagination) will be documented in the API Docs section.

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "providerId": 789,
      "details": { "firstName": "Jane", "lastName": "Smith", "...": "..." },
      "availability": [
        { "utcStartTime": "2026-08-02T14:00:00Z", "utcEndTime": "2026-08-02T14:45:00Z" }
      ]
    }
  ]
}

Pick a providerId and one of its availability slots. next/previous are full URLs — call them directly for the next/previous page, no need to build the query yourself.

3. Create the Booking

POST /partners/v1/booking-request/
Content-Type: application/json

Send the slot's utcStartTime/utcEndTime from step 2 exactly as received — no timezone conversion needed:

{
  "user": { "external_user_id": "patient-00123" },
  "bookingData": {
    "selfSchedulingProviderId": 789,
    "utcStartTime": "2026-08-02T14:00:00Z",
    "utcEndTime": "2026-08-02T14:45:00Z"
  },
  "memberData": {
    "email": "jane.doe@example.com",
    "firstName": "Jane",
    "lastName": "Doe",
    "dob": "1990-01-01",
    "gender": "Female",
    "maritalStatus": "Single",
    "clientType": "Employee",
    "leaveVoicemail": "Yes",
    "phoneNumber": "+15551234567",
    "streetAddress": "123 Main St",
    "suite": "",
    "city": "New York",
    "state": "NY",
    "zipCode": "10001",
    "country": "US",
    "reasonForSeekingSupport": "Anxiety",
    "preferredModality": "Video Counseling",
    "preferredSpokenLanguage": "en"
  },
  "phq9Data": [
    { "question": "PHQ-9 1.Little interest or pleasure in doing things.", "answer": "0 Not at all" }
  ]
}

memberData.preferredSpokenLanguage is optional, a BCP-47 code (e.g. en, en-US, fr-CA). Defaults to the en language code if omitted.

A 201 response confirms the booking:

{
  "id": 456,
  "providerId": 789,
  "phoneNumber": "+15551234567",
  "preferredModality": "Video Counseling",
  "member": { "id": 42, "firstName": "Jane", "email": "jane.doe@example.com" },
  "utcStartTime": "2026-08-02T14:00:00Z"
}

user.external_user_id is your own stable id for this member — calling this endpoint again with the same value updates the same member record (matched on email/name/etc.) and adds another booking, rather than creating a duplicate.

No specific provider or slot yet? Omit bookingData entirely (send only user, memberData, and phq9Data) and this endpoint submits a general intake instead of a booking — our operations team assigns a provider afterward. The response in that case has providerId/acceptedAt/declinedAt/utcStartTime all null (nothing was scheduled yet — once a provider is assigned, this same shape starts returning real values):

{
  "id": 245,
  "providerId": null,
  "authorizationNumber": null,
  "phoneNumber": "+15551234567",
  "preferredModality": "Video Counseling",
  "acceptedAt": null,
  "declinedAt": null,
  "member": { "id": 42, "firstName": "Jane", "email": "jane.doe@example.com" },
  "utcStartTime": null
}

4. Confirm the Member

Now that the booking exists, you can look the member up again by the same external_user_id — this confirms CCA created (or matched to an existing) member record correctly, and gives you back the member's CCA id for your own records.

GET /partners/v1/user/?external_user_id=patient-00123

{
  "id": 42,
  "firstName": "Jane",
  "email": "jane.doe@example.com",
  "userType": "customer",
  "lastName": "Doe",
  "country": "US",
  "preferredSpokenLanguage": "English",
  "preferredSpokenLanguageCode": "en",
  "externalUserId": "patient-00123"
}

Sample Code

Unlike token-based authentication on the members portal, there is no cryptography to implement on the partner side — you send a standard Authorization header.

Python — using requests:

import requests

BASE_URL = "https://api.ccaplatform.com"
BEARER_TOKEN = "<the token CCA gave you>"

def list_regions(country_code: str) -> list:
    response = requests.get(
        f"{BASE_URL}/partners/v1/provider-regions/",
        params={"country_code": country_code},
        headers={"Authorization": f"Bearer {BEARER_TOKEN}"},
    )
    response.raise_for_status()
    return response.json()

Node.js — using fetch:

const BASE_URL = 'https://api.ccaplatform.com';
const BEARER_TOKEN = '<the token CCA gave you>';

async function listRegions(countryCode) {
  const response = await fetch(
    `${BASE_URL}/partners/v1/provider-regions/?country_code=${countryCode}`,
    { headers: { Authorization: `Bearer ${BEARER_TOKEN}` } },
  );
  if (!response.ok) {
    throw new Error(`Request failed: ${response.status}`);
  }
  return response.json();
}

Token Format

Security and Privacy

What Partners Must Do on Their Side

• Store the Bearer token only on trusted servers — never in a browser or mobile client. This token must be attached to the Authorization: Bearer <token> HTTP header for all requests.
• Do not log, cache, or persist the token outside your secrets manager.
• Treat the sandbox token and production token as separate credentials.
• Notify CCA immediately if you suspect the token has been exposed.

Errors

The 401 responses share the shape {"code": "...", "message": "..."}. The code is always one of the stable values above — the message is a safe, generic description; it deliberately never reveals internal configuration details.

Secret Rotation

Sandbox Testing Checklist

1. Confirm CCA sent your sandbox Bearer token and base URL.
2. Store the sandbox token in your server-side vault.
3. Call GET /partners/v1/provider-regions/ to confirm authentication works end-to-end.
4. Search availability and submit a test booking via POST /partners/v1/booking-request/.
5. Confirm you can look the resulting member up again via GET /partners/v1/user/.
6. Call GET /partners/v1/providers/?country_code=<your country> and confirm it returns providers without sending region_id.
7. Add &language=<a BCP-47 code> to an availability search and confirm results narrow to providers who speak it.
8. Test pagination — call with page_size=1 (or similar) and confirm count/next/results behave as expected; then call an out-of-range page and confirm you get a 400, not a raw error.
9. Call POST /partners/v1/booking-request/ with bookingData omitted and confirm you get an intake response (providerId/utcStartTime both null) instead of a booking.
10. Confirm a malformed or incorrect token returns a 401 with a token_invalid code, not a raw error.

Support