Carebit API

Bookings

Appointments booked for Patients.

Endpoints

Scroll this page to read every Bookings endpoint, or jump to one below.

get/v1/bookingsList Bookings
post/v1/bookingsCreate a Booking
post/v1/bookings/:booking_id/cancellationsCancel a Booking
get/v1/bookings/:idGet a Booking
patch/v1/bookings/:idUpdate a Booking

get/v1/bookings

List 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 · enum: arrived | awaiting_payment | awaiting_recall | canceled | confirmed | did_not_attend | overdue_for_recall | prepared | recall_canceled | recall_expired | unconfirmed
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.

Responses

200

Paginated list of Booking objects.

dataarrayrequired
- itemsobject
  - 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.
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":  … ]
     … }
      "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"
}

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.

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 supplied Patient was not found among the Organization's active Patient connections.

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/bookings?start_time_from=2026-01-01T09:00:00Z&start_time_to=2026-01-31T09:00:00Z" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN"

200 response

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

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

post/v1/bookings

Create a Booking

Required API scopes: bookings.create

Parameters

Idempotency-Key
header · required
string
Client-generated idempotency key. Required for every POST/PATCH write. Replay of the same key with the same body returns the stored response with an Idempotency-Replayed: true header. Same key + different body returns 422 idempotency_key_reused. A duplicate that arrives while the first request is still in flight returns 409 idempotency_conflict with Retry-After: 1.

Request body

application/json

clinician_idstring | null · uuid
The identifier of the clinician assigned to the booking, or null when no clinician is assigned.
end_timestring | null · date-time
An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
information_for_patientstring | null
The information shown to the patient before the booking.
information_for_staff_membersstring | null
The internal information shown only to staff members.
is_remoteboolean
Whether the Booking takes place remotely.
location_idstring | null · uuid
The identifier of the location where the booking takes place, or null for a remote booking.
patient_idstring · uuidrequired
The identifier of the patient attending the booking.
payor_idstring | null · uuid
The identifier of the payor responsible for the booking's charges, when different from the patient.
remote_methodstring | null
The remote consultation method. native_video requires is_remote to be true.
Allowed values: native_video | null
room_idstring | null · uuid
The identifier of the room assigned to the booking, when applicable.
service_idstring · uuidrequired
The identifier of the service being provided during the booking.
service_variant_idstring · uuidrequired
The identifier of the service variant selected for the booking.
start_timestring · date-timerequired
The ISO 8601 UTC time at which the booking starts.
statusstring | null
The status to assign to the Booking.
Allowed values: arrived | confirmed | did_not_attend | unconfirmed | null

Responses

201

Booking created.

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.

Example

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

400

The Idempotency-Key header is missing (idempotency_key_required) or exceeds 255 characters (idempotency_key_too_long).

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

A referenced resource was not found in your 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"
  }
}

409

A concurrent request holds the idempotency lease (idempotency_conflict). 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"
  }
}

422

The Idempotency-Key was previously used with a different request body (idempotency_key_reused), or the request body failed validation.

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 POST "https://api.carebit.co/v1/bookings" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "clinician_id": "00000000-0000-4000-8000-000000000002",
  "end_time": "2026-01-01T10:30:00Z",
  "location_id": "00000000-0000-4000-8000-000000000003",
  "patient_id": "00000000-0000-4000-8000-000000000004",
  "service_id": "00000000-0000-4000-8000-000000000005",
  "service_variant_id": "00000000-0000-4000-8000-000000000006",
  "start_time": "2026-01-01T10:00:00Z",
  "status": "unconfirmed"
}'

201 response

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

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

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

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

post/v1/bookings/:booking_id/cancellations

Cancel a Booking

Cancels a Booking through the same path as a StaffMember cancellation. Requires bookings.cancel; bookings.update does not grant this endpoint. cancellation_reason is required when the Organization requires cancellation reasons. API cancellations use cancellation_source api and automatically apply attendance penalty invoices, except when the Booking was awaiting payment. Canceling a diary Booking emits booking.canceled. Canceling a recall Booking sets status to recall_canceled and does not emit that event.

Required API scopes: bookings.cancel

Parameters

booking_id
path · required
string
-
Idempotency-Key
header · required
string
Client-generated idempotency key. Required for every POST/PATCH write. Replay of the same key with the same body returns the stored response with an Idempotency-Replayed: true header. Same key + different body returns 422 idempotency_key_reused. A duplicate that arrives while the first request is still in flight returns 409 idempotency_conflict with Retry-After: 1.

Request body

application/json

cancellation_informationstring | null
Additional notes recorded with the cancellation.
cancellation_reasonstring | null
The reason the Booking is being canceled. Required when the Organization requires 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

Responses

200

The requested Booking.

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.

Example

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

400

The Idempotency-Key header is missing (idempotency_key_required) or exceeds 255 characters (idempotency_key_too_long).

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

Error response.

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

409

A concurrent request holds the idempotency lease (idempotency_conflict). 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"
  }
}

422

The Booking cannot be canceled from its current status, or cancellation_reason is missing or invalid.

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 POST "https://api.carebit.co/v1/bookings/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c/cancellations" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "cancellation_information": "The Patient asked to cancel by phone.",
  "cancellation_reason": "booked_in_error"
}'

200 response

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

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

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

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

get/v1/bookings/:id

Get a Booking

Required API scopes: bookings.read

Parameters

id
path · required
string
-

Responses

200

The requested Booking.

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.

Example

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

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

Error response.

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/bookings/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN"

200 response

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

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

patch/v1/bookings/:id

Update a Booking

Reschedule, confirm, arrive, mark as did not attend, or update Booking details. To cancel a Booking, use POST /v1/bookings/{booking_id}/cancellations, which requires bookings.cancel.

Required API scopes: bookings.update

Parameters

id
path · required
string
-
Idempotency-Key
header · required
string
Client-generated idempotency key. Required for every POST/PATCH write. Replay of the same key with the same body returns the stored response with an Idempotency-Replayed: true header. Same key + different body returns 422 idempotency_key_reused. A duplicate that arrives while the first request is still in flight returns 409 idempotency_conflict with Retry-After: 1.

Request body

application/json

clinician_idstring | null · uuid
The identifier of the clinician assigned to the booking, or null when no clinician is assigned.
end_timestring | null · date-time
An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
information_for_patientstring | null
The information shown to the patient before the booking.
information_for_staff_membersstring | null
The internal information shown only to staff members.
is_remoteboolean
Whether the Booking takes place remotely.
location_idstring | null · uuid
The identifier of the location where the booking takes place, or null for a remote booking.
patient_idstring · uuid
The identifier of the patient attending the booking.
payor_idstring | null · uuid
The identifier of the payor responsible for the booking's charges, when different from the patient.
remote_methodstring | null
The remote consultation method. native_video requires is_remote to be true.
Allowed values: native_video | null
room_idstring | null · uuid
The identifier of the room assigned to the booking, when applicable.
service_idstring · uuid
The identifier of the service being provided during the booking.
service_variant_idstring · uuid
The identifier of the service variant selected for the booking.
start_timestring · date-time
The ISO 8601 UTC time at which the booking starts.
statusstring | null
The status to assign to the Booking.
Allowed values: arrived | confirmed | did_not_attend | unconfirmed | null

Responses

200

The requested Booking.

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.

Example

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

400

The Idempotency-Key header is missing (idempotency_key_required) or exceeds 255 characters (idempotency_key_too_long).

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

Error response.

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

409

A concurrent request holds the idempotency lease (idempotency_conflict). 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"
  }
}

422

The Idempotency-Key was previously used with a different request body (idempotency_key_reused), or the request body failed validation.

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 PATCH "https://api.carebit.co/v1/bookings/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "confirmed"
}'

200 response

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

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

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

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

Prefer plain text? Append ?format=md or send Accept: text/markdown to receive this page as raw Markdown.