Make an API request

This walkthrough takes you from nothing to a working CAIL Health API call. By the end you will have authenticated, sent a request, and read a real response. It assumes only that you can run curl or make an HTTP request from your language of choice.

Before you start

You need two things:

• The API base URL for the environment you are integrating against. The examples below refer to it as $CAIL_API_BASE_URL.
• A bearer token for one of the two audiences. CAIL Health has two authentication paths that never mix:
  • Member clients authenticate anonymously through Firebase Auth.
  • Operator clients authenticate through Auth0.

See Authentication for how to obtain a token on each path. This walkthrough uses a member token, because the endpoint it calls serves the member audience.

Step 1: Set your token

Export your member token so the later commands can reuse it:

$
export CAIL_TOKEN="<your-member-token>"
$
export CAIL_API_BASE_URL="<your-api-base-url>"

Step 2: Send the request

Call the provider proximity search. It is a good first request: it takes only query parameters, needs no request body, and returns a ranked list you can read at a glance. The latitude and longitude mark the centre of the search.

$
curl --get "$CAIL_API_BASE_URL/v1/search/proximity" \
>
  --data-urlencode "latitude=51.5074" \
>
  --data-urlencode "longitude=-0.1278" \
>
  --data-urlencode "radiusKm=5" \
>
  --header "Authorization: Bearer $CAIL_TOKEN"

Every request path begins with the version prefix /v1. See Versioning.

Step 3: Read the response

A successful call returns 200 OK and a ranked page of nearby providers:

1
{
2
  "data": [
3
    {
4
      "providerId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
5
      "name": "St Thomas' Hospital",
6
      "distanceMetres": 1820,
7
      "availabilityStatus": "open_now"
8
    }
9
  ],
10
  "meta": {
11
    "requestId": "4a3b2c1d-5e6f-4890-9abc-def0fedcba98",
12
    "timestamp": "2026-05-13T14:21:00.000Z",
13
    "durationMs": 42
14
  }
15
}

Results are ordered by routing fit, not by distance alone. Each entry carries the detail a client needs to present a choice to a member.

Step 4: Handle a failure

If the call fails, you receive a non-2xx status and a single, predictable error envelope:

1
{
2
  "statusCode": 401,
3
  "message": "Invalid or expired token",
4
  "error": "Unauthorized",
5
  "meta": {
6
    "requestId": "4a3b2c1d-5e6f-4890-9abc-def0fedcba98",
7
    "timestamp": "2026-05-15T10:30:45.000Z"
8
  }
9
}

A 401 means the token was missing, malformed, or expired. Obtain a fresh token and try again. Branch your error handling on the HTTP status code; see Errors for the response shape and its variations.

Next steps

• Find care for a member end to end in Find providers near a member.
• Walk a member through a pathway in Navigate a member to care.
• Browse every endpoint in the API Reference.