get/v1/clinician_agenda

Get a Clinician's diary

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 · required
array
The Clinician whose diary to return. Pass exactly one identifier.
start_date
query · required
string
The first date to include, in ISO 8601 format (YYYY-MM-DD).
end_date
query · required
string
The last date to include, in ISO 8601 format (YYYY-MM-DD). The inclusive range cannot exceed 45 days.

Responses

200

Paginated list of ClinicianAgendaItem objects.

dataarrayrequired
- itemsobject
  A Booking, availability interval, or unavailability interval in a Clinician's diary.
  - bookingobject | nullrequired
    The Booking represented by this item, or null for availability and unavailability.
    - canceled_atstring | null · date-timerequired
      An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
    - cancellation_informationstring | nullrequired
      Additional notes recorded with the cancellation.
    - cancellation_reasonstring | nullrequired
      The reason the Booking was canceled. Required by Organizations that enforce cancellation reasons.
      Allowed values: abusive_behavior | booked_in_error | childcare_issues | clinician_annual_leave | clinician_emergency | clinician_schedule_change | colleague_unavailable | double_booked | duplicate_booking | equipment_issue | facility_unavailable | failed_to_pay_in_advance | family_emergency_illness | fear_or_anxiety | financial_concerns | financial_requirements_not_met | forgot_to_attend | insurance_company_not_permitted | insurance_coverage_issues | insurance_verification_failed | language_barrier | medication_interference | no_longer_required | no_response_to_recall | other | patient_deceased | patient_not_permitted | personal_emergency_illness | pre_booking_steps_not_completed | professional_discretion | referral_not_provided | relocated | rescheduled | scheduling_conflict | staff_issue | switched_to_another_clinician | symptoms_resolved | too_unwell | transportation_issues | unable_failed_to_prepare_for_booking | unknown | weather_conditions | wrong_clinician | wrong_location | wrong_service_type | null
    - cancellation_sourcestring | nullrequired
      Who canceled the Booking. API cancellations use api.
      Allowed values: api | app | automation | patient | staff_member | null
    - clinicianobject | nullrequired
      The clinician assigned to the booking.
      - created_atstring · date-timerequired
        An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
      - display_namestringrequired
        The formatted name of the clinician, including title.
      - emailstring | null · emailrequired
        The practice contact email of the clinician within the organization.
      - first_namestring | nullrequired
        The first name of the clinician.
      - idstring · uuidrequired
        The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
      - last_namestring | nullrequired
        The last name of the clinician.
      - linksobjectrequired
        URLs to related resources.
        bookingsstring · urirequired
        URL to list Bookings for this Clinician.
      - medical_specialtystring | nullrequired
        The medical specialty of the clinician, when recorded.
      - objectanyrequired
        Discriminator value emitted at object.
      - titlestring | nullrequired
        The professional or personal title of the clinician, when recorded, such as Dr.
      - updated_atstring · date-timerequired
        An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
    - created_atstring · date-timerequired
      An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
    - end_timestring | null · date-timerequired
      An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
    - idstring · uuidrequired
      The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
    - information_for_patientstring | nullrequired
      The sanitized HTML shown to the patient.
    - information_for_staff_membersstring | nullrequired
      The sanitized HTML shown only to staff members.
    - is_remotebooleanrequired
      Whether the Booking takes place remotely.
    - linksobjectrequired
      URLs to related resources.
      - clinicianstring | null · urirequired
        The full URL of a related resource.
      - invoicesstring · urirequired
        The full URL of a related resource.
      - lettersstring · urirequired
        The full URL of a related resource.
      - notesstring · urirequired
        The full URL of a related resource.
      - servicestring | null · urirequired
        The full URL of a related resource.
      - test_resultsstring · urirequired
        The full URL of a related resource.
    - locationobject | nullrequired
      The location where the booking takes place, or null for a remote booking.
      - address_line_1string | nullrequired
        The primary address line of the location.
      - address_line_2string | nullrequired
        The secondary address line of the location.
      - citystring | nullrequired
        The city in the location's postal address.
      - country_codestring | nullrequired
        The ISO 3166-1 alpha-2 country code for the postal address, such as GB for the United Kingdom.
      - countystring | nullrequired
        The county or region in the location's postal address.
      - created_atstring · date-timerequired
        An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
      - formatted_addressstring | nullrequired
        The single-line address of the location, formatted for display.
      - idstring · uuidrequired
        The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
      - namestring | nullrequired
        The display name of the location.
      - objectanyrequired
        Discriminator value emitted at object.
      - postcodestring | nullrequired
        The postal code of the location.
      - updated_atstring · date-timerequired
        An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
    - objectanyrequired
      Discriminator value emitted at object.
    - patientobject | nullrequired
      The patient attending the booking.
      - address_line_1string | nullrequired
        The primary address line of the Patient.
      - address_line_2string | nullrequired
        The secondary address line of the Patient.
      - citystring | nullrequired
        The city in the Patient's postal address.
      - country_codestring | nullrequired
        The ISO 3166-1 alpha-2 country code for the postal address, such as GB for the United Kingdom.
      - countystring | nullrequired
        The county or region in the Patient's postal address.
      - created_atstring · date-timerequired
        An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
      - creation_sourcestring | nullrequired
        How the Patient was created. api means the record was created through the Developer Platform. Read-only.
      - date_of_birthstring | null · daterequired
        The date of birth of the patient, in ISO 8601 format (YYYY-MM-DD).
      - display_namestring | nullrequired
        The formatted display name of the patient, including their title when recorded.
      - emailstring | null · emailrequired
        The email address of the patient, when recorded.
      - first_namestring | nullrequired
        The first name of the patient.
      - idstring · uuidrequired
        The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
      - is_opted_out_of_smsbooleanrequired
        Whether the Patient has opted out of SMS messages.
      - last_namestring | nullrequired
        The last name of the patient.
      - mobilestring | nullrequired
        The national mobile number without its country calling code.
      - mobile_country_dial_codestring | nullrequired
        The ISO 3166-1 alpha-2 country code used to derive the mobile calling code.
      - nhs_numberstring | nullrequired
        The 10-digit NHS number of the patient, without formatting.
      - objectanyrequired
        Discriminator value emitted at object.
      - phonestring | nullrequired
        The national phone number without its country calling code.
      - phone_country_dial_codestring | nullrequired
        The ISO 3166-1 alpha-2 country code used to derive the phone calling code.
      - phone_numberstring | nullrequired
        The Patient's preferred contact number, formatted for display and compatible with E.164.
      - postcodestring | nullrequired
        The postal code of the Patient.
      - sexstring | nullrequired
        The Patient's recorded sex.
        Allowed values: female | male | other | null
      - titlestring | nullrequired
        The personal title of the patient, when recorded.
      - updated_atstring · date-timerequired
        An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
    - payorobject | nullrequired
      The payor responsible for the booking's charges.
      - address_line_1string | nullrequired
        The primary address line of the payor.
      - address_line_2string | nullrequired
        The secondary address line of the payor.
      - alternative_payor_idstring | null · uuidrequired
        The identifier of the alternative payor responsible for payment, when payor_type is alternative_payor.
      - citystring | nullrequired
        The city in the payor's postal address.
      - country_codestring | nullrequired
        The ISO 3166-1 alpha-2 country code for the postal address, such as GB for the United Kingdom.
      - countystring | nullrequired
        The county or region in the payor's postal address.
      - created_atstring · date-timerequired
        An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
      - first_namestring | nullrequired
        The first name of the person responsible for payment, when applicable.
      - formatted_namestring | nullrequired
        The formatted name of the person responsible for payment.
      - formatted_payor_namestring | nullrequired
        The display name of the patient, insurer, or alternative payor responsible for payment.
      - idstring · uuidrequired
        The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
      - insurance_authorization_codestring | nullrequired
        The insurer's authorization code.
      - insurance_company_idstring | null · uuidrequired
        The identifier of the insurance company responsible for payment, when payor_type is insurance_company.
      - insurance_policy_end_datestring | null · daterequired
        The end date of the insurance policy, when recorded.
      - insurance_policy_numberstring | nullrequired
        The policy or membership number supplied by the insurer.
      - insurance_policy_start_datestring | null · daterequired
        The start date of the insurance policy, when recorded.
      - last_namestring | nullrequired
        The last name of the person responsible for payment, when applicable.
      - notesstring | nullrequired
        The additional payment or insurance information recorded for this payor.
      - objectanyrequired
        Discriminator value emitted at object.
      - payor_typestringrequired
        The type of party responsible for payment.
        Allowed values: patient | insurance_company | alternative_payor
      - postcodestring | nullrequired
        The postal code of the payor.
      - titlestring | nullrequired
        The personal title of the person responsible for payment, when applicable.
      - updated_atstring · date-timerequired
        An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
    - recall_due_datestring | null · daterequired
      The date the Patient is due to return, in ISO 8601 format (YYYY-MM-DD). Present on recall Bookings. Null on diary Bookings.
    - remote_methodstring | nullrequired
      The remote consultation method. native_video uses Carebit Video.
      Allowed values: native_video | null
    - serviceobject | nullrequired
      The service being provided during the booking.
      - created_atstring · date-timerequired
        An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
      - descriptionstring | nullrequired
        The description of the service shown to staff members and patients.
      - duration_minutesinteger | nullrequired
        The scheduled duration of the service, in minutes.
      - idstring · uuidrequired
        The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
      - is_bookable_onlinebooleanrequired
        Whether patients can book this service online in the Patient Portal.
      - namestringrequired
        The display name of the service.
      - objectanyrequired
        Discriminator value emitted at object.
      - service_variantsarrayrequired
        The bookable variants of this service.
        itemsobject
        clinician_idstring | null · uuidrequired
        The identifier of the clinician assigned to this service variant, when the variant is clinician-specific.
        currencystring | nullrequired
        The ISO 4217 currency code used for this service variant. Must be one of chf, eur, gbp, or usd.
        descriptionstring | nullrequired
        The description of this service variant.
        idstring · uuidrequired
        The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
        linksobjectrequired
        URLs to related resources.
        clinicianstring | null · urirequired
        The full URL of a related resource.
        locationstring | null · urirequired
        The full URL of a related resource.
        location_idstring | null · uuidrequired
        The identifier of the location assigned to this service variant, when the variant is location-specific.
        net_priceinteger | nullrequired
        The net price of this service variant, before tax, in the currency's minor units.
        permits_remote_bookingsbooleanrequired
        Whether this service variant can be used for remote bookings.
      - tax_rateobject | nullrequired
        The tax rate applied to this service. Null when no tax rate is set.
        descriptionstring | nullrequired
        The description of when the tax rate applies.
        idstring · uuidrequired
        The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
        percentagenumberrequired
        The tax rate as a percentage from 0 to 100.
        titlestringrequired
        The display name of the tax rate, for example 20% VAT.
      - updated_atstring · date-timerequired
        An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
    - service_variantsarrayrequired
      The service variants selected for the booking.
      - itemsobject
        clinician_idstring | null · uuidrequired
        The identifier of the clinician assigned to this service variant, when the variant is clinician-specific.
        currencystring | nullrequired
        The ISO 4217 currency code used for this service variant. Must be one of chf, eur, gbp, or usd.
        descriptionstring | nullrequired
        The description of this service variant.
        idstring · uuidrequired
        The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
        linksobjectrequired
        URLs to related resources.
        clinicianstring | null · urirequired
        The full URL of a related resource.
        locationstring | null · urirequired
        The full URL of a related resource.
        location_idstring | null · uuidrequired
        The identifier of the location assigned to this service variant, when the variant is location-specific.
        net_priceinteger | nullrequired
        The net price of this service variant, before tax, in the currency's minor units.
        permits_remote_bookingsbooleanrequired
        Whether this service variant can be used for remote bookings.
    - start_timestring | null · date-timerequired
      An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
    - statusstring | nullrequired
      The Booking's current status. Null while Carebit is creating the record.
      Allowed values: arrived | awaiting_payment | awaiting_recall | canceled | confirmed | did_not_attend | overdue_for_recall | prepared | recall_canceled | recall_expired | unconfirmed | null
    - updated_atstring · date-timerequired
      An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
  - clinician_idstring · uuidrequired
    The identifier of the Clinician whose diary contains the item.
  - end_timestring · date-timerequired
    An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
  - location_idstring | null · uuidrequired
    The Location associated with the item, when applicable.
  - objectanyrequired
    Always clinician_agenda_item.
  - room_idstring | null · uuidrequired
    The Room associated with the item, when applicable.
  - service_idsarrayrequired
    The Services associated with a Booking or availability interval.
    - itemsstring · uuid
  - service_variant_idsarrayrequired
    The ServiceVariants associated with a Booking or availability interval.
    - itemsstring · uuid
  - start_timestring · date-timerequired
    An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
  - typestringrequired
    The kind of diary item.
    Allowed values: availability | booking | unavailability
has_morebooleanrequired
Whether another page is available after next_cursor.
next_cursorstring | nullrequired
The value to pass as cursor for the next page. Null on the last page.
objectanyrequired
Always list.
urlstringrequired
The API path that returned this list.

Example

{
  "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"
}

400

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

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

{
  "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"
  }
}

401

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

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

{
  "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"
  }
}

403

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

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

{
  "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"
  }
}

404

The Clinician was not found in the Organization.

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

{
  "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"
  }
}

429

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

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

{
  "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"
  }
}

Request

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"

200 response

{
  "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"
}

400 response

{
  "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"
  }
}

401 response

{
  "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"
  }
}

403 response

{
  "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"
  }
}

404 response

{
  "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"
  }
}

429 response

{
  "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"
  }
}

Endpoints

Parameters

Responses