# Get a Clinician's diary

`GET /v1/clinician_agenda`

Returns the Clinician's Bookings, availability, and unavailability in time order. Bookings include staff and Patient details, so show only information appropriate for your users. Availability shows the diary schedule, not times that can necessarily be booked. Use the Availability Slots endpoints before creating a Booking. Unavailability labels and notes are not included.

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

## Parameters

- `clinician_ids[]` (query, `array`) (required) - The Clinician whose diary to return. Pass exactly one identifier.
- `start_date` (query, `string`) (required) - The first date to include, in ISO 8601 format (YYYY-MM-DD).
- `end_date` (query, `string`) (required) - The last date to include, in ISO 8601 format (YYYY-MM-DD). The inclusive range cannot exceed 45 days.

## Response `200`

Paginated list of `ClinicianAgendaItem` objects.

- `any`

### Example

```json
{
  "object": "list",
  "data": [
    {
      "object": "clinician_agenda_item",
      "booking": {
        "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"
      },
      "clinician_id": "2b3c4d5e-6f70-489a-9bcd-ef0123456789",
      "end_time": "2026-01-01T10:00:00Z",
      "location_id": "3c4d5e6f-7081-49ab-acde-f0123456789a",
      "room_id": "4d5e6f70-8192-4abc-bdef-0123456789ab",
      "service_ids": [
        "5e6f7081-92a3-4bcd-8ef0-123456789abc"
      ],
      "service_variant_ids": [
        "6f708192-a3b4-4cde-9f01-23456789abcd"
      ],
      "start_time": "2026-01-01T09:00:00Z",
      "type": "availability"
    }
  ],
  "has_more": false,
  "next_cursor": "eyJzdGFydF90aW1lIjoiMjAyNi0wMS0wMVQwOTowMDowMFoifQ",
  "url": "/v1/clinician_agenda"
}
```

## Response `400`

The Clinician list or date range is missing, malformed, or outside the permitted limits.

- `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 Clinician was not found in the Organization.

- `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/clinician_agenda?clinician_ids%5B%5D=8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c&start_date=2026-01-01&end_date=2026-01-01" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN"
```

```javascript
const response = await fetch("https://api.carebit.co/v1/clinician_agenda?clinician_ids%5B%5D=8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c&start_date=2026-01-01&end_date=2026-01-01", {
  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/clinician_agenda?clinician_ids%5B%5D=8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c&start_date=2026-01-01&end_date=2026-01-01",
    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/clinician_agenda?clinician_ids%5B%5D=8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c&start_date=2026-01-01&end_date=2026-01-01",
  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/clinician_agenda?clinician_ids%5B%5D=8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c&start_date=2026-01-01&end_date=2026-01-01", [
    "headers" => [
      "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```