# Carebit Developer Platform API

> This is Carebit's public REST API. Use it to connect your own software and interfaces
to a Carebit Organization’s data.

The Developer Platform currently supports private integrations that the customer
Organization deploys, controls, and operates, including AI agents that run
under that Organization's control. Do not give custom-integration credentials
to third-party products. Reviewed third-party products will use the Carebit
App Store authorization process when it becomes available.

You can authenticate with OAuth2 credentials. To create credentials, you need to sign
into a Carebit Organization as a staff member and go to
Settings > Developer platform, create a project, and create an API
credential with your chosen API scopes for that project. Use the client ID and client
secret to request an access token from the OAuth2 token endpoint. You can then use the
access token to make requests to the API.

Every request is limited to that Organization, and to the scopes
on the developer project. A token may request a subset of those
scopes. Credentials do not store their own scopes.


Documentation for developers building private integrations that their organisation deploys, controls and operates.

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. Reviewed third-party products will use the Carebit App Store authorization process when it becomes available.

## Using these docs

- Follow the linked Markdown pages for complete request, response, authentication, idempotency, and webhook details.
- Treat the OpenAPI 3.1 document as the machine-readable API contract.
- Do not infer undocumented endpoints, fields, enum values, scopes, or behavior.

## Guides

- [Getting started](https://carebit.dev/guides/getting-started?format=md): Create a developer project, mint a credential, set up webhooks, exchange it for an access token, and make your first request.
- [Authentication](https://carebit.dev/guides/authentication?format=md): OAuth2 client credentials and refresh tokens, plus how to revoke a token or rotate a credential.
- [Testing your integration](https://carebit.dev/guides/testing?format=md): Create a safe example patient, send fabricated webhook events, and verify your integration without using real patient data.
- [Pagination and filtering](https://carebit.dev/guides/pagination-and-filtering?format=md): Cursor pagination, page sizes, and how to filter list endpoints.
- [Idempotency and retries](https://carebit.dev/guides/idempotency-and-retries?format=md): Required Idempotency-Key on every POST create and PATCH update. Replays return the stored response.
- [Validation errors](https://carebit.dev/guides/validation-errors?format=md): Error response envelope, HTTP status meanings, and how to correlate a support ticket.
- [Rate limits](https://carebit.dev/guides/rate-limits?format=md): Per-token, per-project, per-Organization, and per-IP limits applied at the Cloudflare edge.
- [Creating and connecting Patients](https://carebit.dev/guides/creating-patients?format=md): How POST /v1/patients creates a Patient, reuses a connected match, or opens a PatientConnectionRequest that your organisation explicitly acts on.
- [File uploads and imports](https://carebit.dev/guides/remote-file-imports?format=md): Upload Base64 file bytes or import files from public URLs, then track asynchronous validation and malware scanning.
- [Webhook setup](https://carebit.dev/guides/webhook-setup?format=md): Register an HTTPS endpoint, subscribe to events, and receive signed deliveries.
- [Webhook signatures](https://carebit.dev/guides/webhook-signatures?format=md): Verify Carebit webhook signatures with a constant-time HMAC-SHA256 compare across every active v1 digest.
- [Webhook retries](https://carebit.dev/guides/webhook-retries?format=md): How the dispatcher retries a failed delivery, when it gives up, and how manual resend works.
- [Support diagnostics](https://carebit.dev/guides/support-diagnostics?format=md): Attach a request id, correlate a webhook delivery, and share the minimum context we need to help.
- [Changelog and versioning](https://carebit.dev/guides/changelog?format=md): Path-versioned. Additive-only inside a major version. Deprecations announced in advance.
- [Google Tag Manager](https://carebit.dev/marketing-and-analytics/google-tag-manager?format=md): Load your GTM container on the Patient Portal booking flow and fire a conversion when a booking is confirmed.

## API endpoints

### OAuth

- [POST /oauth/revoke](https://carebit.dev/api/oauth/revoke?format=md): Revoke an access or refresh token
- [POST /oauth/token](https://carebit.dev/api/oauth/token?format=md): Create an access token
- [GET /v1/token](https://carebit.dev/api/oauth/retrieve?format=md): Get the access token used on this request

### Agenda

- [GET /v1/clinician_agenda](https://carebit.dev/api/clinician-agenda/retrieve?format=md): Get a Clinician's diary

### Availability Periods

- [POST /v1/availability_periods](https://carebit.dev/api/availability-periods/create?format=md): Create an availability or unavailability period
- [PATCH /v1/availability_periods/:id](https://carebit.dev/api/availability-periods/update?format=md): Update an availability or unavailability period
- [DELETE /v1/availability_periods/:id](https://carebit.dev/api/availability-periods/delete?format=md): Delete an availability or unavailability period

### Availability Slots

- [GET /v1/availability_slots](https://carebit.dev/api/availability-slots/list?format=md): List slots that a Clinician can be booked into
- [GET /v1/next_availability_slot](https://carebit.dev/api/next-availability-slot/retrieve?format=md): Get the next slot that a Clinician can be booked into

### Booking Forms

- [GET /v1/booking_forms](https://carebit.dev/api/booking-forms/list?format=md): List Booking Forms
- [POST /v1/booking_forms](https://carebit.dev/api/booking-forms/create?format=md): Create a Booking Form with a file
- [GET /v1/booking_forms/:id](https://carebit.dev/api/booking-forms/retrieve?format=md): Get a Booking Form
- [PATCH /v1/booking_forms/:id](https://carebit.dev/api/booking-forms/update?format=md): Update a Booking Form

### Bookings

- [GET /v1/bookings](https://carebit.dev/api/bookings/list?format=md): List Bookings
- [POST /v1/bookings](https://carebit.dev/api/bookings/create?format=md): Create a Booking
- [GET /v1/bookings/:id](https://carebit.dev/api/bookings/retrieve?format=md): Get a Booking
- [PATCH /v1/bookings/:id](https://carebit.dev/api/bookings/update?format=md): Update a Booking
- [POST /v1/bookings/:id/cancellations](https://carebit.dev/api/booking-cancellations/create?format=md): Cancel a Booking

### Clinicians

- [GET /v1/clinicians](https://carebit.dev/api/clinicians/list?format=md): List the Organization's Clinicians
- [GET /v1/clinicians/:id](https://carebit.dev/api/clinicians/retrieve?format=md): Get a Clinician

### Credit Notes

- [GET /v1/credit_notes](https://carebit.dev/api/credit-notes/list?format=md): List CreditNotes
- [POST /v1/credit_notes](https://carebit.dev/api/credit-notes/create?format=md): Create a CreditNote
- [GET /v1/credit_notes/:id](https://carebit.dev/api/credit-notes/retrieve?format=md): Retrieve a CreditNote
- [PATCH /v1/credit_notes/:id](https://carebit.dev/api/credit-notes/update?format=md): Update a CreditNote
- [DELETE /v1/credit_notes/:id](https://carebit.dev/api/credit-notes/delete?format=md): Delete a CreditNote

### Digital Form Responses

- [GET /v1/digital_form_responses](https://carebit.dev/api/digital-form-responses/list?format=md): List a Patient's DigitalFormResponses
- [POST /v1/digital_form_responses](https://carebit.dev/api/digital-form-responses/create?format=md): Create and send a DigitalFormResponse
- [GET /v1/digital_form_responses/:id](https://carebit.dev/api/digital-form-responses/retrieve?format=md): Retrieve a DigitalFormResponse

### Digital Forms

- [GET /v1/digital_forms](https://carebit.dev/api/digital-forms/list?format=md): List DigitalForms
- [POST /v1/digital_forms](https://carebit.dev/api/digital-forms/create?format=md): Create a DigitalForm
- [GET /v1/digital_forms/:id](https://carebit.dev/api/digital-forms/retrieve?format=md): Retrieve a DigitalForm

### Expirable Files

- [GET /v1/expirable_files](https://carebit.dev/api/expirable-files/list?format=md): List ExpirableFiles
- [GET /v1/expirable_files/:id](https://carebit.dev/api/expirable-files/retrieve?format=md): Retrieve an ExpirableFile

### Human Tasks

- [GET /v1/human_tasks](https://carebit.dev/api/human-tasks/list?format=md): List HumanTasks
- [POST /v1/human_tasks](https://carebit.dev/api/human-tasks/create?format=md): Create a HumanTask
- [GET /v1/human_tasks/:id](https://carebit.dev/api/human-tasks/retrieve?format=md): Get a HumanTask
- [PATCH /v1/human_tasks/:id](https://carebit.dev/api/human-tasks/update?format=md): Update a HumanTask
- [POST /v1/human_tasks/:id/comments](https://carebit.dev/api/human-task-comments/create?format=md): Add a Comment to a HumanTask

### Invoices

- [GET /v1/invoices](https://carebit.dev/api/invoices/list?format=md): List Invoices
- [POST /v1/invoices](https://carebit.dev/api/invoices/create?format=md): Create an Invoice
- [GET /v1/invoices/:id](https://carebit.dev/api/invoices/retrieve?format=md): Retrieve an Invoice

### Leads

Carebit Pro is required.

- [GET /v1/lead_form_responses](https://carebit.dev/api/lead-form-responses/list?format=md): List a Lead's form responses
- [GET /v1/lead_form_responses/:id](https://carebit.dev/api/lead-form-responses/retrieve?format=md): Get a Lead's form response
- [GET /v1/lead_pipelines](https://carebit.dev/api/lead-pipelines/list?format=md): List Lead pipelines and stages
- [GET /v1/leads](https://carebit.dev/api/leads/list?format=md): List Leads
- [POST /v1/leads](https://carebit.dev/api/leads/create?format=md): Create a Lead
- [GET /v1/leads/:id](https://carebit.dev/api/leads/retrieve?format=md): Get a Lead
- [PATCH /v1/leads/:id](https://carebit.dev/api/leads/update?format=md): Update a Lead

### Letters

- [POST /v1/letter_batches](https://carebit.dev/api/letter-batches/create?format=md): Create up to 100 Letters in one request
- [GET /v1/letters](https://carebit.dev/api/letters/list?format=md): List Letters
- [POST /v1/letters](https://carebit.dev/api/letters/create?format=md): Create a Letter with a file
- [GET /v1/letters/:id](https://carebit.dev/api/letters/retrieve?format=md): Get a Letter

### Lists

- [GET /v1/lists](https://carebit.dev/api/lists/list?format=md): List Lists
- [POST /v1/lists](https://carebit.dev/api/lists/create?format=md): Create a List
- [GET /v1/lists/:id](https://carebit.dev/api/lists/retrieve?format=md): Get a List
- [PATCH /v1/lists/:id](https://carebit.dev/api/lists/update?format=md): Update a List
- [DELETE /v1/lists/:id](https://carebit.dev/api/lists/delete?format=md): Delete a List
- [GET /v1/lists/:list_id/members](https://carebit.dev/api/list-members/list?format=md): List members of a List
- [POST /v1/lists/:list_id/members](https://carebit.dev/api/list-members/create?format=md): Add a member to a List
- [DELETE /v1/lists/:list_id/members/:id](https://carebit.dev/api/list-members/delete?format=md): Remove a member from a List

### Locations

- [GET /v1/locations](https://carebit.dev/api/locations/list?format=md): List Locations
- [GET /v1/locations/:id](https://carebit.dev/api/locations/retrieve?format=md): Get a Location

### Notes

- [GET /v1/notes](https://carebit.dev/api/notes/list?format=md): List Notes
- [POST /v1/notes](https://carebit.dev/api/notes/create?format=md): Create a Note
- [GET /v1/notes/:id](https://carebit.dev/api/notes/retrieve?format=md): Get a Note
- [PATCH /v1/notes/:id](https://carebit.dev/api/notes/update?format=md): Update an API-created Note

### Organization

- [GET /v1/organization](https://carebit.dev/api/organization/retrieve?format=md): Get the Organization for this access token
- [GET /v1/organizations](https://carebit.dev/api/organizations/search?format=md): Search Organizations

### Patient Connection Requests

- [GET /v1/patient_connection_requests](https://carebit.dev/api/patient-connection-requests/list?format=md): List PatientConnectionRequests
- [GET /v1/patient_connection_requests/:id](https://carebit.dev/api/patient-connection-requests/retrieve?format=md): Get a PatientConnectionRequest
- [POST /v1/patient_connection_requests/:id/actions](https://carebit.dev/api/patient-connection-request-actions/create?format=md): Action a PatientConnectionRequest

### Patient Connections

- [GET /v1/patients/:patient_id/connections](https://carebit.dev/api/patient-connections/list?format=md): List a Patient's unlocked PatientConnections
- [POST /v1/patients/:patient_id/connections](https://carebit.dev/api/patient-connections/create?format=md): Create a PatientConnection
- [GET /v1/patients/:patient_id/connections/:id](https://carebit.dev/api/patient-connections/retrieve?format=md): Get an unlocked PatientConnection
- [PATCH /v1/patients/:patient_id/connections/:id](https://carebit.dev/api/patient-connections/update?format=md): Update this Organization's PatientConnection

### Patients

- [GET /v1/patients](https://carebit.dev/api/patients/list?format=md): List Patients connected to the Organization
- [POST /v1/patients](https://carebit.dev/api/patients/create?format=md): Create or find a Patient
- [GET /v1/patients/:id](https://carebit.dev/api/patients/retrieve?format=md): Get a Patient
- [PATCH /v1/patients/:id](https://carebit.dev/api/patients/update?format=md): Update a Patient

### Payment Methods

- [GET /v1/patients/:id/payment_methods](https://carebit.dev/api/payment-methods/list?format=md): List a Patient's PaymentMethods

### Payments

- [GET /v1/payments](https://carebit.dev/api/payments/list?format=md): List Payments
- [POST /v1/payments](https://carebit.dev/api/payments/create?format=md): Create a Payment
- [POST /v1/payments/:id/refunds](https://carebit.dev/api/refunds/create?format=md): Create a Refund

### Payors

- [GET /v1/alternative_payors](https://carebit.dev/api/alternative-payors/list?format=md): List Alternative Payors
- [GET /v1/alternative_payors/:id](https://carebit.dev/api/alternative-payors/retrieve?format=md): Get an Alternative Payor
- [GET /v1/insurance_companies](https://carebit.dev/api/insurance-companies/list?format=md): List Insurance Companies
- [GET /v1/insurance_companies/:id](https://carebit.dev/api/insurance-companies/retrieve?format=md): Get an Insurance Company
- [GET /v1/patients/:patient_id/payors](https://carebit.dev/api/payors/list?format=md): List a Patient's Payors
- [POST /v1/patients/:patient_id/payors](https://carebit.dev/api/payors/create?format=md): Create a Patient Payor
- [GET /v1/patients/:patient_id/payors/:id](https://carebit.dev/api/payors/retrieve?format=md): Get a Patient Payor
- [PATCH /v1/patients/:patient_id/payors/:id](https://carebit.dev/api/payors/update?format=md): Update a Patient Payor

### Photos

- [GET /v1/photos](https://carebit.dev/api/photos/list?format=md): List Photos
- [POST /v1/photos](https://carebit.dev/api/photos/create?format=md): Create a Photo with a file
- [GET /v1/photos/:id](https://carebit.dev/api/photos/retrieve?format=md): Get a Photo
- [PATCH /v1/photos/:id](https://carebit.dev/api/photos/update?format=md): Update a Photo

### Quotes

- [POST /v1/quotes](https://carebit.dev/api/quotes/create?format=md): Create a Quote

### Recall Programmes

- [GET /v1/recall_programmes](https://carebit.dev/api/recall-programmes/list?format=md): List RecallProgrammes
- [GET /v1/recall_programmes/:id](https://carebit.dev/api/recall-programmes/retrieve?format=md): Get a RecallProgramme

### Remote File Import Batches

- [GET /v1/remote_file_import_batches/:id](https://carebit.dev/api/remote-file-import-batches/retrieve?format=md): Get a remote file import batch

### Reports

- [POST /v1/reports](https://carebit.dev/api/reports/create?format=md): Create a report

### Services

- [POST /v1/service_variants](https://carebit.dev/api/service-variants/create?format=md): Create a ServiceVariant
- [PATCH /v1/service_variants/:id](https://carebit.dev/api/service-variants/update?format=md): Update a ServiceVariant
- [GET /v1/services](https://carebit.dev/api/services/list?format=md): List the Organization's Services
- [POST /v1/services](https://carebit.dev/api/services/create?format=md): Create a Service
- [GET /v1/services/:id](https://carebit.dev/api/services/retrieve?format=md): Get a Service
- [PATCH /v1/services/:id](https://carebit.dev/api/services/update?format=md): Update a Service

### Staff Members

- [GET /v1/staff_members](https://carebit.dev/api/staff-members/list?format=md): List the Organization's StaffMembers
- [GET /v1/staff_members/:id](https://carebit.dev/api/staff-members/retrieve?format=md): Get a StaffMember

### Test Results

- [POST /v1/test_result_batches](https://carebit.dev/api/test-result-batches/create?format=md): Create up to 100 Test Results in one request
- [GET /v1/test_results](https://carebit.dev/api/test-results/list?format=md): List Test Results
- [POST /v1/test_results](https://carebit.dev/api/test-results/create?format=md): Create a Test Result
- [GET /v1/test_results/:id](https://carebit.dev/api/test-results/retrieve?format=md): Get a Test Result

### Transmissions

- [GET /v1/transmissions](https://carebit.dev/api/transmissions/list?format=md): List Transmissions

## Webhook events

### Booking

- [booking.arrived](https://carebit.dev/webhooks/booking-arrived?format=md): A Patient arrived for a Booking.
- [booking.canceled](https://carebit.dev/webhooks/booking-canceled?format=md): A Booking was canceled.
- [booking.confirmed](https://carebit.dev/webhooks/booking-confirmed?format=md): A Booking was confirmed.
- [booking.did_not_attend](https://carebit.dev/webhooks/booking-did-not-attend?format=md): A Booking was marked as did not attend.
- [booking.end_time_reached](https://carebit.dev/webhooks/booking-end-time-reached?format=md): A Booking reached its scheduled end time.
- [booking.updated](https://carebit.dev/webhooks/booking-updated?format=md): A Booking's schedule, service, or metadata changed.

### Digital form response

- [digital_form_response.completed](https://carebit.dev/webhooks/digital-form-response-completed?format=md): A Patient completed a DigitalFormResponse.

### Expirable file

- [expirable_file.available](https://carebit.dev/webhooks/expirable-file-available?format=md): An ExpirableFile is available to download.

### Invoice

- [invoice.finalized](https://carebit.dev/webhooks/invoice-finalized?format=md): An Invoice was finalized.
- [invoice.overdue](https://carebit.dev/webhooks/invoice-overdue?format=md): An Invoice became overdue.
- [invoice.paid](https://carebit.dev/webhooks/invoice-paid?format=md): An Invoice's status changed to paid.
- [invoice.sent](https://carebit.dev/webhooks/invoice-sent?format=md): An Invoice was sent to the payor.
- [invoice.settled](https://carebit.dev/webhooks/invoice-settled?format=md): An Invoice was settled with no outstanding balance.

### Lead

- [lead.converted_to_patient](https://carebit.dev/webhooks/lead-converted-to-patient?format=md): A Lead was converted to a Patient.
- [lead.created](https://carebit.dev/webhooks/lead-created?format=md): A Lead was created.
- [lead.form_response_submitted](https://carebit.dev/webhooks/lead-form-response-submitted?format=md): A Lead form was submitted.
- [lead.stage_changed](https://carebit.dev/webhooks/lead-stage-changed?format=md): A Lead moved between pipeline stages.
- [lead.updated](https://carebit.dev/webhooks/lead-updated?format=md): A Lead's profile or lifecycle data changed.

### List

- [list.member_added](https://carebit.dev/webhooks/list-member-added?format=md): A Patient was added to a List.
- [list.member_removed](https://carebit.dev/webhooks/list-member-removed?format=md): A Patient was removed from a List.

### Patient connection

- [patient_connection.created](https://carebit.dev/webhooks/patient-connection-created?format=md): A Patient was created for or connected to an Organization.

### Patient connection request

- [patient_connection_request.created](https://carebit.dev/webhooks/patient-connection-request-created?format=md): A PatientConnectionRequest was created after POST /v1/patients matched one or more unconnected Patients.
- [patient_connection_request.denied](https://carebit.dev/webhooks/patient-connection-request-denied?format=md): A PatientConnectionRequest was denied.
- [patient_connection_request.expired](https://carebit.dev/webhooks/patient-connection-request-expired?format=md): A pending PatientConnectionRequest expired after 30 days without a staff action.
- [patient_connection_request.granted](https://carebit.dev/webhooks/patient-connection-request-granted?format=md): A PatientConnectionRequest was granted.

### Payment

- [payment.paid](https://carebit.dev/webhooks/payment-paid?format=md): A Payment was recorded as paid.

### Quote

- [quote.accepted](https://carebit.dev/webhooks/quote-accepted?format=md): A Quote was accepted and an Invoice was created.
- [quote.created](https://carebit.dev/webhooks/quote-created?format=md): A Quote was created.

### Refund

- [refund.created](https://carebit.dev/webhooks/refund-created?format=md): A Refund was created.
- [refund.failed](https://carebit.dev/webhooks/refund-failed?format=md): A Refund to the original payment method failed.

## Machine-readable spec

- [OpenAPI 3.1](https://carebit.dev/openapi.json)
- [Full docs (single file)](https://carebit.dev/llms-full.txt)