# 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.

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 and AI agents building healthcare integrations between Carebit and practice management software, EHR or EPR systems, laboratories, patient applications, and medical software.

## 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.
- [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

### 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
- [POST /v1/bookings/:booking_id/cancellations](https://carebit.dev/api/booking-cancellations/create?format=md): Cancel 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

### 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

### 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
- [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

- [POST /v1/human_tasks](https://carebit.dev/api/human-tasks/create?format=md): Create a HumanTask

### Invoices

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

### Leads

- [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 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

### Payments

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

### 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

### 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

- [GET /v1/services](https://carebit.dev/api/services/list?format=md): List the Organization's Services
- [GET /v1/services/:id](https://carebit.dev/api/services/retrieve?format=md): Get 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.

### 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.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.

### Refund

- [refund.created](https://carebit.dev/webhooks/refund-created?format=md): A Refund was created.

## Machine-readable spec

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