# Changelog and versioning The Developer Platform is path-versioned. Every URL starts with `/v1`. A new major version only ships when a change cannot be made additively. ## Guarantees inside `/v1` - New fields and endpoints may be added at any time. Your integration must ignore unknown fields. - Existing fields will not change type or meaning. - Enum values will only be added, never removed inside `v1`. New values may appear at any time - handle unknown values gracefully. - Deprecations are announced in advance in this changelog and on the relevant reference page. ## Webhook versioning The webhook envelope carries an `api_version` field (currently `"v1"`). The same additive rules apply to webhook payloads. If Carebit introduces another version, endpoint-level version selection and migration guidance will be added before that version is available. ## Change log ### 15 September 2026 - `GET /v1/patients/{patient_id}/connections` lists PatientConnections this Organization already has ResourcePermissions for (unlocked connections). Locked connections, including a GP that has not been unlocked in Carebit, are omitted. Create and update use `patient_connections.create` and `patient_connections.update`. Create connects the Patient to an existing Organization, such as a GP practice. If the Patient is already connected, Carebit returns that PatientConnection and grants this Organization access. This does not create Organizations. Update may change only this Organization's PatientConnection, not an unlocked GP or other Organization's connection. - `GET /v1/organizations` searches active Organizations by `name` or `postcode`. Optionally filter with `organization_type`, for example `gp_practice`. At least one of `name` or `postcode` is required. Requires `organization.search`. Email, subdomain, phone, currency, and time_zone are null so a search cannot harvest contact details. Creating Organizations through the API is not permitted. - `POST /v1/patients/{patient_id}/payors` accepts `set_as_default_payor`. When `true`, Carebit creates the Payor and selects it on this Organization's PatientConnection in the same request. ### 13 September 2026 - `GET /v1/token` confirms the current access token and returns the Organization, project, granted scopes, and expiry. Any valid token can call it. It does not require `organization.read`. The response does not include the token secret. - `GET /v1/invoices` no longer requires `booking_id` or `patient_id`. Those filters remain optional. - `GET /v1/payments` lists Payments. Filter optionally by `patient_id` and by `paid_at_from` / `paid_at_to`. Each Payment includes `internal_notes`, `invoice_id`, `patient_id`, and nested `refunds`. Requires `payments.read`. - Lead objects include `internal_notes`, `referral_notes`, and `referral_source`. These fields are writable on create and update so an API-created enquiry can match one entered in Carebit. `internal_notes` is the Notes box next to presenting problem. `referral_source` uses the same values as the Carebit referral source list, such as `gp_practice` or `website`. ### 12 September 2026 - Diary Booking lists accept a `start_time` window of up to 30 days (90 days when filtering by `patient_id`). - `GET /v1/bookings` no longer requires `start_time_from` and `start_time_to` when `status` is a recall status (`awaiting_recall`, `overdue_for_recall`, `recall_expired`, or `recall_canceled`). Those lists are ordered by `recall_due_date`. `did_not_attend` and other diary queries still require the date window. - Booking objects include `recall_due_date`. - Lists are available at `/v1/lists`, including create, update, and delete. Membership is nested at `/v1/lists/{list_id}/members`. Add a member with `member_type` and `member_id`; currently `member_type` accepts only `patient`. Nested List objects on `list.member_added` and `list.member_removed` now match the List resource, including timestamps, notes, color, Clinician, and links. - `POST /v1/bookings/{booking_id}/cancellations` cancels a Booking. It requires `bookings.cancel`, which is independent of `bookings.update`. `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. Booking objects include `canceled_at`, `cancellation_reason`, `cancellation_information`, and `cancellation_source`. - `refund.created` is emitted when a Refund is created. Entries appear here as the platform grows. The published OpenAPI document at `/openapi.json` is the source of truth for the current surface.