Introduction

Introduction

Orientation for integrating with the CAIL Health API
View as MarkdownOpen in Claude

The CAIL Health API is the programmatic surface of CAIL Health, the healthcare access infrastructure that routes care-seeking demand to available care capacity. Use it to discover providers, resolve jurisdiction-aware pathways, check availability, navigate members to care, and read demand and access analytics.

This reference describes every endpoint. The pages in this section cover what every endpoint shares: how to authenticate, how errors are returned, and how the API is versioned.

Base URL and version

Every endpoint is versioned by a path prefix. The current version is v1, so every path in this reference begins with /v1. See Versioning for what that version guarantees.

How the reference is organized

Operations are grouped by the capability they serve, such as discovering providers, navigating to care, and monitoring performance. Each operation page lists its path, parameters, request body, responses, and worked examples.

Each operation also declares which audience may call it. An operation accepts exactly one authentication path and rejects the other. The required scheme is shown on every operation; see Authentication for how to read it.

Two audiences

CAIL Health serves two audiences, and each authenticates on its own path.

  • Member clients authenticate anonymously through Firebase Auth. They carry no personally identifying information.
  • Operator clients authenticate through Auth0, scoped to the organization the user belongs to.

The two paths never mix. Authentication explains both.

Healthcare data on the wire

Clinical resources are modeled in FHIR R4 where appropriate. Regional differences such as provider taxonomy, network rules, and routing semantics are resolved per jurisdiction, so the same endpoint behaves correctly across the regions CAIL supports. For background, see FHIR R4 in CAIL Health and Jurisdictions.

The shared contract

Before calling any endpoint, read the three pages that describe behavior common to all of them:

  • Authentication: the two token paths and how to send a token.
  • Errors: the single error envelope every failure uses.
  • Versioning: how the API is versioned and what changes are compatible.

Two further references describe contracts shared across endpoints: the Error envelope and Pagination.