# List Bookings

`GET /v1/bookings`

Lists Bookings in the authenticated Organization. Diary queries require `start_time_from` and `start_time_to`, cannot exceed 30 days (90 days when `patient_id` is supplied), and are ordered by `start_time`. When `status` is a recall status (`awaiting_recall`, `overdue_for_recall`, `recall_expired`, or `recall_canceled`), omit the date window. Recall Bookings have no diary `start_time`, so the window is not applied; results are ordered by `recall_due_date`. `did_not_attend` still requires the date window.

**Required API scopes:** `bookings.read`

## Parameters

- `start_time_from` (query, `string`) - Inclusive lower bound for `start_time` in UTC ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ). Required for diary queries, including `did_not_attend`. Omit this parameter when `status` is a recall status.
- `start_time_to` (query, `string`) - Inclusive upper bound for `start_time` in UTC ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ). Required with `start_time_from` for diary queries, including `did_not_attend`. The range cannot exceed 30 days, or 90 days when `patient_id` is supplied. Omit this parameter when `status` is a recall status.
- `clinician_id` (query, `string`)
- `patient_id` (query, `string`) - Filter by a Patient with an active connection to the Organization. A valid connected Patient identifier permits a date range of up to 90 days.
- `status` (query, `string`) - Filter by Booking status. When `status` is `awaiting_recall`, `overdue_for_recall`, `recall_expired`, or `recall_canceled`, omit `start_time_from` and `start_time_to`. Those Bookings have no diary `start_time`. `did_not_attend` still requires the date window.
- `updated_since` (query, `string`)
- `limit` (query, `integer`) - The maximum number of items to return. Defaults to `25`; the maximum is `100`.
- `starting_after` (query, `string`) - Return items after this resource ID. You cannot use this with `cursor`.
- `cursor` (query, `string`) - The `next_cursor` value from the previous page. You cannot use this with `starting_after`.

## Response `200`

Paginated list of `Booking` objects.

- `any`

### Example

```json
{
  "object": "list",
  "data": [
    {
      "id": "92a3b4c5-d6e7-4f01-8234-56789abcdef0",
      "object": "booking",
      "canceled_at": "2026-01-01T09:00:00Z",
      "cancellation_information": "The Patient asked to cancel by phone.",
      "cancellation_reason": "abusive_behavior",
      "cancellation_source": "api",
      "clinician": {
        "id": "2b3c4d5e-6f70-489a-9bcd-ef0123456789",
        "object": "clinician",
        "created_at": "2026-01-01T09:00:00Z",
        "display_name": "Dr Alex Morgan",
        "email": "alex.morgan@example.com",
        "first_name": "Alex",
        "last_name": "Morgan",
        "links": {
          "bookings": "https://api.carebit.co/v1/bookings?clinician_id=2b3c4d5e-6f70-489a-9bcd-ef0123456789"
        },
        "medical_specialty": "Cardiology",
        "title": "Dr",
        "updated_at": "2026-01-01T09:00:00Z"
      },
      "created_at": "2026-01-01T09:00:00Z",
      "end_time": "2026-01-01T10:00:00Z",
      "information_for_patient": "<p>Please arrive 10 minutes before your appointment.</p>",
      "information_for_staff_members": "<p>The Patient has requested step-free access.</p>",
      "is_remote": false,
      "links": {
        "clinician": "https://api.carebit.co/v1/clinicians/2b3c4d5e-6f70-489a-9bcd-ef0123456789",
        "invoices": "https://api.carebit.co/v1/invoices?booking_id=92a3b4c5-d6e7-4f01-8234-56789abcdef0",
        "letters": "https://api.carebit.co/v1/letters?booking_id=92a3b4c5-d6e7-4f01-8234-56789abcdef0",
        "notes": "https://api.carebit.co/v1/notes?booking_id=92a3b4c5-d6e7-4f01-8234-56789abcdef0",
        "service": "https://api.carebit.co/v1/services/5e6f7081-92a3-4bcd-8ef0-123456789abc",
        "test_results": "https://api.carebit.co/v1/test_results?booking_id=92a3b4c5-d6e7-4f01-8234-56789abcdef0"
      },
      "location": {
        "id": "3c4d5e6f-7081-49ab-acde-f0123456789a",
        "object": "location",
        "address_line_1": "10 Harley Street",
        "address_line_2": "Marylebone",
        "city": "London",
        "country_code": "GB",
        "county": "Greater London",
        "created_at": "2026-01-01T09:00:00Z",
        "formatted_address": "10 Harley Street, Marylebone, London, W1G 9PF",
        "name": "Harley Street Clinic",
        "postcode": "W1G 9PF",
        "updated_at": "2026-01-01T09:00:00Z"
      },
      "patient": {
        "id": "1a2b3c4d-5e6f-4789-8abc-def012345678",
        "object": "patient",
        "address_line_1": "10 Harley Street",
        "address_line_2": "Marylebone",
        "city": "London",
        "country_code": "GB",
        "county": "Greater London",
        "created_at": "2026-01-01T09:00:00Z",
        "creation_source": "api",
        "date_of_birth": "1990-01-01",
        "display_name": "Dr Alex Morgan",
        "email": "alex.morgan@example.com",
        "first_name": "Alex",
        "is_opted_out_of_sms": false,
        "last_name": "Morgan",
        "mobile": "7700900123",
        "mobile_country_dial_code": "GB",
        "nhs_number": "485 777 3456",
        "phone": "2071234567",
        "phone_country_dial_code": "GB",
        "phone_number": "+44 7700 900123",
        "postcode": "W1G 9PF",
        "sex": "female",
        "title": "Dr",
        "updated_at": "2026-01-01T09:00:00Z"
      },
      "payor": {
        "id": "708192a3-b4c5-4def-8012-3456789abcde",
        "object": "payor",
        "address_line_1": "10 Harley Street",
        "address_line_2": "Marylebone",
        "alternative_payor_id": null,
        "city": "London",
        "country_code": "GB",
        "county": "Greater London",
        "created_at": "2026-01-01T09:00:00Z",
        "first_name": "Alex",
        "formatted_name": "Dr Alex Morgan",
        "formatted_payor_name": "Bupa",
        "insurance_authorization_code": "AUTH123",
        "insurance_company_id": "855e25b0-b138-48da-86ea-15162ce81f14",
        "insurance_policy_end_date": "2026-12-31",
        "insurance_policy_number": "POLICY123",
        "insurance_policy_start_date": "2026-01-01",
        "last_name": "Morgan",
        "notes": "Please confirm the appointment by email.",
        "payor_type": "insurance_company",
        "postcode": "W1G 9PF",
        "title": "Dr",
        "updated_at": "2026-01-01T09:00:00Z"
      },
      "recall_due_date": "2026-01-01",
      "remote_method": null,
      "service": {
        "id": "5e6f7081-92a3-4bcd-8ef0-123456789abc",
        "object": "service",
        "created_at": "2026-01-01T09:00:00Z",
        "description": "An initial consultation at the Harley Street Clinic.",
        "duration_minutes": 30,
        "is_bookable_online": true,
        "name": "Initial consultation",
        "service_variants": [
          {
            "id": "6f708192-a3b4-4cde-9f01-23456789abcd",
            "clinician_id": "2b3c4d5e-6f70-489a-9bcd-ef0123456789",
            "currency": "GBP",
            "description": "An initial consultation at the Harley Street Clinic.",
            "links": {
              "clinician": "https://api.carebit.co/v1/clinicians/2b3c4d5e-6f70-489a-9bcd-ef0123456789",
              "location": "https://api.carebit.co/v1/locations/3c4d5e6f-7081-49ab-acde-f0123456789a"
            },
            "location_id": "3c4d5e6f-7081-49ab-acde-f0123456789a",
            "net_price": 1,
            "permits_remote_bookings": true
          }
        ],
        "tax_rate": {
          "id": "211b60c7-ec1b-41b4-8a29-e855209bc694",
          "description": "An initial consultation at the Harley Street Clinic.",
          "percentage": 20,
          "title": "VAT"
        },
        "updated_at": "2026-01-01T09:00:00Z"
      },
      "service_variants": [
        {
          "id": "6f708192-a3b4-4cde-9f01-23456789abcd",
          "clinician_id": "2b3c4d5e-6f70-489a-9bcd-ef0123456789",
          "currency": "GBP",
          "description": "An initial consultation at the Harley Street Clinic.",
          "links": {
            "clinician": "https://api.carebit.co/v1/clinicians/2b3c4d5e-6f70-489a-9bcd-ef0123456789",
            "location": "https://api.carebit.co/v1/locations/3c4d5e6f-7081-49ab-acde-f0123456789a"
          },
          "location_id": "3c4d5e6f-7081-49ab-acde-f0123456789a",
          "net_price": 1,
          "permits_remote_bookings": true
        }
      ],
      "start_time": "2026-01-01T09:00:00Z",
      "status": "arrived",
      "updated_at": "2026-01-01T09:00:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": "eyJzdGFydF90aW1lIjoiMjAyNi0wMS0wMVQwOTowMDowMFoifQ",
  "url": "/v1/bookings"
}
```

## Response `400`

A diary date range parameter is missing, malformed, or exceeds the permitted 30-day or Patient-filtered 90-day span. Recall-status lists do not require a date range.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `401`

The access token is missing, invalid, expired, or revoked.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `403`

The access token lacks the required scope, or the project is disabled.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `404`

The supplied Patient was not found among the Organization's active Patient connections.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `429`

Too many requests. Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Code samples

```bash
curl -X GET "https://api.carebit.co/v1/bookings?start_time_from=2026-01-01T09:00:00Z&start_time_to=2026-01-31T09:00:00Z" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN"
```

```javascript
const response = await fetch("https://api.carebit.co/v1/bookings?start_time_from=2026-01-01T09:00:00Z&start_time_to=2026-01-31T09:00:00Z", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
  },
});

if (!response.ok) {
  throw new Error(`Carebit API error: ${response.status}`);
}

const data = await response.json();
```

```python
import os
import requests

response = requests.get(
    "https://api.carebit.co/v1/bookings?start_time_from=2026-01-01T09:00:00Z&start_time_to=2026-01-31T09:00:00Z",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
    }
)
response.raise_for_status()
data = response.json()
```

```ruby
require "httparty"

response = HTTParty.get(
  "https://api.carebit.co/v1/bookings?start_time_from=2026-01-01T09:00:00Z&start_time_to=2026-01-31T09:00:00Z",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}"
  }
)
raise "Carebit API error: #{response.code}" unless response.success?
data = response.parsed_response
```

```php
<?php

$client = new GuzzleHttp\Client();

$response = $client->get("https://api.carebit.co/v1/bookings?start_time_from=2026-01-01T09:00:00Z&start_time_to=2026-01-31T09:00:00Z", [
    "headers" => [
      "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```