Pagination and filtering

List endpoints in /v1 return a JSON list envelope. Pagination fields are at the top level alongside the data array.

{
  "object": "list",
  "url": "https://api.carebit.co/v1/bookings",
  "data": [
    {
      "id": "92a3b4c5-d6e7-4f01-8234-56789abcdef0",
      "object": "booking",
      "...": "..."
    }
  ],
  "has_more": true,
  "next_cursor": "eyJpZCI6ImJrZ18uLi4ifQ"
}

Requesting the next page

Send the value from next_cursor as the cursor query parameter on the next request, together with the original filters. Diary Booking queries require start_time_from and start_time_to on every page, including did_not_attend. Recall-status lists omit that window; keep status on every page instead. When there are no more results, has_more is false and next_cursor is null.

curl "https://api.carebit.co/v1/bookings?start_time_from=2026-08-01T00:00:00Z&start_time_to=2026-08-08T00:00:00Z&cursor=$NEXT_CURSOR" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN"

Page size

Use limit to change the page size. The default is 25 and the maximum is 100. Requests with a larger limit receive a 422 validation error.

curl "https://api.carebit.co/v1/bookings?start_time_from=2026-08-01T00:00:00Z&start_time_to=2026-08-08T00:00:00Z&limit=100" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN"

Filtering

Every list endpoint documents its supported filters on the corresponding API reference page. Filters are query parameters. Date filters are ISO-8601 timestamps in UTC. Enum filters use the values documented by the corresponding API schema.

Combine filters with separate query parameters joined by &. Combining filters narrows the result set because the filters are ANDed.

Recall Bookings (awaiting_recall, overdue_for_recall, recall_expired, and recall_canceled) have no diary start_time. List them by status without start_time_from or start_time_to. Results are ordered by recall_due_date. did_not_attend still requires the date window because those Bookings keep the missed appointment time.

Lists (GET /v1/lists) accept an optional exact name filter, case-insensitively. Results are ordered by name.

GET /v1/organizations searches other Carebit Organizations so you can attach a PatientConnection, such as a GP practice. Provide name or postcode (at least two characters). Optionally filter with organization_type, for example gp_practice. The response uses the Organization object. Email, subdomain, phone, currency, and time_zone are null so a search cannot harvest contact details. This endpoint does not create Organizations.

GET /v1/invoices and GET /v1/payments return every matching record in the Organization. Filter invoices with booking_id or patient_id, and payments with patient_id, paid_at_from, and paid_at_to.

curl "https://api.carebit.co/v1/bookings?status=overdue_for_recall" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN"

Order

Every list endpoint documents its default sort. Unless stated otherwise, results are ordered by created_at descending. Do not depend on an implicit order across pages if you are filtering by a mutable field.