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 October 2026

You can use AI agents as part of a private integration that your organisation deploys, controls and operates. Do not give custom-integration credentials to third-party products.
Carebit does not email organisation staff when a PatientConnectionRequest is created. The 202 payload includes links.dashboard, which opens the Patient connection requests list in Carebit. Send that URL if you want someone to review pending requests.

6 October 2026

Transmission objects include an embedded message_template when Carebit can resolve the MessageTemplate from the Workflow or Booking that sent the Transmission. Recipient (to), date sent (sent_at), and delivery status were already on the object.

25 September 2026

A Patient created with an email address gets a Patient Portal account for that email. Carebit does not send the portal welcome email. Adding an email later with PATCH /v1/patients/{id} does the same when the Patient does not already have a portal account.
Letters, BookingForms, Photos, and TestResults accept assigned_staff_member_id, created_at, and sent_at on create. Photos and BookingForms also accept them on update. Responses include assigned_staff_member and sent_at. Setting sent_at marks the document complete. Omit created_at to use the current time.
GET /v1/transmissions accepts patient_id, document_id, invoice_id, quote_id, booking_id, digital_form_response_id, and resource_type. Supply at least one. A patient_id filter with no other filter returns every Transmission for that Patient. resource_type=digital_form_response still limits the list to DigitalFormResponse emails.
POST /v1/bookings and PATCH /v1/bookings/{id} accept notify_patient. Omit it to keep the default, which is true. Confirmation, update, and cancellation emails use this value once the Booking is confirmed.

24 September 2026

An unconnected match from POST /v1/patients always creates a PatientConnectionRequest and returns 202. Carebit never connects it as part of the create call, even when a supplied contact field agrees. The previous 409 patient_match_requires_review response is no longer used.
GET /v1/patient_connection_requests and GET /v1/patient_connection_requests/{id} list and retrieve those requests. Requires patients.read. Pending payloads omit patient_id and expose only the strongest candidate. Only matching demographic field names are disclosed; contact and NHS number classifications remain private.
Any project in the organisation can use POST /v1/patient_connection_requests/{id}/actions with connect_existing_patient, create_new_patient, or deny. If you are ready to connect the recommended Patient immediately, POST connect_existing_patient; Carebit connects the strongest current recommendation. Acting uses patients.create; there is no separate grant scope.
Webhook events patient_connection_request.created, patient_connection_request.granted, patient_connection_request.denied, and patient_connection_request.expired are required system events. Carebit always delivers them to every enabled webhook endpoint on the project that created the request. Other projects do not receive them. You do not subscribe to them, and they do not appear in the subscription picker. Connecting an existing candidate or creating a separate Patient also emits patient_connection.created.
See Creating and connecting Patients.

22 September 2026

GET /v1/lead_form_responses lists the forms a Lead submitted, newest first. Requires leads.read and Carebit Pro. lead_id is required. Lost Leads are included. Enquiries a staff member recorded by hand are not returned, because they have no form.
GET /v1/lead_form_responses/{id} returns one submission with its questions and answers, the referral data captured with it, and its marketing attribution in tracking. Match answers on field_name rather than on label, which an Organization can reword at any time. A multiselect question returns its selected option values in values and null in value. Layout blocks, hidden fields, and the form's bot trap are omitted. A file upload question is omitted too; the uploaded files appear in the Lead's attachments.
Lead objects include form_responses, a summary of each submission, oldest first, with a url to the full response. Lead objects also include referred_by_clinician_id and referred_by_organization_id, taken from the Lead's first submission that identified one. Per-submission values are on the LeadFormResponse.
Webhook event lead.form_response_submitted fires for every submission, including the one that creates the Lead. A repeat submission from someone already in the pipeline emits only this event, because reusing an existing Lead does not change it and so does not emit lead.updated.
POST /v1/patients and PATCH /v1/patients/{id} accept nhs_number. Send a 10-digit NHS number without spaces or other formatting. The number must pass the NHS check digit. Set it to null to clear it.

21 September 2026

POST /v1/quotes creates a draft Quote. Requires quotes.create. Supply patient_id for a Patient Quote, or omit it and supply alternative_payor_id to quote another organisation. Supply booking_ids to generate line items from Bookings, or line_items with title and unit_price in minor currency units. Bookings require a Patient. Sending, accepting, and converting remain in the Carebit staff and Patient Portal interfaces.
Webhook events quote.created and quote.accepted are now available. quote.created fires when a Quote is first persisted. quote.accepted fires after acceptance creates the linked Invoice. The accepted Quote object includes invoice_id and links.invoice.
GET /v1/invoices/{id} returns one Invoice. Requires invoices.read. Use this to follow Invoice links on Quote objects.

18 September 2026

GET /v1/patients/{id}/payment_methods lists stored card PaymentMethods for a connected Patient. Requires payment_methods.read. Only PaymentMethods that the Organization has ResourcePermissions to access are returned. Expired cards are included and marked with is_expired.
POST /v1/payments creates a card Payment for a connected Patient. Requires payments.create. Supply amount in minor currency units and payment_method_type. Supply payment_method_id to charge a specific stored card from the Patient's PaymentMethods list. When payment_method_id is omitted, Carebit charges the Patient's default stored card. If the Patient has no stored card, the request fails. Send the Patient to patient_portal_add_payment_method_url on the Patient object so they can add a card in the Patient Portal. If Stripe requires extra authentication, Carebit emails the Patient a Patient Portal link to complete it. Other payment method types are not accepted.
Payment objects include payment_method_id when a stored card was charged.
Patient objects include patient_portal_add_payment_method_url. This is the Patient Portal URL where the Patient can add a stored card PaymentMethod for the Organization. Use this URL to collect a card before calling POST /v1/payments.
POST /v1/payments/{id}/refunds creates a Refund against a card Payment. Requires refunds.create. Supply amount in minor currency units and reason. Carebit returns the funds to the original card through Stripe. The Refund starts as processing. Other payment method types are not accepted.
Webhook event refund.failed fires when Stripe rejects a card or Klarna Refund to the original payment method. The Refund object includes error and next_steps. Carebit does not retry the Refund automatically. Refund objects also include next_steps on list payloads when a Refund has failed in this way.
Invoice objects include payment_url. This is the Patient Portal URL where the Patient can pay the Invoice. The value is null when the Invoice has no invoice_number. Webhook events invoice.finalized, invoice.sent, and invoice.settled carry the same Invoice object.

16 September 2026

Patient objects include patient_number. This is the clinic-specific identifier from this Organization's PatientConnection. It is read-only. The value is null when numbering is disabled or no number has been assigned.
Webhook events invoice.finalized, invoice.sent, invoice.settled, and payment.paid are now available. invoice.finalized fires when an Invoice leaves draft. invoice.sent fires when a send record is created for the Invoice. invoice.settled fires the first time the Invoice has no outstanding balance. payment.paid fires when a Payment is recorded as paid.
POST /v1/invoices creates a self-pay Invoice for a connected Patient. Requires invoices.create. Supply line_items with title and unit_price in minor currency units. Set tax_rate_id on a line item to apply a TaxRate from the Organization. payor_type must be patient. Automated billing and insurance-submission attributes are not accepted.

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/{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.