Carebit API

Availability Slots

Find slots that a Clinician can be booked into.

Endpoints

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

get/v1/availability_slotsList slots that a Clinician can be booked into
get/v1/next_availability_slotGet the next slot that a Clinician can be booked into

get/v1/availability_slots

List slots that a Clinician can be booked into

Returns times when the Clinician can be booked for the ServiceVariant. The results account for existing Bookings, unavailability, Service duration, Clinician buffers, and Room conflicts. They include Services that patients cannot book online and do not apply the Patient Portal's minimum booking notice.

Required API scopes: availability_slots.read

Parameters

clinician_id
query · required
string
The Clinician to find slots for.
service_variant_id
query · required
string
The ServiceVariant to find slots for. It determines the duration and booking rules.
start_date
query · required
string
The first date to include, in ISO 8601 format (YYYY-MM-DD).
end_date
query · required
string
The last date to include, in ISO 8601 format (YYYY-MM-DD). The inclusive range cannot exceed 45 days.

Responses

200

The slots that the Clinician can be booked into.

dataarrayrequired
- itemsobject
  A time when the Clinician can be booked for the requested ServiceVariant.
  - clinician_idstring · uuidrequired
    The identifier of the Clinician who can provide the slot.
  - end_timestring · date-timerequired
    An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
  - location_idstring | null · uuidrequired
    The identifier of the Location at which the slot is available.
  - objectanyrequired
    Always availability_slot.
  - resource_typestringrequired
    The type of resource that can be booked. Currently clinician; a future API version may also support room.
  - room_idstring | null · uuidrequired
    The identifier of the Room required by the ServiceVariant, when applicable.
  - service_idstring · uuidrequired
    The identifier of the Service provided during the slot.
  - service_variant_idstring · uuidrequired
    The identifier of the ServiceVariant provided during the slot.
  - start_timestring · 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":  … ]
     … }
      "object": "availability_slot",
      "clinician_id": "2b3c4d5e-6f70-489a-9bcd-ef0123456789",
      "end_time": "2026-01-01T10:00:00Z",
      "location_id": "3c4d5e6f-7081-49ab-acde-f0123456789a",
      "resource_type": "clinician",
      "room_id": "4d5e6f70-8192-4abc-bdef-0123456789ab",
      "service_id": "5e6f7081-92a3-4bcd-8ef0-123456789abc",
      "service_variant_id": "6f708192-a3b4-4cde-9f01-23456789abcd",
      "start_time": "2026-01-01T09:00:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": "eyJzdGFydF90aW1lIjoiMjAyNi0wMS0wMVQwOTowMDowMFoifQ",
  "url": "/v1/availability_slots"
}

400

A required parameter is missing, malformed, or outside the permitted 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 Clinician or ServiceVariant was not found in the Organization.

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

Example

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

429

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

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

Example

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

Request

curl -X GET "https://api.carebit.co/v1/availability_slots?clinician_id=8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c&service_variant_id=8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c&start_date=2026-01-01&end_date=2026-01-01" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN"

200 response

{
  "object": "list",
  "data":  … ]
     … }
      "object": "availability_slot",
      "clinician_id": "2b3c4d5e-6f70-489a-9bcd-ef0123456789",
      "end_time": "2026-01-01T10:00:00Z",
      "location_id": "3c4d5e6f-7081-49ab-acde-f0123456789a",
      "resource_type": "clinician",
      "room_id": "4d5e6f70-8192-4abc-bdef-0123456789ab",
      "service_id": "5e6f7081-92a3-4bcd-8ef0-123456789abc",
      "service_variant_id": "6f708192-a3b4-4cde-9f01-23456789abcd",
      "start_time": "2026-01-01T09:00:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": "eyJzdGFydF90aW1lIjoiMjAyNi0wMS0wMVQwOTowMDowMFoifQ",
  "url": "/v1/availability_slots"
}

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

get/v1/next_availability_slot

Get the next slot that a Clinician can be booked into

Finds the next time the Clinician can be booked for the ServiceVariant, searching up to 8 months ahead. The search includes Services that patients cannot book online and does not apply the Patient Portal's minimum booking notice.

Required API scopes: availability_slots.read

Parameters

clinician_id
query · required
string
The Clinician to find the next slot for.
service_variant_id
query · required
string
The ServiceVariant to find the next slot for. It determines the duration and booking rules.
from_date
query
string
The date from which to search, in ISO 8601 format (YYYY-MM-DD). Defaults to today.

Responses

200

The requested AvailabilitySlot.

clinician_idstring · uuidrequired
The identifier of the Clinician who can provide the slot.
end_timestring · date-timerequired
An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
location_idstring | null · uuidrequired
The identifier of the Location at which the slot is available.
objectanyrequired
Always availability_slot.
resource_typestringrequired
The type of resource that can be booked. Currently clinician; a future API version may also support room.
room_idstring | null · uuidrequired
The identifier of the Room required by the ServiceVariant, when applicable.
service_idstring · uuidrequired
The identifier of the Service provided during the slot.
service_variant_idstring · uuidrequired
The identifier of the ServiceVariant provided during the slot.
start_timestring · date-timerequired
An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.

Example

{
  "object": "availability_slot",
  "clinician_id": "2b3c4d5e-6f70-489a-9bcd-ef0123456789",
  "end_time": "2026-01-01T10:00:00Z",
  "location_id": "3c4d5e6f-7081-49ab-acde-f0123456789a",
  "resource_type": "clinician",
  "room_id": "4d5e6f70-8192-4abc-bdef-0123456789ab",
  "service_id": "5e6f7081-92a3-4bcd-8ef0-123456789abc",
  "service_variant_id": "6f708192-a3b4-4cde-9f01-23456789abcd",
  "start_time": "2026-01-01T09:00:00Z"
}

400

A required parameter is missing, malformed, or outside the permitted 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 Clinician or ServiceVariant was not found, or no slot was available within 8 months.

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/next_availability_slot?clinician_id=8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c&service_variant_id=8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN"

200 response

{
  "object": "availability_slot",
  "clinician_id": "2b3c4d5e-6f70-489a-9bcd-ef0123456789",
  "end_time": "2026-01-01T10:00:00Z",
  "location_id": "3c4d5e6f-7081-49ab-acde-f0123456789a",
  "resource_type": "clinician",
  "room_id": "4d5e6f70-8192-4abc-bdef-0123456789ab",
  "service_id": "5e6f7081-92a3-4bcd-8ef0-123456789abc",
  "service_variant_id": "6f708192-a3b4-4cde-9f01-23456789abcd",
  "start_time": "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"
  }
}

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.