> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.cail.health/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.cail.health/_mcp/server.

# 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](/api-reference/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:

```bash
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.

```bash
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](/api-reference/versioning).

## Step 3: Read the response

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

```json
{
  "data": [
    {
      "providerId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "name": "St Thomas' Hospital",
      "distanceMetres": 1820,
      "availabilityStatus": "open_now"
    }
  ],
  "meta": {
    "requestId": "4a3b2c1d-5e6f-4890-9abc-def0fedcba98",
    "timestamp": "2026-05-13T14:21:00.000Z",
    "durationMs": 42
  }
}
```

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:

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

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](/api-reference/errors) for the response shape and its variations.

## Next steps

* Find care for a member end to end in [Find providers near a member](/guides/find-providers-near-a-member).
* Walk a member through a pathway in [Navigate a member to care](/guides/navigate-a-member-to-care).
* Browse every endpoint in the [API Reference](/api-reference/introduction).