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


---

# Guides

<!-- Carebit docs: Getting started -->

# Getting started

This guide walks you from zero to a working request against the Carebit
Developer Platform, and shows how to receive webhook events.

## 1. Create a developer project

First, make sure you have already been added as a staff member to the Carebit
organisation that you want to build an integration for. If you don't already
have a staff member account, please speak to the administrator of your Carebit
organisation as they can add to you as a staff member with a developer role
in **Settings > Staff members** within Carebit.

Sign in to Carebit and go to **Settings > Developer platform > Projects**.
Click to create a new project and give it a descriptive name. You can now pick the API scopes your project
will need (for example `bookings.read`, `bookings.create`) and the webhook events you want to receive. Save the
project.

## 2. Create an API credential

Inside the project, open the **API credentials** tab and click **Create
credential**. Copy the `client_id` and `client_secret` returned by the
form. The `client_secret` is shown once. If you lose it, rotate the
credential rather than creating a duplicate project. Client secrets use a
`carebit_cs_live_...` prefix so leaked values can be classified by secret
scanners. Customer credentials work against the API at
`https://api.carebit.co`.

## 3. Set up webhooks

If your integration needs to react when something happens in Carebit,
register an HTTPS endpoint on the project. Webhooks do not use the
access token from the next step; Carebit POSTs signed JSON to your
URL when a subscribed event occurs.

Open **Settings > Developer platform > Projects > (your project) >
Webhook endpoints**, click **Add endpoint**, and paste the HTTPS URL
that will receive deliveries. Copy the signing secret shown when the
endpoint is created. The secret is shown once and uses a
`carebit_whsec_live_...` prefix. If you lose it, rotate the secret
from the dashboard rather than creating a duplicate endpoint.

Subscribe the endpoint to the event types you need. Webhook
subscriptions are independent from API scopes: selecting an event type
authorizes that endpoint to receive the payload. Verify the
`Carebit-Signature` header against the exact raw request body before
you trust the payload, then return a `2XX` within 20 seconds.

Use **Send test event** in the dashboard to deliver a test
payload with `livemode: false` while you build your receiving endpoint.

See [Webhook setup](/guides/webhook-setup) for the delivery envelope
and headers, [Webhook signatures](/guides/webhook-signatures) for
verification, and [Webhook retries](/guides/webhook-retries) for
retry behavior. The event catalog is on the
[webhooks](/webhooks) page.

## 4. Exchange the credential for an access token

The token endpoint is form-encoded per the OAuth2 spec. Do not send JSON
and do not send an `Authorization: Bearer` header.

<!-- code-tabs -->

### cURL

```bash
curl -X POST "https://api.carebit.co/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "client_id=$CAREBIT_CLIENT_ID" \
  --data-urlencode "client_secret=$CAREBIT_CLIENT_SECRET" \
  --data-urlencode "scope=organization.read bookings.read"
```

### JavaScript

```javascript
const body = new URLSearchParams({
  grant_type: "client_credentials",
  client_id: process.env.CAREBIT_CLIENT_ID,
  client_secret: process.env.CAREBIT_CLIENT_SECRET,
  scope: "organization.read bookings.read",
});

const response = await fetch("https://api.carebit.co/oauth/token", {
  method: "POST",
  headers: { "Content-Type": "application/x-www-form-urlencoded" },
  body,
});
const { access_token } = await response.json();
```

### Python

```python
import os
import requests

response = requests.post(
    "https://api.carebit.co/oauth/token",
    data={
        "grant_type": "client_credentials",
        "client_id": os.environ["CAREBIT_CLIENT_ID"],
        "client_secret": os.environ["CAREBIT_CLIENT_SECRET"],
        "scope": "organization.read bookings.read",
    },
)
access_token = response.json()["access_token"]
```

### Ruby

```ruby
require "httparty"

response = HTTParty.post(
  "https://api.carebit.co/oauth/token",
  body: {
    grant_type: "client_credentials",
    client_id: ENV.fetch("CAREBIT_CLIENT_ID"),
    client_secret: ENV.fetch("CAREBIT_CLIENT_SECRET"),
    scope: "organization.read bookings.read"
  }
)
access_token = response.parsed_response.fetch("access_token")
```

### PHP

```php
$client = new GuzzleHttp\Client();

$response = $client->post("https://api.carebit.co/oauth/token", [
    "form_params" => [
        "grant_type" => "client_credentials",
        "client_id" => getenv("CAREBIT_CLIENT_ID"),
        "client_secret" => getenv("CAREBIT_CLIENT_SECRET"),
        "scope" => "organization.read bookings.read",
    ],
]);
$accessToken = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR)["access_token"];
```

<!-- /code-tabs -->

The `scope` value must be a subset of the scopes on the developer
project. If you omit `scope`, the token receives every scope on the
project. Requesting a scope the project does not have returns `400`
with `error.code` `invalid_scope`.

The response contains a short-lived `access_token` and a rotating
`refresh_token`. Access tokens live for about one hour. See
[Authentication](/guides/authentication) for the full scope rule, token
refresh, and revocation.

## 5. Make your first request

Call `GET /v1/token` to confirm the access token works. Any valid token
can call this endpoint. It does not require `organization.read`.

<!-- code-tabs -->

### cURL

```bash
curl "https://api.carebit.co/v1/token" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN"
```

### JavaScript

```javascript
const response = await fetch("https://api.carebit.co/v1/token", {
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
  },
});
const token = await response.json();
```

### Python

```python
import os
import requests

response = requests.get(
    "https://api.carebit.co/v1/token",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
    },
)
token = response.json()
```

### Ruby

```ruby
require "httparty"

response = HTTParty.get(
  "https://api.carebit.co/v1/token",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}"
  }
)
token = response.parsed_response
```

### PHP

```php
$client = new GuzzleHttp\Client();

$response = $client->get("https://api.carebit.co/v1/token", [
    "headers" => [
        "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
    ],
]);
$token = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```

<!-- /code-tabs -->

A `200 OK` with a JSON body means the credential and token are healthy.
From here, browse the [API reference](/api) for every endpoint
you can call.


---

<!-- Carebit docs: Authentication -->

# Authentication

Carebit uses OAuth2. Every developer project owns one or more **API
credentials** (`client_id` + `client_secret` pairs), and every access
token is scoped to a single credential.

## Credential prefixes

Carebit prefixes every secret so leaked values can be detected and
classified. Customer credentials use these prefixes:

| Kind                   | Prefix                   |
| ---------------------- | ------------------------ |
| Client secret          | `carebit_cs_live_...`    |
| Access token           | `carebit_at_live_...`    |
| Refresh token          | `carebit_rt_live_...`    |
| Webhook signing secret | `carebit_whsec_live_...` |

`client_id` is the OAuth application UID. Do not depend on any specific
prefix for `client_id`.

Never commit these values. Rotate a credential immediately if you suspect
it has leaked.

## Client-credentials grant

The token endpoint is `POST /oauth/token`. It accepts
`application/x-www-form-urlencoded` per the OAuth2 spec.

<!-- code-tabs -->

### cURL

```bash
curl -X POST "https://api.carebit.co/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "client_id=$CAREBIT_CLIENT_ID" \
  --data-urlencode "client_secret=$CAREBIT_CLIENT_SECRET" \
  --data-urlencode "scope=bookings.read bookings.create"
```

### JavaScript

```javascript
const body = new URLSearchParams({
  grant_type: "client_credentials",
  client_id: process.env.CAREBIT_CLIENT_ID,
  client_secret: process.env.CAREBIT_CLIENT_SECRET,
  scope: "bookings.read bookings.create",
});

const response = await fetch("https://api.carebit.co/oauth/token", {
  method: "POST",
  headers: { "Content-Type": "application/x-www-form-urlencoded" },
  body,
});
const { access_token, refresh_token } = await response.json();
```

### Python

```python
import os
import requests

response = requests.post(
    "https://api.carebit.co/oauth/token",
    data={
        "grant_type": "client_credentials",
        "client_id": os.environ["CAREBIT_CLIENT_ID"],
        "client_secret": os.environ["CAREBIT_CLIENT_SECRET"],
        "scope": "bookings.read bookings.create",
    },
)
tokens = response.json()
access_token = tokens["access_token"]
refresh_token = tokens["refresh_token"]
```

### Ruby

```ruby
require "httparty"

response = HTTParty.post(
  "https://api.carebit.co/oauth/token",
  body: {
    grant_type: "client_credentials",
    client_id: ENV.fetch("CAREBIT_CLIENT_ID"),
    client_secret: ENV.fetch("CAREBIT_CLIENT_SECRET"),
    scope: "bookings.read bookings.create"
  }
)
tokens = response.parsed_response
access_token = tokens.fetch("access_token")
refresh_token = tokens.fetch("refresh_token")
```

### PHP

```php
$client = new GuzzleHttp\Client();

$response = $client->post("https://api.carebit.co/oauth/token", [
    "form_params" => [
        "grant_type" => "client_credentials",
        "client_id" => getenv("CAREBIT_CLIENT_ID"),
        "client_secret" => getenv("CAREBIT_CLIENT_SECRET"),
        "scope" => "bookings.read bookings.create",
    ],
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
$accessToken = $data["access_token"];
$refreshToken = $data["refresh_token"];
```

<!-- /code-tabs -->

Response:

```json
{
  "access_token": "carebit_at_live_...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "created_at": 1767193200,
  "refresh_token": "carebit_rt_live_...",
  "scope": "bookings.read bookings.create"
}
```

## Refreshing tokens

Refresh tokens rotate on every use. Store the new `refresh_token` from
each response and discard the old one.

<!-- code-tabs -->

### cURL

```bash
curl -X POST "https://api.carebit.co/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=refresh_token" \
  --data-urlencode "client_id=$CAREBIT_CLIENT_ID" \
  --data-urlencode "client_secret=$CAREBIT_CLIENT_SECRET" \
  --data-urlencode "refresh_token=$CAREBIT_REFRESH_TOKEN"
```

### JavaScript

```javascript
const body = new URLSearchParams({
  grant_type: "refresh_token",
  client_id: process.env.CAREBIT_CLIENT_ID,
  client_secret: process.env.CAREBIT_CLIENT_SECRET,
  refresh_token: process.env.CAREBIT_REFRESH_TOKEN,
});

const response = await fetch("https://api.carebit.co/oauth/token", {
  method: "POST",
  headers: { "Content-Type": "application/x-www-form-urlencoded" },
  body,
});
const { access_token, refresh_token } = await response.json();
```

### Python

```python
import os
import requests

response = requests.post(
    "https://api.carebit.co/oauth/token",
    data={
        "grant_type": "refresh_token",
        "client_id": os.environ["CAREBIT_CLIENT_ID"],
        "client_secret": os.environ["CAREBIT_CLIENT_SECRET"],
        "refresh_token": os.environ["CAREBIT_REFRESH_TOKEN"],
    },
)
tokens = response.json()
access_token = tokens["access_token"]
refresh_token = tokens["refresh_token"]
```

### Ruby

```ruby
require "httparty"

response = HTTParty.post(
  "https://api.carebit.co/oauth/token",
  body: {
    grant_type: "refresh_token",
    client_id: ENV.fetch("CAREBIT_CLIENT_ID"),
    client_secret: ENV.fetch("CAREBIT_CLIENT_SECRET"),
    refresh_token: ENV.fetch("CAREBIT_REFRESH_TOKEN")
  }
)
tokens = response.parsed_response
access_token = tokens.fetch("access_token")
refresh_token = tokens.fetch("refresh_token")
```

### PHP

```php
$client = new GuzzleHttp\Client();

$response = $client->post("https://api.carebit.co/oauth/token", [
    "form_params" => [
        "grant_type" => "refresh_token",
        "client_id" => getenv("CAREBIT_CLIENT_ID"),
        "client_secret" => getenv("CAREBIT_CLIENT_SECRET"),
        "refresh_token" => getenv("CAREBIT_REFRESH_TOKEN"),
    ],
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
$accessToken = $data["access_token"];
$refreshToken = $data["refresh_token"];
```

<!-- /code-tabs -->

## Revoking a token

`POST /oauth/revoke` immediately invalidates an access or refresh token.

<!-- code-tabs -->

### cURL

```bash
curl -X POST "https://api.carebit.co/oauth/revoke" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "client_id=$CAREBIT_CLIENT_ID" \
  --data-urlencode "client_secret=$CAREBIT_CLIENT_SECRET" \
  --data-urlencode "token=$CAREBIT_ACCESS_TOKEN" \
  --data-urlencode "token_type_hint=access_token"
```

### JavaScript

```javascript
const body = new URLSearchParams({
  client_id: process.env.CAREBIT_CLIENT_ID,
  client_secret: process.env.CAREBIT_CLIENT_SECRET,
  token: process.env.CAREBIT_ACCESS_TOKEN,
  token_type_hint: "access_token",
});

await fetch("https://api.carebit.co/oauth/revoke", {
  method: "POST",
  headers: { "Content-Type": "application/x-www-form-urlencoded" },
  body,
});
```

### Python

```python
import os
import requests

requests.post(
    "https://api.carebit.co/oauth/revoke",
    data={
        "client_id": os.environ["CAREBIT_CLIENT_ID"],
        "client_secret": os.environ["CAREBIT_CLIENT_SECRET"],
        "token": os.environ["CAREBIT_ACCESS_TOKEN"],
        "token_type_hint": "access_token",
    },
)
```

### Ruby

```ruby
require "httparty"

HTTParty.post(
  "https://api.carebit.co/oauth/revoke",
  body: {
    client_id: ENV.fetch("CAREBIT_CLIENT_ID"),
    client_secret: ENV.fetch("CAREBIT_CLIENT_SECRET"),
    token: ENV.fetch("CAREBIT_ACCESS_TOKEN"),
    token_type_hint: "access_token"
  }
)
```

### PHP

```php
$client = new GuzzleHttp\Client();

$client->post("https://api.carebit.co/oauth/revoke", [
    "form_params" => [
        "client_id" => getenv("CAREBIT_CLIENT_ID"),
        "client_secret" => getenv("CAREBIT_CLIENT_SECRET"),
        "token" => getenv("CAREBIT_ACCESS_TOKEN"),
        "token_type_hint" => "access_token",
    ],
]);
```

<!-- /code-tabs -->

## Scopes

Scopes are granular: `resource.read`, `resource.create`, `resource.update`,
`resource.delete`. The developer project owns the maximum scope set.
Credentials do not store their own scopes.

When you request `scope` on `POST /oauth/token` with
`grant_type=client_credentials`, every requested scope must already be
on the project. The issued token receives exactly the scopes you
requested. If you omit `scope`, the token receives the project's full
scope set. Requesting a scope the project does not have returns `400`
with `error.code` `invalid_scope`.

Refresh grants ignore `scope`. The new access token keeps the scopes
from the original grant, and those scopes must still be on the project.

Removing a scope from the project takes effect on the next API request,
including for tokens that were already issued.

## Sending an access token

Send the access token as an `Authorization: Bearer` header on every API
request. Do not send the client credentials on regular API requests.

<!-- code-tabs -->

### cURL

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

### JavaScript

```javascript
const params = new URLSearchParams({
  start_time_from: "2026-08-01T00:00:00Z",
  start_time_to: "2026-08-08T00:00:00Z",
});
const response = await fetch(`https://api.carebit.co/v1/bookings?${params}`, {
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
  },
});
const bookings = await response.json();
```

### Python

```python
import os
import requests

response = requests.get(
    "https://api.carebit.co/v1/bookings",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
    },
    params={
        "start_time_from": "2026-08-01T00:00:00Z",
        "start_time_to": "2026-08-08T00:00:00Z",
    },
)
bookings = response.json()
```

### Ruby

```ruby
require "httparty"

response = HTTParty.get(
  "https://api.carebit.co/v1/bookings",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}"
  },
  query: {
    start_time_from: "2026-08-01T00:00:00Z",
    start_time_to: "2026-08-08T00:00:00Z"
  }
)
bookings = response.parsed_response
```

### PHP

```php
$client = new GuzzleHttp\Client();

$response = $client->get("https://api.carebit.co/v1/bookings", [
    "headers" => [
        "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
    ],
    "query" => [
        "start_time_from" => "2026-08-01T00:00:00Z",
        "start_time_to" => "2026-08-08T00:00:00Z",
    ],
]);
$bookings = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```

<!-- /code-tabs -->


---

<!-- Carebit docs: Testing your integration -->

# Testing your integration

Test with example data before connecting an integration to real
clinical data. Never use a real patient's details, and never paste API
credentials or patient information into third-party request inspectors.

## Test safely

Integrations use the production API at `https://api.carebit.co`.
Use a dedicated example patient and take care not to trigger real messages,
billing, or clinical automations while testing.

## Create or find an example patient

The public API can create a Patient with `POST /v1/patients` and the
`patients.create` scope. Before creating another record, use
`GET /v1/patients` with the `patients.read` scope to look for an existing
example Patient by exact first name, last name, and date of birth:

<!-- code-tabs -->

### cURL

```bash
curl "https://api.carebit.co/v1/patients?first_name=Example%20API&last_name=Patient&date_of_birth=1970-01-01" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN"
```

### JavaScript

```javascript
const params = new URLSearchParams({
  first_name: "Example API",
  last_name: "Patient",
  date_of_birth: "1970-01-01",
});
const response = await fetch(`https://api.carebit.co/v1/patients?${params}`, {
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
  },
});
const patients = await response.json();
```

### Python

```python
import os
import requests

response = requests.get(
    "https://api.carebit.co/v1/patients",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
    },
    params={
        "first_name": "Example API",
        "last_name": "Patient",
        "date_of_birth": "1970-01-01",
    },
)
patients = response.json()
```

### Ruby

```ruby
require "httparty"

response = HTTParty.get(
  "https://api.carebit.co/v1/patients",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}"
  },
  query: {
    first_name: "Example API",
    last_name: "Patient",
    date_of_birth: "1970-01-01"
  }
)
patients = response.parsed_response
```

### PHP

```php
$client = new GuzzleHttp\Client();

$response = $client->get("https://api.carebit.co/v1/patients", [
    "headers" => [
        "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
    ],
    "query" => [
        "first_name" => "Example API",
        "last_name" => "Patient",
        "date_of_birth" => "1970-01-01",
    ],
]);
$patients = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```

<!-- /code-tabs -->

If your StaffMember account has only the Developer role, it cannot open the
Patients area. Create the example Patient through the API with a project that
has `patients.create`, or ask an Admin or another StaffMember with patient
access to create it in Carebit.

New Carebit organizations normally include a patient named **Mr Example
Patient**. Open **Patients** and search for that name before creating another
record. Check its contact details before triggering any communication because
the onboarding record may use an email address belonging to your organization.

If you need a separate record:

1. In Carebit, open **Patients** and select **New patient**.
2. Enter an unmistakably fabricated first and last name, such as `Example API`
   and `Patient`.
3. Enter a fabricated date of birth, such as 1 January 1970, and select a sex.
4. Leave email address, telephone numbers, NHS number, address, and other
   optional fields empty unless the behavior under test requires them.
5. Select **Save**.
6. If Carebit asks for a payment method because of the organization's billing
   settings, select **Skip** rather than entering real payment details.

After saving, Carebit opens the patient profile. The UUID at the end of the
browser URL and the `id` returned by `GET /v1/patients` are the `patient_id` to
use in API requests. The example patient is a real record inside your Carebit
organization, so API writes against it can still run configured automations.
Review the organization's messaging, billing, and automation settings before
testing.

## Prepare a webhook receiver

Your receiver must be available at the HTTPS URL configured on the webhook
endpoint. It should:

- preserve the raw request bytes for signature verification;
- verify the `Carebit-Signature` header before trusting the body;
- log the `Carebit-Delivery-Id` and `Carebit-Event-Id`; and
- return a `2XX` response within 20 seconds.

See [Webhook setup](/guides/webhook-setup) and
[Webhook signatures](/guides/webhook-signatures) before sending an event.

## Send a test webhook event

The project must be active, and the endpoint must be enabled and subscribed to
at least one event type.

1. In Carebit, open **Settings > Developer platform > Projects**.
2. Open the project and its **Webhook endpoints** section.
3. Open an enabled endpoint, then select **Send test event**.
4. Choose an event type. The list contains only event types to which that
   endpoint is currently subscribed.
5. Review the payload preview and select **Send test event**.

Carebit queues the payload only for the selected endpoint through the same
delivery and retry pipeline used by live webhooks. The dashboard then opens
the project's **Events** tab and filters it to the new event. Delivery attempts
are recorded asynchronously, so they may take a few moments to appear.

The event ID and `created_at` value are generated when you send the event.
The remaining preview values are sent as shown. Test payloads:

- contain deterministic, fabricated resource UUIDs;
- use names such as `Test Patient` and `Dr Ada Lovelace`;
- use reserved `example.invalid` email addresses;
- set `livemode` to `false`; and
- use the normal retry schedule after a failed attempt, but do not affect the
  endpoint's failure streak or automatic disablement.

The resources represented by a test payload do not exist in your
organization. A test webhook validates delivery, signature handling, and
payload parsing, but it cannot be followed by an API request for the
fabricated resource.

## Test a complete workflow

Use the dashboard's test event first to validate webhook transport. To test a
complete workflow with queryable data, perform an API action against your
example patient, such as creating or updating a Booking, and receive the real
webhook generated by that action.

Before doing so, confirm that:

- the project has the resource scopes required by the API operation;
- the endpoint is enabled and subscribed to the expected event;
- any messages, invoices, or automations triggered by the action are safe; and
- your receiver treats repeated deliveries as idempotent.

Use the API request ID, event ID, and delivery ID to correlate both sides of
the workflow. See [Support diagnostics](/guides/support-diagnostics) for the
details to retain.


---

<!-- Carebit docs: Pagination and filtering -->

# Pagination and filtering

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

```json
{
  "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`.

<!-- code-tabs -->

### cURL

```bash
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"
```

### JavaScript

```javascript
const params = new URLSearchParams({
  start_time_from: "2026-08-01T00:00:00Z",
  start_time_to: "2026-08-08T00:00:00Z",
  cursor: process.env.NEXT_CURSOR,
});
const response = await fetch(`https://api.carebit.co/v1/bookings?${params}`, {
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
  },
});
const page = await response.json();
```

### Python

```python
import os
import requests

response = requests.get(
    "https://api.carebit.co/v1/bookings",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
    },
    params={
        "start_time_from": "2026-08-01T00:00:00Z",
        "start_time_to": "2026-08-08T00:00:00Z",
        "cursor": os.environ["NEXT_CURSOR"],
    },
)
page = response.json()
```

### Ruby

```ruby
require "httparty"

response = HTTParty.get(
  "https://api.carebit.co/v1/bookings",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}"
  },
  query: {
    start_time_from: "2026-08-01T00:00:00Z",
    start_time_to: "2026-08-08T00:00:00Z",
    cursor: ENV.fetch("NEXT_CURSOR")
  }
)
page = response.parsed_response
```

### PHP

```php
$client = new GuzzleHttp\Client();

$response = $client->get("https://api.carebit.co/v1/bookings", [
    "headers" => [
        "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
    ],
    "query" => [
        "start_time_from" => "2026-08-01T00:00:00Z",
        "start_time_to" => "2026-08-08T00:00:00Z",
        "cursor" => getenv("NEXT_CURSOR"),
    ],
]);
$page = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```

<!-- /code-tabs -->

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

<!-- code-tabs -->

### cURL

```bash
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"
```

### JavaScript

```javascript
const params = new URLSearchParams({
  start_time_from: "2026-08-01T00:00:00Z",
  start_time_to: "2026-08-08T00:00:00Z",
  limit: "100",
});
const response = await fetch(`https://api.carebit.co/v1/bookings?${params}`, {
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
  },
});
const page = await response.json();
```

### Python

```python
import os
import requests

response = requests.get(
    "https://api.carebit.co/v1/bookings",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
    },
    params={
        "start_time_from": "2026-08-01T00:00:00Z",
        "start_time_to": "2026-08-08T00:00:00Z",
        "limit": 100,
    },
)
page = response.json()
```

### Ruby

```ruby
require "httparty"

response = HTTParty.get(
  "https://api.carebit.co/v1/bookings",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}"
  },
  query: {
    start_time_from: "2026-08-01T00:00:00Z",
    start_time_to: "2026-08-08T00:00:00Z",
    limit: 100
  }
)
page = response.parsed_response
```

### PHP

```php
$client = new GuzzleHttp\Client();

$response = $client->get("https://api.carebit.co/v1/bookings", [
    "headers" => [
        "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
    ],
    "query" => [
        "start_time_from" => "2026-08-01T00:00:00Z",
        "start_time_to" => "2026-08-08T00:00:00Z",
        "limit" => 100,
    ],
]);
$page = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```

<!-- /code-tabs -->

## Filtering

Every list endpoint documents its supported filters on the corresponding
[API reference](/api) 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`.

<!-- code-tabs -->

### cURL

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

### JavaScript

```javascript
const params = new URLSearchParams({
  status: "overdue_for_recall",
});
const response = await fetch(`https://api.carebit.co/v1/bookings?${params}`, {
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
  },
});
const page = await response.json();
```

### Python

```python
import os
import requests

response = requests.get(
    "https://api.carebit.co/v1/bookings",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
    },
    params={
        "status": "overdue_for_recall",
    },
)
page = response.json()
```

### Ruby

```ruby
require "httparty"

response = HTTParty.get(
  "https://api.carebit.co/v1/bookings",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}"
  },
  query: {
    status: "overdue_for_recall"
  }
)
page = response.parsed_response
```

### PHP

```php
$client = new GuzzleHttp\Client();

$response = $client->get("https://api.carebit.co/v1/bookings", [
    "headers" => [
        "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
    ],
    "query" => [
        "status" => "overdue_for_recall",
    ],
]);
$page = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```

<!-- /code-tabs -->

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


---

<!-- Carebit docs: Idempotency and retries -->

# Idempotency and retries

Every `POST` create and `PATCH` update endpoint in the Developer Platform
API requires an `Idempotency-Key` header. Sending the same key twice with
the same request body returns the stored response, so a network retry
never creates duplicate resources.

## Sending the key

Generate one UUID per logical operation (not per network attempt). Send
it on the initial request and on every retry of that operation.

<!-- code-tabs -->

### cURL

```bash
IDEMPOTENCY_KEY=$(uuidgen)

curl -X POST "https://api.carebit.co/v1/bookings" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -d '{
    "patient_id": "00000000-0000-4000-8000-000000000004",
    "start_time": "2026-01-01T09:00:00Z",
    "service_id": "00000000-0000-4000-8000-000000000005",
    "service_variant_id": "00000000-0000-4000-8000-000000000006"
  }'
```

### JavaScript

```javascript
const response = await fetch("https://api.carebit.co/v1/bookings", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    patient_id: "00000000-0000-4000-8000-000000000004",
    start_time: "2026-01-01T09:00:00Z",
    service_id: "00000000-0000-4000-8000-000000000005",
    service_variant_id: "00000000-0000-4000-8000-000000000006",
  }),
});
const booking = await response.json();
```

### Python

```python
import os
import uuid
import requests

response = requests.post(
    "https://api.carebit.co/v1/bookings",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "patient_id": "00000000-0000-4000-8000-000000000004",
        "start_time": "2026-01-01T09:00:00Z",
        "service_id": "00000000-0000-4000-8000-000000000005",
        "service_variant_id": "00000000-0000-4000-8000-000000000006",
    },
)
booking = response.json()
```

### Ruby

```ruby
require "httparty"
require "json"
require "securerandom"

response = HTTParty.post(
  "https://api.carebit.co/v1/bookings",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}",
    "Content-Type" => "application/json",
    "Idempotency-Key" => SecureRandom.uuid
  },
  body: {
    patient_id: "00000000-0000-4000-8000-000000000004",
    start_time: "2026-01-01T09:00:00Z",
    service_id: "00000000-0000-4000-8000-000000000005",
    service_variant_id: "00000000-0000-4000-8000-000000000006"
  }.to_json
)
booking = response.parsed_response
```

### PHP

```php
$client = new GuzzleHttp\Client();

$response = $client->post("https://api.carebit.co/v1/bookings", [
    "headers" => [
        "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
        "Idempotency-Key" => bin2hex(random_bytes(16)),
    ],
    "json" => [
        "patient_id" => "00000000-0000-4000-8000-000000000004",
        "start_time" => "2026-01-01T09:00:00Z",
        "service_id" => "00000000-0000-4000-8000-000000000005",
        "service_variant_id" => "00000000-0000-4000-8000-000000000006",
    ],
]);
$booking = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```

<!-- /code-tabs -->

## Header contract

| Condition                                      | Response                                                    |
| ---------------------------------------------- | ----------------------------------------------------------- |
| Missing or blank `Idempotency-Key`             | `400 idempotency_key_required`                              |
| Key longer than 255 characters                 | `400 idempotency_key_too_long`                              |
| Same key + same request body                   | Original status and body, plus `Idempotency-Replayed: true` |
| Same key + different request body              | `422 idempotency_key_reused`                                |
| Same key while an earlier request is in flight | `409 idempotency_conflict` with `Retry-After: 1`            |

The `Idempotency-Replayed: true` response header indicates that the body
was replayed from storage rather than freshly computed. The status code
and body are byte-for-byte identical to the first successful response.

## Retention

Idempotency records are retained for **24 hours** and then purged. A
retry after 24 hours is treated as a fresh request.

## Retry policy

Retry `5xx` responses and network failures with exponential backoff (for
example: 1s, 2s, 4s, 8s, 16s, 30s, then every minute for 15 minutes).
Send the same `Idempotency-Key` on every retry so a duplicate request
never mutates state twice.

Do not retry `4xx` responses other than:

- `409 idempotency_conflict` - retry after the value in the `Retry-After`
  header (defaults to 1 second).
- `429 rate_limited` - retry after the value in the `Retry-After` header
  (defaults to 60 seconds).

These recipient-side retry guidelines are separate from the webhook
delivery retry schedule described in [Webhook retries](/guides/webhook-retries).


---

<!-- Carebit docs: Validation errors -->

# Validation errors

Every error response is a JSON object with an `error` envelope:

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "idempotency_key_reused",
    "message": "This `Idempotency-Key` was already used for a different request."
  }
}
```

The `type` groups errors by category and the `code` is a stable machine
identifier. Do not rely on `message` for logic; localize display strings
in your frontend and switch on `code`.

## Status codes

| Status | Meaning                                                                 |
| ------ | ----------------------------------------------------------------------- |
| `400`  | Malformed request. Missing headers, unparseable body, invalid encoding. |
| `401`  | Missing, expired, or invalid access token.                              |
| `403`  | Access token does not carry the scope this endpoint requires.           |
| `404`  | Resource does not exist or is out of the caller's Organization.         |
| `409`  | Domain conflict, for example an `Idempotency-Key` in flight.            |
| `422`  | Semantic validation failure (invalid enum, missing required field).     |
| `429`  | Rate limit hit. Retry after `Retry-After` seconds.                      |
| `5xx`  | Retryable server error.                                                 |

## Field-level errors

Semantic `422` responses list every offending field:

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "missing_parameter",
    "message": "`patient_id` is required.",
    "param": "patient_id",
    "errors": [
      {
        "code": "missing_parameter",
        "message": "`patient_id` is required.",
        "param": "patient_id"
      },
      {
        "code": "missing_parameter",
        "message": "`start_time` is required.",
        "param": "start_time"
      }
    ]
  }
}
```

The first validation error is promoted to `error.code`, `error.message`,
and `error.param`. Every entry in `error.errors` uses the same stable
`code`, `message`, and `param` shape.

## Request ID

Every response includes a `Carebit-Developer-Platform-API-Request-Id`
header. Include it in every support ticket and log it alongside your own
correlation IDs. See [Support diagnostics](/guides/support-diagnostics)
for what to attach.


---

<!-- Carebit docs: Rate limits -->

# Rate limits

The Developer Platform enforces rate limits at the Cloudflare edge, in
front of `api.carebit.co`. Every limit uses a rolling 60-second window.

| Limit                            | Value                     |
| -------------------------------- | ------------------------- |
| Per access token                 | 120 requests per minute   |
| Per developer project            | 240 requests per minute   |
| Per Organization                 | 300 requests per minute   |
| Writes per access token          | 30 requests per minute    |
| Writes per developer project     | 60 requests per minute    |
| Writes per Organization          | 90 requests per minute    |
| Patient creates per access token | 10 requests per minute    |
| `/oauth/token` per IP            | 10 requests per minute    |
| `/oauth/token` per `client_id`   | 10 requests per minute    |
| Unattributed requests per IP     | 120 requests per minute   |
| API backstop per IP              | 1,000 requests per minute |

**Per access token** is keyed on the SHA-256 hash of the raw bearer
token. The gateway never persists or logs the token itself.

**Write** limits apply to `POST`, `PUT`, `PATCH`, and `DELETE` requests
under `/v1`. They use separate counters and apply in addition to the
all-request limits above. Read requests do not consume write capacity.

**Patient create** limits apply to `POST /v1/patients` in addition to
the general write and all-request limits. This lower limit protects the
duplicate-review workflow from automated probing.

**Unattributed** requests are those the edge cannot map to a real project
or Organization yet: unauthenticated requests, fabricated tokens, and
real requests that arrive before Rails has cached the token's identity.

**API backstop** is a defense-in-depth per-IP limit applied to every
resource API request in addition to the tenant limits. It is higher than
the tenant limits because one integration IP typically serves several
Organizations.

## 429 response

When any limit is hit the API returns `429` with `Retry-After: 60`.

```
HTTP/1.1 429 Too Many Requests
Retry-After: 60
Content-Type: application/json

{ "error": { "type": "rate_limit_error", "code": "too_many_requests",
  "message": "Too many requests. Please slow down." } }
```

Back off for at least the number of seconds in `Retry-After`, using the
same `Idempotency-Key` on any write retry so a duplicate write never
mutates state twice.

## Requesting a higher ceiling

Contact support with your project ID, an estimate of steady-state and
burst traffic, and the endpoint mix you are calling. Include the
`Carebit-Developer-Platform-API-Request-Id` header from a recent
`429` response so we can trace the throttle.


---

<!-- Carebit docs: File uploads and imports -->

# File uploads and imports

The `/v1/remote_file_import_batches/:id` endpoint returns the status of a
batch of files that Carebit is validating and attaching on your behalf.

You can provide a file in either of these ways:

- Inline Base64 bytes. Use this when the file is not available at a public URL.
- A public HTTPS URL. Carebit downloads the file without authentication.

Both sources use the same asynchronous validation, malware scanning, and
polling workflow.

## Upload Base64 bytes

Developer Platform request bodies are JSON, so encode raw file bytes as
Base64. Do not include a `data:` URI prefix. The decoded file can be at most
7 MB, and `filename` is required so Carebit can validate the file extension.

Letters and TestResults accept `file_base64` at the top level:

```json
{
  "patient_id": "00000000-0000-4000-8000-000000000001",
  "title": "Referral letter",
  "status": "complete",
  "file_base64": "JVBERi0xLjQKJ...",
  "filename": "referral-letter.pdf",
  "automatically_create_resource_permission_for_patient": true,
  "notify_patient_of_resource_permission": false
}
```

Lead and Note attachments accept `file_base64` inside each attachment:

```json
{
  "subject_type": "patient",
  "subject_id": "00000000-0000-4000-8000-000000000001",
  "content": "<p>Referral attached.</p>",
  "attachments": [
    {
      "file_base64": "JVBERi0xLjQKJ...",
      "filename": "referral-letter.pdf"
    }
  ]
}
```

For example, callers can encode a local file with:

<!-- code-tabs -->

### cURL

```bash
file_base64=$(base64 < referral-letter.pdf | tr -d '\n')
```

### JavaScript

```javascript
import { readFile } from "node:fs/promises";

const fileBase64 = (await readFile("referral-letter.pdf")).toString("base64");
```

### Python

```python
import base64
from pathlib import Path

file_base64 = base64.b64encode(Path("referral-letter.pdf").read_bytes()).decode()
```

### Ruby

```ruby
require "base64"

file_base64 = Base64.strict_encode64(File.binread("referral-letter.pdf"))
```

### PHP

```php
$fileBase64 = base64_encode(file_get_contents("referral-letter.pdf"));
```

<!-- /code-tabs -->

Never send both `file_base64` and the corresponding URL field for the same
file.

## Import from a URL

Use `file_url` for a Letter or TestResult, or `url` inside a Lead or Note
attachment:

```json
{
  "url": "https://files.example.com/referral-letter.pdf",
  "filename": "referral-letter.pdf"
}
```

The URL must use HTTPS, port 443, and be publicly reachable without
authentication. Redirects are not followed. URL imports can be up to 50 MB.

## Lifecycle

A batch progresses through these statuses:

- `pending` - the batch was created and Carebit has not started processing yet.
- `processing` - at least one file is being loaded, validated, or malware
  scanned.
- `completed` - every item reached a terminal state. Individual items can
  still have failed.

Each file in the batch has its own `status` and, on failure, a stable
`error.code` that identifies the reason. A successful item includes its
created Letter, Note, or TestResult. Pending and failed items do not
expose a created resource.

Every file passes through malware scanning before its item succeeds
or its download URL becomes available. A file that does not pass scanning
fails with `malware_scan_rejected`.

## Polling

Poll `GET /v1/remote_file_import_batches/:id` at a modest interval (for
example every 5 seconds) until the batch reaches `completed`.
Batches expire from active polling storage after they finish. The
canonical outcome is available on the resource the files were attached
to: a Letter, Note, or TestResult.

## Idempotency

The endpoint that creates a batch requires an `Idempotency-Key` the same
way every other create does. See [Idempotency and retries](/guides/idempotency-and-retries).


---

<!-- Carebit docs: Webhook setup -->

# Webhook setup

Every developer project can register HTTPS endpoints and subscribe each
endpoint to one or more [event types](/webhooks). When Carebit records a subscribed
event, the dispatcher POSTs a signed JSON payload to the endpoint.

## 1. Create an endpoint

Open **Settings > Developer platform > Projects > (your project) >
Webhook endpoints**, click **Add endpoint**, and paste the HTTPS URL that
will receive deliveries.

## 2. Copy the signing secret

The dashboard shows the endpoint's signing secret once when the endpoint
is created. Store it as a secret in your deployment. Signing secrets use
the `carebit_whsec_live_...` prefix.

If you lose the secret, rotate it from the dashboard. Carebit signs
every request with the current secret AND the previous secret for 24
hours after a rotation so a receiver that has both configured can
validate either signature.

## 3. Subscribe to events

Pick the event types the endpoint should receive. See
[Webhook events](/webhooks) for the complete list of event types and
payload schemas. Webhook subscriptions are independent from API scopes:
selecting an event type authorizes that endpoint to receive the payload.
API credentials are still governed by project scopes.

## 4. Delivery envelope

Every request is `POST application/json`:

```json
{
  "id": "evt_00000000-0000-4000-8000-000000000012",
  "object": "event",
  "api_version": "v1",
  "created_at": "2026-08-17T10:00:00Z",
  "livemode": true,
  "source": "dashboard",
  "developer_platform_project_id": null,
  "type": "booking.confirmed",
  "data": {
    "object": {
      "id": "00000000-0000-4000-8000-000000000001",
      "object": "booking",
      "...": "..."
    }
  }
}
```

## 5. Request headers

| Header                | Purpose                                                                                  |
| --------------------- | ---------------------------------------------------------------------------------------- |
| `Content-Type`        | Always `application/json`.                                                               |
| `User-Agent`          | Always `Carebit-Webhooks/1.0`.                                                           |
| `Carebit-Delivery-Id` | Unique id for this delivery. Stable across every retry of the delivery.                  |
| `Carebit-Event-Id`    | The event id (matches `id` in the JSON body). Use this for dedupe.                       |
| `Carebit-Event-Type`  | The event type, for example `booking.confirmed`.                                         |
| `Carebit-Endpoint-Id` | The id of the endpoint the request was routed to.                                        |
| `Carebit-Signature`   | Signed timestamp and HMAC digests. See [Webhook signatures](/guides/webhook-signatures). |

Carebit does not publish stable egress IPs for the dispatcher. Use the
signature as the security boundary.

## 6. Verify and respond

Verify the signature before you trust the body. See
[Webhook signatures](/guides/webhook-signatures) for reference
implementations in Node.js, Python, Ruby, and PHP. Return `2XX` within
20 seconds. Move slow work off the request thread.


---

<!-- Carebit docs: Webhook signatures -->

# Verifying webhook signatures

Every webhook delivery carries a single `Carebit-Signature` header. There
is no separate `Carebit-Timestamp` header - the timestamp is inside
`Carebit-Signature`.

The header is a comma-separated list of `key=value` pairs:

```
Carebit-Signature: t=1755428400,v1=5a1c...abcd,v1=9f2e...beef
```

- `t=` is the unix timestamp of the signature.
- `v1=` is an HMAC-SHA256 hex digest.

There may be more than one `v1=` value. During a 24-hour rotation window
after you rotate an endpoint's signing secret, Carebit signs every
request with the new secret AND the previous secret so a receiver that
has both configured can accept either.

## Steps

1. Parse the header. Extract `t` and every `v1=` value into a list.
2. Compute the signed payload string. It is the timestamp, a literal
   period, then the **exact raw request body bytes**. Do not
   re-serialize the JSON; use the raw bytes as received.
3. Compute `HMAC-SHA256(secret, signed_payload)` using each of your
   endpoint's active signing secrets. Compare each expected digest
   against every `v1=` value in the header using a constant-time
   comparison. If any `v1=` matches any active secret, the signature is
   valid.
4. Reject the request if `t` is more than 5 minutes older than your
   server clock, or more than 5 minutes in the future.

Capture the raw body **before** any JSON parser touches it. A single
whitespace difference will invalidate the signature.

<!-- code-tabs -->

### Node.js

```javascript
import crypto from "node:crypto";

// activeSecrets is [currentSecret, previousSecret?] read from your config.
// Returns false for any malformed input; never throws.
export function verifyCarebitSignature({
  header,
  rawBody,
  activeSecrets,
  toleranceSeconds = 300,
}) {
  if (typeof header !== "string" || header.length === 0) {
    return false;
  }
  const pairs = header.split(",").map((pair) => pair.trim().split("=", 2));
  const timestampPair = pairs.find(([key]) => key === "t");
  const timestampRaw = timestampPair?.[1];
  if (typeof timestampRaw !== "string" || !/^\d{1,15}$/.test(timestampRaw)) {
    return false;
  }
  const timestamp = Number(timestampRaw);
  if (!Number.isFinite(timestamp)) {
    return false;
  }
  if (Math.abs(Math.floor(Date.now() / 1000) - timestamp) > toleranceSeconds) {
    return false;
  }
  const signatures = pairs
    .filter(
      ([key, value]) =>
        key === "v1" &&
        typeof value === "string" &&
        /^[0-9a-f]{64}$/i.test(value),
    )
    .map(([, value]) => value.toLowerCase());
  if (signatures.length === 0) {
    return false;
  }
  const bodyBuffer = Buffer.isBuffer(rawBody)
    ? rawBody
    : Buffer.from(String(rawBody), "utf8");
  const signedPayload = Buffer.concat([
    Buffer.from(`${timestamp}.`, "utf8"),
    bodyBuffer,
  ]);
  return activeSecrets.some((secret) => {
    if (typeof secret !== "string" || secret.length === 0) {
      return false;
    }
    const expected = crypto
      .createHmac("sha256", secret)
      .update(signedPayload)
      .digest("hex");
    const expectedBytes = Buffer.from(expected, "hex");
    return signatures.some((provided) => {
      const providedBytes = Buffer.from(provided, "hex");
      if (providedBytes.length !== expectedBytes.length) {
        return false;
      }
      return crypto.timingSafeEqual(providedBytes, expectedBytes);
    });
  });
}
```

### Python

```python
import hmac
import time
from hashlib import sha256


def verify_carebit_signature(header: str, raw_body: bytes, active_secrets: list[str], tolerance_seconds: int = 300) -> bool:
    if not isinstance(header, str) or not header:
        return False
    pairs = [pair.strip().split("=", 1) for pair in header.split(",") if "=" in pair]
    timestamp_raw = next((value for key, value in pairs if key == "t"), None)
    if not timestamp_raw or len(timestamp_raw) > 15 or not timestamp_raw.isdigit():
        return False
    timestamp = int(timestamp_raw)
    if abs(int(time.time()) - timestamp) > tolerance_seconds:
        return False
    signatures = [value.lower() for key, value in pairs if key == "v1" and len(value) == 64]
    if not signatures:
        return False
    signed_payload = f"{timestamp}.".encode() + raw_body
    for secret in active_secrets:
        if not isinstance(secret, str) or not secret:
            continue
        expected = hmac.new(secret.encode(), signed_payload, sha256).hexdigest()
        for provided in signatures:
            if hmac.compare_digest(expected, provided):
                return True
    return False
```

### Ruby

```ruby
require "openssl"

# active_secrets is an array like [current_secret, previous_secret] read from your config.
# Returns false for any malformed input; never raises.
def verify_carebit_signature(header:, raw_body:, active_secrets:, tolerance_seconds: 300)
  return false unless header.is_a?(String) && !header.empty?

  pairs = header.split(",").map { |pair| pair.strip.split("=", 2) }
  timestamp_raw = pairs.find { |key, _| key == "t" }&.last
  return false unless timestamp_raw.is_a?(String) && /\A\d{1,15}\z/.match?(timestamp_raw)

  timestamp = timestamp_raw.to_i
  return false if (Time.now.to_i - timestamp).abs > tolerance_seconds

  signatures = pairs
    .select { |key, value| key == "v1" && value.is_a?(String) && /\A[0-9a-f]{64}\z/i.match?(value) }
    .map { |(_, value)| value.downcase }
  return false if signatures.empty?

  signed_payload = "#{timestamp}.#{raw_body}"
  active_secrets.any? do |secret|
    next false unless secret.is_a?(String) && !secret.empty?

    expected = OpenSSL::HMAC.hexdigest("SHA256", secret, signed_payload)
    signatures.any? do |provided|
      next false if provided.bytesize != expected.bytesize

      OpenSSL.fixed_length_secure_compare(provided, expected)
    end
  end
end
```

### PHP

```php
<?php

// $activeSecrets is an array like [$currentSecret, $previousSecret].
// $rawBody must be the exact bytes of the request body, before any parser.
function verify_carebit_signature(string $header, string $rawBody, array $activeSecrets, int $toleranceSeconds = 300): bool {
    if ($header === '') {
        return false;
    }
    $pairs = [];
    foreach (explode(',', $header) as $part) {
        $trimmed = trim($part);
        $split = explode('=', $trimmed, 2);
        if (count($split) === 2) {
            $pairs[] = $split;
        }
    }
    $timestampRaw = null;
    foreach ($pairs as [$key, $value]) {
        if ($key === 't') {
            $timestampRaw = $value;
            break;
        }
    }
    if ($timestampRaw === null || !preg_match('/^\d{1,15}$/', $timestampRaw)) {
        return false;
    }
    $timestamp = (int) $timestampRaw;
    if (abs(time() - $timestamp) > $toleranceSeconds) {
        return false;
    }
    $signatures = [];
    foreach ($pairs as [$key, $value]) {
        if ($key === 'v1' && is_string($value) && preg_match('/^[0-9a-f]{64}$/i', $value)) {
            $signatures[] = strtolower($value);
        }
    }
    if (empty($signatures)) {
        return false;
    }
    $signedPayload = $timestampRaw . '.' . $rawBody;
    foreach ($activeSecrets as $secret) {
        if (!is_string($secret) || $secret === '') {
            continue;
        }
        $expected = hash_hmac('sha256', $signedPayload, $secret);
        foreach ($signatures as $provided) {
            if (hash_equals($expected, $provided)) {
                return true;
            }
        }
    }
    return false;
}
```

<!-- /code-tabs -->

## Deterministic test vectors

The published OpenAPI document under `x-carebit-signature-vectors`
contains three deterministic vectors: `primary`, `rotation`, and
`stale_timestamp_rejected`. Every reference implementation above
produces identical digests against those vectors.


---

<!-- Carebit docs: Webhook retries -->

# Webhook retries

The webhook dispatcher retries a failed delivery on your endpoint's
behalf. Every attempt is logged in the developer dashboard.

## Delivery budget

- **Timeout.** Each attempt gives your endpoint up to 20 seconds to
  return a `2XX` response.
- **Retries.** A non-`2XX`, timeout, or connection error is retried with
  a scheduled backoff. The dispatcher makes up to **10 attempts per
  delivery** within a window of up to **3 days**.
- **Schedule.** The inter-attempt delays are configured in
  `workers/developer-platform-webhook-dispatcher/src/retry.ts`. The base
  delays are 1 minute, 5 minutes, 30 minutes, 2 hours, 5 hours, 10 hours,
  14 hours, 16 hours 40 minutes, and 16 hours 40 minutes. Carebit applies
  up to 10% positive or negative jitter to each delay. The cumulative
  retry window remains under 3 days.
- **At-least-once.** Network partitions can cause the same event to be
  delivered twice. Dedupe on `Carebit-Event-Id` (equivalent to `id` in
  the JSON body).
- **Order.** Events are not delivered in a strict order per endpoint.
  Design handlers to be commutative, or reconcile against the resource
  state via the public API.
- **Redirects.** The dispatcher does not follow HTTP redirects. Respond
  `2XX` from the exact URL configured on the endpoint. A `3XX` response
  counts as a failure.
- **Auto-disable.** If an endpoint fails continuously for 3 days,
  Carebit pauses it and emails the project's Admin and Developer
  StaffMembers. Re-enable it from the developer dashboard after fixing
  the receiver. The failure streak clears the first time any attempt
  succeeds.

These schedule numbers describe how Carebit dispatches. They are
independent of your own retry policy against the outbound API (see
[Idempotency and retries](/guides/idempotency-and-retries)).

## Manual resend

Every exhausted delivery in the developer dashboard has a **Resend**
button. Resend reuses the existing `Carebit-Delivery-Id` and adds
exactly one attempt to that delivery. If that attempt fails, resend does
not queue further retries and cannot be triggered again. Use resend to
replay a specific past event after fixing the receiver, not to escalate
retries.

## Test events

The **Send test event** action in the dashboard sends a fabricated
payload with `livemode: false`. Fixture IDs are deterministic UUIDs for
Organizations that do not exist, and payloads use `example.invalid`
addresses and clearly fake names. Test deliveries do not affect the
failure streak.

## Log retention

Every attempt is logged with the request headers, the raw body, the
response status, the response body, and the outcome. Logs are retained
for 30 days and are searchable in the developer dashboard by event
type, endpoint, delivery id, and outcome.


---

<!-- Carebit docs: Support diagnostics -->

# Support diagnostics

Every response includes a `Carebit-Developer-Platform-API-Request-Id`
header. Store it alongside your own log correlation IDs and include it
in every [support ticket](mailto:support@carebit.co) you open.

## What to attach

For an API problem:

- The HTTP method and full URL, including query string.
- The `Carebit-Developer-Platform-API-Request-Id` from the response.
- The response status, response body, and response headers.
- The request headers you sent (redact `Authorization`).
- The `Idempotency-Key`, if the endpoint is a create or update.
- A minimal reproduction: the shortest request that reproduces the
  behavior.

For a webhook problem:

- The `Carebit-Delivery-Id` and `Carebit-Event-Id` values from the
  request headers.
- The event type and the endpoint id.
- The raw request body bytes (do NOT reformat the JSON) if you suspect a
  signature mismatch.
- Which secrets were active on the endpoint at the time of the delivery.

## What we do not need

Do not paste customer PHI in a support ticket. Redact patient names and
identifiers, or share the `Carebit-Developer-Platform-API-Request-Id`
and event id and let Carebit look up the payload internally.

## Status page

Follow the [Carebit status page](https://status.carebit.co) for platform incidents. Individual
delivery failures are visible in the developer dashboard.


---

<!-- Carebit docs: Changelog and versioning -->

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


---

<!-- Carebit docs: Google Tag Manager -->

# Google Tag Manager

Carebit can load your Google Tag Manager container on the Patient Portal
booking flow, from the first booking page through to a successful
booking. When the booking is confirmed, Carebit pushes a
`booking.confirmed` event into the GTM data layer with a `booking`
object. You can use that event to send a conversion to Google Ads or
another tag.

This page is for marketing agencies and developers who manage PPC or
analytics for a Carebit clinic. You do not need a Carebit staff login
to configure GTM itself. A member of the clinic team with access to
**Settings** must paste your container ID into Carebit.

This is browser-side tracking on the Patient Portal. It is separate from
[Developer Platform webhooks](/guides/webhook-setup). Those deliver
signed JSON to your server. They do not load GTM.

## Add your container ID

1. In Google Tag Manager, copy the container ID. It looks like
   `GTM-ABCDEF`.
2. Ask a clinic administrator to sign in to Carebit and open
   **Settings & tools > Organisation settings > Patient Portal**.
3. Paste the container ID into **Google Tag Manager container ID** and
   click **Save**.

Carebit then loads the GTM snippet on these Patient Portal paths:

- `/patients/bookings/new` - the patient starts the booking. Track
  landing-page hits and any `utm_*` or `gclid` parameters on the URL
  here.
- `/patients/bookings/complete` - the booking succeeded. Carebit pushes
  `booking.confirmed` on this page.
- `/patients/bookings/:id/complete-payment` - the patient finishes
  paying for a booking that required payment.

Replace the hostname with the clinic's Patient Portal, for example
`https://example-clinic.carebit.co/patients/bookings/new`.

## The booking.confirmed event

When `/patients/bookings/complete` loads a confirmed booking, Carebit
pushes one data-layer event:

- `event` is `booking.confirmed`
- `booking` is the booking that was just created

Carebit pushes that event once per booking ID in the current page. A
refresh does not send a second conversion for the same booking.

In Google Tag Manager, create a **Custom Event** trigger whose event
name is `booking.confirmed`. Point your Google Ads conversion tag, or
any other tag, at that trigger.

You can also create Data Layer variables for fields you want to send
with the conversion, such as `booking.id`, `booking.services.0.price`,
or `booking.clinician.formatted_name`.

![The browser console showing window.dataLayer after Carebit pushes booking.confirmed](/guides/gtm-booking-confirmed-data-layer.png)

An example `booking` object is:

```json
{
  "id": "da6ed73c-63bf-4ac7-883b-a2bf5d48fa76",
  "creation_source": "patient",
  "start_time": "2025-05-12T16:45:00.000+01:00",
  "end_time": "2025-05-12T17:45:00.000+01:00",
  "status": "confirmed",
  "location": {
    "id": "3e29d297-5f56-443f-9efa-9d420eeec01a",
    "title": "The Hampshire Clinic"
  },
  "services": [
    {
      "id": "c6357daa-8778-4c83-848a-9a51901a42de",
      "title": "Initial patient consultation",
      "price": "320.0",
      "currency": "gbp"
    }
  ],
  "clinician": {
    "id": "e11acb4d-aeb2-4864-8211-922d5cd61cf8",
    "formatted_name": "Dr James Smith"
  },
  "organization": {
    "id": "00000000-0000-4000-8000-000000000001",
    "name": "Example Clinic"
  },
  "patient": {
    "id": "65905116-f474-48ce-b8cf-3d1d87ea1d21"
  },
  "is_remote": false
}
```

The `patient` object contains only the Patient ID. It does not include
the patient's name or contact details.

## Test the integration

You need a live booking-complete URL with a booking ID, patient ID, and
booking magic-link token. If you do not have a Carebit login, ask the
clinic to send you a URL for an example or test patient. Do not use a
real patient's booking.

To build the URL from Carebit:

1. Open an example patient's profile and go to the **Bookings** tab.
2. Find a confirmed booking, then click **Actions > View in Patient
   Portal**.
3. That opens a path like
   `/patients/bookings/123?patientId=456&magicLinkToken=789`, where
   `123` is the booking ID, `456` is the patient ID, and `789` is the
   magic-link token.
4. Change the path to
   `/patients/bookings/complete?id=123&patientId=456&magicLinkToken=789`
   and load it in the browser.

In the browser developer console, inspect `window.dataLayer`. You should
see `booking.confirmed` and the `booking` object. Preview your GTM
container to confirm that your conversion tag fires.

## Optional thank-you page redirect

Organisation settings can also set **Redirect patients after they
complete an online booking**. If that URL is set and GTM is configured,
Carebit waits up to two seconds for GTM tags that listen to
`booking.confirmed` to finish, then sends the patient to your thank-you
page. The redirect URL does not include booking or patient identifiers.

If the redirect URL is set and no GTM container ID is set, Carebit
redirects immediately.

## Lead forms

Lead forms can load a separate GTM container ID. That container is
independent of the Patient Portal booking container. A submitted lead
form pushes a `lead_form_submit` data-layer event.


---

# API reference

# Revoke an access or refresh token

`POST /oauth/revoke`

This operation is idempotent. It returns `200 {}` whether or not the token was valid, which prevents token enumeration.

## Request body (`application/x-www-form-urlencoded`)

- `object`
  - `client_id` (`string`) - The OAuth application UID.
  - `client_secret` (`string`) - The OAuth application secret.
  - `token` (`string`) - The access or refresh token value to revoke.
  - `token_type_hint` (`string`) - enum: `access_token`, `refresh_token`; The type of token supplied in `token`.

### Example

```json
{
  "client_id": "example_client_id",
  "client_secret": "carebit_cs_live_example_client_secret",
  "token": "carebit_at_live_example_access_token",
  "token_type_hint": "access_token"
}
```

## Response `200`

The token was revoked, or was already invalid.

- `object` - An empty object returned whether or not the token was valid. This prevents token enumeration.

### Example

```json
{}
```

## Response `401`

The client credentials are invalid.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Code samples

```bash
curl -X POST "https://api.carebit.co/oauth/revoke" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "client_id=example_client_id" \
  --data-urlencode "client_secret=carebit_cs_live_example_client_secret" \
  --data-urlencode "token=carebit_at_live_example_access_token" \
  --data-urlencode "token_type_hint=access_token"
```

```javascript
const response = await fetch("https://api.carebit.co/oauth/revoke", {
  method: "POST",
  headers: {
    "Content-Type": "application/x-www-form-urlencoded",
  },
  body: new URLSearchParams({
  "client_id": "example_client_id",
  "client_secret": "carebit_cs_live_example_client_secret",
  "token": "carebit_at_live_example_access_token",
  "token_type_hint": "access_token",
}),
});

if (!response.ok) {
  throw new Error(`Carebit API error: ${response.status}`);
}

const data = await response.json();
```

```python
import os
import requests

response = requests.post(
    "https://api.carebit.co/oauth/revoke",
    data={
        "client_id": "example_client_id",
        "client_secret": "carebit_cs_live_example_client_secret",
        "token": "carebit_at_live_example_access_token",
        "token_type_hint": "access_token"
    }
)
response.raise_for_status()
data = response.json()
```

```ruby
require "httparty"

response = HTTParty.post(
  "https://api.carebit.co/oauth/revoke",
  body: {
    "client_id" => "example_client_id",
    "client_secret" => "carebit_cs_live_example_client_secret",
    "token" => "carebit_at_live_example_access_token",
    "token_type_hint" => "access_token"
  }
)
raise "Carebit API error: #{response.code}" unless response.success?
data = response.parsed_response
```

```php
<?php

$client = new GuzzleHttp\Client();

$response = $client->post("https://api.carebit.co/oauth/revoke", [
    "form_params" => [
      "client_id" => "example_client_id",
      "client_secret" => "carebit_cs_live_example_client_secret",
      "token" => "carebit_at_live_example_access_token",
      "token_type_hint" => "access_token"
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```


---

# Create an access token

`POST /oauth/token`

Exchange client credentials or a refresh token for an access token. Send `client_id` and `client_secret` using HTTP Basic authentication or as request body fields. This endpoint does not require a Bearer token; it issues one.

## Request body (`application/x-www-form-urlencoded`)

- `object`
  - `client_id` (`string`) - The OAuth application UID. Omit when passing credentials via HTTP Basic.
  - `client_secret` (`string`) - The OAuth application secret. Omit when passing credentials via HTTP Basic.
  - `grant_type` (`string`) - enum: `client_credentials`, `refresh_token`; The OAuth grant type to exchange for an access token.
  - `refresh_token` (`string`) - The refresh token issued by a previous grant. Required only for `grant_type=refresh_token`.
  - `scope` (`string`) - The space-separated list of requested scopes. Must be a subset of the developer project's scopes. Defaults to the project's full scope set for `client_credentials`. Requesting a scope the project does not have returns `invalid_scope`. Ignored for `refresh_token`.

### Example

```json
{
  "client_id": "example_client_id",
  "client_secret": "carebit_cs_live_example_client_secret",
  "grant_type": "client_credentials",
  "scope": "bookings.read bookings.create"
}
```

## Response `200`

The access token was created. The response includes a `refresh_token` for both supported grant types.

- `object`
  - `access_token` (`string`) - The issued Bearer access token.
  - `created_at` (`integer`) - The Unix timestamp at which the token was issued.
  - `expires_in` (`integer`) - The lifetime of the access token, in seconds.
  - `refresh_token` (`string`) - The refresh token. A new one is issued with each access token.
  - `scope` (`string`) - The space-separated list of granted scopes.
  - `token_type` (`string`) - The authentication scheme to use in the `Authorization` header.

### Example

```json
{
  "access_token": "carebit_at_live_example_access_token",
  "created_at": 1767193200,
  "expires_in": 3600,
  "refresh_token": "carebit_rt_live_example_refresh_token",
  "scope": "bookings.read bookings.create",
  "token_type": "Bearer"
}
```

## Response `400`

The token request is malformed, or one or more requested scopes are not on the project (`invalid_scope`).

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `401`

The client credentials are invalid.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `403`

The project is disabled or archived, or the Organization does not have the developer_platform entitlement.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `429`

Too many token requests.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Code samples

```bash
curl -X POST "https://api.carebit.co/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "client_id=example_client_id" \
  --data-urlencode "client_secret=carebit_cs_live_example_client_secret" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "scope=bookings.read bookings.create"
```

```javascript
const response = await fetch("https://api.carebit.co/oauth/token", {
  method: "POST",
  headers: {
    "Content-Type": "application/x-www-form-urlencoded",
  },
  body: new URLSearchParams({
  "client_id": "example_client_id",
  "client_secret": "carebit_cs_live_example_client_secret",
  "grant_type": "client_credentials",
  "scope": "bookings.read bookings.create",
}),
});

if (!response.ok) {
  throw new Error(`Carebit API error: ${response.status}`);
}

const data = await response.json();
```

```python
import os
import requests

response = requests.post(
    "https://api.carebit.co/oauth/token",
    data={
        "client_id": "example_client_id",
        "client_secret": "carebit_cs_live_example_client_secret",
        "grant_type": "client_credentials",
        "scope": "bookings.read bookings.create"
    }
)
response.raise_for_status()
data = response.json()
```

```ruby
require "httparty"

response = HTTParty.post(
  "https://api.carebit.co/oauth/token",
  body: {
    "client_id" => "example_client_id",
    "client_secret" => "carebit_cs_live_example_client_secret",
    "grant_type" => "client_credentials",
    "scope" => "bookings.read bookings.create"
  }
)
raise "Carebit API error: #{response.code}" unless response.success?
data = response.parsed_response
```

```php
<?php

$client = new GuzzleHttp\Client();

$response = $client->post("https://api.carebit.co/oauth/token", [
    "form_params" => [
      "client_id" => "example_client_id",
      "client_secret" => "carebit_cs_live_example_client_secret",
      "grant_type" => "client_credentials",
      "scope" => "bookings.read bookings.create"
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```


---

# List Alternative Payors

`GET /v1/alternative_payors`

**Required API scopes:** `payors.read`

## Parameters

- `limit` (query, `integer`) - The maximum number of items to return. Defaults to `25`; the maximum is `100`.
- `starting_after` (query, `string`) - Return items after this resource ID. You cannot use this with `cursor`.
- `cursor` (query, `string`) - The `next_cursor` value from the previous page. You cannot use this with `starting_after`.

## Response `200`

Paginated list of `AlternativePayor` objects.

- `any`

### Example

```json
{
  "object": "list",
  "data": [
    {
      "id": null,
      "object": "alternative_payor",
      "created_at": "2026-01-01T09:00:00Z",
      "name": "Acme Health Benefits",
      "payor_type": "insurance_company",
      "updated_at": "2026-01-01T09:00:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": "eyJzdGFydF90aW1lIjoiMjAyNi0wMS0wMVQwOTowMDowMFoifQ",
  "url": "/v1/alternative_payors"
}
```

## Response `401`

The access token is missing, invalid, expired, or revoked.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `403`

The access token lacks the required scope, or the project is disabled.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `429`

Too many requests. Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Code samples

```bash
curl -X GET "https://api.carebit.co/v1/alternative_payors" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN"
```

```javascript
const response = await fetch("https://api.carebit.co/v1/alternative_payors", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
  },
});

if (!response.ok) {
  throw new Error(`Carebit API error: ${response.status}`);
}

const data = await response.json();
```

```python
import os
import requests

response = requests.get(
    "https://api.carebit.co/v1/alternative_payors",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
    }
)
response.raise_for_status()
data = response.json()
```

```ruby
require "httparty"

response = HTTParty.get(
  "https://api.carebit.co/v1/alternative_payors",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}"
  }
)
raise "Carebit API error: #{response.code}" unless response.success?
data = response.parsed_response
```

```php
<?php

$client = new GuzzleHttp\Client();

$response = $client->get("https://api.carebit.co/v1/alternative_payors", [
    "headers" => [
      "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```


---

# Get an Alternative Payor

`GET /v1/alternative_payors/:id`

**Required API scopes:** `payors.read`

## Parameters

- `id` (path, `string`) (required)

## Response `200`

The requested `AlternativePayor`.

- `object`
  - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - `name` (`string`) - The name of the alternative payor.
  - `object` (`any`) - Discriminator value emitted at `object`.
  - `payor_type` (`string`) - enum: `legal`, `medical_facility`, `other`; The category of the alternative payor.
  - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.

### Example

```json
{
  "id": null,
  "object": "alternative_payor",
  "created_at": "2026-01-01T09:00:00Z",
  "name": "Acme Health Benefits",
  "payor_type": "insurance_company",
  "updated_at": "2026-01-01T09:00:00Z"
}
```

## Response `401`

The access token is missing, invalid, expired, or revoked.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `403`

The access token lacks the required scope, or the project is disabled.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `404`

Error response.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `429`

Too many requests. Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Code samples

```bash
curl -X GET "https://api.carebit.co/v1/alternative_payors/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN"
```

```javascript
const response = await fetch("https://api.carebit.co/v1/alternative_payors/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
  },
});

if (!response.ok) {
  throw new Error(`Carebit API error: ${response.status}`);
}

const data = await response.json();
```

```python
import os
import requests

response = requests.get(
    "https://api.carebit.co/v1/alternative_payors/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
    }
)
response.raise_for_status()
data = response.json()
```

```ruby
require "httparty"

response = HTTParty.get(
  "https://api.carebit.co/v1/alternative_payors/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}"
  }
)
raise "Carebit API error: #{response.code}" unless response.success?
data = response.parsed_response
```

```php
<?php

$client = new GuzzleHttp\Client();

$response = $client->get("https://api.carebit.co/v1/alternative_payors/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c", [
    "headers" => [
      "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```


---

# Create an availability or unavailability period

`POST /v1/availability_periods`

Set `is_recurring` to `false` for a one-off period and supply `start_time` and `end_time`. Set `is_recurring` to `true` for a repeating period and choose `simple` or `advanced` as the `recurring_strategy`. A simple weekly Tuesday uses `recurring_strategy: "simple"`, `recurring_day_number_of_week: 2`, `recurring_interval_in_seconds: 604800`, and a Tuesday `recurring_start_date`. A simple fortnightly period uses 1209600 seconds. The second Thursday of every month uses `recurring_strategy: "advanced"`, `recurring_nth_day_in_month: 2`, `recurring_day_number_of_week: 4`, and a matching start date such as `2026-01-08`. Add `recurring_dates_to_skip: ["2026-02-12"]` to omit that specific monthly occurrence. Recurring start and end times use the Organization's local time.

**Required API scopes:** `availability_periods.create`

## Parameters

- `Idempotency-Key` (header, `string`) (required) - Client-generated idempotency key. Required for every POST/PATCH write. Replay of the same key with the same body returns the stored response with an `Idempotency-Replayed: true` header. Same key + different body returns `422 idempotency_key_reused`. A duplicate that arrives while the first request is still in flight returns `409 idempotency_conflict` with `Retry-After: 1`.

## Request body (`application/json`)

- `object`
  - `availability_type` (`string`) - enum: `availability`, `unavailability`; Whether the period makes the Clinician available or unavailable.
  - `clinician_id` (`string | null`) - format: `uuid`; The Clinician affected by the period.
  - `end_time` (`string | null`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `is_active` (`boolean`) - Whether the period contributes to the diary.
  - `is_recurring` (`boolean`) - Whether the period repeats. When false, supply `start_time` and `end_time`; recurring fields are cleared.
  - `notes` (`string | null`) - Internal notes about the period.
  - `recurring_dates_to_skip` (`array`) - Specific ISO 8601 dates on which a recurring period must not occur. For example, `["2026-02-12"]` skips the occurrence on 12 February 2026. Only dates that are today or in the future are retained.
    - `items` (`string`) - format: `date`
  - `recurring_day_number_of_week` (`integer | null`) - The ISO weekday number used by a recurring period. The values start at 1, not 0: 1 is Monday, 2 is Tuesday, 3 is Wednesday, 4 is Thursday, 5 is Friday, 6 is Saturday, and 7 is Sunday.
  - `recurring_end_date` (`string | null`) - format: `date`; The optional final recurrence date. It must be after `recurring_start_date`.
  - `recurring_end_time` (`string | null`) - The end time for each recurring occurrence in the Organization's local time.
  - `recurring_interval_in_seconds` (`integer | null`) - Required for `simple`. Use 604800 for weekly or 1209600 for every two weeks.
  - `recurring_nth_day_in_month` (`integer | null`) - Required for `advanced`. Use 2 with weekday 4 for the second Thursday of each month.
  - `recurring_start_date` (`string | null`) - format: `date`; The first recurrence date. Supply a date that matches `recurring_day_number_of_week`.
  - `recurring_start_time` (`string | null`) - The start time for each recurring occurrence in the Organization's local time.
  - `recurring_strategy` (`string | null`) - enum: `simple`, `advanced`, `null`; Select `simple` for a fixed interval measured in seconds, such as every week or every two weeks. Select `advanced` for an occurrence such as the second Thursday of every month. Use null for a non-recurring period.
  - `room_id` (`string | null`) - format: `uuid`; The Room affected by the period.
  - `service_variant_ids` (`array`) - The ServiceVariants offered during an availability period.
    - `items` (`string`) - format: `uuid`
  - `start_time` (`string | null`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.

### Example

```json
{
  "availability_type": "unavailability",
  "clinician_id": "00000000-0000-4000-8000-000000000002",
  "end_time": "2026-01-01T10:30:00Z",
  "is_active": true,
  "is_recurring": false,
  "notes": "Team meeting",
  "start_time": "2026-01-01T10:00:00Z"
}
```

## Response `201`

The requested `AvailabilityPeriod`.

- `object`
  - `availability_type` (`string`) - enum: `availability`, `unavailability`; Whether the period makes the Clinician available or unavailable.
  - `clinician_id` (`string | null`) - format: `uuid`; The Clinician affected by the period.
  - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `end_time` (`string | null`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - `is_active` (`boolean`) - Whether the period contributes to the diary.
  - `is_recurring` (`boolean`) - Whether the period repeats. When false, use `start_time` and `end_time`; recurring fields are cleared.
  - `links` (`object`) - URLs to related resources.
    - `clinician` (`string | null`) - format: `uri`; The full URL of a related resource.
  - `notes` (`string | null`) - Internal notes about the period.
  - `object` (`any`) - Discriminator value emitted at `object`.
  - `recurring_dates_to_skip` (`array`) - Specific ISO 8601 dates on which a recurring period must not occur. For example, `["2026-02-12"]` skips the occurrence on 12 February 2026. Only dates that are today or in the future are retained.
    - `items` (`string`) - format: `date`
  - `recurring_day_number_of_week` (`integer | null`) - The ISO weekday number used by a recurring period. The values start at 1, not 0: 1 is Monday, 2 is Tuesday, 3 is Wednesday, 4 is Thursday, 5 is Friday, 6 is Saturday, and 7 is Sunday.
  - `recurring_end_date` (`string | null`) - format: `date`; The optional final date on which the recurrence can apply. It must be after `recurring_start_date`.
  - `recurring_end_time` (`string | null`) - The end time for each recurring occurrence in the Organization's local time.
  - `recurring_interval_in_seconds` (`integer | null`) - Required for the `simple` strategy. Use 604800 for weekly or 1209600 for every two weeks.
  - `recurring_nth_day_in_month` (`integer | null`) - Required for the `advanced` strategy. For example, use 2 with weekday 4 for the second Thursday of each month.
  - `recurring_start_date` (`string | null`) - format: `date`; The first date on which the recurrence can apply. Supply a date that matches `recurring_day_number_of_week`.
  - `recurring_start_time` (`string | null`) - The start time for each recurring occurrence in the Organization's local time.
  - `recurring_strategy` (`string | null`) - enum: `simple`, `advanced`, `null`; Select `simple` for a fixed interval measured in seconds, such as every week or every two weeks. Select `advanced` for an occurrence such as the second Thursday of every month. Use null for a non-recurring period.
  - `room_id` (`string | null`) - format: `uuid`; The Room affected by the period.
  - `service_variant_ids` (`array`) - The ServiceVariants offered during an availability period.
    - `items` (`string`) - format: `uuid`
  - `start_time` (`string | null`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.

### Example

```json
{
  "id": "5267a739-2a80-4eaa-80c5-4baeb6a766a9",
  "object": "availability_period",
  "availability_type": "availability",
  "clinician_id": "2b3c4d5e-6f70-489a-9bcd-ef0123456789",
  "created_at": "2026-01-01T09:00:00Z",
  "end_time": "2026-01-01T10:00:00Z",
  "is_active": true,
  "is_recurring": true,
  "links": {
    "clinician": "https://api.carebit.co/v1/clinicians/2b3c4d5e-6f70-489a-9bcd-ef0123456789"
  },
  "notes": "Please confirm the appointment by email.",
  "recurring_dates_to_skip": [
    "2026-01-01"
  ],
  "recurring_day_number_of_week": 1,
  "recurring_end_date": "2026-12-31",
  "recurring_end_time": "17:00:00",
  "recurring_interval_in_seconds": 1,
  "recurring_nth_day_in_month": 1,
  "recurring_start_date": "2026-01-01",
  "recurring_start_time": "09:00:00",
  "recurring_strategy": "simple",
  "room_id": "4d5e6f70-8192-4abc-bdef-0123456789ab",
  "service_variant_ids": [
    "6f708192-a3b4-4cde-9f01-23456789abcd"
  ],
  "start_time": "2026-01-01T09:00:00Z",
  "updated_at": "2026-01-01T09:00:00Z"
}
```

## Response `400`

The `Idempotency-Key` header is missing (`idempotency_key_required`) or exceeds 255 characters (`idempotency_key_too_long`).

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `401`

The access token is missing, invalid, expired, or revoked.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `403`

The access token lacks the required scope, or the project is disabled.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `404`

A referenced resource was not found in the Organization.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `409`

A concurrent request holds the idempotency lease (`idempotency_conflict`). Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `422`

The `Idempotency-Key` was previously used with a different request body (`idempotency_key_reused`), or the request body failed validation.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `429`

Too many requests. Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Code samples

```bash
curl -X POST "https://api.carebit.co/v1/availability_periods" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "availability_type": "unavailability",
  "clinician_id": "00000000-0000-4000-8000-000000000002",
  "end_time": "2026-01-01T10:30:00Z",
  "is_active": true,
  "is_recurring": false,
  "notes": "Team meeting",
  "start_time": "2026-01-01T10:00:00Z"
}'
```

```javascript
const response = await fetch("https://api.carebit.co/v1/availability_periods", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
  "availability_type": "unavailability",
  "clinician_id": "00000000-0000-4000-8000-000000000002",
  "end_time": "2026-01-01T10:30:00Z",
  "is_active": true,
  "is_recurring": false,
  "notes": "Team meeting",
  "start_time": "2026-01-01T10:00:00Z"
}),
});

if (!response.ok) {
  throw new Error(`Carebit API error: ${response.status}`);
}

const data = await response.json();
```

```python
import os
import requests
import uuid

response = requests.post(
    "https://api.carebit.co/v1/availability_periods",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "availability_type": "unavailability",
        "clinician_id": "00000000-0000-4000-8000-000000000002",
        "end_time": "2026-01-01T10:30:00Z",
        "is_active": True,
        "is_recurring": False,
        "notes": "Team meeting",
        "start_time": "2026-01-01T10:00:00Z"
    }
)
response.raise_for_status()
data = response.json()
```

```ruby
require "httparty"
require "json"
require "securerandom"

response = HTTParty.post(
  "https://api.carebit.co/v1/availability_periods",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}",
    "Idempotency-Key" => SecureRandom.uuid,
    "Content-Type" => "application/json"
  },
  body: {
    "availability_type" => "unavailability",
    "clinician_id" => "00000000-0000-4000-8000-000000000002",
    "end_time" => "2026-01-01T10:30:00Z",
    "is_active" => true,
    "is_recurring" => false,
    "notes" => "Team meeting",
    "start_time" => "2026-01-01T10:00:00Z"
  }.to_json
)
raise "Carebit API error: #{response.code}" unless response.success?
data = response.parsed_response
```

```php
<?php

$client = new GuzzleHttp\Client();

$response = $client->post("https://api.carebit.co/v1/availability_periods", [
    "headers" => [
      "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
      "Idempotency-Key" => bin2hex(random_bytes(16)),
    ],
    "json" => [
      "availability_type" => "unavailability",
      "clinician_id" => "00000000-0000-4000-8000-000000000002",
      "end_time" => "2026-01-01T10:30:00Z",
      "is_active" => true,
      "is_recurring" => false,
      "notes" => "Team meeting",
      "start_time" => "2026-01-01T10:00:00Z"
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```


---

# Update an availability or unavailability period

`PATCH /v1/availability_periods/:id`

Set `is_recurring` to `false` for a one-off period and supply `start_time` and `end_time`. Set `is_recurring` to `true` for a repeating period and choose `simple` or `advanced` as the `recurring_strategy`. A simple weekly Tuesday uses `recurring_strategy: "simple"`, `recurring_day_number_of_week: 2`, `recurring_interval_in_seconds: 604800`, and a Tuesday `recurring_start_date`. A simple fortnightly period uses 1209600 seconds. The second Thursday of every month uses `recurring_strategy: "advanced"`, `recurring_nth_day_in_month: 2`, `recurring_day_number_of_week: 4`, and a matching start date such as `2026-01-08`. Add `recurring_dates_to_skip: ["2026-02-12"]` to omit that specific monthly occurrence. Recurring start and end times use the Organization's local time.

**Required API scopes:** `availability_periods.update`

## Parameters

- `id` (path, `string`) (required)
- `Idempotency-Key` (header, `string`) (required) - Client-generated idempotency key. Required for every POST/PATCH write. Replay of the same key with the same body returns the stored response with an `Idempotency-Replayed: true` header. Same key + different body returns `422 idempotency_key_reused`. A duplicate that arrives while the first request is still in flight returns `409 idempotency_conflict` with `Retry-After: 1`.

## Request body (`application/json`)

- `object`
  - `availability_type` (`string`) - enum: `availability`, `unavailability`; Whether the period makes the Clinician available or unavailable.
  - `clinician_id` (`string | null`) - format: `uuid`; The Clinician affected by the period.
  - `end_time` (`string | null`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `is_active` (`boolean`) - Whether the period contributes to the diary.
  - `is_recurring` (`boolean`) - Whether the period repeats. When false, supply `start_time` and `end_time`; recurring fields are cleared.
  - `notes` (`string | null`) - Internal notes about the period.
  - `recurring_dates_to_skip` (`array`) - Specific ISO 8601 dates on which a recurring period must not occur. For example, `["2026-02-12"]` skips the occurrence on 12 February 2026. Only dates that are today or in the future are retained.
    - `items` (`string`) - format: `date`
  - `recurring_day_number_of_week` (`integer | null`) - The ISO weekday number used by a recurring period. The values start at 1, not 0: 1 is Monday, 2 is Tuesday, 3 is Wednesday, 4 is Thursday, 5 is Friday, 6 is Saturday, and 7 is Sunday.
  - `recurring_end_date` (`string | null`) - format: `date`; The optional final recurrence date. It must be after `recurring_start_date`.
  - `recurring_end_time` (`string | null`) - The end time for each recurring occurrence in the Organization's local time.
  - `recurring_interval_in_seconds` (`integer | null`) - Required for `simple`. Use 604800 for weekly or 1209600 for every two weeks.
  - `recurring_nth_day_in_month` (`integer | null`) - Required for `advanced`. Use 2 with weekday 4 for the second Thursday of each month.
  - `recurring_start_date` (`string | null`) - format: `date`; The first recurrence date. Supply a date that matches `recurring_day_number_of_week`.
  - `recurring_start_time` (`string | null`) - The start time for each recurring occurrence in the Organization's local time.
  - `recurring_strategy` (`string | null`) - enum: `simple`, `advanced`, `null`; Select `simple` for a fixed interval measured in seconds, such as every week or every two weeks. Select `advanced` for an occurrence such as the second Thursday of every month. Use null for a non-recurring period.
  - `room_id` (`string | null`) - format: `uuid`; The Room affected by the period.
  - `service_variant_ids` (`array`) - The ServiceVariants offered during an availability period.
    - `items` (`string`) - format: `uuid`
  - `start_time` (`string | null`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.

### Example

```json
{
  "notes": "Updated team meeting"
}
```

## Response `200`

The requested `AvailabilityPeriod`.

- `object`
  - `availability_type` (`string`) - enum: `availability`, `unavailability`; Whether the period makes the Clinician available or unavailable.
  - `clinician_id` (`string | null`) - format: `uuid`; The Clinician affected by the period.
  - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `end_time` (`string | null`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - `is_active` (`boolean`) - Whether the period contributes to the diary.
  - `is_recurring` (`boolean`) - Whether the period repeats. When false, use `start_time` and `end_time`; recurring fields are cleared.
  - `links` (`object`) - URLs to related resources.
    - `clinician` (`string | null`) - format: `uri`; The full URL of a related resource.
  - `notes` (`string | null`) - Internal notes about the period.
  - `object` (`any`) - Discriminator value emitted at `object`.
  - `recurring_dates_to_skip` (`array`) - Specific ISO 8601 dates on which a recurring period must not occur. For example, `["2026-02-12"]` skips the occurrence on 12 February 2026. Only dates that are today or in the future are retained.
    - `items` (`string`) - format: `date`
  - `recurring_day_number_of_week` (`integer | null`) - The ISO weekday number used by a recurring period. The values start at 1, not 0: 1 is Monday, 2 is Tuesday, 3 is Wednesday, 4 is Thursday, 5 is Friday, 6 is Saturday, and 7 is Sunday.
  - `recurring_end_date` (`string | null`) - format: `date`; The optional final date on which the recurrence can apply. It must be after `recurring_start_date`.
  - `recurring_end_time` (`string | null`) - The end time for each recurring occurrence in the Organization's local time.
  - `recurring_interval_in_seconds` (`integer | null`) - Required for the `simple` strategy. Use 604800 for weekly or 1209600 for every two weeks.
  - `recurring_nth_day_in_month` (`integer | null`) - Required for the `advanced` strategy. For example, use 2 with weekday 4 for the second Thursday of each month.
  - `recurring_start_date` (`string | null`) - format: `date`; The first date on which the recurrence can apply. Supply a date that matches `recurring_day_number_of_week`.
  - `recurring_start_time` (`string | null`) - The start time for each recurring occurrence in the Organization's local time.
  - `recurring_strategy` (`string | null`) - enum: `simple`, `advanced`, `null`; Select `simple` for a fixed interval measured in seconds, such as every week or every two weeks. Select `advanced` for an occurrence such as the second Thursday of every month. Use null for a non-recurring period.
  - `room_id` (`string | null`) - format: `uuid`; The Room affected by the period.
  - `service_variant_ids` (`array`) - The ServiceVariants offered during an availability period.
    - `items` (`string`) - format: `uuid`
  - `start_time` (`string | null`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.

### Example

```json
{
  "id": "5267a739-2a80-4eaa-80c5-4baeb6a766a9",
  "object": "availability_period",
  "availability_type": "availability",
  "clinician_id": "2b3c4d5e-6f70-489a-9bcd-ef0123456789",
  "created_at": "2026-01-01T09:00:00Z",
  "end_time": "2026-01-01T10:00:00Z",
  "is_active": true,
  "is_recurring": true,
  "links": {
    "clinician": "https://api.carebit.co/v1/clinicians/2b3c4d5e-6f70-489a-9bcd-ef0123456789"
  },
  "notes": "Please confirm the appointment by email.",
  "recurring_dates_to_skip": [
    "2026-01-01"
  ],
  "recurring_day_number_of_week": 1,
  "recurring_end_date": "2026-12-31",
  "recurring_end_time": "17:00:00",
  "recurring_interval_in_seconds": 1,
  "recurring_nth_day_in_month": 1,
  "recurring_start_date": "2026-01-01",
  "recurring_start_time": "09:00:00",
  "recurring_strategy": "simple",
  "room_id": "4d5e6f70-8192-4abc-bdef-0123456789ab",
  "service_variant_ids": [
    "6f708192-a3b4-4cde-9f01-23456789abcd"
  ],
  "start_time": "2026-01-01T09:00:00Z",
  "updated_at": "2026-01-01T09:00:00Z"
}
```

## Response `400`

The `Idempotency-Key` header is missing (`idempotency_key_required`) or exceeds 255 characters (`idempotency_key_too_long`).

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `401`

The access token is missing, invalid, expired, or revoked.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `403`

The access token lacks the required scope, or the project is disabled.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `404`

Error response.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `409`

A concurrent request holds the idempotency lease (`idempotency_conflict`). Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `422`

The `Idempotency-Key` was previously used with a different request body (`idempotency_key_reused`), or the request body failed validation.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `429`

Too many requests. Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Code samples

```bash
curl -X PATCH "https://api.carebit.co/v1/availability_periods/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "notes": "Updated team meeting"
}'
```

```javascript
const response = await fetch("https://api.carebit.co/v1/availability_periods/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
  "notes": "Updated team meeting"
}),
});

if (!response.ok) {
  throw new Error(`Carebit API error: ${response.status}`);
}

const data = await response.json();
```

```python
import os
import requests
import uuid

response = requests.patch(
    "https://api.carebit.co/v1/availability_periods/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "notes": "Updated team meeting"
    }
)
response.raise_for_status()
data = response.json()
```

```ruby
require "httparty"
require "json"
require "securerandom"

response = HTTParty.patch(
  "https://api.carebit.co/v1/availability_periods/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}",
    "Idempotency-Key" => SecureRandom.uuid,
    "Content-Type" => "application/json"
  },
  body: {
    "notes" => "Updated team meeting"
  }.to_json
)
raise "Carebit API error: #{response.code}" unless response.success?
data = response.parsed_response
```

```php
<?php

$client = new GuzzleHttp\Client();

$response = $client->patch("https://api.carebit.co/v1/availability_periods/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c", [
    "headers" => [
      "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
      "Idempotency-Key" => bin2hex(random_bytes(16)),
    ],
    "json" => [
      "notes" => "Updated team meeting"
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```


---

# Delete an availability or unavailability period

`DELETE /v1/availability_periods/:id`

**Required API scopes:** `availability_periods.delete`

## Parameters

- `id` (path, `string`) (required)

## Response `204`

No content.

## Response `401`

The access token is missing, invalid, expired, or revoked.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `403`

The access token lacks the required scope, or the project is disabled.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `404`

Error response.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `429`

Too many requests. Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Code samples

```bash
curl -X DELETE "https://api.carebit.co/v1/availability_periods/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN"
```

```javascript
const response = await fetch("https://api.carebit.co/v1/availability_periods/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c", {
  method: "DELETE",
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
  },
});

if (!response.ok) {
  throw new Error(`Carebit API error: ${response.status}`);
}

const data = await response.json();
```

```python
import os
import requests

response = requests.delete(
    "https://api.carebit.co/v1/availability_periods/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
    }
)
response.raise_for_status()
data = response.json()
```

```ruby
require "httparty"

response = HTTParty.delete(
  "https://api.carebit.co/v1/availability_periods/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}"
  }
)
raise "Carebit API error: #{response.code}" unless response.success?
data = response.parsed_response
```

```php
<?php

$client = new GuzzleHttp\Client();

$response = $client->delete("https://api.carebit.co/v1/availability_periods/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c", [
    "headers" => [
      "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```


---

# List slots that a Clinician can be booked into

`GET /v1/availability_slots`

Returns times when the Clinician can be booked for the ServiceVariant. The results account for existing Bookings, unavailability, Service duration, Clinician buffers, and Room conflicts. They include Services that patients cannot book online and do not apply the Patient Portal's minimum booking notice.

**Required API scopes:** `availability_slots.read`

## Parameters

- `clinician_id` (query, `string`) (required) - The Clinician to find slots for.
- `service_variant_id` (query, `string`) (required) - The ServiceVariant to find slots for. It determines the duration and booking rules.
- `start_date` (query, `string`) (required) - The first date to include, in ISO 8601 format (YYYY-MM-DD).
- `end_date` (query, `string`) (required) - The last date to include, in ISO 8601 format (YYYY-MM-DD). The inclusive range cannot exceed 45 days.

## Response `200`

The slots that the Clinician can be booked into.

- `any`

### Example

```json
{
  "object": "list",
  "data": [
    {
      "object": "availability_slot",
      "clinician_id": "2b3c4d5e-6f70-489a-9bcd-ef0123456789",
      "end_time": "2026-01-01T10:00:00Z",
      "location_id": "3c4d5e6f-7081-49ab-acde-f0123456789a",
      "resource_type": "clinician",
      "room_id": "4d5e6f70-8192-4abc-bdef-0123456789ab",
      "service_id": "5e6f7081-92a3-4bcd-8ef0-123456789abc",
      "service_variant_id": "6f708192-a3b4-4cde-9f01-23456789abcd",
      "start_time": "2026-01-01T09:00:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": "eyJzdGFydF90aW1lIjoiMjAyNi0wMS0wMVQwOTowMDowMFoifQ",
  "url": "/v1/availability_slots"
}
```

## Response `400`

A required parameter is missing, malformed, or outside the permitted date range.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `401`

The access token is missing, invalid, expired, or revoked.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `403`

The access token lacks the required scope, or the project is disabled.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `404`

The Clinician or ServiceVariant was not found in the Organization.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `429`

Too many requests. Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Code samples

```bash
curl -X GET "https://api.carebit.co/v1/availability_slots?clinician_id=8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c&service_variant_id=8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c&start_date=2026-01-01&end_date=2026-01-01" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN"
```

```javascript
const response = await fetch("https://api.carebit.co/v1/availability_slots?clinician_id=8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c&service_variant_id=8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c&start_date=2026-01-01&end_date=2026-01-01", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
  },
});

if (!response.ok) {
  throw new Error(`Carebit API error: ${response.status}`);
}

const data = await response.json();
```

```python
import os
import requests

response = requests.get(
    "https://api.carebit.co/v1/availability_slots?clinician_id=8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c&service_variant_id=8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c&start_date=2026-01-01&end_date=2026-01-01",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
    }
)
response.raise_for_status()
data = response.json()
```

```ruby
require "httparty"

response = HTTParty.get(
  "https://api.carebit.co/v1/availability_slots?clinician_id=8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c&service_variant_id=8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c&start_date=2026-01-01&end_date=2026-01-01",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}"
  }
)
raise "Carebit API error: #{response.code}" unless response.success?
data = response.parsed_response
```

```php
<?php

$client = new GuzzleHttp\Client();

$response = $client->get("https://api.carebit.co/v1/availability_slots?clinician_id=8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c&service_variant_id=8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c&start_date=2026-01-01&end_date=2026-01-01", [
    "headers" => [
      "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```


---

# List Bookings

`GET /v1/bookings`

Lists Bookings in the authenticated Organization. Diary queries require `start_time_from` and `start_time_to`, cannot exceed 30 days (90 days when `patient_id` is supplied), and are ordered by `start_time`. When `status` is a recall status (`awaiting_recall`, `overdue_for_recall`, `recall_expired`, or `recall_canceled`), omit the date window. Recall Bookings have no diary `start_time`, so the window is not applied; results are ordered by `recall_due_date`. `did_not_attend` still requires the date window.

**Required API scopes:** `bookings.read`

## Parameters

- `start_time_from` (query, `string`) - Inclusive lower bound for `start_time` in UTC ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ). Required for diary queries, including `did_not_attend`. Omit this parameter when `status` is a recall status.
- `start_time_to` (query, `string`) - Inclusive upper bound for `start_time` in UTC ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ). Required with `start_time_from` for diary queries, including `did_not_attend`. The range cannot exceed 30 days, or 90 days when `patient_id` is supplied. Omit this parameter when `status` is a recall status.
- `clinician_id` (query, `string`)
- `patient_id` (query, `string`) - Filter by a Patient with an active connection to the Organization. A valid connected Patient identifier permits a date range of up to 90 days.
- `status` (query, `string`) - Filter by Booking status. When `status` is `awaiting_recall`, `overdue_for_recall`, `recall_expired`, or `recall_canceled`, omit `start_time_from` and `start_time_to`. Those Bookings have no diary `start_time`. `did_not_attend` still requires the date window.
- `updated_since` (query, `string`)
- `limit` (query, `integer`) - The maximum number of items to return. Defaults to `25`; the maximum is `100`.
- `starting_after` (query, `string`) - Return items after this resource ID. You cannot use this with `cursor`.
- `cursor` (query, `string`) - The `next_cursor` value from the previous page. You cannot use this with `starting_after`.

## Response `200`

Paginated list of `Booking` objects.

- `any`

### Example

```json
{
  "object": "list",
  "data": [
    {
      "id": "92a3b4c5-d6e7-4f01-8234-56789abcdef0",
      "object": "booking",
      "canceled_at": "2026-01-01T09:00:00Z",
      "cancellation_information": "The Patient asked to cancel by phone.",
      "cancellation_reason": "abusive_behavior",
      "cancellation_source": "api",
      "clinician": {
        "id": "2b3c4d5e-6f70-489a-9bcd-ef0123456789",
        "object": "clinician",
        "created_at": "2026-01-01T09:00:00Z",
        "display_name": "Dr Alex Morgan",
        "email": "alex.morgan@example.com",
        "first_name": "Alex",
        "last_name": "Morgan",
        "links": {
          "bookings": "https://api.carebit.co/v1/bookings?clinician_id=2b3c4d5e-6f70-489a-9bcd-ef0123456789"
        },
        "medical_specialty": "Cardiology",
        "title": "Dr",
        "updated_at": "2026-01-01T09:00:00Z"
      },
      "created_at": "2026-01-01T09:00:00Z",
      "end_time": "2026-01-01T10:00:00Z",
      "information_for_patient": "<p>Please arrive 10 minutes before your appointment.</p>",
      "information_for_staff_members": "<p>The Patient has requested step-free access.</p>",
      "is_remote": false,
      "links": {
        "clinician": "https://api.carebit.co/v1/clinicians/2b3c4d5e-6f70-489a-9bcd-ef0123456789",
        "invoices": "https://api.carebit.co/v1/invoices?booking_id=92a3b4c5-d6e7-4f01-8234-56789abcdef0",
        "letters": "https://api.carebit.co/v1/letters?booking_id=92a3b4c5-d6e7-4f01-8234-56789abcdef0",
        "notes": "https://api.carebit.co/v1/notes?booking_id=92a3b4c5-d6e7-4f01-8234-56789abcdef0",
        "service": "https://api.carebit.co/v1/services/5e6f7081-92a3-4bcd-8ef0-123456789abc",
        "test_results": "https://api.carebit.co/v1/test_results?booking_id=92a3b4c5-d6e7-4f01-8234-56789abcdef0"
      },
      "location": {
        "id": "3c4d5e6f-7081-49ab-acde-f0123456789a",
        "object": "location",
        "address_line_1": "10 Harley Street",
        "address_line_2": "Marylebone",
        "city": "London",
        "country_code": "GB",
        "county": "Greater London",
        "created_at": "2026-01-01T09:00:00Z",
        "formatted_address": "10 Harley Street, Marylebone, London, W1G 9PF",
        "name": "Harley Street Clinic",
        "postcode": "W1G 9PF",
        "updated_at": "2026-01-01T09:00:00Z"
      },
      "patient": {
        "id": "1a2b3c4d-5e6f-4789-8abc-def012345678",
        "object": "patient",
        "address_line_1": "10 Harley Street",
        "address_line_2": "Marylebone",
        "city": "London",
        "country_code": "GB",
        "county": "Greater London",
        "created_at": "2026-01-01T09:00:00Z",
        "creation_source": "api",
        "date_of_birth": "1990-01-01",
        "display_name": "Dr Alex Morgan",
        "email": "alex.morgan@example.com",
        "first_name": "Alex",
        "is_opted_out_of_sms": false,
        "last_name": "Morgan",
        "mobile": "7700900123",
        "mobile_country_dial_code": "GB",
        "nhs_number": "485 777 3456",
        "phone": "2071234567",
        "phone_country_dial_code": "GB",
        "phone_number": "+44 7700 900123",
        "postcode": "W1G 9PF",
        "sex": "female",
        "title": "Dr",
        "updated_at": "2026-01-01T09:00:00Z"
      },
      "payor": {
        "id": "708192a3-b4c5-4def-8012-3456789abcde",
        "object": "payor",
        "address_line_1": "10 Harley Street",
        "address_line_2": "Marylebone",
        "alternative_payor_id": null,
        "city": "London",
        "country_code": "GB",
        "county": "Greater London",
        "created_at": "2026-01-01T09:00:00Z",
        "first_name": "Alex",
        "formatted_name": "Dr Alex Morgan",
        "formatted_payor_name": "Bupa",
        "insurance_authorization_code": "AUTH123",
        "insurance_company_id": "855e25b0-b138-48da-86ea-15162ce81f14",
        "insurance_policy_end_date": "2026-12-31",
        "insurance_policy_number": "POLICY123",
        "insurance_policy_start_date": "2026-01-01",
        "last_name": "Morgan",
        "notes": "Please confirm the appointment by email.",
        "payor_type": "insurance_company",
        "postcode": "W1G 9PF",
        "title": "Dr",
        "updated_at": "2026-01-01T09:00:00Z"
      },
      "recall_due_date": "2026-01-01",
      "remote_method": null,
      "service": {
        "id": "5e6f7081-92a3-4bcd-8ef0-123456789abc",
        "object": "service",
        "created_at": "2026-01-01T09:00:00Z",
        "description": "An initial consultation at the Harley Street Clinic.",
        "duration_minutes": 30,
        "is_bookable_online": true,
        "name": "Initial consultation",
        "service_variants": [
          {
            "id": "6f708192-a3b4-4cde-9f01-23456789abcd",
            "clinician_id": "2b3c4d5e-6f70-489a-9bcd-ef0123456789",
            "currency": "GBP",
            "description": "An initial consultation at the Harley Street Clinic.",
            "links": {
              "clinician": "https://api.carebit.co/v1/clinicians/2b3c4d5e-6f70-489a-9bcd-ef0123456789",
              "location": "https://api.carebit.co/v1/locations/3c4d5e6f-7081-49ab-acde-f0123456789a"
            },
            "location_id": "3c4d5e6f-7081-49ab-acde-f0123456789a",
            "net_price": 1,
            "permits_remote_bookings": true
          }
        ],
        "tax_rate": {
          "id": "211b60c7-ec1b-41b4-8a29-e855209bc694",
          "description": "An initial consultation at the Harley Street Clinic.",
          "percentage": 20,
          "title": "VAT"
        },
        "updated_at": "2026-01-01T09:00:00Z"
      },
      "service_variants": [
        {
          "id": "6f708192-a3b4-4cde-9f01-23456789abcd",
          "clinician_id": "2b3c4d5e-6f70-489a-9bcd-ef0123456789",
          "currency": "GBP",
          "description": "An initial consultation at the Harley Street Clinic.",
          "links": {
            "clinician": "https://api.carebit.co/v1/clinicians/2b3c4d5e-6f70-489a-9bcd-ef0123456789",
            "location": "https://api.carebit.co/v1/locations/3c4d5e6f-7081-49ab-acde-f0123456789a"
          },
          "location_id": "3c4d5e6f-7081-49ab-acde-f0123456789a",
          "net_price": 1,
          "permits_remote_bookings": true
        }
      ],
      "start_time": "2026-01-01T09:00:00Z",
      "status": "arrived",
      "updated_at": "2026-01-01T09:00:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": "eyJzdGFydF90aW1lIjoiMjAyNi0wMS0wMVQwOTowMDowMFoifQ",
  "url": "/v1/bookings"
}
```

## Response `400`

A diary date range parameter is missing, malformed, or exceeds the permitted 30-day or Patient-filtered 90-day span. Recall-status lists do not require a date range.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `401`

The access token is missing, invalid, expired, or revoked.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `403`

The access token lacks the required scope, or the project is disabled.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `404`

The supplied Patient was not found among the Organization's active Patient connections.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `429`

Too many requests. Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Code samples

```bash
curl -X GET "https://api.carebit.co/v1/bookings?start_time_from=2026-01-01T09:00:00Z&start_time_to=2026-01-31T09:00:00Z" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN"
```

```javascript
const response = await fetch("https://api.carebit.co/v1/bookings?start_time_from=2026-01-01T09:00:00Z&start_time_to=2026-01-31T09:00:00Z", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
  },
});

if (!response.ok) {
  throw new Error(`Carebit API error: ${response.status}`);
}

const data = await response.json();
```

```python
import os
import requests

response = requests.get(
    "https://api.carebit.co/v1/bookings?start_time_from=2026-01-01T09:00:00Z&start_time_to=2026-01-31T09:00:00Z",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
    }
)
response.raise_for_status()
data = response.json()
```

```ruby
require "httparty"

response = HTTParty.get(
  "https://api.carebit.co/v1/bookings?start_time_from=2026-01-01T09:00:00Z&start_time_to=2026-01-31T09:00:00Z",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}"
  }
)
raise "Carebit API error: #{response.code}" unless response.success?
data = response.parsed_response
```

```php
<?php

$client = new GuzzleHttp\Client();

$response = $client->get("https://api.carebit.co/v1/bookings?start_time_from=2026-01-01T09:00:00Z&start_time_to=2026-01-31T09:00:00Z", [
    "headers" => [
      "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```


---

# Create a Booking

`POST /v1/bookings`

**Required API scopes:** `bookings.create`

## Parameters

- `Idempotency-Key` (header, `string`) (required) - Client-generated idempotency key. Required for every POST/PATCH write. Replay of the same key with the same body returns the stored response with an `Idempotency-Replayed: true` header. Same key + different body returns `422 idempotency_key_reused`. A duplicate that arrives while the first request is still in flight returns `409 idempotency_conflict` with `Retry-After: 1`.

## Request body (`application/json`)

- `object`
  - `clinician_id` (`string | null`) - format: `uuid`; The identifier of the clinician assigned to the booking, or null when no clinician is assigned.
  - `end_time` (`string | null`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `information_for_patient` (`string | null`) - The information shown to the patient before the booking.
  - `information_for_staff_members` (`string | null`) - The internal information shown only to staff members.
  - `is_remote` (`boolean`) - Whether the Booking takes place remotely.
  - `location_id` (`string | null`) - format: `uuid`; The identifier of the location where the booking takes place, or null for a remote booking.
  - `patient_id` (`string`) - format: `uuid`; The identifier of the patient attending the booking.
  - `payor_id` (`string | null`) - format: `uuid`; The identifier of the payor responsible for the booking's charges, when different from the patient.
  - `remote_method` (`string | null`) - enum: `native_video`, `null`; The remote consultation method. `native_video` requires `is_remote` to be true.
  - `room_id` (`string | null`) - format: `uuid`; The identifier of the room assigned to the booking, when applicable.
  - `service_id` (`string`) - format: `uuid`; The identifier of the service being provided during the booking.
  - `service_variant_id` (`string`) - format: `uuid`; The identifier of the service variant selected for the booking.
  - `start_time` (`string`) - format: `date-time`; The ISO 8601 UTC time at which the booking starts.
  - `status` (`string | null`) - enum: `arrived`, `confirmed`, `did_not_attend`, `unconfirmed`, `null`; The status to assign to the Booking.

### Example

```json
{
  "clinician_id": "00000000-0000-4000-8000-000000000002",
  "end_time": "2026-01-01T10:30:00Z",
  "location_id": "00000000-0000-4000-8000-000000000003",
  "patient_id": "00000000-0000-4000-8000-000000000004",
  "service_id": "00000000-0000-4000-8000-000000000005",
  "service_variant_id": "00000000-0000-4000-8000-000000000006",
  "start_time": "2026-01-01T10:00:00Z",
  "status": "unconfirmed"
}
```

## Response `201`

Booking created.

- `object`
  - `canceled_at` (`string | null`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `cancellation_information` (`string | null`) - Additional notes recorded with the cancellation.
  - `cancellation_reason` (`string | null`) - enum: `abusive_behavior`, `booked_in_error`, `childcare_issues`, `clinician_annual_leave`, `clinician_emergency`, `clinician_schedule_change`, `colleague_unavailable`, `double_booked`, `duplicate_booking`, `equipment_issue`, `facility_unavailable`, `failed_to_pay_in_advance`, `family_emergency_illness`, `fear_or_anxiety`, `financial_concerns`, `financial_requirements_not_met`, `forgot_to_attend`, `insurance_company_not_permitted`, `insurance_coverage_issues`, `insurance_verification_failed`, `language_barrier`, `medication_interference`, `no_longer_required`, `no_response_to_recall`, `other`, `patient_deceased`, `patient_not_permitted`, `personal_emergency_illness`, `pre_booking_steps_not_completed`, `professional_discretion`, `referral_not_provided`, `relocated`, `rescheduled`, `scheduling_conflict`, `staff_issue`, `switched_to_another_clinician`, `symptoms_resolved`, `too_unwell`, `transportation_issues`, `unable_failed_to_prepare_for_booking`, `unknown`, `weather_conditions`, `wrong_clinician`, `wrong_location`, `wrong_service_type`, `null`; The reason the Booking was canceled. Required by Organizations that enforce cancellation reasons.
  - `cancellation_source` (`string | null`) - enum: `api`, `app`, `automation`, `patient`, `staff_member`, `null`; Who canceled the Booking. API cancellations use `api`.
  - `clinician` (`any`) - The clinician assigned to the booking.
  - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `end_time` (`string | null`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - `information_for_patient` (`string | null`) - The sanitized HTML shown to the patient.
  - `information_for_staff_members` (`string | null`) - The sanitized HTML shown only to staff members.
  - `is_remote` (`boolean`) - Whether the Booking takes place remotely.
  - `links` (`object`) - URLs to related resources.
    - `clinician` (`string | null`) - format: `uri`; The full URL of a related resource.
    - `invoices` (`string`) - format: `uri`; The full URL of a related resource.
    - `letters` (`string`) - format: `uri`; The full URL of a related resource.
    - `notes` (`string`) - format: `uri`; The full URL of a related resource.
    - `service` (`string | null`) - format: `uri`; The full URL of a related resource.
    - `test_results` (`string`) - format: `uri`; The full URL of a related resource.
  - `location` (`any`) - The location where the booking takes place, or null for a remote booking.
  - `object` (`any`) - Discriminator value emitted at `object`.
  - `patient` (`any`) - The patient attending the booking.
  - `payor` (`any`) - The payor responsible for the booking's charges.
  - `recall_due_date` (`string | null`) - format: `date`; The date the Patient is due to return, in ISO 8601 format (YYYY-MM-DD). Present on recall Bookings. Null on diary Bookings.
  - `remote_method` (`string | null`) - enum: `native_video`, `null`; The remote consultation method. `native_video` uses Carebit Video.
  - `service` (`any`) - The service being provided during the booking.
  - `service_variants` (`array`) - The service variants selected for the booking.
    - `items` (`object`)
      - `clinician_id` (`string | null`) - format: `uuid`; The identifier of the clinician assigned to this service variant, when the variant is clinician-specific.
      - `currency` (`string | null`) - The ISO 4217 currency code used for this service variant. Must be one of `chf`, `eur`, `gbp`, or `usd`.
      - `description` (`string | null`) - The description of this service variant.
      - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
      - `links` (`object`) - URLs to related resources.
        - `clinician` (`string | null`) - format: `uri`; The full URL of a related resource.
        - `location` (`string | null`) - format: `uri`; The full URL of a related resource.
      - `location_id` (`string | null`) - format: `uuid`; The identifier of the location assigned to this service variant, when the variant is location-specific.
      - `net_price` (`integer | null`) - The net price of this service variant, before tax, in the currency's minor units.
      - `permits_remote_bookings` (`boolean`) - Whether this service variant can be used for remote bookings.
  - `start_time` (`string | null`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `status` (`string | null`) - enum: `arrived`, `awaiting_payment`, `awaiting_recall`, `canceled`, `confirmed`, `did_not_attend`, `overdue_for_recall`, `prepared`, `recall_canceled`, `recall_expired`, `unconfirmed`, `null`; The Booking's current status. Null while Carebit is creating the record.
  - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.

### Example

```json
{
  "id": "92a3b4c5-d6e7-4f01-8234-56789abcdef0",
  "object": "booking",
  "canceled_at": "2026-01-01T09:00:00Z",
  "cancellation_information": "The Patient asked to cancel by phone.",
  "cancellation_reason": "abusive_behavior",
  "cancellation_source": "api",
  "clinician": {
    "id": "2b3c4d5e-6f70-489a-9bcd-ef0123456789",
    "object": "clinician",
    "created_at": "2026-01-01T09:00:00Z",
    "display_name": "Dr Alex Morgan",
    "email": "alex.morgan@example.com",
    "first_name": "Alex",
    "last_name": "Morgan",
    "links": {
      "bookings": "https://api.carebit.co/v1/bookings?clinician_id=2b3c4d5e-6f70-489a-9bcd-ef0123456789"
    },
    "medical_specialty": "Cardiology",
    "title": "Dr",
    "updated_at": "2026-01-01T09:00:00Z"
  },
  "created_at": "2026-01-01T09:00:00Z",
  "end_time": "2026-01-01T10:00:00Z",
  "information_for_patient": "<p>Please arrive 10 minutes before your appointment.</p>",
  "information_for_staff_members": "<p>The Patient has requested step-free access.</p>",
  "is_remote": false,
  "links": {
    "clinician": "https://api.carebit.co/v1/clinicians/2b3c4d5e-6f70-489a-9bcd-ef0123456789",
    "invoices": "https://api.carebit.co/v1/invoices?booking_id=92a3b4c5-d6e7-4f01-8234-56789abcdef0",
    "letters": "https://api.carebit.co/v1/letters?booking_id=92a3b4c5-d6e7-4f01-8234-56789abcdef0",
    "notes": "https://api.carebit.co/v1/notes?booking_id=92a3b4c5-d6e7-4f01-8234-56789abcdef0",
    "service": "https://api.carebit.co/v1/services/5e6f7081-92a3-4bcd-8ef0-123456789abc",
    "test_results": "https://api.carebit.co/v1/test_results?booking_id=92a3b4c5-d6e7-4f01-8234-56789abcdef0"
  },
  "location": {
    "id": "3c4d5e6f-7081-49ab-acde-f0123456789a",
    "object": "location",
    "address_line_1": "10 Harley Street",
    "address_line_2": "Marylebone",
    "city": "London",
    "country_code": "GB",
    "county": "Greater London",
    "created_at": "2026-01-01T09:00:00Z",
    "formatted_address": "10 Harley Street, Marylebone, London, W1G 9PF",
    "name": "Harley Street Clinic",
    "postcode": "W1G 9PF",
    "updated_at": "2026-01-01T09:00:00Z"
  },
  "patient": {
    "id": "1a2b3c4d-5e6f-4789-8abc-def012345678",
    "object": "patient",
    "address_line_1": "10 Harley Street",
    "address_line_2": "Marylebone",
    "city": "London",
    "country_code": "GB",
    "county": "Greater London",
    "created_at": "2026-01-01T09:00:00Z",
    "creation_source": "api",
    "date_of_birth": "1990-01-01",
    "display_name": "Dr Alex Morgan",
    "email": "alex.morgan@example.com",
    "first_name": "Alex",
    "is_opted_out_of_sms": false,
    "last_name": "Morgan",
    "mobile": "7700900123",
    "mobile_country_dial_code": "GB",
    "nhs_number": "485 777 3456",
    "phone": "2071234567",
    "phone_country_dial_code": "GB",
    "phone_number": "+44 7700 900123",
    "postcode": "W1G 9PF",
    "sex": "female",
    "title": "Dr",
    "updated_at": "2026-01-01T09:00:00Z"
  },
  "payor": {
    "id": "708192a3-b4c5-4def-8012-3456789abcde",
    "object": "payor",
    "address_line_1": "10 Harley Street",
    "address_line_2": "Marylebone",
    "alternative_payor_id": null,
    "city": "London",
    "country_code": "GB",
    "county": "Greater London",
    "created_at": "2026-01-01T09:00:00Z",
    "first_name": "Alex",
    "formatted_name": "Dr Alex Morgan",
    "formatted_payor_name": "Bupa",
    "insurance_authorization_code": "AUTH123",
    "insurance_company_id": "855e25b0-b138-48da-86ea-15162ce81f14",
    "insurance_policy_end_date": "2026-12-31",
    "insurance_policy_number": "POLICY123",
    "insurance_policy_start_date": "2026-01-01",
    "last_name": "Morgan",
    "notes": "Please confirm the appointment by email.",
    "payor_type": "insurance_company",
    "postcode": "W1G 9PF",
    "title": "Dr",
    "updated_at": "2026-01-01T09:00:00Z"
  },
  "recall_due_date": "2026-01-01",
  "remote_method": null,
  "service": {
    "id": "5e6f7081-92a3-4bcd-8ef0-123456789abc",
    "object": "service",
    "created_at": "2026-01-01T09:00:00Z",
    "description": "An initial consultation at the Harley Street Clinic.",
    "duration_minutes": 30,
    "is_bookable_online": true,
    "name": "Initial consultation",
    "service_variants": [
      {
        "id": "6f708192-a3b4-4cde-9f01-23456789abcd",
        "clinician_id": "2b3c4d5e-6f70-489a-9bcd-ef0123456789",
        "currency": "GBP",
        "description": "An initial consultation at the Harley Street Clinic.",
        "links": {
          "clinician": "https://api.carebit.co/v1/clinicians/2b3c4d5e-6f70-489a-9bcd-ef0123456789",
          "location": "https://api.carebit.co/v1/locations/3c4d5e6f-7081-49ab-acde-f0123456789a"
        },
        "location_id": "3c4d5e6f-7081-49ab-acde-f0123456789a",
        "net_price": 1,
        "permits_remote_bookings": true
      }
    ],
    "tax_rate": {
      "id": "211b60c7-ec1b-41b4-8a29-e855209bc694",
      "description": "An initial consultation at the Harley Street Clinic.",
      "percentage": 20,
      "title": "VAT"
    },
    "updated_at": "2026-01-01T09:00:00Z"
  },
  "service_variants": [
    {
      "id": "6f708192-a3b4-4cde-9f01-23456789abcd",
      "clinician_id": "2b3c4d5e-6f70-489a-9bcd-ef0123456789",
      "currency": "GBP",
      "description": "An initial consultation at the Harley Street Clinic.",
      "links": {
        "clinician": "https://api.carebit.co/v1/clinicians/2b3c4d5e-6f70-489a-9bcd-ef0123456789",
        "location": "https://api.carebit.co/v1/locations/3c4d5e6f-7081-49ab-acde-f0123456789a"
      },
      "location_id": "3c4d5e6f-7081-49ab-acde-f0123456789a",
      "net_price": 1,
      "permits_remote_bookings": true
    }
  ],
  "start_time": "2026-01-01T09:00:00Z",
  "status": "arrived",
  "updated_at": "2026-01-01T09:00:00Z"
}
```

## Response `400`

The `Idempotency-Key` header is missing (`idempotency_key_required`) or exceeds 255 characters (`idempotency_key_too_long`).

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `401`

The access token is missing, invalid, expired, or revoked.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `403`

The access token lacks the required scope, or the project is disabled.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `404`

A referenced resource was not found in your Organization.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `409`

A concurrent request holds the idempotency lease (`idempotency_conflict`). Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `422`

The `Idempotency-Key` was previously used with a different request body (`idempotency_key_reused`), or the request body failed validation.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `429`

Too many requests. Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Code samples

```bash
curl -X POST "https://api.carebit.co/v1/bookings" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "clinician_id": "00000000-0000-4000-8000-000000000002",
  "end_time": "2026-01-01T10:30:00Z",
  "location_id": "00000000-0000-4000-8000-000000000003",
  "patient_id": "00000000-0000-4000-8000-000000000004",
  "service_id": "00000000-0000-4000-8000-000000000005",
  "service_variant_id": "00000000-0000-4000-8000-000000000006",
  "start_time": "2026-01-01T10:00:00Z",
  "status": "unconfirmed"
}'
```

```javascript
const response = await fetch("https://api.carebit.co/v1/bookings", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
  "clinician_id": "00000000-0000-4000-8000-000000000002",
  "end_time": "2026-01-01T10:30:00Z",
  "location_id": "00000000-0000-4000-8000-000000000003",
  "patient_id": "00000000-0000-4000-8000-000000000004",
  "service_id": "00000000-0000-4000-8000-000000000005",
  "service_variant_id": "00000000-0000-4000-8000-000000000006",
  "start_time": "2026-01-01T10:00:00Z",
  "status": "unconfirmed"
}),
});

if (!response.ok) {
  throw new Error(`Carebit API error: ${response.status}`);
}

const data = await response.json();
```

```python
import os
import requests
import uuid

response = requests.post(
    "https://api.carebit.co/v1/bookings",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "clinician_id": "00000000-0000-4000-8000-000000000002",
        "end_time": "2026-01-01T10:30:00Z",
        "location_id": "00000000-0000-4000-8000-000000000003",
        "patient_id": "00000000-0000-4000-8000-000000000004",
        "service_id": "00000000-0000-4000-8000-000000000005",
        "service_variant_id": "00000000-0000-4000-8000-000000000006",
        "start_time": "2026-01-01T10:00:00Z",
        "status": "unconfirmed"
    }
)
response.raise_for_status()
data = response.json()
```

```ruby
require "httparty"
require "json"
require "securerandom"

response = HTTParty.post(
  "https://api.carebit.co/v1/bookings",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}",
    "Idempotency-Key" => SecureRandom.uuid,
    "Content-Type" => "application/json"
  },
  body: {
    "clinician_id" => "00000000-0000-4000-8000-000000000002",
    "end_time" => "2026-01-01T10:30:00Z",
    "location_id" => "00000000-0000-4000-8000-000000000003",
    "patient_id" => "00000000-0000-4000-8000-000000000004",
    "service_id" => "00000000-0000-4000-8000-000000000005",
    "service_variant_id" => "00000000-0000-4000-8000-000000000006",
    "start_time" => "2026-01-01T10:00:00Z",
    "status" => "unconfirmed"
  }.to_json
)
raise "Carebit API error: #{response.code}" unless response.success?
data = response.parsed_response
```

```php
<?php

$client = new GuzzleHttp\Client();

$response = $client->post("https://api.carebit.co/v1/bookings", [
    "headers" => [
      "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
      "Idempotency-Key" => bin2hex(random_bytes(16)),
    ],
    "json" => [
      "clinician_id" => "00000000-0000-4000-8000-000000000002",
      "end_time" => "2026-01-01T10:30:00Z",
      "location_id" => "00000000-0000-4000-8000-000000000003",
      "patient_id" => "00000000-0000-4000-8000-000000000004",
      "service_id" => "00000000-0000-4000-8000-000000000005",
      "service_variant_id" => "00000000-0000-4000-8000-000000000006",
      "start_time" => "2026-01-01T10:00:00Z",
      "status" => "unconfirmed"
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```


---

# Cancel a Booking

`POST /v1/bookings/:booking_id/cancellations`

Cancels a Booking through the same path as a StaffMember cancellation. Requires `bookings.cancel`; `bookings.update` does not grant this endpoint. `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. Canceling a diary Booking emits `booking.canceled`. Canceling a recall Booking sets status to `recall_canceled` and does not emit that event.

**Required API scopes:** `bookings.cancel`

## Parameters

- `booking_id` (path, `string`) (required)
- `Idempotency-Key` (header, `string`) (required) - Client-generated idempotency key. Required for every POST/PATCH write. Replay of the same key with the same body returns the stored response with an `Idempotency-Replayed: true` header. Same key + different body returns `422 idempotency_key_reused`. A duplicate that arrives while the first request is still in flight returns `409 idempotency_conflict` with `Retry-After: 1`.

## Request body (`application/json`)

- `object`
  - `cancellation_information` (`string | null`) - Additional notes recorded with the cancellation.
  - `cancellation_reason` (`string | null`) - enum: `abusive_behavior`, `booked_in_error`, `childcare_issues`, `clinician_annual_leave`, `clinician_emergency`, `clinician_schedule_change`, `colleague_unavailable`, `double_booked`, `duplicate_booking`, `equipment_issue`, `facility_unavailable`, `failed_to_pay_in_advance`, `family_emergency_illness`, `fear_or_anxiety`, `financial_concerns`, `financial_requirements_not_met`, `forgot_to_attend`, `insurance_company_not_permitted`, `insurance_coverage_issues`, `insurance_verification_failed`, `language_barrier`, `medication_interference`, `no_longer_required`, `no_response_to_recall`, `other`, `patient_deceased`, `patient_not_permitted`, `personal_emergency_illness`, `pre_booking_steps_not_completed`, `professional_discretion`, `referral_not_provided`, `relocated`, `rescheduled`, `scheduling_conflict`, `staff_issue`, `switched_to_another_clinician`, `symptoms_resolved`, `too_unwell`, `transportation_issues`, `unable_failed_to_prepare_for_booking`, `unknown`, `weather_conditions`, `wrong_clinician`, `wrong_location`, `wrong_service_type`, `null`; The reason the Booking is being canceled. Required when the Organization requires cancellation reasons.

### Example

```json
{
  "cancellation_information": "The Patient asked to cancel by phone.",
  "cancellation_reason": "booked_in_error"
}
```

## Response `200`

The requested `Booking`.

- `object`
  - `canceled_at` (`string | null`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `cancellation_information` (`string | null`) - Additional notes recorded with the cancellation.
  - `cancellation_reason` (`string | null`) - enum: `abusive_behavior`, `booked_in_error`, `childcare_issues`, `clinician_annual_leave`, `clinician_emergency`, `clinician_schedule_change`, `colleague_unavailable`, `double_booked`, `duplicate_booking`, `equipment_issue`, `facility_unavailable`, `failed_to_pay_in_advance`, `family_emergency_illness`, `fear_or_anxiety`, `financial_concerns`, `financial_requirements_not_met`, `forgot_to_attend`, `insurance_company_not_permitted`, `insurance_coverage_issues`, `insurance_verification_failed`, `language_barrier`, `medication_interference`, `no_longer_required`, `no_response_to_recall`, `other`, `patient_deceased`, `patient_not_permitted`, `personal_emergency_illness`, `pre_booking_steps_not_completed`, `professional_discretion`, `referral_not_provided`, `relocated`, `rescheduled`, `scheduling_conflict`, `staff_issue`, `switched_to_another_clinician`, `symptoms_resolved`, `too_unwell`, `transportation_issues`, `unable_failed_to_prepare_for_booking`, `unknown`, `weather_conditions`, `wrong_clinician`, `wrong_location`, `wrong_service_type`, `null`; The reason the Booking was canceled. Required by Organizations that enforce cancellation reasons.
  - `cancellation_source` (`string | null`) - enum: `api`, `app`, `automation`, `patient`, `staff_member`, `null`; Who canceled the Booking. API cancellations use `api`.
  - `clinician` (`any`) - The clinician assigned to the booking.
  - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `end_time` (`string | null`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - `information_for_patient` (`string | null`) - The sanitized HTML shown to the patient.
  - `information_for_staff_members` (`string | null`) - The sanitized HTML shown only to staff members.
  - `is_remote` (`boolean`) - Whether the Booking takes place remotely.
  - `links` (`object`) - URLs to related resources.
    - `clinician` (`string | null`) - format: `uri`; The full URL of a related resource.
    - `invoices` (`string`) - format: `uri`; The full URL of a related resource.
    - `letters` (`string`) - format: `uri`; The full URL of a related resource.
    - `notes` (`string`) - format: `uri`; The full URL of a related resource.
    - `service` (`string | null`) - format: `uri`; The full URL of a related resource.
    - `test_results` (`string`) - format: `uri`; The full URL of a related resource.
  - `location` (`any`) - The location where the booking takes place, or null for a remote booking.
  - `object` (`any`) - Discriminator value emitted at `object`.
  - `patient` (`any`) - The patient attending the booking.
  - `payor` (`any`) - The payor responsible for the booking's charges.
  - `recall_due_date` (`string | null`) - format: `date`; The date the Patient is due to return, in ISO 8601 format (YYYY-MM-DD). Present on recall Bookings. Null on diary Bookings.
  - `remote_method` (`string | null`) - enum: `native_video`, `null`; The remote consultation method. `native_video` uses Carebit Video.
  - `service` (`any`) - The service being provided during the booking.
  - `service_variants` (`array`) - The service variants selected for the booking.
    - `items` (`object`)
      - `clinician_id` (`string | null`) - format: `uuid`; The identifier of the clinician assigned to this service variant, when the variant is clinician-specific.
      - `currency` (`string | null`) - The ISO 4217 currency code used for this service variant. Must be one of `chf`, `eur`, `gbp`, or `usd`.
      - `description` (`string | null`) - The description of this service variant.
      - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
      - `links` (`object`) - URLs to related resources.
        - `clinician` (`string | null`) - format: `uri`; The full URL of a related resource.
        - `location` (`string | null`) - format: `uri`; The full URL of a related resource.
      - `location_id` (`string | null`) - format: `uuid`; The identifier of the location assigned to this service variant, when the variant is location-specific.
      - `net_price` (`integer | null`) - The net price of this service variant, before tax, in the currency's minor units.
      - `permits_remote_bookings` (`boolean`) - Whether this service variant can be used for remote bookings.
  - `start_time` (`string | null`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `status` (`string | null`) - enum: `arrived`, `awaiting_payment`, `awaiting_recall`, `canceled`, `confirmed`, `did_not_attend`, `overdue_for_recall`, `prepared`, `recall_canceled`, `recall_expired`, `unconfirmed`, `null`; The Booking's current status. Null while Carebit is creating the record.
  - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.

### Example

```json
{
  "id": "92a3b4c5-d6e7-4f01-8234-56789abcdef0",
  "object": "booking",
  "canceled_at": "2026-01-01T09:00:00Z",
  "cancellation_information": "The Patient asked to cancel by phone.",
  "cancellation_reason": "abusive_behavior",
  "cancellation_source": "api",
  "clinician": {
    "id": "2b3c4d5e-6f70-489a-9bcd-ef0123456789",
    "object": "clinician",
    "created_at": "2026-01-01T09:00:00Z",
    "display_name": "Dr Alex Morgan",
    "email": "alex.morgan@example.com",
    "first_name": "Alex",
    "last_name": "Morgan",
    "links": {
      "bookings": "https://api.carebit.co/v1/bookings?clinician_id=2b3c4d5e-6f70-489a-9bcd-ef0123456789"
    },
    "medical_specialty": "Cardiology",
    "title": "Dr",
    "updated_at": "2026-01-01T09:00:00Z"
  },
  "created_at": "2026-01-01T09:00:00Z",
  "end_time": "2026-01-01T10:00:00Z",
  "information_for_patient": "<p>Please arrive 10 minutes before your appointment.</p>",
  "information_for_staff_members": "<p>The Patient has requested step-free access.</p>",
  "is_remote": false,
  "links": {
    "clinician": "https://api.carebit.co/v1/clinicians/2b3c4d5e-6f70-489a-9bcd-ef0123456789",
    "invoices": "https://api.carebit.co/v1/invoices?booking_id=92a3b4c5-d6e7-4f01-8234-56789abcdef0",
    "letters": "https://api.carebit.co/v1/letters?booking_id=92a3b4c5-d6e7-4f01-8234-56789abcdef0",
    "notes": "https://api.carebit.co/v1/notes?booking_id=92a3b4c5-d6e7-4f01-8234-56789abcdef0",
    "service": "https://api.carebit.co/v1/services/5e6f7081-92a3-4bcd-8ef0-123456789abc",
    "test_results": "https://api.carebit.co/v1/test_results?booking_id=92a3b4c5-d6e7-4f01-8234-56789abcdef0"
  },
  "location": {
    "id": "3c4d5e6f-7081-49ab-acde-f0123456789a",
    "object": "location",
    "address_line_1": "10 Harley Street",
    "address_line_2": "Marylebone",
    "city": "London",
    "country_code": "GB",
    "county": "Greater London",
    "created_at": "2026-01-01T09:00:00Z",
    "formatted_address": "10 Harley Street, Marylebone, London, W1G 9PF",
    "name": "Harley Street Clinic",
    "postcode": "W1G 9PF",
    "updated_at": "2026-01-01T09:00:00Z"
  },
  "patient": {
    "id": "1a2b3c4d-5e6f-4789-8abc-def012345678",
    "object": "patient",
    "address_line_1": "10 Harley Street",
    "address_line_2": "Marylebone",
    "city": "London",
    "country_code": "GB",
    "county": "Greater London",
    "created_at": "2026-01-01T09:00:00Z",
    "creation_source": "api",
    "date_of_birth": "1990-01-01",
    "display_name": "Dr Alex Morgan",
    "email": "alex.morgan@example.com",
    "first_name": "Alex",
    "is_opted_out_of_sms": false,
    "last_name": "Morgan",
    "mobile": "7700900123",
    "mobile_country_dial_code": "GB",
    "nhs_number": "485 777 3456",
    "phone": "2071234567",
    "phone_country_dial_code": "GB",
    "phone_number": "+44 7700 900123",
    "postcode": "W1G 9PF",
    "sex": "female",
    "title": "Dr",
    "updated_at": "2026-01-01T09:00:00Z"
  },
  "payor": {
    "id": "708192a3-b4c5-4def-8012-3456789abcde",
    "object": "payor",
    "address_line_1": "10 Harley Street",
    "address_line_2": "Marylebone",
    "alternative_payor_id": null,
    "city": "London",
    "country_code": "GB",
    "county": "Greater London",
    "created_at": "2026-01-01T09:00:00Z",
    "first_name": "Alex",
    "formatted_name": "Dr Alex Morgan",
    "formatted_payor_name": "Bupa",
    "insurance_authorization_code": "AUTH123",
    "insurance_company_id": "855e25b0-b138-48da-86ea-15162ce81f14",
    "insurance_policy_end_date": "2026-12-31",
    "insurance_policy_number": "POLICY123",
    "insurance_policy_start_date": "2026-01-01",
    "last_name": "Morgan",
    "notes": "Please confirm the appointment by email.",
    "payor_type": "insurance_company",
    "postcode": "W1G 9PF",
    "title": "Dr",
    "updated_at": "2026-01-01T09:00:00Z"
  },
  "recall_due_date": "2026-01-01",
  "remote_method": null,
  "service": {
    "id": "5e6f7081-92a3-4bcd-8ef0-123456789abc",
    "object": "service",
    "created_at": "2026-01-01T09:00:00Z",
    "description": "An initial consultation at the Harley Street Clinic.",
    "duration_minutes": 30,
    "is_bookable_online": true,
    "name": "Initial consultation",
    "service_variants": [
      {
        "id": "6f708192-a3b4-4cde-9f01-23456789abcd",
        "clinician_id": "2b3c4d5e-6f70-489a-9bcd-ef0123456789",
        "currency": "GBP",
        "description": "An initial consultation at the Harley Street Clinic.",
        "links": {
          "clinician": "https://api.carebit.co/v1/clinicians/2b3c4d5e-6f70-489a-9bcd-ef0123456789",
          "location": "https://api.carebit.co/v1/locations/3c4d5e6f-7081-49ab-acde-f0123456789a"
        },
        "location_id": "3c4d5e6f-7081-49ab-acde-f0123456789a",
        "net_price": 1,
        "permits_remote_bookings": true
      }
    ],
    "tax_rate": {
      "id": "211b60c7-ec1b-41b4-8a29-e855209bc694",
      "description": "An initial consultation at the Harley Street Clinic.",
      "percentage": 20,
      "title": "VAT"
    },
    "updated_at": "2026-01-01T09:00:00Z"
  },
  "service_variants": [
    {
      "id": "6f708192-a3b4-4cde-9f01-23456789abcd",
      "clinician_id": "2b3c4d5e-6f70-489a-9bcd-ef0123456789",
      "currency": "GBP",
      "description": "An initial consultation at the Harley Street Clinic.",
      "links": {
        "clinician": "https://api.carebit.co/v1/clinicians/2b3c4d5e-6f70-489a-9bcd-ef0123456789",
        "location": "https://api.carebit.co/v1/locations/3c4d5e6f-7081-49ab-acde-f0123456789a"
      },
      "location_id": "3c4d5e6f-7081-49ab-acde-f0123456789a",
      "net_price": 1,
      "permits_remote_bookings": true
    }
  ],
  "start_time": "2026-01-01T09:00:00Z",
  "status": "arrived",
  "updated_at": "2026-01-01T09:00:00Z"
}
```

## Response `400`

The `Idempotency-Key` header is missing (`idempotency_key_required`) or exceeds 255 characters (`idempotency_key_too_long`).

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `401`

The access token is missing, invalid, expired, or revoked.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `403`

The access token lacks the required scope, or the project is disabled.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `404`

Error response.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `409`

A concurrent request holds the idempotency lease (`idempotency_conflict`). Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `422`

The Booking cannot be canceled from its current status, or `cancellation_reason` is missing or invalid.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `429`

Too many requests. Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Code samples

```bash
curl -X POST "https://api.carebit.co/v1/bookings/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c/cancellations" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "cancellation_information": "The Patient asked to cancel by phone.",
  "cancellation_reason": "booked_in_error"
}'
```

```javascript
const response = await fetch("https://api.carebit.co/v1/bookings/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c/cancellations", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
  "cancellation_information": "The Patient asked to cancel by phone.",
  "cancellation_reason": "booked_in_error"
}),
});

if (!response.ok) {
  throw new Error(`Carebit API error: ${response.status}`);
}

const data = await response.json();
```

```python
import os
import requests
import uuid

response = requests.post(
    "https://api.carebit.co/v1/bookings/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c/cancellations",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "cancellation_information": "The Patient asked to cancel by phone.",
        "cancellation_reason": "booked_in_error"
    }
)
response.raise_for_status()
data = response.json()
```

```ruby
require "httparty"
require "json"
require "securerandom"

response = HTTParty.post(
  "https://api.carebit.co/v1/bookings/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c/cancellations",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}",
    "Idempotency-Key" => SecureRandom.uuid,
    "Content-Type" => "application/json"
  },
  body: {
    "cancellation_information" => "The Patient asked to cancel by phone.",
    "cancellation_reason" => "booked_in_error"
  }.to_json
)
raise "Carebit API error: #{response.code}" unless response.success?
data = response.parsed_response
```

```php
<?php

$client = new GuzzleHttp\Client();

$response = $client->post("https://api.carebit.co/v1/bookings/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c/cancellations", [
    "headers" => [
      "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
      "Idempotency-Key" => bin2hex(random_bytes(16)),
    ],
    "json" => [
      "cancellation_information" => "The Patient asked to cancel by phone.",
      "cancellation_reason" => "booked_in_error"
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```


---

# Get a Booking

`GET /v1/bookings/:id`

**Required API scopes:** `bookings.read`

## Parameters

- `id` (path, `string`) (required)

## Response `200`

The requested `Booking`.

- `object`
  - `canceled_at` (`string | null`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `cancellation_information` (`string | null`) - Additional notes recorded with the cancellation.
  - `cancellation_reason` (`string | null`) - enum: `abusive_behavior`, `booked_in_error`, `childcare_issues`, `clinician_annual_leave`, `clinician_emergency`, `clinician_schedule_change`, `colleague_unavailable`, `double_booked`, `duplicate_booking`, `equipment_issue`, `facility_unavailable`, `failed_to_pay_in_advance`, `family_emergency_illness`, `fear_or_anxiety`, `financial_concerns`, `financial_requirements_not_met`, `forgot_to_attend`, `insurance_company_not_permitted`, `insurance_coverage_issues`, `insurance_verification_failed`, `language_barrier`, `medication_interference`, `no_longer_required`, `no_response_to_recall`, `other`, `patient_deceased`, `patient_not_permitted`, `personal_emergency_illness`, `pre_booking_steps_not_completed`, `professional_discretion`, `referral_not_provided`, `relocated`, `rescheduled`, `scheduling_conflict`, `staff_issue`, `switched_to_another_clinician`, `symptoms_resolved`, `too_unwell`, `transportation_issues`, `unable_failed_to_prepare_for_booking`, `unknown`, `weather_conditions`, `wrong_clinician`, `wrong_location`, `wrong_service_type`, `null`; The reason the Booking was canceled. Required by Organizations that enforce cancellation reasons.
  - `cancellation_source` (`string | null`) - enum: `api`, `app`, `automation`, `patient`, `staff_member`, `null`; Who canceled the Booking. API cancellations use `api`.
  - `clinician` (`any`) - The clinician assigned to the booking.
  - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `end_time` (`string | null`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - `information_for_patient` (`string | null`) - The sanitized HTML shown to the patient.
  - `information_for_staff_members` (`string | null`) - The sanitized HTML shown only to staff members.
  - `is_remote` (`boolean`) - Whether the Booking takes place remotely.
  - `links` (`object`) - URLs to related resources.
    - `clinician` (`string | null`) - format: `uri`; The full URL of a related resource.
    - `invoices` (`string`) - format: `uri`; The full URL of a related resource.
    - `letters` (`string`) - format: `uri`; The full URL of a related resource.
    - `notes` (`string`) - format: `uri`; The full URL of a related resource.
    - `service` (`string | null`) - format: `uri`; The full URL of a related resource.
    - `test_results` (`string`) - format: `uri`; The full URL of a related resource.
  - `location` (`any`) - The location where the booking takes place, or null for a remote booking.
  - `object` (`any`) - Discriminator value emitted at `object`.
  - `patient` (`any`) - The patient attending the booking.
  - `payor` (`any`) - The payor responsible for the booking's charges.
  - `recall_due_date` (`string | null`) - format: `date`; The date the Patient is due to return, in ISO 8601 format (YYYY-MM-DD). Present on recall Bookings. Null on diary Bookings.
  - `remote_method` (`string | null`) - enum: `native_video`, `null`; The remote consultation method. `native_video` uses Carebit Video.
  - `service` (`any`) - The service being provided during the booking.
  - `service_variants` (`array`) - The service variants selected for the booking.
    - `items` (`object`)
      - `clinician_id` (`string | null`) - format: `uuid`; The identifier of the clinician assigned to this service variant, when the variant is clinician-specific.
      - `currency` (`string | null`) - The ISO 4217 currency code used for this service variant. Must be one of `chf`, `eur`, `gbp`, or `usd`.
      - `description` (`string | null`) - The description of this service variant.
      - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
      - `links` (`object`) - URLs to related resources.
        - `clinician` (`string | null`) - format: `uri`; The full URL of a related resource.
        - `location` (`string | null`) - format: `uri`; The full URL of a related resource.
      - `location_id` (`string | null`) - format: `uuid`; The identifier of the location assigned to this service variant, when the variant is location-specific.
      - `net_price` (`integer | null`) - The net price of this service variant, before tax, in the currency's minor units.
      - `permits_remote_bookings` (`boolean`) - Whether this service variant can be used for remote bookings.
  - `start_time` (`string | null`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `status` (`string | null`) - enum: `arrived`, `awaiting_payment`, `awaiting_recall`, `canceled`, `confirmed`, `did_not_attend`, `overdue_for_recall`, `prepared`, `recall_canceled`, `recall_expired`, `unconfirmed`, `null`; The Booking's current status. Null while Carebit is creating the record.
  - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.

### Example

```json
{
  "id": "92a3b4c5-d6e7-4f01-8234-56789abcdef0",
  "object": "booking",
  "canceled_at": "2026-01-01T09:00:00Z",
  "cancellation_information": "The Patient asked to cancel by phone.",
  "cancellation_reason": "abusive_behavior",
  "cancellation_source": "api",
  "clinician": {
    "id": "2b3c4d5e-6f70-489a-9bcd-ef0123456789",
    "object": "clinician",
    "created_at": "2026-01-01T09:00:00Z",
    "display_name": "Dr Alex Morgan",
    "email": "alex.morgan@example.com",
    "first_name": "Alex",
    "last_name": "Morgan",
    "links": {
      "bookings": "https://api.carebit.co/v1/bookings?clinician_id=2b3c4d5e-6f70-489a-9bcd-ef0123456789"
    },
    "medical_specialty": "Cardiology",
    "title": "Dr",
    "updated_at": "2026-01-01T09:00:00Z"
  },
  "created_at": "2026-01-01T09:00:00Z",
  "end_time": "2026-01-01T10:00:00Z",
  "information_for_patient": "<p>Please arrive 10 minutes before your appointment.</p>",
  "information_for_staff_members": "<p>The Patient has requested step-free access.</p>",
  "is_remote": false,
  "links": {
    "clinician": "https://api.carebit.co/v1/clinicians/2b3c4d5e-6f70-489a-9bcd-ef0123456789",
    "invoices": "https://api.carebit.co/v1/invoices?booking_id=92a3b4c5-d6e7-4f01-8234-56789abcdef0",
    "letters": "https://api.carebit.co/v1/letters?booking_id=92a3b4c5-d6e7-4f01-8234-56789abcdef0",
    "notes": "https://api.carebit.co/v1/notes?booking_id=92a3b4c5-d6e7-4f01-8234-56789abcdef0",
    "service": "https://api.carebit.co/v1/services/5e6f7081-92a3-4bcd-8ef0-123456789abc",
    "test_results": "https://api.carebit.co/v1/test_results?booking_id=92a3b4c5-d6e7-4f01-8234-56789abcdef0"
  },
  "location": {
    "id": "3c4d5e6f-7081-49ab-acde-f0123456789a",
    "object": "location",
    "address_line_1": "10 Harley Street",
    "address_line_2": "Marylebone",
    "city": "London",
    "country_code": "GB",
    "county": "Greater London",
    "created_at": "2026-01-01T09:00:00Z",
    "formatted_address": "10 Harley Street, Marylebone, London, W1G 9PF",
    "name": "Harley Street Clinic",
    "postcode": "W1G 9PF",
    "updated_at": "2026-01-01T09:00:00Z"
  },
  "patient": {
    "id": "1a2b3c4d-5e6f-4789-8abc-def012345678",
    "object": "patient",
    "address_line_1": "10 Harley Street",
    "address_line_2": "Marylebone",
    "city": "London",
    "country_code": "GB",
    "county": "Greater London",
    "created_at": "2026-01-01T09:00:00Z",
    "creation_source": "api",
    "date_of_birth": "1990-01-01",
    "display_name": "Dr Alex Morgan",
    "email": "alex.morgan@example.com",
    "first_name": "Alex",
    "is_opted_out_of_sms": false,
    "last_name": "Morgan",
    "mobile": "7700900123",
    "mobile_country_dial_code": "GB",
    "nhs_number": "485 777 3456",
    "phone": "2071234567",
    "phone_country_dial_code": "GB",
    "phone_number": "+44 7700 900123",
    "postcode": "W1G 9PF",
    "sex": "female",
    "title": "Dr",
    "updated_at": "2026-01-01T09:00:00Z"
  },
  "payor": {
    "id": "708192a3-b4c5-4def-8012-3456789abcde",
    "object": "payor",
    "address_line_1": "10 Harley Street",
    "address_line_2": "Marylebone",
    "alternative_payor_id": null,
    "city": "London",
    "country_code": "GB",
    "county": "Greater London",
    "created_at": "2026-01-01T09:00:00Z",
    "first_name": "Alex",
    "formatted_name": "Dr Alex Morgan",
    "formatted_payor_name": "Bupa",
    "insurance_authorization_code": "AUTH123",
    "insurance_company_id": "855e25b0-b138-48da-86ea-15162ce81f14",
    "insurance_policy_end_date": "2026-12-31",
    "insurance_policy_number": "POLICY123",
    "insurance_policy_start_date": "2026-01-01",
    "last_name": "Morgan",
    "notes": "Please confirm the appointment by email.",
    "payor_type": "insurance_company",
    "postcode": "W1G 9PF",
    "title": "Dr",
    "updated_at": "2026-01-01T09:00:00Z"
  },
  "recall_due_date": "2026-01-01",
  "remote_method": null,
  "service": {
    "id": "5e6f7081-92a3-4bcd-8ef0-123456789abc",
    "object": "service",
    "created_at": "2026-01-01T09:00:00Z",
    "description": "An initial consultation at the Harley Street Clinic.",
    "duration_minutes": 30,
    "is_bookable_online": true,
    "name": "Initial consultation",
    "service_variants": [
      {
        "id": "6f708192-a3b4-4cde-9f01-23456789abcd",
        "clinician_id": "2b3c4d5e-6f70-489a-9bcd-ef0123456789",
        "currency": "GBP",
        "description": "An initial consultation at the Harley Street Clinic.",
        "links": {
          "clinician": "https://api.carebit.co/v1/clinicians/2b3c4d5e-6f70-489a-9bcd-ef0123456789",
          "location": "https://api.carebit.co/v1/locations/3c4d5e6f-7081-49ab-acde-f0123456789a"
        },
        "location_id": "3c4d5e6f-7081-49ab-acde-f0123456789a",
        "net_price": 1,
        "permits_remote_bookings": true
      }
    ],
    "tax_rate": {
      "id": "211b60c7-ec1b-41b4-8a29-e855209bc694",
      "description": "An initial consultation at the Harley Street Clinic.",
      "percentage": 20,
      "title": "VAT"
    },
    "updated_at": "2026-01-01T09:00:00Z"
  },
  "service_variants": [
    {
      "id": "6f708192-a3b4-4cde-9f01-23456789abcd",
      "clinician_id": "2b3c4d5e-6f70-489a-9bcd-ef0123456789",
      "currency": "GBP",
      "description": "An initial consultation at the Harley Street Clinic.",
      "links": {
        "clinician": "https://api.carebit.co/v1/clinicians/2b3c4d5e-6f70-489a-9bcd-ef0123456789",
        "location": "https://api.carebit.co/v1/locations/3c4d5e6f-7081-49ab-acde-f0123456789a"
      },
      "location_id": "3c4d5e6f-7081-49ab-acde-f0123456789a",
      "net_price": 1,
      "permits_remote_bookings": true
    }
  ],
  "start_time": "2026-01-01T09:00:00Z",
  "status": "arrived",
  "updated_at": "2026-01-01T09:00:00Z"
}
```

## Response `401`

The access token is missing, invalid, expired, or revoked.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `403`

The access token lacks the required scope, or the project is disabled.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `404`

Error response.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `429`

Too many requests. Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Code samples

```bash
curl -X GET "https://api.carebit.co/v1/bookings/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN"
```

```javascript
const response = await fetch("https://api.carebit.co/v1/bookings/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
  },
});

if (!response.ok) {
  throw new Error(`Carebit API error: ${response.status}`);
}

const data = await response.json();
```

```python
import os
import requests

response = requests.get(
    "https://api.carebit.co/v1/bookings/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
    }
)
response.raise_for_status()
data = response.json()
```

```ruby
require "httparty"

response = HTTParty.get(
  "https://api.carebit.co/v1/bookings/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}"
  }
)
raise "Carebit API error: #{response.code}" unless response.success?
data = response.parsed_response
```

```php
<?php

$client = new GuzzleHttp\Client();

$response = $client->get("https://api.carebit.co/v1/bookings/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c", [
    "headers" => [
      "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```


---

# Update a Booking

`PATCH /v1/bookings/:id`

Reschedule, confirm, arrive, mark as did not attend, or update Booking details. To cancel a Booking, use `POST /v1/bookings/{booking_id}/cancellations`, which requires `bookings.cancel`.

**Required API scopes:** `bookings.update`

## Parameters

- `id` (path, `string`) (required)
- `Idempotency-Key` (header, `string`) (required) - Client-generated idempotency key. Required for every POST/PATCH write. Replay of the same key with the same body returns the stored response with an `Idempotency-Replayed: true` header. Same key + different body returns `422 idempotency_key_reused`. A duplicate that arrives while the first request is still in flight returns `409 idempotency_conflict` with `Retry-After: 1`.

## Request body (`application/json`)

- `object`
  - `clinician_id` (`string | null`) - format: `uuid`; The identifier of the clinician assigned to the booking, or null when no clinician is assigned.
  - `end_time` (`string | null`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `information_for_patient` (`string | null`) - The information shown to the patient before the booking.
  - `information_for_staff_members` (`string | null`) - The internal information shown only to staff members.
  - `is_remote` (`boolean`) - Whether the Booking takes place remotely.
  - `location_id` (`string | null`) - format: `uuid`; The identifier of the location where the booking takes place, or null for a remote booking.
  - `patient_id` (`string`) - format: `uuid`; The identifier of the patient attending the booking.
  - `payor_id` (`string | null`) - format: `uuid`; The identifier of the payor responsible for the booking's charges, when different from the patient.
  - `remote_method` (`string | null`) - enum: `native_video`, `null`; The remote consultation method. `native_video` requires `is_remote` to be true.
  - `room_id` (`string | null`) - format: `uuid`; The identifier of the room assigned to the booking, when applicable.
  - `service_id` (`string`) - format: `uuid`; The identifier of the service being provided during the booking.
  - `service_variant_id` (`string`) - format: `uuid`; The identifier of the service variant selected for the booking.
  - `start_time` (`string`) - format: `date-time`; The ISO 8601 UTC time at which the booking starts.
  - `status` (`string | null`) - enum: `arrived`, `confirmed`, `did_not_attend`, `unconfirmed`, `null`; The status to assign to the Booking.

### Example

```json
{
  "status": "confirmed"
}
```

## Response `200`

The requested `Booking`.

- `object`
  - `canceled_at` (`string | null`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `cancellation_information` (`string | null`) - Additional notes recorded with the cancellation.
  - `cancellation_reason` (`string | null`) - enum: `abusive_behavior`, `booked_in_error`, `childcare_issues`, `clinician_annual_leave`, `clinician_emergency`, `clinician_schedule_change`, `colleague_unavailable`, `double_booked`, `duplicate_booking`, `equipment_issue`, `facility_unavailable`, `failed_to_pay_in_advance`, `family_emergency_illness`, `fear_or_anxiety`, `financial_concerns`, `financial_requirements_not_met`, `forgot_to_attend`, `insurance_company_not_permitted`, `insurance_coverage_issues`, `insurance_verification_failed`, `language_barrier`, `medication_interference`, `no_longer_required`, `no_response_to_recall`, `other`, `patient_deceased`, `patient_not_permitted`, `personal_emergency_illness`, `pre_booking_steps_not_completed`, `professional_discretion`, `referral_not_provided`, `relocated`, `rescheduled`, `scheduling_conflict`, `staff_issue`, `switched_to_another_clinician`, `symptoms_resolved`, `too_unwell`, `transportation_issues`, `unable_failed_to_prepare_for_booking`, `unknown`, `weather_conditions`, `wrong_clinician`, `wrong_location`, `wrong_service_type`, `null`; The reason the Booking was canceled. Required by Organizations that enforce cancellation reasons.
  - `cancellation_source` (`string | null`) - enum: `api`, `app`, `automation`, `patient`, `staff_member`, `null`; Who canceled the Booking. API cancellations use `api`.
  - `clinician` (`any`) - The clinician assigned to the booking.
  - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `end_time` (`string | null`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - `information_for_patient` (`string | null`) - The sanitized HTML shown to the patient.
  - `information_for_staff_members` (`string | null`) - The sanitized HTML shown only to staff members.
  - `is_remote` (`boolean`) - Whether the Booking takes place remotely.
  - `links` (`object`) - URLs to related resources.
    - `clinician` (`string | null`) - format: `uri`; The full URL of a related resource.
    - `invoices` (`string`) - format: `uri`; The full URL of a related resource.
    - `letters` (`string`) - format: `uri`; The full URL of a related resource.
    - `notes` (`string`) - format: `uri`; The full URL of a related resource.
    - `service` (`string | null`) - format: `uri`; The full URL of a related resource.
    - `test_results` (`string`) - format: `uri`; The full URL of a related resource.
  - `location` (`any`) - The location where the booking takes place, or null for a remote booking.
  - `object` (`any`) - Discriminator value emitted at `object`.
  - `patient` (`any`) - The patient attending the booking.
  - `payor` (`any`) - The payor responsible for the booking's charges.
  - `recall_due_date` (`string | null`) - format: `date`; The date the Patient is due to return, in ISO 8601 format (YYYY-MM-DD). Present on recall Bookings. Null on diary Bookings.
  - `remote_method` (`string | null`) - enum: `native_video`, `null`; The remote consultation method. `native_video` uses Carebit Video.
  - `service` (`any`) - The service being provided during the booking.
  - `service_variants` (`array`) - The service variants selected for the booking.
    - `items` (`object`)
      - `clinician_id` (`string | null`) - format: `uuid`; The identifier of the clinician assigned to this service variant, when the variant is clinician-specific.
      - `currency` (`string | null`) - The ISO 4217 currency code used for this service variant. Must be one of `chf`, `eur`, `gbp`, or `usd`.
      - `description` (`string | null`) - The description of this service variant.
      - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
      - `links` (`object`) - URLs to related resources.
        - `clinician` (`string | null`) - format: `uri`; The full URL of a related resource.
        - `location` (`string | null`) - format: `uri`; The full URL of a related resource.
      - `location_id` (`string | null`) - format: `uuid`; The identifier of the location assigned to this service variant, when the variant is location-specific.
      - `net_price` (`integer | null`) - The net price of this service variant, before tax, in the currency's minor units.
      - `permits_remote_bookings` (`boolean`) - Whether this service variant can be used for remote bookings.
  - `start_time` (`string | null`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `status` (`string | null`) - enum: `arrived`, `awaiting_payment`, `awaiting_recall`, `canceled`, `confirmed`, `did_not_attend`, `overdue_for_recall`, `prepared`, `recall_canceled`, `recall_expired`, `unconfirmed`, `null`; The Booking's current status. Null while Carebit is creating the record.
  - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.

### Example

```json
{
  "id": "92a3b4c5-d6e7-4f01-8234-56789abcdef0",
  "object": "booking",
  "canceled_at": "2026-01-01T09:00:00Z",
  "cancellation_information": "The Patient asked to cancel by phone.",
  "cancellation_reason": "abusive_behavior",
  "cancellation_source": "api",
  "clinician": {
    "id": "2b3c4d5e-6f70-489a-9bcd-ef0123456789",
    "object": "clinician",
    "created_at": "2026-01-01T09:00:00Z",
    "display_name": "Dr Alex Morgan",
    "email": "alex.morgan@example.com",
    "first_name": "Alex",
    "last_name": "Morgan",
    "links": {
      "bookings": "https://api.carebit.co/v1/bookings?clinician_id=2b3c4d5e-6f70-489a-9bcd-ef0123456789"
    },
    "medical_specialty": "Cardiology",
    "title": "Dr",
    "updated_at": "2026-01-01T09:00:00Z"
  },
  "created_at": "2026-01-01T09:00:00Z",
  "end_time": "2026-01-01T10:00:00Z",
  "information_for_patient": "<p>Please arrive 10 minutes before your appointment.</p>",
  "information_for_staff_members": "<p>The Patient has requested step-free access.</p>",
  "is_remote": false,
  "links": {
    "clinician": "https://api.carebit.co/v1/clinicians/2b3c4d5e-6f70-489a-9bcd-ef0123456789",
    "invoices": "https://api.carebit.co/v1/invoices?booking_id=92a3b4c5-d6e7-4f01-8234-56789abcdef0",
    "letters": "https://api.carebit.co/v1/letters?booking_id=92a3b4c5-d6e7-4f01-8234-56789abcdef0",
    "notes": "https://api.carebit.co/v1/notes?booking_id=92a3b4c5-d6e7-4f01-8234-56789abcdef0",
    "service": "https://api.carebit.co/v1/services/5e6f7081-92a3-4bcd-8ef0-123456789abc",
    "test_results": "https://api.carebit.co/v1/test_results?booking_id=92a3b4c5-d6e7-4f01-8234-56789abcdef0"
  },
  "location": {
    "id": "3c4d5e6f-7081-49ab-acde-f0123456789a",
    "object": "location",
    "address_line_1": "10 Harley Street",
    "address_line_2": "Marylebone",
    "city": "London",
    "country_code": "GB",
    "county": "Greater London",
    "created_at": "2026-01-01T09:00:00Z",
    "formatted_address": "10 Harley Street, Marylebone, London, W1G 9PF",
    "name": "Harley Street Clinic",
    "postcode": "W1G 9PF",
    "updated_at": "2026-01-01T09:00:00Z"
  },
  "patient": {
    "id": "1a2b3c4d-5e6f-4789-8abc-def012345678",
    "object": "patient",
    "address_line_1": "10 Harley Street",
    "address_line_2": "Marylebone",
    "city": "London",
    "country_code": "GB",
    "county": "Greater London",
    "created_at": "2026-01-01T09:00:00Z",
    "creation_source": "api",
    "date_of_birth": "1990-01-01",
    "display_name": "Dr Alex Morgan",
    "email": "alex.morgan@example.com",
    "first_name": "Alex",
    "is_opted_out_of_sms": false,
    "last_name": "Morgan",
    "mobile": "7700900123",
    "mobile_country_dial_code": "GB",
    "nhs_number": "485 777 3456",
    "phone": "2071234567",
    "phone_country_dial_code": "GB",
    "phone_number": "+44 7700 900123",
    "postcode": "W1G 9PF",
    "sex": "female",
    "title": "Dr",
    "updated_at": "2026-01-01T09:00:00Z"
  },
  "payor": {
    "id": "708192a3-b4c5-4def-8012-3456789abcde",
    "object": "payor",
    "address_line_1": "10 Harley Street",
    "address_line_2": "Marylebone",
    "alternative_payor_id": null,
    "city": "London",
    "country_code": "GB",
    "county": "Greater London",
    "created_at": "2026-01-01T09:00:00Z",
    "first_name": "Alex",
    "formatted_name": "Dr Alex Morgan",
    "formatted_payor_name": "Bupa",
    "insurance_authorization_code": "AUTH123",
    "insurance_company_id": "855e25b0-b138-48da-86ea-15162ce81f14",
    "insurance_policy_end_date": "2026-12-31",
    "insurance_policy_number": "POLICY123",
    "insurance_policy_start_date": "2026-01-01",
    "last_name": "Morgan",
    "notes": "Please confirm the appointment by email.",
    "payor_type": "insurance_company",
    "postcode": "W1G 9PF",
    "title": "Dr",
    "updated_at": "2026-01-01T09:00:00Z"
  },
  "recall_due_date": "2026-01-01",
  "remote_method": null,
  "service": {
    "id": "5e6f7081-92a3-4bcd-8ef0-123456789abc",
    "object": "service",
    "created_at": "2026-01-01T09:00:00Z",
    "description": "An initial consultation at the Harley Street Clinic.",
    "duration_minutes": 30,
    "is_bookable_online": true,
    "name": "Initial consultation",
    "service_variants": [
      {
        "id": "6f708192-a3b4-4cde-9f01-23456789abcd",
        "clinician_id": "2b3c4d5e-6f70-489a-9bcd-ef0123456789",
        "currency": "GBP",
        "description": "An initial consultation at the Harley Street Clinic.",
        "links": {
          "clinician": "https://api.carebit.co/v1/clinicians/2b3c4d5e-6f70-489a-9bcd-ef0123456789",
          "location": "https://api.carebit.co/v1/locations/3c4d5e6f-7081-49ab-acde-f0123456789a"
        },
        "location_id": "3c4d5e6f-7081-49ab-acde-f0123456789a",
        "net_price": 1,
        "permits_remote_bookings": true
      }
    ],
    "tax_rate": {
      "id": "211b60c7-ec1b-41b4-8a29-e855209bc694",
      "description": "An initial consultation at the Harley Street Clinic.",
      "percentage": 20,
      "title": "VAT"
    },
    "updated_at": "2026-01-01T09:00:00Z"
  },
  "service_variants": [
    {
      "id": "6f708192-a3b4-4cde-9f01-23456789abcd",
      "clinician_id": "2b3c4d5e-6f70-489a-9bcd-ef0123456789",
      "currency": "GBP",
      "description": "An initial consultation at the Harley Street Clinic.",
      "links": {
        "clinician": "https://api.carebit.co/v1/clinicians/2b3c4d5e-6f70-489a-9bcd-ef0123456789",
        "location": "https://api.carebit.co/v1/locations/3c4d5e6f-7081-49ab-acde-f0123456789a"
      },
      "location_id": "3c4d5e6f-7081-49ab-acde-f0123456789a",
      "net_price": 1,
      "permits_remote_bookings": true
    }
  ],
  "start_time": "2026-01-01T09:00:00Z",
  "status": "arrived",
  "updated_at": "2026-01-01T09:00:00Z"
}
```

## Response `400`

The `Idempotency-Key` header is missing (`idempotency_key_required`) or exceeds 255 characters (`idempotency_key_too_long`).

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `401`

The access token is missing, invalid, expired, or revoked.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `403`

The access token lacks the required scope, or the project is disabled.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `404`

Error response.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `409`

A concurrent request holds the idempotency lease (`idempotency_conflict`). Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `422`

The `Idempotency-Key` was previously used with a different request body (`idempotency_key_reused`), or the request body failed validation.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `429`

Too many requests. Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Code samples

```bash
curl -X PATCH "https://api.carebit.co/v1/bookings/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "confirmed"
}'
```

```javascript
const response = await fetch("https://api.carebit.co/v1/bookings/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
  "status": "confirmed"
}),
});

if (!response.ok) {
  throw new Error(`Carebit API error: ${response.status}`);
}

const data = await response.json();
```

```python
import os
import requests
import uuid

response = requests.patch(
    "https://api.carebit.co/v1/bookings/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "status": "confirmed"
    }
)
response.raise_for_status()
data = response.json()
```

```ruby
require "httparty"
require "json"
require "securerandom"

response = HTTParty.patch(
  "https://api.carebit.co/v1/bookings/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}",
    "Idempotency-Key" => SecureRandom.uuid,
    "Content-Type" => "application/json"
  },
  body: {
    "status" => "confirmed"
  }.to_json
)
raise "Carebit API error: #{response.code}" unless response.success?
data = response.parsed_response
```

```php
<?php

$client = new GuzzleHttp\Client();

$response = $client->patch("https://api.carebit.co/v1/bookings/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c", [
    "headers" => [
      "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
      "Idempotency-Key" => bin2hex(random_bytes(16)),
    ],
    "json" => [
      "status" => "confirmed"
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```


---

# Get a Clinician's diary

`GET /v1/clinician_agenda`

Returns the Clinician's Bookings, availability, and unavailability in time order. Bookings include staff and Patient details, so show only information appropriate for your users. Availability shows the diary schedule, not times that can necessarily be booked. Use the Availability Slots endpoints before creating a Booking. Unavailability labels and notes are not included.

**Required API scopes:** `clinician_agenda.read`

## Parameters

- `clinician_ids[]` (query, `array`) (required) - The Clinician whose diary to return. Pass exactly one identifier.
- `start_date` (query, `string`) (required) - The first date to include, in ISO 8601 format (YYYY-MM-DD).
- `end_date` (query, `string`) (required) - The last date to include, in ISO 8601 format (YYYY-MM-DD). The inclusive range cannot exceed 45 days.

## Response `200`

Paginated list of `ClinicianAgendaItem` objects.

- `any`

### Example

```json
{
  "object": "list",
  "data": [
    {
      "object": "clinician_agenda_item",
      "booking": {
        "id": "92a3b4c5-d6e7-4f01-8234-56789abcdef0",
        "object": "booking",
        "canceled_at": "2026-01-01T09:00:00Z",
        "cancellation_information": "The Patient asked to cancel by phone.",
        "cancellation_reason": "abusive_behavior",
        "cancellation_source": "api",
        "clinician": {
          "id": "2b3c4d5e-6f70-489a-9bcd-ef0123456789",
          "object": "clinician",
          "created_at": "2026-01-01T09:00:00Z",
          "display_name": "Dr Alex Morgan",
          "email": "alex.morgan@example.com",
          "first_name": "Alex",
          "last_name": "Morgan",
          "links": {
            "bookings": "https://api.carebit.co/v1/bookings?clinician_id=2b3c4d5e-6f70-489a-9bcd-ef0123456789"
          },
          "medical_specialty": "Cardiology",
          "title": "Dr",
          "updated_at": "2026-01-01T09:00:00Z"
        },
        "created_at": "2026-01-01T09:00:00Z",
        "end_time": "2026-01-01T10:00:00Z",
        "information_for_patient": "<p>Please arrive 10 minutes before your appointment.</p>",
        "information_for_staff_members": "<p>The Patient has requested step-free access.</p>",
        "is_remote": false,
        "links": {
          "clinician": "https://api.carebit.co/v1/clinicians/2b3c4d5e-6f70-489a-9bcd-ef0123456789",
          "invoices": "https://api.carebit.co/v1/invoices?booking_id=92a3b4c5-d6e7-4f01-8234-56789abcdef0",
          "letters": "https://api.carebit.co/v1/letters?booking_id=92a3b4c5-d6e7-4f01-8234-56789abcdef0",
          "notes": "https://api.carebit.co/v1/notes?booking_id=92a3b4c5-d6e7-4f01-8234-56789abcdef0",
          "service": "https://api.carebit.co/v1/services/5e6f7081-92a3-4bcd-8ef0-123456789abc",
          "test_results": "https://api.carebit.co/v1/test_results?booking_id=92a3b4c5-d6e7-4f01-8234-56789abcdef0"
        },
        "location": {
          "id": "3c4d5e6f-7081-49ab-acde-f0123456789a",
          "object": "location",
          "address_line_1": "10 Harley Street",
          "address_line_2": "Marylebone",
          "city": "London",
          "country_code": "GB",
          "county": "Greater London",
          "created_at": "2026-01-01T09:00:00Z",
          "formatted_address": "10 Harley Street, Marylebone, London, W1G 9PF",
          "name": "Harley Street Clinic",
          "postcode": "W1G 9PF",
          "updated_at": "2026-01-01T09:00:00Z"
        },
        "patient": {
          "id": "1a2b3c4d-5e6f-4789-8abc-def012345678",
          "object": "patient",
          "address_line_1": "10 Harley Street",
          "address_line_2": "Marylebone",
          "city": "London",
          "country_code": "GB",
          "county": "Greater London",
          "created_at": "2026-01-01T09:00:00Z",
          "creation_source": "api",
          "date_of_birth": "1990-01-01",
          "display_name": "Dr Alex Morgan",
          "email": "alex.morgan@example.com",
          "first_name": "Alex",
          "is_opted_out_of_sms": false,
          "last_name": "Morgan",
          "mobile": "7700900123",
          "mobile_country_dial_code": "GB",
          "nhs_number": "485 777 3456",
          "phone": "2071234567",
          "phone_country_dial_code": "GB",
          "phone_number": "+44 7700 900123",
          "postcode": "W1G 9PF",
          "sex": "female",
          "title": "Dr",
          "updated_at": "2026-01-01T09:00:00Z"
        },
        "payor": {
          "id": "708192a3-b4c5-4def-8012-3456789abcde",
          "object": "payor",
          "address_line_1": "10 Harley Street",
          "address_line_2": "Marylebone",
          "alternative_payor_id": null,
          "city": "London",
          "country_code": "GB",
          "county": "Greater London",
          "created_at": "2026-01-01T09:00:00Z",
          "first_name": "Alex",
          "formatted_name": "Dr Alex Morgan",
          "formatted_payor_name": "Bupa",
          "insurance_authorization_code": "AUTH123",
          "insurance_company_id": "855e25b0-b138-48da-86ea-15162ce81f14",
          "insurance_policy_end_date": "2026-12-31",
          "insurance_policy_number": "POLICY123",
          "insurance_policy_start_date": "2026-01-01",
          "last_name": "Morgan",
          "notes": "Please confirm the appointment by email.",
          "payor_type": "insurance_company",
          "postcode": "W1G 9PF",
          "title": "Dr",
          "updated_at": "2026-01-01T09:00:00Z"
        },
        "recall_due_date": "2026-01-01",
        "remote_method": null,
        "service": {
          "id": "5e6f7081-92a3-4bcd-8ef0-123456789abc",
          "object": "service",
          "created_at": "2026-01-01T09:00:00Z",
          "description": "An initial consultation at the Harley Street Clinic.",
          "duration_minutes": 30,
          "is_bookable_online": true,
          "name": "Initial consultation",
          "service_variants": [
            {
              "id": "6f708192-a3b4-4cde-9f01-23456789abcd",
              "clinician_id": "2b3c4d5e-6f70-489a-9bcd-ef0123456789",
              "currency": "GBP",
              "description": "An initial consultation at the Harley Street Clinic.",
              "links": {
                "clinician": "https://api.carebit.co/v1/clinicians/2b3c4d5e-6f70-489a-9bcd-ef0123456789",
                "location": "https://api.carebit.co/v1/locations/3c4d5e6f-7081-49ab-acde-f0123456789a"
              },
              "location_id": "3c4d5e6f-7081-49ab-acde-f0123456789a",
              "net_price": 1,
              "permits_remote_bookings": true
            }
          ],
          "tax_rate": {
            "id": "211b60c7-ec1b-41b4-8a29-e855209bc694",
            "description": "An initial consultation at the Harley Street Clinic.",
            "percentage": 20,
            "title": "VAT"
          },
          "updated_at": "2026-01-01T09:00:00Z"
        },
        "service_variants": [
          {
            "id": "6f708192-a3b4-4cde-9f01-23456789abcd",
            "clinician_id": "2b3c4d5e-6f70-489a-9bcd-ef0123456789",
            "currency": "GBP",
            "description": "An initial consultation at the Harley Street Clinic.",
            "links": {
              "clinician": "https://api.carebit.co/v1/clinicians/2b3c4d5e-6f70-489a-9bcd-ef0123456789",
              "location": "https://api.carebit.co/v1/locations/3c4d5e6f-7081-49ab-acde-f0123456789a"
            },
            "location_id": "3c4d5e6f-7081-49ab-acde-f0123456789a",
            "net_price": 1,
            "permits_remote_bookings": true
          }
        ],
        "start_time": "2026-01-01T09:00:00Z",
        "status": "arrived",
        "updated_at": "2026-01-01T09:00:00Z"
      },
      "clinician_id": "2b3c4d5e-6f70-489a-9bcd-ef0123456789",
      "end_time": "2026-01-01T10:00:00Z",
      "location_id": "3c4d5e6f-7081-49ab-acde-f0123456789a",
      "room_id": "4d5e6f70-8192-4abc-bdef-0123456789ab",
      "service_ids": [
        "5e6f7081-92a3-4bcd-8ef0-123456789abc"
      ],
      "service_variant_ids": [
        "6f708192-a3b4-4cde-9f01-23456789abcd"
      ],
      "start_time": "2026-01-01T09:00:00Z",
      "type": "availability"
    }
  ],
  "has_more": false,
  "next_cursor": "eyJzdGFydF90aW1lIjoiMjAyNi0wMS0wMVQwOTowMDowMFoifQ",
  "url": "/v1/clinician_agenda"
}
```

## Response `400`

The Clinician list or date range is missing, malformed, or outside the permitted limits.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `401`

The access token is missing, invalid, expired, or revoked.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `403`

The access token lacks the required scope, or the project is disabled.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `404`

The Clinician was not found in the Organization.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `429`

Too many requests. Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Code samples

```bash
curl -X GET "https://api.carebit.co/v1/clinician_agenda?clinician_ids%5B%5D=8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c&start_date=2026-01-01&end_date=2026-01-01" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN"
```

```javascript
const response = await fetch("https://api.carebit.co/v1/clinician_agenda?clinician_ids%5B%5D=8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c&start_date=2026-01-01&end_date=2026-01-01", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
  },
});

if (!response.ok) {
  throw new Error(`Carebit API error: ${response.status}`);
}

const data = await response.json();
```

```python
import os
import requests

response = requests.get(
    "https://api.carebit.co/v1/clinician_agenda?clinician_ids%5B%5D=8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c&start_date=2026-01-01&end_date=2026-01-01",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
    }
)
response.raise_for_status()
data = response.json()
```

```ruby
require "httparty"

response = HTTParty.get(
  "https://api.carebit.co/v1/clinician_agenda?clinician_ids%5B%5D=8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c&start_date=2026-01-01&end_date=2026-01-01",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}"
  }
)
raise "Carebit API error: #{response.code}" unless response.success?
data = response.parsed_response
```

```php
<?php

$client = new GuzzleHttp\Client();

$response = $client->get("https://api.carebit.co/v1/clinician_agenda?clinician_ids%5B%5D=8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c&start_date=2026-01-01&end_date=2026-01-01", [
    "headers" => [
      "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```


---

# List the Organization's Clinicians

`GET /v1/clinicians`

**Required API scopes:** `clinicians.read`

## Parameters

- `limit` (query, `integer`) - The maximum number of items to return. Defaults to `25`; the maximum is `100`.
- `starting_after` (query, `string`) - Return items after this resource ID. You cannot use this with `cursor`.
- `cursor` (query, `string`) - The `next_cursor` value from the previous page. You cannot use this with `starting_after`.

## Response `200`

Paginated list of `Clinician` objects.

- `any`

### Example

```json
{
  "object": "list",
  "data": [
    {
      "id": "2b3c4d5e-6f70-489a-9bcd-ef0123456789",
      "object": "clinician",
      "created_at": "2026-01-01T09:00:00Z",
      "display_name": "Dr Alex Morgan",
      "email": "alex.morgan@example.com",
      "first_name": "Alex",
      "last_name": "Morgan",
      "links": {
        "bookings": "https://api.carebit.co/v1/bookings?clinician_id=2b3c4d5e-6f70-489a-9bcd-ef0123456789"
      },
      "medical_specialty": "Cardiology",
      "title": "Dr",
      "updated_at": "2026-01-01T09:00:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": "eyJzdGFydF90aW1lIjoiMjAyNi0wMS0wMVQwOTowMDowMFoifQ",
  "url": "/v1/clinicians"
}
```

## Response `400`

A pagination parameter is invalid.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `401`

The access token is missing, invalid, expired, or revoked.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `403`

The access token lacks the required scope, or the project is disabled.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `429`

Too many requests. Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Code samples

```bash
curl -X GET "https://api.carebit.co/v1/clinicians" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN"
```

```javascript
const response = await fetch("https://api.carebit.co/v1/clinicians", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
  },
});

if (!response.ok) {
  throw new Error(`Carebit API error: ${response.status}`);
}

const data = await response.json();
```

```python
import os
import requests

response = requests.get(
    "https://api.carebit.co/v1/clinicians",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
    }
)
response.raise_for_status()
data = response.json()
```

```ruby
require "httparty"

response = HTTParty.get(
  "https://api.carebit.co/v1/clinicians",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}"
  }
)
raise "Carebit API error: #{response.code}" unless response.success?
data = response.parsed_response
```

```php
<?php

$client = new GuzzleHttp\Client();

$response = $client->get("https://api.carebit.co/v1/clinicians", [
    "headers" => [
      "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```


---

# Get a Clinician

`GET /v1/clinicians/:id`

**Required API scopes:** `clinicians.read`

## Parameters

- `id` (path, `string`) (required)

## Response `200`

The requested `Clinician`.

- `object`
  - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `display_name` (`string`) - The formatted name of the clinician, including title.
  - `email` (`string | null`) - format: `email`; The practice contact email of the clinician within the organization.
  - `first_name` (`string | null`) - The first name of the clinician.
  - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - `last_name` (`string | null`) - The last name of the clinician.
  - `links` (`object`) - URLs to related resources.
    - `bookings` (`string`) - format: `uri`; URL to list Bookings for this Clinician.
  - `medical_specialty` (`string | null`) - The medical specialty of the clinician, when recorded.
  - `object` (`any`) - Discriminator value emitted at `object`.
  - `title` (`string | null`) - The professional or personal title of the clinician, when recorded, such as `Dr`.
  - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.

### Example

```json
{
  "id": "2b3c4d5e-6f70-489a-9bcd-ef0123456789",
  "object": "clinician",
  "created_at": "2026-01-01T09:00:00Z",
  "display_name": "Dr Alex Morgan",
  "email": "alex.morgan@example.com",
  "first_name": "Alex",
  "last_name": "Morgan",
  "links": {
    "bookings": "https://api.carebit.co/v1/bookings?clinician_id=2b3c4d5e-6f70-489a-9bcd-ef0123456789"
  },
  "medical_specialty": "Cardiology",
  "title": "Dr",
  "updated_at": "2026-01-01T09:00:00Z"
}
```

## Response `401`

The access token is missing, invalid, expired, or revoked.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `403`

The access token lacks the required scope, or the project is disabled.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `404`

Error response.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `429`

Too many requests. Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Code samples

```bash
curl -X GET "https://api.carebit.co/v1/clinicians/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN"
```

```javascript
const response = await fetch("https://api.carebit.co/v1/clinicians/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
  },
});

if (!response.ok) {
  throw new Error(`Carebit API error: ${response.status}`);
}

const data = await response.json();
```

```python
import os
import requests

response = requests.get(
    "https://api.carebit.co/v1/clinicians/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
    }
)
response.raise_for_status()
data = response.json()
```

```ruby
require "httparty"

response = HTTParty.get(
  "https://api.carebit.co/v1/clinicians/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}"
  }
)
raise "Carebit API error: #{response.code}" unless response.success?
data = response.parsed_response
```

```php
<?php

$client = new GuzzleHttp\Client();

$response = $client->get("https://api.carebit.co/v1/clinicians/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c", [
    "headers" => [
      "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```


---

# List a Patient's DigitalFormResponses

`GET /v1/digital_form_responses`

**Required API scopes:** `digital_form_responses.read`

## Parameters

- `patient_id` (query, `string`) (required) - The Patient whose DigitalFormResponses should be returned.
- `limit` (query, `integer`) - The maximum number of items to return. Defaults to `25`; the maximum is `100`.
- `starting_after` (query, `string`) - Return items after this resource ID. You cannot use this with `cursor`.
- `cursor` (query, `string`) - The `next_cursor` value from the previous page. You cannot use this with `starting_after`.

## Response `200`

Paginated list of `DigitalFormResponse` objects.

- `any`

### Example

```json
{
  "object": "list",
  "data": [
    {
      "id": "4262fdc0-c7a1-4856-83c4-16ed34cb8773",
      "object": "digital_form_response",
      "answers": [
        {
          "id": "7ae2abaf-6f3e-4fbf-842d-5cbbe91b8492",
          "attachment_url": "https://files.example.invalid/document.pdf?signature=test",
          "date_value": "2026-01-01",
          "digital_form_question": {
            "id": "6d826770-c3ae-43c6-8b16-5ff8a72a24da",
            "choices": [
              {
                "id": "4f4f0cb8-0f36-42ed-8292-e679adb19729",
                "numerical_value": 1.5,
                "text_value": "yes",
                "title": "Dr"
              }
            ],
            "help_text": "Select every option that applies.",
            "is_answer_required": true,
            "list_order_number": 1,
            "question_type": "consent_required",
            "title": "Dr"
          },
          "digital_form_question_choice_id": "26a2ba65-f724-4add-8940-9f63f02f8711",
          "digital_form_question_id": "6d826770-c3ae-43c6-8b16-5ff8a72a24da",
          "has_consented": true,
          "numerical_value": 1.5,
          "text_value": "The symptoms started two weeks ago."
        }
      ],
      "booking_id": "92a3b4c5-d6e7-4f01-8234-56789abcdef0",
      "completed_at": "2026-01-01T09:00:00Z",
      "created_at": "2026-01-01T09:00:00Z",
      "digital_form": {
        "id": "e75b04dc-2889-491d-8e08-691c3a830d9c",
        "object": "digital_form",
        "attachment_url": "https://files.example.invalid/document.pdf?signature=test",
        "created_at": "2026-01-01T09:00:00Z",
        "patient_instructions": "Please complete this form before your appointment.",
        "questions": [
          {
            "id": "2214b284-64d6-4130-8b10-1602a2050126",
            "choices": [
              {
                "id": "4f4f0cb8-0f36-42ed-8292-e679adb19729",
                "numerical_value": 1.5,
                "text_value": "yes",
                "title": "Dr"
              }
            ],
            "help_text": "Select every option that applies.",
            "is_answer_required": true,
            "list_order_number": 1,
            "question_type": "consent_required",
            "title": "Dr"
          }
        ],
        "title": "Dr",
        "updated_at": "2026-01-01T09:00:00Z"
      },
      "due_at": "2026-01-01T09:00:00Z",
      "links": {
        "patient": "https://api.carebit.co/v1/patients/1a2b3c4d-5e6f-4789-8abc-def012345678",
        "transmissions": "https://api.carebit.co/v1/transmissions?patient_id=1a2b3c4d-5e6f-4789-8abc-def012345678&resource_type=digital_form_response"
      },
      "patient_id": "1a2b3c4d-5e6f-4789-8abc-def012345678",
      "status": "awaiting_completion",
      "total_score": 1,
      "updated_at": "2026-01-01T09:00:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": "eyJzdGFydF90aW1lIjoiMjAyNi0wMS0wMVQwOTowMDowMFoifQ",
  "url": "/v1/digital_form_responses"
}
```

## Response `401`

The access token is missing, invalid, expired, or revoked.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `403`

The access token lacks the required scope, or the project is disabled.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `404`

Error response.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `429`

Too many requests. Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Code samples

```bash
curl -X GET "https://api.carebit.co/v1/digital_form_responses?patient_id=8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN"
```

```javascript
const response = await fetch("https://api.carebit.co/v1/digital_form_responses?patient_id=8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
  },
});

if (!response.ok) {
  throw new Error(`Carebit API error: ${response.status}`);
}

const data = await response.json();
```

```python
import os
import requests

response = requests.get(
    "https://api.carebit.co/v1/digital_form_responses?patient_id=8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
    }
)
response.raise_for_status()
data = response.json()
```

```ruby
require "httparty"

response = HTTParty.get(
  "https://api.carebit.co/v1/digital_form_responses?patient_id=8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}"
  }
)
raise "Carebit API error: #{response.code}" unless response.success?
data = response.parsed_response
```

```php
<?php

$client = new GuzzleHttp\Client();

$response = $client->get("https://api.carebit.co/v1/digital_form_responses?patient_id=8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c", [
    "headers" => [
      "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```


---

# Create and send a DigitalFormResponse

`POST /v1/digital_form_responses`

Creates a pending DigitalFormResponse and queues an email asking the Patient to complete it.

**Required API scopes:** `digital_form_responses.create`

## Parameters

- `Idempotency-Key` (header, `string`) (required) - Client-generated idempotency key. Required for every POST/PATCH write. Replay of the same key with the same body returns the stored response with an `Idempotency-Replayed: true` header. Same key + different body returns `422 idempotency_key_reused`. A duplicate that arrives while the first request is still in flight returns `409 idempotency_conflict` with `Retry-After: 1`.

## Request body (`application/json`)

- `object`
  - `booking_id` (`string | null`) - format: `uuid`; The optional Booking associated with the response.
  - `digital_form_id` (`string`) - format: `uuid`; The DigitalForm to send to the Patient.
  - `due_at` (`string | null`) - format: `date-time`; The optional time by which the Patient should complete the DigitalForm.
  - `patient_id` (`string`) - format: `uuid`; The Patient who should complete the DigitalForm.

### Example

```json
{
  "booking_id": "00000000-0000-4000-8000-000000000001",
  "digital_form_id": "00000000-0000-4000-8000-000000000020",
  "due_at": "2026-01-04T17:00:00Z",
  "patient_id": "00000000-0000-4000-8000-000000000004"
}
```

## Response `201`

The requested `DigitalFormResponse`.

- `object`
  - `answers` (`array`) - The answers currently recorded for the DigitalFormResponse.
    - `items` (`object`)
      - `attachment_url` (`string | null`) - format: `uri`; The temporary URL for an attached answer.
      - `date_value` (`string | null`) - format: `date`; The date supplied for a date question.
      - `digital_form_question` (`object`) - A question on a DigitalForm. Embedded on DigitalForm and on each DigitalFormResponse answer.
        - `choices` (`array`) - The choices available for a choice question.
          - `items` (`object`)
            - `id` (`string`) - format: `uuid`; The identifier of the DigitalFormQuestionChoice.
            - `numerical_value` (`number | null`) - The optional numerical value assigned to the choice.
            - `text_value` (`string | null`) - The optional machine-readable text value assigned to the choice.
            - `title` (`string`) - The choice shown to the Patient.
        - `help_text` (`string | null`) - The supplementary guidance shown with the question.
        - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
        - `is_answer_required` (`boolean`) - Whether the Patient must answer the question.
        - `list_order_number` (`integer | null`) - The position of the question in the DigitalForm.
        - `question_type` (`string`) - enum: `consent_required`, `information_statement`, `multiple_choice_input`, `single_choice_input`, `text_input`, `number_input`, `date_input`, `signature_input`; The input and consent behavior of the question.
        - `title` (`string`) - The question shown to the Patient.
      - `digital_form_question_choice_id` (`string | null`) - format: `uuid`; The selected DigitalFormQuestionChoice.
      - `digital_form_question_id` (`string`) - format: `uuid`; The DigitalFormQuestion answered.
      - `has_consented` (`boolean | null`) - Whether the Patient granted the requested consent.
      - `id` (`string`) - format: `uuid`; The identifier of the DigitalFormQuestionAnswer.
      - `numerical_value` (`number | null`) - The numerical answer.
      - `text_value` (`string | null`) - The text answer or selected choice title.
  - `booking_id` (`string | null`) - format: `uuid`; The Booking associated with the response.
  - `completed_at` (`string | null`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `digital_form` (`object`)
    - `attachment_url` (`string | null`) - format: `uri`; The temporary URL for the attachment displayed with the DigitalForm.
    - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
    - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
    - `object` (`any`) - Discriminator value emitted at `object`.
    - `patient_instructions` (`string | null`) - The sanitized instructions shown to the Patient.
    - `questions` (`array`) - The ordered questions included in the DigitalForm.
      - `items` (`object`) - A question on a DigitalForm. Embedded on DigitalForm and on each DigitalFormResponse answer.
        - `choices` (`array`) - The choices available for a choice question.
          - `items` (`object`)
            - `id` (`string`) - format: `uuid`; The identifier of the DigitalFormQuestionChoice.
            - `numerical_value` (`number | null`) - The optional numerical value assigned to the choice.
            - `text_value` (`string | null`) - The optional machine-readable text value assigned to the choice.
            - `title` (`string`) - The choice shown to the Patient.
        - `help_text` (`string | null`) - The supplementary guidance shown with the question.
        - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
        - `is_answer_required` (`boolean`) - Whether the Patient must answer the question.
        - `list_order_number` (`integer | null`) - The position of the question in the DigitalForm.
        - `question_type` (`string`) - enum: `consent_required`, `information_statement`, `multiple_choice_input`, `single_choice_input`, `text_input`, `number_input`, `date_input`, `signature_input`; The input and consent behavior of the question.
        - `title` (`string`) - The question shown to the Patient.
    - `title` (`string`) - The title of the DigitalForm.
    - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `due_at` (`string | null`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - `links` (`object`) - URLs to related resources.
    - `patient` (`string`) - format: `uri`; The full URL of a related resource.
    - `transmissions` (`string`) - format: `uri`; The full URL of a related resource.
  - `object` (`any`) - Discriminator value emitted at `object`.
  - `patient_id` (`string`) - format: `uuid`; The Patient asked to complete the DigitalForm.
  - `status` (`string`) - enum: `awaiting_completion`, `partially_completed`, `overdue`, `completed`; The completion status of the DigitalFormResponse.
  - `total_score` (`integer | null`) - The sum of numerical answers configured to contribute to the score.
  - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.

### Example

```json
{
  "id": "4262fdc0-c7a1-4856-83c4-16ed34cb8773",
  "object": "digital_form_response",
  "answers": [
    {
      "id": "7ae2abaf-6f3e-4fbf-842d-5cbbe91b8492",
      "attachment_url": "https://files.example.invalid/document.pdf?signature=test",
      "date_value": "2026-01-01",
      "digital_form_question": {
        "id": "6d826770-c3ae-43c6-8b16-5ff8a72a24da",
        "choices": [
          {
            "id": "4f4f0cb8-0f36-42ed-8292-e679adb19729",
            "numerical_value": 1.5,
            "text_value": "yes",
            "title": "Dr"
          }
        ],
        "help_text": "Select every option that applies.",
        "is_answer_required": true,
        "list_order_number": 1,
        "question_type": "consent_required",
        "title": "Dr"
      },
      "digital_form_question_choice_id": "26a2ba65-f724-4add-8940-9f63f02f8711",
      "digital_form_question_id": "6d826770-c3ae-43c6-8b16-5ff8a72a24da",
      "has_consented": true,
      "numerical_value": 1.5,
      "text_value": "The symptoms started two weeks ago."
    }
  ],
  "booking_id": "92a3b4c5-d6e7-4f01-8234-56789abcdef0",
  "completed_at": "2026-01-01T09:00:00Z",
  "created_at": "2026-01-01T09:00:00Z",
  "digital_form": {
    "id": "e75b04dc-2889-491d-8e08-691c3a830d9c",
    "object": "digital_form",
    "attachment_url": "https://files.example.invalid/document.pdf?signature=test",
    "created_at": "2026-01-01T09:00:00Z",
    "patient_instructions": "Please complete this form before your appointment.",
    "questions": [
      {
        "id": "2214b284-64d6-4130-8b10-1602a2050126",
        "choices": [
          {
            "id": "4f4f0cb8-0f36-42ed-8292-e679adb19729",
            "numerical_value": 1.5,
            "text_value": "yes",
            "title": "Dr"
          }
        ],
        "help_text": "Select every option that applies.",
        "is_answer_required": true,
        "list_order_number": 1,
        "question_type": "consent_required",
        "title": "Dr"
      }
    ],
    "title": "Dr",
    "updated_at": "2026-01-01T09:00:00Z"
  },
  "due_at": "2026-01-01T09:00:00Z",
  "links": {
    "patient": "https://api.carebit.co/v1/patients/1a2b3c4d-5e6f-4789-8abc-def012345678",
    "transmissions": "https://api.carebit.co/v1/transmissions?patient_id=1a2b3c4d-5e6f-4789-8abc-def012345678&resource_type=digital_form_response"
  },
  "patient_id": "1a2b3c4d-5e6f-4789-8abc-def012345678",
  "status": "awaiting_completion",
  "total_score": 1,
  "updated_at": "2026-01-01T09:00:00Z"
}
```

## Response `400`

The `Idempotency-Key` header is missing (`idempotency_key_required`) or exceeds 255 characters (`idempotency_key_too_long`).

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `401`

The access token is missing, invalid, expired, or revoked.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `403`

The access token lacks the required scope, or the project is disabled.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `404`

Error response.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `409`

A concurrent request holds the idempotency lease (`idempotency_conflict`). Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `422`

The `Idempotency-Key` was previously used with a different request body (`idempotency_key_reused`), or the request body failed validation.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `429`

Too many requests. Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Code samples

```bash
curl -X POST "https://api.carebit.co/v1/digital_form_responses" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "booking_id": "00000000-0000-4000-8000-000000000001",
  "digital_form_id": "00000000-0000-4000-8000-000000000020",
  "due_at": "2026-01-04T17:00:00Z",
  "patient_id": "00000000-0000-4000-8000-000000000004"
}'
```

```javascript
const response = await fetch("https://api.carebit.co/v1/digital_form_responses", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
  "booking_id": "00000000-0000-4000-8000-000000000001",
  "digital_form_id": "00000000-0000-4000-8000-000000000020",
  "due_at": "2026-01-04T17:00:00Z",
  "patient_id": "00000000-0000-4000-8000-000000000004"
}),
});

if (!response.ok) {
  throw new Error(`Carebit API error: ${response.status}`);
}

const data = await response.json();
```

```python
import os
import requests
import uuid

response = requests.post(
    "https://api.carebit.co/v1/digital_form_responses",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "booking_id": "00000000-0000-4000-8000-000000000001",
        "digital_form_id": "00000000-0000-4000-8000-000000000020",
        "due_at": "2026-01-04T17:00:00Z",
        "patient_id": "00000000-0000-4000-8000-000000000004"
    }
)
response.raise_for_status()
data = response.json()
```

```ruby
require "httparty"
require "json"
require "securerandom"

response = HTTParty.post(
  "https://api.carebit.co/v1/digital_form_responses",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}",
    "Idempotency-Key" => SecureRandom.uuid,
    "Content-Type" => "application/json"
  },
  body: {
    "booking_id" => "00000000-0000-4000-8000-000000000001",
    "digital_form_id" => "00000000-0000-4000-8000-000000000020",
    "due_at" => "2026-01-04T17:00:00Z",
    "patient_id" => "00000000-0000-4000-8000-000000000004"
  }.to_json
)
raise "Carebit API error: #{response.code}" unless response.success?
data = response.parsed_response
```

```php
<?php

$client = new GuzzleHttp\Client();

$response = $client->post("https://api.carebit.co/v1/digital_form_responses", [
    "headers" => [
      "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
      "Idempotency-Key" => bin2hex(random_bytes(16)),
    ],
    "json" => [
      "booking_id" => "00000000-0000-4000-8000-000000000001",
      "digital_form_id" => "00000000-0000-4000-8000-000000000020",
      "due_at" => "2026-01-04T17:00:00Z",
      "patient_id" => "00000000-0000-4000-8000-000000000004"
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```


---

# Retrieve a DigitalFormResponse

`GET /v1/digital_form_responses/:id`

**Required API scopes:** `digital_form_responses.read`

## Parameters

- `id` (path, `string`) (required) - The identifier of the DigitalFormResponse.

## Response `200`

The requested `DigitalFormResponse`.

- `object`
  - `answers` (`array`) - The answers currently recorded for the DigitalFormResponse.
    - `items` (`object`)
      - `attachment_url` (`string | null`) - format: `uri`; The temporary URL for an attached answer.
      - `date_value` (`string | null`) - format: `date`; The date supplied for a date question.
      - `digital_form_question` (`object`) - A question on a DigitalForm. Embedded on DigitalForm and on each DigitalFormResponse answer.
        - `choices` (`array`) - The choices available for a choice question.
          - `items` (`object`)
            - `id` (`string`) - format: `uuid`; The identifier of the DigitalFormQuestionChoice.
            - `numerical_value` (`number | null`) - The optional numerical value assigned to the choice.
            - `text_value` (`string | null`) - The optional machine-readable text value assigned to the choice.
            - `title` (`string`) - The choice shown to the Patient.
        - `help_text` (`string | null`) - The supplementary guidance shown with the question.
        - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
        - `is_answer_required` (`boolean`) - Whether the Patient must answer the question.
        - `list_order_number` (`integer | null`) - The position of the question in the DigitalForm.
        - `question_type` (`string`) - enum: `consent_required`, `information_statement`, `multiple_choice_input`, `single_choice_input`, `text_input`, `number_input`, `date_input`, `signature_input`; The input and consent behavior of the question.
        - `title` (`string`) - The question shown to the Patient.
      - `digital_form_question_choice_id` (`string | null`) - format: `uuid`; The selected DigitalFormQuestionChoice.
      - `digital_form_question_id` (`string`) - format: `uuid`; The DigitalFormQuestion answered.
      - `has_consented` (`boolean | null`) - Whether the Patient granted the requested consent.
      - `id` (`string`) - format: `uuid`; The identifier of the DigitalFormQuestionAnswer.
      - `numerical_value` (`number | null`) - The numerical answer.
      - `text_value` (`string | null`) - The text answer or selected choice title.
  - `booking_id` (`string | null`) - format: `uuid`; The Booking associated with the response.
  - `completed_at` (`string | null`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `digital_form` (`object`)
    - `attachment_url` (`string | null`) - format: `uri`; The temporary URL for the attachment displayed with the DigitalForm.
    - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
    - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
    - `object` (`any`) - Discriminator value emitted at `object`.
    - `patient_instructions` (`string | null`) - The sanitized instructions shown to the Patient.
    - `questions` (`array`) - The ordered questions included in the DigitalForm.
      - `items` (`object`) - A question on a DigitalForm. Embedded on DigitalForm and on each DigitalFormResponse answer.
        - `choices` (`array`) - The choices available for a choice question.
          - `items` (`object`)
            - `id` (`string`) - format: `uuid`; The identifier of the DigitalFormQuestionChoice.
            - `numerical_value` (`number | null`) - The optional numerical value assigned to the choice.
            - `text_value` (`string | null`) - The optional machine-readable text value assigned to the choice.
            - `title` (`string`) - The choice shown to the Patient.
        - `help_text` (`string | null`) - The supplementary guidance shown with the question.
        - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
        - `is_answer_required` (`boolean`) - Whether the Patient must answer the question.
        - `list_order_number` (`integer | null`) - The position of the question in the DigitalForm.
        - `question_type` (`string`) - enum: `consent_required`, `information_statement`, `multiple_choice_input`, `single_choice_input`, `text_input`, `number_input`, `date_input`, `signature_input`; The input and consent behavior of the question.
        - `title` (`string`) - The question shown to the Patient.
    - `title` (`string`) - The title of the DigitalForm.
    - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `due_at` (`string | null`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - `links` (`object`) - URLs to related resources.
    - `patient` (`string`) - format: `uri`; The full URL of a related resource.
    - `transmissions` (`string`) - format: `uri`; The full URL of a related resource.
  - `object` (`any`) - Discriminator value emitted at `object`.
  - `patient_id` (`string`) - format: `uuid`; The Patient asked to complete the DigitalForm.
  - `status` (`string`) - enum: `awaiting_completion`, `partially_completed`, `overdue`, `completed`; The completion status of the DigitalFormResponse.
  - `total_score` (`integer | null`) - The sum of numerical answers configured to contribute to the score.
  - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.

### Example

```json
{
  "id": "4262fdc0-c7a1-4856-83c4-16ed34cb8773",
  "object": "digital_form_response",
  "answers": [
    {
      "id": "7ae2abaf-6f3e-4fbf-842d-5cbbe91b8492",
      "attachment_url": "https://files.example.invalid/document.pdf?signature=test",
      "date_value": "2026-01-01",
      "digital_form_question": {
        "id": "6d826770-c3ae-43c6-8b16-5ff8a72a24da",
        "choices": [
          {
            "id": "4f4f0cb8-0f36-42ed-8292-e679adb19729",
            "numerical_value": 1.5,
            "text_value": "yes",
            "title": "Dr"
          }
        ],
        "help_text": "Select every option that applies.",
        "is_answer_required": true,
        "list_order_number": 1,
        "question_type": "consent_required",
        "title": "Dr"
      },
      "digital_form_question_choice_id": "26a2ba65-f724-4add-8940-9f63f02f8711",
      "digital_form_question_id": "6d826770-c3ae-43c6-8b16-5ff8a72a24da",
      "has_consented": true,
      "numerical_value": 1.5,
      "text_value": "The symptoms started two weeks ago."
    }
  ],
  "booking_id": "92a3b4c5-d6e7-4f01-8234-56789abcdef0",
  "completed_at": "2026-01-01T09:00:00Z",
  "created_at": "2026-01-01T09:00:00Z",
  "digital_form": {
    "id": "e75b04dc-2889-491d-8e08-691c3a830d9c",
    "object": "digital_form",
    "attachment_url": "https://files.example.invalid/document.pdf?signature=test",
    "created_at": "2026-01-01T09:00:00Z",
    "patient_instructions": "Please complete this form before your appointment.",
    "questions": [
      {
        "id": "2214b284-64d6-4130-8b10-1602a2050126",
        "choices": [
          {
            "id": "4f4f0cb8-0f36-42ed-8292-e679adb19729",
            "numerical_value": 1.5,
            "text_value": "yes",
            "title": "Dr"
          }
        ],
        "help_text": "Select every option that applies.",
        "is_answer_required": true,
        "list_order_number": 1,
        "question_type": "consent_required",
        "title": "Dr"
      }
    ],
    "title": "Dr",
    "updated_at": "2026-01-01T09:00:00Z"
  },
  "due_at": "2026-01-01T09:00:00Z",
  "links": {
    "patient": "https://api.carebit.co/v1/patients/1a2b3c4d-5e6f-4789-8abc-def012345678",
    "transmissions": "https://api.carebit.co/v1/transmissions?patient_id=1a2b3c4d-5e6f-4789-8abc-def012345678&resource_type=digital_form_response"
  },
  "patient_id": "1a2b3c4d-5e6f-4789-8abc-def012345678",
  "status": "awaiting_completion",
  "total_score": 1,
  "updated_at": "2026-01-01T09:00:00Z"
}
```

## Response `401`

The access token is missing, invalid, expired, or revoked.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `403`

The access token lacks the required scope, or the project is disabled.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `404`

Error response.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `429`

Too many requests. Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Code samples

```bash
curl -X GET "https://api.carebit.co/v1/digital_form_responses/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN"
```

```javascript
const response = await fetch("https://api.carebit.co/v1/digital_form_responses/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
  },
});

if (!response.ok) {
  throw new Error(`Carebit API error: ${response.status}`);
}

const data = await response.json();
```

```python
import os
import requests

response = requests.get(
    "https://api.carebit.co/v1/digital_form_responses/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
    }
)
response.raise_for_status()
data = response.json()
```

```ruby
require "httparty"

response = HTTParty.get(
  "https://api.carebit.co/v1/digital_form_responses/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}"
  }
)
raise "Carebit API error: #{response.code}" unless response.success?
data = response.parsed_response
```

```php
<?php

$client = new GuzzleHttp\Client();

$response = $client->get("https://api.carebit.co/v1/digital_form_responses/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c", [
    "headers" => [
      "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```


---

# List DigitalForms

`GET /v1/digital_forms`

**Required API scopes:** `digital_forms.read`

## Parameters

- `limit` (query, `integer`) - The maximum number of items to return. Defaults to `25`; the maximum is `100`.
- `starting_after` (query, `string`) - Return items after this resource ID. You cannot use this with `cursor`.
- `cursor` (query, `string`) - The `next_cursor` value from the previous page. You cannot use this with `starting_after`.

## Response `200`

Paginated list of `DigitalForm` objects.

- `any`

### Example

```json
{
  "object": "list",
  "data": [
    {
      "id": "e75b04dc-2889-491d-8e08-691c3a830d9c",
      "object": "digital_form",
      "attachment_url": "https://files.example.invalid/document.pdf?signature=test",
      "created_at": "2026-01-01T09:00:00Z",
      "patient_instructions": "Please complete this form before your appointment.",
      "questions": [
        {
          "id": "2214b284-64d6-4130-8b10-1602a2050126",
          "choices": [
            {
              "id": "4f4f0cb8-0f36-42ed-8292-e679adb19729",
              "numerical_value": 1.5,
              "text_value": "yes",
              "title": "Dr"
            }
          ],
          "help_text": "Select every option that applies.",
          "is_answer_required": true,
          "list_order_number": 1,
          "question_type": "consent_required",
          "title": "Dr"
        }
      ],
      "title": "Dr",
      "updated_at": "2026-01-01T09:00:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": "eyJzdGFydF90aW1lIjoiMjAyNi0wMS0wMVQwOTowMDowMFoifQ",
  "url": "/v1/digital_forms"
}
```

## Response `401`

The access token is missing, invalid, expired, or revoked.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `403`

The access token lacks the required scope, or the project is disabled.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `429`

Too many requests. Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Code samples

```bash
curl -X GET "https://api.carebit.co/v1/digital_forms" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN"
```

```javascript
const response = await fetch("https://api.carebit.co/v1/digital_forms", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
  },
});

if (!response.ok) {
  throw new Error(`Carebit API error: ${response.status}`);
}

const data = await response.json();
```

```python
import os
import requests

response = requests.get(
    "https://api.carebit.co/v1/digital_forms",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
    }
)
response.raise_for_status()
data = response.json()
```

```ruby
require "httparty"

response = HTTParty.get(
  "https://api.carebit.co/v1/digital_forms",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}"
  }
)
raise "Carebit API error: #{response.code}" unless response.success?
data = response.parsed_response
```

```php
<?php

$client = new GuzzleHttp\Client();

$response = $client->get("https://api.carebit.co/v1/digital_forms", [
    "headers" => [
      "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```


---

# Retrieve a DigitalForm

`GET /v1/digital_forms/:id`

**Required API scopes:** `digital_forms.read`

## Parameters

- `id` (path, `string`) (required) - The identifier of the DigitalForm.

## Response `200`

The requested `DigitalForm`.

- `object`
  - `attachment_url` (`string | null`) - format: `uri`; The temporary URL for the attachment displayed with the DigitalForm.
  - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - `object` (`any`) - Discriminator value emitted at `object`.
  - `patient_instructions` (`string | null`) - The sanitized instructions shown to the Patient.
  - `questions` (`array`) - The ordered questions included in the DigitalForm.
    - `items` (`object`) - A question on a DigitalForm. Embedded on DigitalForm and on each DigitalFormResponse answer.
      - `choices` (`array`) - The choices available for a choice question.
        - `items` (`object`)
          - `id` (`string`) - format: `uuid`; The identifier of the DigitalFormQuestionChoice.
          - `numerical_value` (`number | null`) - The optional numerical value assigned to the choice.
          - `text_value` (`string | null`) - The optional machine-readable text value assigned to the choice.
          - `title` (`string`) - The choice shown to the Patient.
      - `help_text` (`string | null`) - The supplementary guidance shown with the question.
      - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
      - `is_answer_required` (`boolean`) - Whether the Patient must answer the question.
      - `list_order_number` (`integer | null`) - The position of the question in the DigitalForm.
      - `question_type` (`string`) - enum: `consent_required`, `information_statement`, `multiple_choice_input`, `single_choice_input`, `text_input`, `number_input`, `date_input`, `signature_input`; The input and consent behavior of the question.
      - `title` (`string`) - The question shown to the Patient.
  - `title` (`string`) - The title of the DigitalForm.
  - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.

### Example

```json
{
  "id": "e75b04dc-2889-491d-8e08-691c3a830d9c",
  "object": "digital_form",
  "attachment_url": "https://files.example.invalid/document.pdf?signature=test",
  "created_at": "2026-01-01T09:00:00Z",
  "patient_instructions": "Please complete this form before your appointment.",
  "questions": [
    {
      "id": "2214b284-64d6-4130-8b10-1602a2050126",
      "choices": [
        {
          "id": "4f4f0cb8-0f36-42ed-8292-e679adb19729",
          "numerical_value": 1.5,
          "text_value": "yes",
          "title": "Dr"
        }
      ],
      "help_text": "Select every option that applies.",
      "is_answer_required": true,
      "list_order_number": 1,
      "question_type": "consent_required",
      "title": "Dr"
    }
  ],
  "title": "Dr",
  "updated_at": "2026-01-01T09:00:00Z"
}
```

## Response `401`

The access token is missing, invalid, expired, or revoked.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `403`

The access token lacks the required scope, or the project is disabled.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `404`

Error response.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `429`

Too many requests. Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Code samples

```bash
curl -X GET "https://api.carebit.co/v1/digital_forms/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN"
```

```javascript
const response = await fetch("https://api.carebit.co/v1/digital_forms/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
  },
});

if (!response.ok) {
  throw new Error(`Carebit API error: ${response.status}`);
}

const data = await response.json();
```

```python
import os
import requests

response = requests.get(
    "https://api.carebit.co/v1/digital_forms/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
    }
)
response.raise_for_status()
data = response.json()
```

```ruby
require "httparty"

response = HTTParty.get(
  "https://api.carebit.co/v1/digital_forms/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}"
  }
)
raise "Carebit API error: #{response.code}" unless response.success?
data = response.parsed_response
```

```php
<?php

$client = new GuzzleHttp\Client();

$response = $client->get("https://api.carebit.co/v1/digital_forms/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c", [
    "headers" => [
      "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```


---

# List ExpirableFiles

`GET /v1/expirable_files`

Returns ExpirableFiles created by API report requests for the authenticated Organization.

**Required API scopes:** `expirable_files.read`

## Parameters

- `limit` (query, `integer`) - The maximum number of items to return. Defaults to `25`; the maximum is `100`.
- `starting_after` (query, `string`) - Return items after this resource ID. You cannot use this with `cursor`.
- `cursor` (query, `string`) - The `next_cursor` value from the previous page. You cannot use this with `starting_after`.

## Response `200`

Paginated list of `ExpirableFile` objects.

- `any`

### Example

```json
{
  "object": "list",
  "data": [
    {
      "id": "08bbb801-b197-40de-8865-f2d3086221f2",
      "object": "expirable_file",
      "attachment_url": "https://files.example.invalid/document.pdf?signature=test",
      "created_at": "2026-01-01T09:00:00Z",
      "expires_at": "2026-01-01T09:00:00Z",
      "status": "processing",
      "title": "account_balances",
      "updated_at": "2026-01-01T09:00:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": "eyJzdGFydF90aW1lIjoiMjAyNi0wMS0wMVQwOTowMDowMFoifQ",
  "url": "/v1/expirable_files"
}
```

## Response `401`

The access token is missing, invalid, expired, or revoked.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `403`

The access token lacks the required scope, or the project is disabled.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `429`

Too many requests. Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Code samples

```bash
curl -X GET "https://api.carebit.co/v1/expirable_files" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN"
```

```javascript
const response = await fetch("https://api.carebit.co/v1/expirable_files", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
  },
});

if (!response.ok) {
  throw new Error(`Carebit API error: ${response.status}`);
}

const data = await response.json();
```

```python
import os
import requests

response = requests.get(
    "https://api.carebit.co/v1/expirable_files",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
    }
)
response.raise_for_status()
data = response.json()
```

```ruby
require "httparty"

response = HTTParty.get(
  "https://api.carebit.co/v1/expirable_files",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}"
  }
)
raise "Carebit API error: #{response.code}" unless response.success?
data = response.parsed_response
```

```php
<?php

$client = new GuzzleHttp\Client();

$response = $client->get("https://api.carebit.co/v1/expirable_files", [
    "headers" => [
      "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```


---

# Retrieve an ExpirableFile

`GET /v1/expirable_files/:id`

**Required API scopes:** `expirable_files.read`

## Parameters

- `id` (path, `string`) (required) - The identifier of the ExpirableFile.

## Response `200`

The requested `ExpirableFile`.

- `object`
  - `attachment_url` (`string | null`) - format: `uri`; The temporary signed download URL, or null while Carebit generates the file and download URL.
  - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `expires_at` (`string`) - format: `date-time`; The time after which Carebit can delete the file.
  - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - `object` (`any`) - Discriminator value emitted at `object`.
  - `status` (`string`) - enum: `processing`, `succeeded`; Whether Carebit is still creating the report or the file is ready to download.
  - `title` (`string`) - enum: `account_balances`, `audio_recordings`, `billing_codes`, `booked_services`, `bookings`, `bookings_summary_for_child_organizations`, `bookings_with_invoices`, `bookings_without_invoices`, `care_episodes`, `cari_credits_usage`, `credit_notes`, `creditors`, `debtors`, `debtors_per_invoice`, `end_of_year_accounts_zip`, `expenses`, `financial_summary`, `indemnity_bookings`, `indemnity_income`, `invoice_line_items`, `issued_invoices`, `issued_invoices_summary_for_child_organizations`, `leads_and_enquiries`, `patient_referrals`, `patient_registrations`, `prescriptions_report`, `product_sales_audit_log`, `product_sales_report`, `product_stock_levels_report`, `profit_and_loss`, `recall_bookings`, `received_payments`, `received_payments_for_invoice_line_items`, `received_payments_summary_for_child_organizations`, `referral_summary`, `refunds`, `remittance_adjustments`, `service_variants`, `tasks_due_per_staff_member`, `tasks_raised`; The report type used as the title of the ExpirableFile.
  - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.

### Example

```json
{
  "id": "08bbb801-b197-40de-8865-f2d3086221f2",
  "object": "expirable_file",
  "attachment_url": "https://files.example.invalid/document.pdf?signature=test",
  "created_at": "2026-01-01T09:00:00Z",
  "expires_at": "2026-01-01T09:00:00Z",
  "status": "processing",
  "title": "account_balances",
  "updated_at": "2026-01-01T09:00:00Z"
}
```

## Response `401`

The access token is missing, invalid, expired, or revoked.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `403`

The access token lacks the required scope, or the project is disabled.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `404`

The ExpirableFile was not found in the authenticated Organization.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `429`

Too many requests. Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Code samples

```bash
curl -X GET "https://api.carebit.co/v1/expirable_files/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN"
```

```javascript
const response = await fetch("https://api.carebit.co/v1/expirable_files/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
  },
});

if (!response.ok) {
  throw new Error(`Carebit API error: ${response.status}`);
}

const data = await response.json();
```

```python
import os
import requests

response = requests.get(
    "https://api.carebit.co/v1/expirable_files/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
    }
)
response.raise_for_status()
data = response.json()
```

```ruby
require "httparty"

response = HTTParty.get(
  "https://api.carebit.co/v1/expirable_files/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}"
  }
)
raise "Carebit API error: #{response.code}" unless response.success?
data = response.parsed_response
```

```php
<?php

$client = new GuzzleHttp\Client();

$response = $client->get("https://api.carebit.co/v1/expirable_files/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c", [
    "headers" => [
      "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```


---

# Create a HumanTask

`POST /v1/human_tasks`

Creates a HumanTask in the Organization's existing staff task queue. Look up assignable StaffMembers with `GET /v1/staff_members`.

**Required API scopes:** `human_tasks.create`

## Parameters

- `Idempotency-Key` (header, `string`) (required) - Client-generated idempotency key. Required for every POST/PATCH write. Replay of the same key with the same body returns the stored response with an `Idempotency-Replayed: true` header. Same key + different body returns `422 idempotency_key_reused`. A duplicate that arrives while the first request is still in flight returns `409 idempotency_conflict` with `Retry-After: 1`.

## Request body (`application/json`)

- `object`
  - `assignees` (`array`) - The people to assign to the HumanTask. Each object requires `assignee_type` and `assignee_id`. Currently only `staff_member` is supported.
    - `items` (`object`)
      - `assignee_id` (`string`) - format: `uuid`; The identifier of the assignee. For `staff_member`, use an identifier from `GET /v1/staff_members`.
      - `assignee_type` (`string`) - enum: `staff_member`; The type of assignee. Currently only `staff_member` is supported.
  - `content` (`string`) - The description of the work to complete.
  - `due_date` (`string`) - format: `date`; The date by which staff should complete the HumanTask.
  - `is_remindable` (`boolean`) - Whether Carebit can send reminders when the HumanTask becomes due.
  - `is_urgent` (`boolean`) - Whether the HumanTask should be marked as urgent.
  - `patient_id` (`string | null`) - format: `uuid`; The optional Patient associated with the HumanTask.

### Example

```json
{
  "assignees": [
    {
      "assignee_id": "00000000-0000-4000-8000-000000000021",
      "assignee_type": "staff_member"
    }
  ],
  "content": "Review the Patient's pre-operative DigitalFormResponse.",
  "due_date": "2026-01-04",
  "is_urgent": false,
  "patient_id": "00000000-0000-4000-8000-000000000004"
}
```

## Response `201`

The requested `HumanTask`.

- `object`
  - `assignees` (`array`) - The people assigned to the HumanTask. Currently only `staff_member` is supported.
    - `items` (`object`)
      - `assignee_id` (`string`) - format: `uuid`; The identifier of the assignee. For `staff_member`, use an identifier from `GET /v1/staff_members`.
      - `assignee_type` (`string`) - enum: `staff_member`; The type of assignee. Currently only `staff_member` is supported.
  - `completed_at` (`string | null`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `content` (`string`) - The sanitized description of the work to complete.
  - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `creation_source` (`any`) - The channel through which the HumanTask was created.
  - `due_date` (`string`) - format: `date`; The date by which staff should complete the HumanTask.
  - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - `is_remindable` (`boolean`) - Whether Carebit can send reminders when the HumanTask becomes due.
  - `is_urgent` (`boolean`) - Whether the HumanTask is marked as urgent.
  - `links` (`object`) - URLs to related resources.
    - `patient` (`string | null`) - format: `uri`; The full URL of a related resource.
  - `object` (`any`) - Discriminator value emitted at `object`.
  - `patient_id` (`string | null`) - format: `uuid`; The Patient associated with the HumanTask.
  - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.

### Example

```json
{
  "id": "8408d9e2-6643-4aee-8ebd-8edf57ead496",
  "object": "human_task",
  "assignees": [
    {
      "assignee_id": "8574233b-dbe0-4535-8ab3-4617f736a5cc",
      "assignee_type": "staff_member"
    }
  ],
  "completed_at": "2026-01-01T09:00:00Z",
  "content": "Review the Patient's completed consent form.",
  "created_at": "2026-01-01T09:00:00Z",
  "creation_source": "api",
  "due_date": "2026-01-01",
  "is_remindable": true,
  "is_urgent": true,
  "links": {
    "patient": "https://api.carebit.co/v1/patients/1a2b3c4d-5e6f-4789-8abc-def012345678"
  },
  "patient_id": "1a2b3c4d-5e6f-4789-8abc-def012345678",
  "updated_at": "2026-01-01T09:00:00Z"
}
```

## Response `400`

The `Idempotency-Key` header is missing (`idempotency_key_required`) or exceeds 255 characters (`idempotency_key_too_long`).

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `401`

The access token is missing, invalid, expired, or revoked.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `403`

The access token lacks the required scope, or the project is disabled.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `404`

Error response.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `409`

A concurrent request holds the idempotency lease (`idempotency_conflict`). Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `422`

The `Idempotency-Key` was previously used with a different request body (`idempotency_key_reused`), or the request body failed validation.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `429`

Too many requests. Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Code samples

```bash
curl -X POST "https://api.carebit.co/v1/human_tasks" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "assignees": [
    {
      "assignee_id": "00000000-0000-4000-8000-000000000021",
      "assignee_type": "staff_member"
    }
  ],
  "content": "Review the Patient'\''s pre-operative DigitalFormResponse.",
  "due_date": "2026-01-04",
  "is_urgent": false,
  "patient_id": "00000000-0000-4000-8000-000000000004"
}'
```

```javascript
const response = await fetch("https://api.carebit.co/v1/human_tasks", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
  "assignees": [
    {
      "assignee_id": "00000000-0000-4000-8000-000000000021",
      "assignee_type": "staff_member"
    }
  ],
  "content": "Review the Patient's pre-operative DigitalFormResponse.",
  "due_date": "2026-01-04",
  "is_urgent": false,
  "patient_id": "00000000-0000-4000-8000-000000000004"
}),
});

if (!response.ok) {
  throw new Error(`Carebit API error: ${response.status}`);
}

const data = await response.json();
```

```python
import os
import requests
import uuid

response = requests.post(
    "https://api.carebit.co/v1/human_tasks",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "assignees": [
            {
                "assignee_id": "00000000-0000-4000-8000-000000000021",
                "assignee_type": "staff_member"
            }
        ],
        "content": "Review the Patient's pre-operative DigitalFormResponse.",
        "due_date": "2026-01-04",
        "is_urgent": False,
        "patient_id": "00000000-0000-4000-8000-000000000004"
    }
)
response.raise_for_status()
data = response.json()
```

```ruby
require "httparty"
require "json"
require "securerandom"

response = HTTParty.post(
  "https://api.carebit.co/v1/human_tasks",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}",
    "Idempotency-Key" => SecureRandom.uuid,
    "Content-Type" => "application/json"
  },
  body: {
    "assignees" => [
      {
        "assignee_id" => "00000000-0000-4000-8000-000000000021",
        "assignee_type" => "staff_member"
      }
    ],
    "content" => "Review the Patient's pre-operative DigitalFormResponse.",
    "due_date" => "2026-01-04",
    "is_urgent" => false,
    "patient_id" => "00000000-0000-4000-8000-000000000004"
  }.to_json
)
raise "Carebit API error: #{response.code}" unless response.success?
data = response.parsed_response
```

```php
<?php

$client = new GuzzleHttp\Client();

$response = $client->post("https://api.carebit.co/v1/human_tasks", [
    "headers" => [
      "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
      "Idempotency-Key" => bin2hex(random_bytes(16)),
    ],
    "json" => [
      "assignees" => [
        [
          "assignee_id" => "00000000-0000-4000-8000-000000000021",
          "assignee_type" => "staff_member"
        ]
      ],
      "content" => "Review the Patient's pre-operative DigitalFormResponse.",
      "due_date" => "2026-01-04",
      "is_urgent" => false,
      "patient_id" => "00000000-0000-4000-8000-000000000004"
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```


---

# List Insurance Companies

`GET /v1/insurance_companies`

Returns active insurance companies. Embassies and overseas government health offices are excluded.

**Required API scopes:** `payors.read`

## Parameters

- `limit` (query, `integer`) - The maximum number of items to return. Defaults to `25`; the maximum is `100`.
- `starting_after` (query, `string`) - Return items after this resource ID. You cannot use this with `cursor`.
- `cursor` (query, `string`) - The `next_cursor` value from the previous page. You cannot use this with `starting_after`.

## Response `200`

Paginated list of `InsuranceCompany` objects.

- `any`

### Example

```json
{
  "object": "list",
  "data": [
    {
      "id": "855e25b0-b138-48da-86ea-15162ce81f14",
      "object": "insurance_company",
      "created_at": "2026-01-01T09:00:00Z",
      "name": "Bupa",
      "updated_at": "2026-01-01T09:00:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": "eyJzdGFydF90aW1lIjoiMjAyNi0wMS0wMVQwOTowMDowMFoifQ",
  "url": "/v1/insurance_companies"
}
```

## Response `401`

The access token is missing, invalid, expired, or revoked.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `403`

The access token lacks the required scope, or the project is disabled.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `429`

Too many requests. Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Code samples

```bash
curl -X GET "https://api.carebit.co/v1/insurance_companies" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN"
```

```javascript
const response = await fetch("https://api.carebit.co/v1/insurance_companies", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
  },
});

if (!response.ok) {
  throw new Error(`Carebit API error: ${response.status}`);
}

const data = await response.json();
```

```python
import os
import requests

response = requests.get(
    "https://api.carebit.co/v1/insurance_companies",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
    }
)
response.raise_for_status()
data = response.json()
```

```ruby
require "httparty"

response = HTTParty.get(
  "https://api.carebit.co/v1/insurance_companies",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}"
  }
)
raise "Carebit API error: #{response.code}" unless response.success?
data = response.parsed_response
```

```php
<?php

$client = new GuzzleHttp\Client();

$response = $client->get("https://api.carebit.co/v1/insurance_companies", [
    "headers" => [
      "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```


---

# Get an Insurance Company

`GET /v1/insurance_companies/:id`

Returns an active insurance company. Embassy and overseas government health office identifiers return `404`.

**Required API scopes:** `payors.read`

## Parameters

- `id` (path, `string`) (required)

## Response `200`

The requested `InsuranceCompany`.

- `object`
  - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - `name` (`string`) - The name of the insurance company.
  - `object` (`any`) - Discriminator value emitted at `object`.
  - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.

### Example

```json
{
  "id": "855e25b0-b138-48da-86ea-15162ce81f14",
  "object": "insurance_company",
  "created_at": "2026-01-01T09:00:00Z",
  "name": "Bupa",
  "updated_at": "2026-01-01T09:00:00Z"
}
```

## Response `401`

The access token is missing, invalid, expired, or revoked.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `403`

The access token lacks the required scope, or the project is disabled.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `404`

Error response.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `429`

Too many requests. Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Code samples

```bash
curl -X GET "https://api.carebit.co/v1/insurance_companies/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN"
```

```javascript
const response = await fetch("https://api.carebit.co/v1/insurance_companies/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
  },
});

if (!response.ok) {
  throw new Error(`Carebit API error: ${response.status}`);
}

const data = await response.json();
```

```python
import os
import requests

response = requests.get(
    "https://api.carebit.co/v1/insurance_companies/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
    }
)
response.raise_for_status()
data = response.json()
```

```ruby
require "httparty"

response = HTTParty.get(
  "https://api.carebit.co/v1/insurance_companies/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}"
  }
)
raise "Carebit API error: #{response.code}" unless response.success?
data = response.parsed_response
```

```php
<?php

$client = new GuzzleHttp\Client();

$response = $client->get("https://api.carebit.co/v1/insurance_companies/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c", [
    "headers" => [
      "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```


---

# List Invoices

`GET /v1/invoices`

Returns Invoices in the authenticated Organization. `booking_id` and `patient_id` are optional. When both are supplied, an Invoice must match both filters.

**Required API scopes:** `invoices.read`

## Parameters

- `booking_id` (query, `string`) - Filter by a Booking in the Organization.
- `patient_id` (query, `string`) - Filter by a Patient with an active connection to the Organization.
- `limit` (query, `integer`) - The maximum number of items to return. Defaults to `25`; the maximum is `100`.
- `starting_after` (query, `string`) - Return items after this resource ID. You cannot use this with `cursor`.
- `cursor` (query, `string`) - The `next_cursor` value from the previous page. You cannot use this with `starting_after`.

## Response `200`

Paginated list of `Invoice` objects.

- `any`

### Example

```json
{
  "object": "list",
  "data": [
    {
      "id": "2fc3a636-66c0-4677-86be-032dd32125e1",
      "object": "invoice",
      "booking_ids": [
        "92a3b4c5-d6e7-4f01-8234-56789abcdef0"
      ],
      "clinician_id": "2b3c4d5e-6f70-489a-9bcd-ef0123456789",
      "created_at": "2026-01-01T09:00:00Z",
      "currency": "GBP",
      "invoice_notes": "<p>Payment is due within 30 days.</p>",
      "invoice_number": "INV-1001",
      "line_items": [
        {
          "id": "1bf0a3b9-0974-4fd3-8bf6-817d28071309",
          "object": "invoice_line_item",
          "booking_id": "92a3b4c5-d6e7-4f01-8234-56789abcdef0",
          "created_at": "2026-01-01T09:00:00Z",
          "currency": "GBP",
          "discount_amount": 1,
          "gross_amount": 1,
          "net_amount": 1,
          "quantity": 1.5,
          "service_variant_id": "6f708192-a3b4-4cde-9f01-23456789abcd",
          "tax_amount": 1,
          "title": "Dr",
          "total": 1,
          "unit_price": 1,
          "updated_at": "2026-01-01T09:00:00Z"
        }
      ],
      "links": {
        "patient": "https://api.carebit.co/v1/patients/1a2b3c4d-5e6f-4789-8abc-def012345678"
      },
      "patient_id": "1a2b3c4d-5e6f-4789-8abc-def012345678",
      "payor_type": "insurance_company",
      "status": "awaiting_patient",
      "subtotal": 1,
      "supply_date": "2026-01-01",
      "tax_amount": 1,
      "title": "Dr",
      "total": 1,
      "total_discount_amount": 1,
      "total_outstanding": 1,
      "total_paid": 1,
      "updated_at": "2026-01-01T09:00:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": "eyJzdGFydF90aW1lIjoiMjAyNi0wMS0wMVQwOTowMDowMFoifQ",
  "url": "/v1/invoices"
}
```

## Response `400`

A pagination parameter is invalid.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `401`

The access token is missing, invalid, expired, or revoked.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `403`

The access token lacks the required scope, or the project is disabled.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `404`

The Booking or Patient was not found in the Organization.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `429`

Too many requests. Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Code samples

```bash
curl -X GET "https://api.carebit.co/v1/invoices" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN"
```

```javascript
const response = await fetch("https://api.carebit.co/v1/invoices", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
  },
});

if (!response.ok) {
  throw new Error(`Carebit API error: ${response.status}`);
}

const data = await response.json();
```

```python
import os
import requests

response = requests.get(
    "https://api.carebit.co/v1/invoices",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
    }
)
response.raise_for_status()
data = response.json()
```

```ruby
require "httparty"

response = HTTParty.get(
  "https://api.carebit.co/v1/invoices",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}"
  }
)
raise "Carebit API error: #{response.code}" unless response.success?
data = response.parsed_response
```

```php
<?php

$client = new GuzzleHttp\Client();

$response = $client->get("https://api.carebit.co/v1/invoices", [
    "headers" => [
      "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```


---

# List Lead pipelines and stages

`GET /v1/lead_pipelines`

Returns the Organization's Lead and referral pipelines. When updating a Lead, use a stage from the pipeline for its `lead_type`. Carebit Pro is required.

**Required API scopes:** `leads.read`

## Response `200`

Paginated list of `LeadPipeline` objects.

- `any`

### Example

```json
{
  "object": "list",
  "data": [
    {
      "id": "5412a51a-d3f9-44d8-8291-939bc55c434e",
      "object": "lead_pipeline",
      "created_at": "2026-01-01T09:00:00Z",
      "lead_type": "inquiry",
      "name": "Initial consultation",
      "stages": [
        {
          "id": "306f78be-ffcc-472b-812e-a63d99e76e61",
          "object": "lead_stage",
          "created_at": "2026-01-01T09:00:00Z",
          "is_conversion_stage": true,
          "is_lost_stage": true,
          "name": "Initial consultation",
          "position": 1,
          "updated_at": "2026-01-01T09:00:00Z"
        }
      ],
      "updated_at": "2026-01-01T09:00:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": "eyJzdGFydF90aW1lIjoiMjAyNi0wMS0wMVQwOTowMDowMFoifQ",
  "url": "/v1/lead_pipelines"
}
```

## Response `401`

The access token is missing, invalid, expired, or revoked.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `403`

The access token lacks the required scope, the project is disabled, or the Organization does not have Carebit Pro.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `429`

Too many requests. Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Code samples

```bash
curl -X GET "https://api.carebit.co/v1/lead_pipelines" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN"
```

```javascript
const response = await fetch("https://api.carebit.co/v1/lead_pipelines", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
  },
});

if (!response.ok) {
  throw new Error(`Carebit API error: ${response.status}`);
}

const data = await response.json();
```

```python
import os
import requests

response = requests.get(
    "https://api.carebit.co/v1/lead_pipelines",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
    }
)
response.raise_for_status()
data = response.json()
```

```ruby
require "httparty"

response = HTTParty.get(
  "https://api.carebit.co/v1/lead_pipelines",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}"
  }
)
raise "Carebit API error: #{response.code}" unless response.success?
data = response.parsed_response
```

```php
<?php

$client = new GuzzleHttp\Client();

$response = $client->get("https://api.carebit.co/v1/lead_pipelines", [
    "headers" => [
      "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```


---

# List Leads

`GET /v1/leads`

Returns the Organization's patient inquiries and referrals. By default, results include active and lost Leads. Use `is_lost` to return only one group. Carebit Pro is required.

**Required API scopes:** `leads.read`

## Parameters

- `clinician_id` (query, `string`) - Filter by the identifier of the assigned clinician.
- `email` (query, `string`) - Filter by exact email address.
- `is_lost` (query, `boolean`) - When `true`, only lost Leads are returned. When `false`, only active Leads are returned. Omit to return both.
- `service_id` (query, `string`) - Filter by the Service the Lead is inquiring about.
- `updated_since` (query, `string`) - Return Leads updated at or after this ISO 8601 timestamp.
- `limit` (query, `integer`) - The maximum number of items to return. Defaults to `25`; the maximum is `100`.
- `starting_after` (query, `string`) - Return items after this resource ID. You cannot use this with `cursor`.
- `cursor` (query, `string`) - The `next_cursor` value from the previous page. You cannot use this with `starting_after`.

## Response `200`

Paginated list of `Lead` objects.

- `any`

### Example

```json
{
  "object": "list",
  "data": [
    {
      "id": "c0b9e949-67e8-4a50-8038-6168ab7f1d70",
      "object": "lead",
      "address_line_1": "10 Harley Street",
      "address_line_2": "Marylebone",
      "attachments": [
        {
          "id": "f631636b-32e2-41be-8e4f-0a34ee0d5d59",
          "download_url": "https://files.example.invalid/document.pdf?signature=test",
          "filename": "referral-letter.pdf"
        }
      ],
      "city": "London",
      "clinician": {
        "id": "2b3c4d5e-6f70-489a-9bcd-ef0123456789",
        "object": "clinician",
        "created_at": "2026-01-01T09:00:00Z",
        "display_name": "Dr Alex Morgan",
        "email": "alex.morgan@example.com",
        "first_name": "Alex",
        "last_name": "Morgan",
        "links": {
          "bookings": "https://api.carebit.co/v1/bookings?clinician_id=2b3c4d5e-6f70-489a-9bcd-ef0123456789"
        },
        "medical_specialty": "Cardiology",
        "title": "Dr",
        "updated_at": "2026-01-01T09:00:00Z"
      },
      "country_code": "GB",
      "county": "Greater London",
      "created_at": "2026-01-01T09:00:00Z",
      "creation_source": "api",
      "date_of_birth": "1990-01-01",
      "display_name": "Dr Alex Morgan",
      "email": "alex.morgan@example.com",
      "first_name": "Alex",
      "gdpr_consent_granted_at": "2026-01-01T09:00:00Z",
      "gdpr_consent_withdrawn_at": "2026-01-01T09:00:00Z",
      "internal_notes": "Asked about evening appointments with Dr Smith.",
      "is_converted_to_patient": true,
      "is_lost": false,
      "is_opted_out_of_sms": false,
      "is_signed_up_to_newsletters": true,
      "last_name": "Morgan",
      "lead_type": "inquiry",
      "links": {
        "clinician": "https://api.carebit.co/v1/clinicians/2b3c4d5e-6f70-489a-9bcd-ef0123456789",
        "remote_file_import_batch": "https://api.carebit.co/v1/remote_file_import_batches/ebc38802-f219-4c7b-8136-8e963a0c69e0",
        "self": "https://api.carebit.co/v1/leads/c0b9e949-67e8-4a50-8038-6168ab7f1d70",
        "service": "https://api.carebit.co/v1/services/5e6f7081-92a3-4bcd-8ef0-123456789abc"
      },
      "mobile": "7700900123",
      "mobile_country_dial_code": "GB",
      "organization_privacy_policy_consent_granted_at": "2026-01-01T09:00:00Z",
      "patient_id": "1a2b3c4d-5e6f-4789-8abc-def012345678",
      "phone": "2071234567",
      "phone_country_dial_code": "GB",
      "postcode": "W1G 9PF",
      "presenting_problem": "Persistent right knee pain",
      "referral_notes": "Referred by Dr Patel at Riverside Medical.",
      "referral_source": "consultant",
      "remote_file_import_batch_id": "ebc38802-f219-4c7b-8136-8e963a0c69e0",
      "service": {
        "id": "5e6f7081-92a3-4bcd-8ef0-123456789abc",
        "object": "service",
        "created_at": "2026-01-01T09:00:00Z",
        "description": "An initial consultation at the Harley Street Clinic.",
        "duration_minutes": 30,
        "is_bookable_online": true,
        "name": "Initial consultation",
        "service_variants": [
          {
            "id": "6f708192-a3b4-4cde-9f01-23456789abcd",
            "clinician_id": "2b3c4d5e-6f70-489a-9bcd-ef0123456789",
            "currency": "GBP",
            "description": "An initial consultation at the Harley Street Clinic.",
            "links": {
              "clinician": "https://api.carebit.co/v1/clinicians/2b3c4d5e-6f70-489a-9bcd-ef0123456789",
              "location": "https://api.carebit.co/v1/locations/3c4d5e6f-7081-49ab-acde-f0123456789a"
            },
            "location_id": "3c4d5e6f-7081-49ab-acde-f0123456789a",
            "net_price": 1,
            "permits_remote_bookings": true
          }
        ],
        "tax_rate": {
          "id": "211b60c7-ec1b-41b4-8a29-e855209bc694",
          "description": "An initial consultation at the Harley Street Clinic.",
          "percentage": 20,
          "title": "VAT"
        },
        "updated_at": "2026-01-01T09:00:00Z"
      },
      "sex": "female",
      "stage": {
        "id": "306f78be-ffcc-472b-812e-a63d99e76e61",
        "object": "lead_stage",
        "created_at": "2026-01-01T09:00:00Z",
        "is_conversion_stage": true,
        "is_lost_stage": true,
        "name": "Initial consultation",
        "position": 1,
        "updated_at": "2026-01-01T09:00:00Z"
      },
      "title": "Dr",
      "updated_at": "2026-01-01T09:00:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": "eyJzdGFydF90aW1lIjoiMjAyNi0wMS0wMVQwOTowMDowMFoifQ",
  "url": "/v1/leads"
}
```

## Response `400`

A filter or pagination parameter is invalid.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `401`

The access token is missing, invalid, expired, or revoked.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `403`

The access token lacks the required scope, the project is disabled, or the Organization does not have Carebit Pro.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `429`

Too many requests. Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Code samples

```bash
curl -X GET "https://api.carebit.co/v1/leads" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN"
```

```javascript
const response = await fetch("https://api.carebit.co/v1/leads", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
  },
});

if (!response.ok) {
  throw new Error(`Carebit API error: ${response.status}`);
}

const data = await response.json();
```

```python
import os
import requests

response = requests.get(
    "https://api.carebit.co/v1/leads",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
    }
)
response.raise_for_status()
data = response.json()
```

```ruby
require "httparty"

response = HTTParty.get(
  "https://api.carebit.co/v1/leads",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}"
  }
)
raise "Carebit API error: #{response.code}" unless response.success?
data = response.parsed_response
```

```php
<?php

$client = new GuzzleHttp\Client();

$response = $client->get("https://api.carebit.co/v1/leads", [
    "headers" => [
      "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```


---

# Create a Lead

`POST /v1/leads`

Creates a patient inquiry or referral in the Organization. Attachments can use a public HTTPS URL or Base64-encoded data. Carebit validates and scans them for malware in the background; poll the returned remote file import batch for their status. Each successful request creates a new Lead unless the response is an Idempotency-Key replay. Carebit Pro is required.

**Required API scopes:** `leads.create`

## Parameters

- `Idempotency-Key` (header, `string`) (required) - Client-generated idempotency key. Required for every POST/PATCH write. Replay of the same key with the same body returns the stored response with an `Idempotency-Replayed: true` header. Same key + different body returns `422 idempotency_key_reused`. A duplicate that arrives while the first request is still in flight returns `409 idempotency_conflict` with `Retry-After: 1`.

## Request body (`application/json`)

- `object`
  - `address_line_1` (`string | null`) - The primary address line of the lead.
  - `address_line_2` (`string | null`) - The secondary address line of the lead.
  - `attachments` (`array`) - The files to attach to the Lead in the background. Provide either `url` or `file_base64` for each file. Carebit validates and scans every file for malware.
    - `items` (`object`)
      - `file_base64` (`string`) - format: `byte`; The file bytes encoded as Base64. Provide this with `filename` instead of `url`. The decoded file can be at most 7 MB.
      - `filename` (`string | null`) - The filename to use for the attachment. Required with `file_base64`; defaults to the remote file's filename for URL sources.
      - `url` (`string`) - format: `uri`; The public HTTPS URL that Carebit can fetch.
  - `city` (`string | null`) - The city in the lead's postal address.
  - `clinician_id` (`string | null`) - format: `uuid`; The identifier of the clinician the lead is assigned to. Must be a clinician enabled in your Organization. Pass `null` to unassign.
  - `country_code` (`string | null`) - The uppercase ISO 3166-1 alpha-2 country code for the lead's postal address.
  - `county` (`string | null`) - The county or region in the lead's postal address.
  - `date_of_birth` (`string | null`) - format: `date`; The date of birth of the lead, in ISO 8601 format (YYYY-MM-DD).
  - `email` (`string | null`) - format: `email`; The contact email address of the lead.
  - `first_name` (`string`) - The first name of the lead. Required on create.
  - `gdpr_consent_granted_at` (`string | null`) - format: `date-time`; The ISO 8601 UTC timestamp at which the lead granted GDPR consent.
  - `gdpr_consent_withdrawn_at` (`string | null`) - format: `date-time`; The ISO 8601 UTC timestamp at which the lead withdrew GDPR consent.
  - `internal_notes` (`string | null`) - Internal notes shown in the Notes box next to presenting problem on the Carebit lead enquiry screen. Distinct from `referral_notes`.
  - `is_opted_out_of_sms` (`boolean`) - Whether the lead has opted out of SMS communication.
  - `is_signed_up_to_newsletters` (`boolean`) - Whether the lead has signed up to receive newsletters.
  - `last_name` (`string`) - The last name of the lead. Required on create.
  - `lead_type` (`string`) - enum: `inquiry`, `referral`; Whether to treat the record as a patient inquiry or a referral. Defaults to `inquiry` on create.
  - `mobile` (`string | null`) - The mobile phone number of the lead, without the country dial code.
  - `mobile_country_dial_code` (`string | null`) - The ISO 3166-1 alpha-2 country code that selects the international dial code for `mobile`, for example `GB` selects `+44`.
  - `organization_privacy_policy_consent_granted_at` (`string | null`) - format: `date-time`; The ISO 8601 UTC timestamp at which the lead granted consent to the Organization's privacy policy.
  - `phone` (`string | null`) - The landline phone number of the lead, without the country dial code.
  - `phone_country_dial_code` (`string | null`) - The ISO 3166-1 alpha-2 country code that selects the international dial code for `phone`, for example `GB` selects `+44`.
  - `postcode` (`string | null`) - The postal code in the lead's postal address.
  - `presenting_problem` (`string | null`) - The presenting problem the lead described. Shown next to Notes on the Carebit lead enquiry screen.
  - `referral_notes` (`string | null`) - The referral notes shown on the Carebit lead enquiry screen.
  - `referral_source` (`string | null`) - enum: `consultant`, `embassy`, `family_or_friend`, `gp_practice`, `hospital`, `insurance_company`, `physiotherapist`, `presentation_talk`, `previous_patient`, `private_practice`, `search_engine`, `self_referral`, `social_media`, `website`, `other`, `null`; The referral source shown on the Carebit lead enquiry screen.
  - `service_id` (`string | null`) - format: `uuid`; The Service the Lead is inquiring about. It must belong to your Organization. Pass `null` to clear.
  - `sex` (`string | null`) - The sex of the Lead as supplied on the inquiry.
  - `title` (`string | null`) - The personal title of the lead, when recorded.

### Example

```json
{
  "attachments": [
    {
      "filename": "referral-letter.pdf",
      "url": "https://files.example.com/referral-letter.pdf"
    }
  ],
  "clinician_id": "00000000-0000-4000-8000-000000000002",
  "country_code": "GB",
  "email": "riley.cooper@example.invalid",
  "first_name": "Riley",
  "internal_notes": "Asked about evening appointments with Dr Smith.",
  "last_name": "Cooper",
  "lead_type": "inquiry",
  "mobile": "7700900123",
  "mobile_country_dial_code": "GB",
  "presenting_problem": "Right knee pain",
  "referral_notes": "Referred by Dr Patel at Riverside Medical.",
  "referral_source": "gp_practice",
  "service_id": "00000000-0000-4000-8000-000000000005"
}
```

## Response `201`

Lead created.

- `object`
  - `address_line_1` (`string | null`) - The primary address line of the lead.
  - `address_line_2` (`string | null`) - The secondary address line of the lead.
  - `attachments` (`array`) - The files attached to the lead.
    - `items` (`object`)
      - `download_url` (`string | null`) - format: `uri`; The short-lived signed download URL for the attachment. Null while the malware scan is not complete.
      - `filename` (`string | null`) - The original filename of the attachment.
      - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - `city` (`string | null`) - The city in the lead's postal address.
  - `clinician` (`any`) - The clinician the lead is assigned to, when recorded.
  - `country_code` (`string | null`) - The ISO 3166-1 alpha-2 country code for the postal address, such as `GB` for the United Kingdom.
  - `county` (`string | null`) - The county or region in the lead's postal address.
  - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `creation_source` (`string | null`) - How the Lead was created. `api` means the record was created through the Developer Platform. Read-only.
  - `date_of_birth` (`string | null`) - format: `date`; The date of birth of the lead, in ISO 8601 format (YYYY-MM-DD).
  - `display_name` (`string | null`) - The formatted display name of the lead, including their title when recorded.
  - `email` (`string | null`) - format: `email`; The contact email address of the lead.
  - `first_name` (`string`) - The first name of the lead.
  - `gdpr_consent_granted_at` (`string | null`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `gdpr_consent_withdrawn_at` (`string | null`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - `internal_notes` (`string | null`) - Internal notes shown in the Notes box next to presenting problem on the Carebit lead enquiry screen. Distinct from `referral_notes`.
  - `is_converted_to_patient` (`boolean`) - Whether the lead has been converted to a patient. Read-only.
  - `is_lost` (`boolean`) - Whether the lead has been marked as lost. Read-only.
  - `is_opted_out_of_sms` (`boolean`) - Whether the lead has opted out of SMS communication.
  - `is_signed_up_to_newsletters` (`boolean`) - Whether the lead has signed up to receive newsletters.
  - `last_name` (`string`) - The last name of the lead.
  - `lead_type` (`string`) - enum: `inquiry`, `referral`; Whether the record is a patient inquiry or a referral.
  - `links` (`object`) - URLs to related resources. `remote_file_import_batch` is present on create responses when at least one attachment was submitted.
    - `clinician` (`string | null`) - format: `uri`; The full URL of a related resource.
    - `remote_file_import_batch` (`string`) - format: `uri`; The full URL of a related resource.
    - `self` (`string`) - format: `uri`; The full URL of a related resource.
    - `service` (`string | null`) - format: `uri`; The full URL of a related resource.
  - `mobile` (`string | null`) - The mobile phone number of the lead, without the country dial code.
  - `mobile_country_dial_code` (`string | null`) - The ISO 3166-1 alpha-2 country code that selects the international dial code for `mobile`, for example `GB` selects `+44`.
  - `object` (`any`) - Discriminator value emitted at `object`.
  - `organization_privacy_policy_consent_granted_at` (`string | null`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `patient_id` (`string | null`) - format: `uuid`; The identifier of the Patient this Lead was converted to. Null until conversion. Read-only.
  - `phone` (`string | null`) - The landline phone number of the lead, without the country dial code.
  - `phone_country_dial_code` (`string | null`) - The ISO 3166-1 alpha-2 country code that selects the international dial code for `phone`, for example `GB` selects `+44`.
  - `postcode` (`string | null`) - The postal code in the lead's postal address.
  - `presenting_problem` (`string | null`) - The presenting problem the lead described. Shown next to Notes on the Carebit lead enquiry screen.
  - `referral_notes` (`string | null`) - The referral notes shown on the Carebit lead enquiry screen.
  - `referral_source` (`string | null`) - enum: `consultant`, `embassy`, `family_or_friend`, `gp_practice`, `hospital`, `insurance_company`, `physiotherapist`, `presentation_talk`, `previous_patient`, `private_practice`, `search_engine`, `self_referral`, `social_media`, `website`, `other`, `null`; The referral source shown on the Carebit lead enquiry screen.
  - `remote_file_import_batch_id` (`string`) - format: `uuid`; The identifier of the remote file import batch created for the submitted attachments. Present on create responses when at least one attachment was submitted.
  - `service` (`any`) - The Service the Lead is inquiring about, when recorded.
  - `sex` (`string | null`) - The sex of the Lead as supplied on the inquiry.
  - `stage` (`any`) - The current pipeline stage of the lead. Read-only; use `stage_id` when updating the lead.
  - `title` (`string | null`) - The personal title of the lead, when recorded.
  - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.

### Example

```json
{
  "id": "c0b9e949-67e8-4a50-8038-6168ab7f1d70",
  "object": "lead",
  "address_line_1": "10 Harley Street",
  "address_line_2": "Marylebone",
  "attachments": [
    {
      "id": "f631636b-32e2-41be-8e4f-0a34ee0d5d59",
      "download_url": "https://files.example.invalid/document.pdf?signature=test",
      "filename": "referral-letter.pdf"
    }
  ],
  "city": "London",
  "clinician": {
    "id": "2b3c4d5e-6f70-489a-9bcd-ef0123456789",
    "object": "clinician",
    "created_at": "2026-01-01T09:00:00Z",
    "display_name": "Dr Alex Morgan",
    "email": "alex.morgan@example.com",
    "first_name": "Alex",
    "last_name": "Morgan",
    "links": {
      "bookings": "https://api.carebit.co/v1/bookings?clinician_id=2b3c4d5e-6f70-489a-9bcd-ef0123456789"
    },
    "medical_specialty": "Cardiology",
    "title": "Dr",
    "updated_at": "2026-01-01T09:00:00Z"
  },
  "country_code": "GB",
  "county": "Greater London",
  "created_at": "2026-01-01T09:00:00Z",
  "creation_source": "api",
  "date_of_birth": "1990-01-01",
  "display_name": "Dr Alex Morgan",
  "email": "alex.morgan@example.com",
  "first_name": "Alex",
  "gdpr_consent_granted_at": "2026-01-01T09:00:00Z",
  "gdpr_consent_withdrawn_at": "2026-01-01T09:00:00Z",
  "internal_notes": "Asked about evening appointments with Dr Smith.",
  "is_converted_to_patient": true,
  "is_lost": false,
  "is_opted_out_of_sms": false,
  "is_signed_up_to_newsletters": true,
  "last_name": "Morgan",
  "lead_type": "inquiry",
  "links": {
    "clinician": "https://api.carebit.co/v1/clinicians/2b3c4d5e-6f70-489a-9bcd-ef0123456789",
    "remote_file_import_batch": "https://api.carebit.co/v1/remote_file_import_batches/ebc38802-f219-4c7b-8136-8e963a0c69e0",
    "self": "https://api.carebit.co/v1/leads/c0b9e949-67e8-4a50-8038-6168ab7f1d70",
    "service": "https://api.carebit.co/v1/services/5e6f7081-92a3-4bcd-8ef0-123456789abc"
  },
  "mobile": "7700900123",
  "mobile_country_dial_code": "GB",
  "organization_privacy_policy_consent_granted_at": "2026-01-01T09:00:00Z",
  "patient_id": "1a2b3c4d-5e6f-4789-8abc-def012345678",
  "phone": "2071234567",
  "phone_country_dial_code": "GB",
  "postcode": "W1G 9PF",
  "presenting_problem": "Persistent right knee pain",
  "referral_notes": "Referred by Dr Patel at Riverside Medical.",
  "referral_source": "consultant",
  "remote_file_import_batch_id": "ebc38802-f219-4c7b-8136-8e963a0c69e0",
  "service": {
    "id": "5e6f7081-92a3-4bcd-8ef0-123456789abc",
    "object": "service",
    "created_at": "2026-01-01T09:00:00Z",
    "description": "An initial consultation at the Harley Street Clinic.",
    "duration_minutes": 30,
    "is_bookable_online": true,
    "name": "Initial consultation",
    "service_variants": [
      {
        "id": "6f708192-a3b4-4cde-9f01-23456789abcd",
        "clinician_id": "2b3c4d5e-6f70-489a-9bcd-ef0123456789",
        "currency": "GBP",
        "description": "An initial consultation at the Harley Street Clinic.",
        "links": {
          "clinician": "https://api.carebit.co/v1/clinicians/2b3c4d5e-6f70-489a-9bcd-ef0123456789",
          "location": "https://api.carebit.co/v1/locations/3c4d5e6f-7081-49ab-acde-f0123456789a"
        },
        "location_id": "3c4d5e6f-7081-49ab-acde-f0123456789a",
        "net_price": 1,
        "permits_remote_bookings": true
      }
    ],
    "tax_rate": {
      "id": "211b60c7-ec1b-41b4-8a29-e855209bc694",
      "description": "An initial consultation at the Harley Street Clinic.",
      "percentage": 20,
      "title": "VAT"
    },
    "updated_at": "2026-01-01T09:00:00Z"
  },
  "sex": "female",
  "stage": {
    "id": "306f78be-ffcc-472b-812e-a63d99e76e61",
    "object": "lead_stage",
    "created_at": "2026-01-01T09:00:00Z",
    "is_conversion_stage": true,
    "is_lost_stage": true,
    "name": "Initial consultation",
    "position": 1,
    "updated_at": "2026-01-01T09:00:00Z"
  },
  "title": "Dr",
  "updated_at": "2026-01-01T09:00:00Z"
}
```

## Response `400`

The `Idempotency-Key` header is missing (`idempotency_key_required`) or exceeds 255 characters (`idempotency_key_too_long`).

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `401`

The access token is missing, invalid, expired, or revoked.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `403`

The access token lacks the required scope, the project is disabled, or the Organization does not have Carebit Pro.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `404`

A referenced resource was not found in your Organization.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `409`

A concurrent request holds the idempotency lease (`idempotency_conflict`). Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `422`

The `Idempotency-Key` was previously used with a different request body (`idempotency_key_reused`), or the request body failed validation.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `429`

Too many requests. Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Code samples

```bash
curl -X POST "https://api.carebit.co/v1/leads" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "attachments": [
    {
      "filename": "referral-letter.pdf",
      "url": "https://files.example.com/referral-letter.pdf"
    }
  ],
  "clinician_id": "00000000-0000-4000-8000-000000000002",
  "country_code": "GB",
  "email": "riley.cooper@example.invalid",
  "first_name": "Riley",
  "internal_notes": "Asked about evening appointments with Dr Smith.",
  "last_name": "Cooper",
  "lead_type": "inquiry",
  "mobile": "7700900123",
  "mobile_country_dial_code": "GB",
  "presenting_problem": "Right knee pain",
  "referral_notes": "Referred by Dr Patel at Riverside Medical.",
  "referral_source": "gp_practice",
  "service_id": "00000000-0000-4000-8000-000000000005"
}'
```

```javascript
const response = await fetch("https://api.carebit.co/v1/leads", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
  "attachments": [
    {
      "filename": "referral-letter.pdf",
      "url": "https://files.example.com/referral-letter.pdf"
    }
  ],
  "clinician_id": "00000000-0000-4000-8000-000000000002",
  "country_code": "GB",
  "email": "riley.cooper@example.invalid",
  "first_name": "Riley",
  "internal_notes": "Asked about evening appointments with Dr Smith.",
  "last_name": "Cooper",
  "lead_type": "inquiry",
  "mobile": "7700900123",
  "mobile_country_dial_code": "GB",
  "presenting_problem": "Right knee pain",
  "referral_notes": "Referred by Dr Patel at Riverside Medical.",
  "referral_source": "gp_practice",
  "service_id": "00000000-0000-4000-8000-000000000005"
}),
});

if (!response.ok) {
  throw new Error(`Carebit API error: ${response.status}`);
}

const data = await response.json();
```

```python
import os
import requests
import uuid

response = requests.post(
    "https://api.carebit.co/v1/leads",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "attachments": [
            {
                "filename": "referral-letter.pdf",
                "url": "https://files.example.com/referral-letter.pdf"
            }
        ],
        "clinician_id": "00000000-0000-4000-8000-000000000002",
        "country_code": "GB",
        "email": "riley.cooper@example.invalid",
        "first_name": "Riley",
        "internal_notes": "Asked about evening appointments with Dr Smith.",
        "last_name": "Cooper",
        "lead_type": "inquiry",
        "mobile": "7700900123",
        "mobile_country_dial_code": "GB",
        "presenting_problem": "Right knee pain",
        "referral_notes": "Referred by Dr Patel at Riverside Medical.",
        "referral_source": "gp_practice",
        "service_id": "00000000-0000-4000-8000-000000000005"
    }
)
response.raise_for_status()
data = response.json()
```

```ruby
require "httparty"
require "json"
require "securerandom"

response = HTTParty.post(
  "https://api.carebit.co/v1/leads",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}",
    "Idempotency-Key" => SecureRandom.uuid,
    "Content-Type" => "application/json"
  },
  body: {
    "attachments" => [
      {
        "filename" => "referral-letter.pdf",
        "url" => "https://files.example.com/referral-letter.pdf"
      }
    ],
    "clinician_id" => "00000000-0000-4000-8000-000000000002",
    "country_code" => "GB",
    "email" => "riley.cooper@example.invalid",
    "first_name" => "Riley",
    "internal_notes" => "Asked about evening appointments with Dr Smith.",
    "last_name" => "Cooper",
    "lead_type" => "inquiry",
    "mobile" => "7700900123",
    "mobile_country_dial_code" => "GB",
    "presenting_problem" => "Right knee pain",
    "referral_notes" => "Referred by Dr Patel at Riverside Medical.",
    "referral_source" => "gp_practice",
    "service_id" => "00000000-0000-4000-8000-000000000005"
  }.to_json
)
raise "Carebit API error: #{response.code}" unless response.success?
data = response.parsed_response
```

```php
<?php

$client = new GuzzleHttp\Client();

$response = $client->post("https://api.carebit.co/v1/leads", [
    "headers" => [
      "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
      "Idempotency-Key" => bin2hex(random_bytes(16)),
    ],
    "json" => [
      "attachments" => [
        [
          "filename" => "referral-letter.pdf",
          "url" => "https://files.example.com/referral-letter.pdf"
        ]
      ],
      "clinician_id" => "00000000-0000-4000-8000-000000000002",
      "country_code" => "GB",
      "email" => "riley.cooper@example.invalid",
      "first_name" => "Riley",
      "internal_notes" => "Asked about evening appointments with Dr Smith.",
      "last_name" => "Cooper",
      "lead_type" => "inquiry",
      "mobile" => "7700900123",
      "mobile_country_dial_code" => "GB",
      "presenting_problem" => "Right knee pain",
      "referral_notes" => "Referred by Dr Patel at Riverside Medical.",
      "referral_source" => "gp_practice",
      "service_id" => "00000000-0000-4000-8000-000000000005"
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```


---

# Get a Lead

`GET /v1/leads/:id`

Returns a patient inquiry or referral from the Organization. Carebit Pro is required.

**Required API scopes:** `leads.read`

## Parameters

- `id` (path, `string`) (required)

## Response `200`

The requested `Lead`.

- `object`
  - `address_line_1` (`string | null`) - The primary address line of the lead.
  - `address_line_2` (`string | null`) - The secondary address line of the lead.
  - `attachments` (`array`) - The files attached to the lead.
    - `items` (`object`)
      - `download_url` (`string | null`) - format: `uri`; The short-lived signed download URL for the attachment. Null while the malware scan is not complete.
      - `filename` (`string | null`) - The original filename of the attachment.
      - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - `city` (`string | null`) - The city in the lead's postal address.
  - `clinician` (`any`) - The clinician the lead is assigned to, when recorded.
  - `country_code` (`string | null`) - The ISO 3166-1 alpha-2 country code for the postal address, such as `GB` for the United Kingdom.
  - `county` (`string | null`) - The county or region in the lead's postal address.
  - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `creation_source` (`string | null`) - How the Lead was created. `api` means the record was created through the Developer Platform. Read-only.
  - `date_of_birth` (`string | null`) - format: `date`; The date of birth of the lead, in ISO 8601 format (YYYY-MM-DD).
  - `display_name` (`string | null`) - The formatted display name of the lead, including their title when recorded.
  - `email` (`string | null`) - format: `email`; The contact email address of the lead.
  - `first_name` (`string`) - The first name of the lead.
  - `gdpr_consent_granted_at` (`string | null`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `gdpr_consent_withdrawn_at` (`string | null`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - `internal_notes` (`string | null`) - Internal notes shown in the Notes box next to presenting problem on the Carebit lead enquiry screen. Distinct from `referral_notes`.
  - `is_converted_to_patient` (`boolean`) - Whether the lead has been converted to a patient. Read-only.
  - `is_lost` (`boolean`) - Whether the lead has been marked as lost. Read-only.
  - `is_opted_out_of_sms` (`boolean`) - Whether the lead has opted out of SMS communication.
  - `is_signed_up_to_newsletters` (`boolean`) - Whether the lead has signed up to receive newsletters.
  - `last_name` (`string`) - The last name of the lead.
  - `lead_type` (`string`) - enum: `inquiry`, `referral`; Whether the record is a patient inquiry or a referral.
  - `links` (`object`) - URLs to related resources. `remote_file_import_batch` is present on create responses when at least one attachment was submitted.
    - `clinician` (`string | null`) - format: `uri`; The full URL of a related resource.
    - `remote_file_import_batch` (`string`) - format: `uri`; The full URL of a related resource.
    - `self` (`string`) - format: `uri`; The full URL of a related resource.
    - `service` (`string | null`) - format: `uri`; The full URL of a related resource.
  - `mobile` (`string | null`) - The mobile phone number of the lead, without the country dial code.
  - `mobile_country_dial_code` (`string | null`) - The ISO 3166-1 alpha-2 country code that selects the international dial code for `mobile`, for example `GB` selects `+44`.
  - `object` (`any`) - Discriminator value emitted at `object`.
  - `organization_privacy_policy_consent_granted_at` (`string | null`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `patient_id` (`string | null`) - format: `uuid`; The identifier of the Patient this Lead was converted to. Null until conversion. Read-only.
  - `phone` (`string | null`) - The landline phone number of the lead, without the country dial code.
  - `phone_country_dial_code` (`string | null`) - The ISO 3166-1 alpha-2 country code that selects the international dial code for `phone`, for example `GB` selects `+44`.
  - `postcode` (`string | null`) - The postal code in the lead's postal address.
  - `presenting_problem` (`string | null`) - The presenting problem the lead described. Shown next to Notes on the Carebit lead enquiry screen.
  - `referral_notes` (`string | null`) - The referral notes shown on the Carebit lead enquiry screen.
  - `referral_source` (`string | null`) - enum: `consultant`, `embassy`, `family_or_friend`, `gp_practice`, `hospital`, `insurance_company`, `physiotherapist`, `presentation_talk`, `previous_patient`, `private_practice`, `search_engine`, `self_referral`, `social_media`, `website`, `other`, `null`; The referral source shown on the Carebit lead enquiry screen.
  - `remote_file_import_batch_id` (`string`) - format: `uuid`; The identifier of the remote file import batch created for the submitted attachments. Present on create responses when at least one attachment was submitted.
  - `service` (`any`) - The Service the Lead is inquiring about, when recorded.
  - `sex` (`string | null`) - The sex of the Lead as supplied on the inquiry.
  - `stage` (`any`) - The current pipeline stage of the lead. Read-only; use `stage_id` when updating the lead.
  - `title` (`string | null`) - The personal title of the lead, when recorded.
  - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.

### Example

```json
{
  "id": "c0b9e949-67e8-4a50-8038-6168ab7f1d70",
  "object": "lead",
  "address_line_1": "10 Harley Street",
  "address_line_2": "Marylebone",
  "attachments": [
    {
      "id": "f631636b-32e2-41be-8e4f-0a34ee0d5d59",
      "download_url": "https://files.example.invalid/document.pdf?signature=test",
      "filename": "referral-letter.pdf"
    }
  ],
  "city": "London",
  "clinician": {
    "id": "2b3c4d5e-6f70-489a-9bcd-ef0123456789",
    "object": "clinician",
    "created_at": "2026-01-01T09:00:00Z",
    "display_name": "Dr Alex Morgan",
    "email": "alex.morgan@example.com",
    "first_name": "Alex",
    "last_name": "Morgan",
    "links": {
      "bookings": "https://api.carebit.co/v1/bookings?clinician_id=2b3c4d5e-6f70-489a-9bcd-ef0123456789"
    },
    "medical_specialty": "Cardiology",
    "title": "Dr",
    "updated_at": "2026-01-01T09:00:00Z"
  },
  "country_code": "GB",
  "county": "Greater London",
  "created_at": "2026-01-01T09:00:00Z",
  "creation_source": "api",
  "date_of_birth": "1990-01-01",
  "display_name": "Dr Alex Morgan",
  "email": "alex.morgan@example.com",
  "first_name": "Alex",
  "gdpr_consent_granted_at": "2026-01-01T09:00:00Z",
  "gdpr_consent_withdrawn_at": "2026-01-01T09:00:00Z",
  "internal_notes": "Asked about evening appointments with Dr Smith.",
  "is_converted_to_patient": true,
  "is_lost": false,
  "is_opted_out_of_sms": false,
  "is_signed_up_to_newsletters": true,
  "last_name": "Morgan",
  "lead_type": "inquiry",
  "links": {
    "clinician": "https://api.carebit.co/v1/clinicians/2b3c4d5e-6f70-489a-9bcd-ef0123456789",
    "remote_file_import_batch": "https://api.carebit.co/v1/remote_file_import_batches/ebc38802-f219-4c7b-8136-8e963a0c69e0",
    "self": "https://api.carebit.co/v1/leads/c0b9e949-67e8-4a50-8038-6168ab7f1d70",
    "service": "https://api.carebit.co/v1/services/5e6f7081-92a3-4bcd-8ef0-123456789abc"
  },
  "mobile": "7700900123",
  "mobile_country_dial_code": "GB",
  "organization_privacy_policy_consent_granted_at": "2026-01-01T09:00:00Z",
  "patient_id": "1a2b3c4d-5e6f-4789-8abc-def012345678",
  "phone": "2071234567",
  "phone_country_dial_code": "GB",
  "postcode": "W1G 9PF",
  "presenting_problem": "Persistent right knee pain",
  "referral_notes": "Referred by Dr Patel at Riverside Medical.",
  "referral_source": "consultant",
  "remote_file_import_batch_id": "ebc38802-f219-4c7b-8136-8e963a0c69e0",
  "service": {
    "id": "5e6f7081-92a3-4bcd-8ef0-123456789abc",
    "object": "service",
    "created_at": "2026-01-01T09:00:00Z",
    "description": "An initial consultation at the Harley Street Clinic.",
    "duration_minutes": 30,
    "is_bookable_online": true,
    "name": "Initial consultation",
    "service_variants": [
      {
        "id": "6f708192-a3b4-4cde-9f01-23456789abcd",
        "clinician_id": "2b3c4d5e-6f70-489a-9bcd-ef0123456789",
        "currency": "GBP",
        "description": "An initial consultation at the Harley Street Clinic.",
        "links": {
          "clinician": "https://api.carebit.co/v1/clinicians/2b3c4d5e-6f70-489a-9bcd-ef0123456789",
          "location": "https://api.carebit.co/v1/locations/3c4d5e6f-7081-49ab-acde-f0123456789a"
        },
        "location_id": "3c4d5e6f-7081-49ab-acde-f0123456789a",
        "net_price": 1,
        "permits_remote_bookings": true
      }
    ],
    "tax_rate": {
      "id": "211b60c7-ec1b-41b4-8a29-e855209bc694",
      "description": "An initial consultation at the Harley Street Clinic.",
      "percentage": 20,
      "title": "VAT"
    },
    "updated_at": "2026-01-01T09:00:00Z"
  },
  "sex": "female",
  "stage": {
    "id": "306f78be-ffcc-472b-812e-a63d99e76e61",
    "object": "lead_stage",
    "created_at": "2026-01-01T09:00:00Z",
    "is_conversion_stage": true,
    "is_lost_stage": true,
    "name": "Initial consultation",
    "position": 1,
    "updated_at": "2026-01-01T09:00:00Z"
  },
  "title": "Dr",
  "updated_at": "2026-01-01T09:00:00Z"
}
```

## Response `401`

The access token is missing, invalid, expired, or revoked.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `403`

The access token lacks the required scope, the project is disabled, or the Organization does not have Carebit Pro.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `404`

Error response.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `429`

Too many requests. Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Code samples

```bash
curl -X GET "https://api.carebit.co/v1/leads/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN"
```

```javascript
const response = await fetch("https://api.carebit.co/v1/leads/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
  },
});

if (!response.ok) {
  throw new Error(`Carebit API error: ${response.status}`);
}

const data = await response.json();
```

```python
import os
import requests

response = requests.get(
    "https://api.carebit.co/v1/leads/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
    }
)
response.raise_for_status()
data = response.json()
```

```ruby
require "httparty"

response = HTTParty.get(
  "https://api.carebit.co/v1/leads/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}"
  }
)
raise "Carebit API error: #{response.code}" unless response.success?
data = response.parsed_response
```

```php
<?php

$client = new GuzzleHttp\Client();

$response = $client->get("https://api.carebit.co/v1/leads/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c", [
    "headers" => [
      "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```


---

# Update a Lead

`PATCH /v1/leads/:id`

Updates any patient inquiry or referral in the Organization, regardless of how it was created. Use `stage_id` to move the Lead within the pipeline for its resulting `lead_type`. Conversion and lost stages can start the Organization's configured workflows. Attribution and lifecycle fields are read-only. Carebit Pro is required.

**Required API scopes:** `leads.update`

## Parameters

- `id` (path, `string`) (required)
- `Idempotency-Key` (header, `string`) (required) - Client-generated idempotency key. Required for every POST/PATCH write. Replay of the same key with the same body returns the stored response with an `Idempotency-Replayed: true` header. Same key + different body returns `422 idempotency_key_reused`. A duplicate that arrives while the first request is still in flight returns `409 idempotency_conflict` with `Retry-After: 1`.

## Request body (`application/json`)

- `object`
  - `address_line_1` (`string | null`) - The primary address line of the lead.
  - `address_line_2` (`string | null`) - The secondary address line of the lead.
  - `city` (`string | null`) - The city in the lead's postal address.
  - `clinician_id` (`string | null`) - format: `uuid`; The identifier of the clinician the lead is assigned to. Must be a clinician enabled in your Organization. Pass `null` to unassign.
  - `country_code` (`string | null`) - The uppercase ISO 3166-1 alpha-2 country code for the lead's postal address.
  - `county` (`string | null`) - The county or region in the lead's postal address.
  - `date_of_birth` (`string | null`) - format: `date`; The date of birth of the lead, in ISO 8601 format (YYYY-MM-DD).
  - `email` (`string | null`) - format: `email`; The contact email address of the lead.
  - `first_name` (`string`) - The first name of the lead. Required on create.
  - `gdpr_consent_granted_at` (`string | null`) - format: `date-time`; The ISO 8601 UTC timestamp at which the lead granted GDPR consent.
  - `gdpr_consent_withdrawn_at` (`string | null`) - format: `date-time`; The ISO 8601 UTC timestamp at which the lead withdrew GDPR consent.
  - `internal_notes` (`string | null`) - Internal notes shown in the Notes box next to presenting problem on the Carebit lead enquiry screen. Distinct from `referral_notes`.
  - `is_opted_out_of_sms` (`boolean`) - Whether the lead has opted out of SMS communication.
  - `is_signed_up_to_newsletters` (`boolean`) - Whether the lead has signed up to receive newsletters.
  - `last_name` (`string`) - The last name of the lead. Required on create.
  - `lead_type` (`string`) - enum: `inquiry`, `referral`; Whether to treat the record as a patient inquiry or a referral. Defaults to `inquiry` on create.
  - `mobile` (`string | null`) - The mobile phone number of the lead, without the country dial code.
  - `mobile_country_dial_code` (`string | null`) - The ISO 3166-1 alpha-2 country code that selects the international dial code for `mobile`, for example `GB` selects `+44`.
  - `organization_privacy_policy_consent_granted_at` (`string | null`) - format: `date-time`; The ISO 8601 UTC timestamp at which the lead granted consent to the Organization's privacy policy.
  - `phone` (`string | null`) - The landline phone number of the lead, without the country dial code.
  - `phone_country_dial_code` (`string | null`) - The ISO 3166-1 alpha-2 country code that selects the international dial code for `phone`, for example `GB` selects `+44`.
  - `postcode` (`string | null`) - The postal code in the lead's postal address.
  - `presenting_problem` (`string | null`) - The presenting problem the lead described. Shown next to Notes on the Carebit lead enquiry screen.
  - `referral_notes` (`string | null`) - The referral notes shown on the Carebit lead enquiry screen.
  - `referral_source` (`string | null`) - enum: `consultant`, `embassy`, `family_or_friend`, `gp_practice`, `hospital`, `insurance_company`, `physiotherapist`, `presentation_talk`, `previous_patient`, `private_practice`, `search_engine`, `self_referral`, `social_media`, `website`, `other`, `null`; The referral source shown on the Carebit lead enquiry screen.
  - `service_id` (`string | null`) - format: `uuid`; The Service the Lead is inquiring about. It must belong to your Organization. Pass `null` to clear.
  - `sex` (`string | null`) - The sex of the Lead as supplied on the inquiry.
  - `stage_id` (`string`) - format: `uuid`; The identifier of a stage in the pipeline that matches the Lead's resulting `lead_type`.
  - `title` (`string | null`) - The personal title of the lead, when recorded.

### Example

```json
{
  "presenting_problem": "Left knee pain (updated)",
  "stage_id": "00000000-0000-4000-8000-00000000000d"
}
```

## Response `200`

The requested `Lead`.

- `object`
  - `address_line_1` (`string | null`) - The primary address line of the lead.
  - `address_line_2` (`string | null`) - The secondary address line of the lead.
  - `attachments` (`array`) - The files attached to the lead.
    - `items` (`object`)
      - `download_url` (`string | null`) - format: `uri`; The short-lived signed download URL for the attachment. Null while the malware scan is not complete.
      - `filename` (`string | null`) - The original filename of the attachment.
      - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - `city` (`string | null`) - The city in the lead's postal address.
  - `clinician` (`any`) - The clinician the lead is assigned to, when recorded.
  - `country_code` (`string | null`) - The ISO 3166-1 alpha-2 country code for the postal address, such as `GB` for the United Kingdom.
  - `county` (`string | null`) - The county or region in the lead's postal address.
  - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `creation_source` (`string | null`) - How the Lead was created. `api` means the record was created through the Developer Platform. Read-only.
  - `date_of_birth` (`string | null`) - format: `date`; The date of birth of the lead, in ISO 8601 format (YYYY-MM-DD).
  - `display_name` (`string | null`) - The formatted display name of the lead, including their title when recorded.
  - `email` (`string | null`) - format: `email`; The contact email address of the lead.
  - `first_name` (`string`) - The first name of the lead.
  - `gdpr_consent_granted_at` (`string | null`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `gdpr_consent_withdrawn_at` (`string | null`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - `internal_notes` (`string | null`) - Internal notes shown in the Notes box next to presenting problem on the Carebit lead enquiry screen. Distinct from `referral_notes`.
  - `is_converted_to_patient` (`boolean`) - Whether the lead has been converted to a patient. Read-only.
  - `is_lost` (`boolean`) - Whether the lead has been marked as lost. Read-only.
  - `is_opted_out_of_sms` (`boolean`) - Whether the lead has opted out of SMS communication.
  - `is_signed_up_to_newsletters` (`boolean`) - Whether the lead has signed up to receive newsletters.
  - `last_name` (`string`) - The last name of the lead.
  - `lead_type` (`string`) - enum: `inquiry`, `referral`; Whether the record is a patient inquiry or a referral.
  - `links` (`object`) - URLs to related resources. `remote_file_import_batch` is present on create responses when at least one attachment was submitted.
    - `clinician` (`string | null`) - format: `uri`; The full URL of a related resource.
    - `remote_file_import_batch` (`string`) - format: `uri`; The full URL of a related resource.
    - `self` (`string`) - format: `uri`; The full URL of a related resource.
    - `service` (`string | null`) - format: `uri`; The full URL of a related resource.
  - `mobile` (`string | null`) - The mobile phone number of the lead, without the country dial code.
  - `mobile_country_dial_code` (`string | null`) - The ISO 3166-1 alpha-2 country code that selects the international dial code for `mobile`, for example `GB` selects `+44`.
  - `object` (`any`) - Discriminator value emitted at `object`.
  - `organization_privacy_policy_consent_granted_at` (`string | null`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `patient_id` (`string | null`) - format: `uuid`; The identifier of the Patient this Lead was converted to. Null until conversion. Read-only.
  - `phone` (`string | null`) - The landline phone number of the lead, without the country dial code.
  - `phone_country_dial_code` (`string | null`) - The ISO 3166-1 alpha-2 country code that selects the international dial code for `phone`, for example `GB` selects `+44`.
  - `postcode` (`string | null`) - The postal code in the lead's postal address.
  - `presenting_problem` (`string | null`) - The presenting problem the lead described. Shown next to Notes on the Carebit lead enquiry screen.
  - `referral_notes` (`string | null`) - The referral notes shown on the Carebit lead enquiry screen.
  - `referral_source` (`string | null`) - enum: `consultant`, `embassy`, `family_or_friend`, `gp_practice`, `hospital`, `insurance_company`, `physiotherapist`, `presentation_talk`, `previous_patient`, `private_practice`, `search_engine`, `self_referral`, `social_media`, `website`, `other`, `null`; The referral source shown on the Carebit lead enquiry screen.
  - `remote_file_import_batch_id` (`string`) - format: `uuid`; The identifier of the remote file import batch created for the submitted attachments. Present on create responses when at least one attachment was submitted.
  - `service` (`any`) - The Service the Lead is inquiring about, when recorded.
  - `sex` (`string | null`) - The sex of the Lead as supplied on the inquiry.
  - `stage` (`any`) - The current pipeline stage of the lead. Read-only; use `stage_id` when updating the lead.
  - `title` (`string | null`) - The personal title of the lead, when recorded.
  - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.

### Example

```json
{
  "id": "c0b9e949-67e8-4a50-8038-6168ab7f1d70",
  "object": "lead",
  "address_line_1": "10 Harley Street",
  "address_line_2": "Marylebone",
  "attachments": [
    {
      "id": "f631636b-32e2-41be-8e4f-0a34ee0d5d59",
      "download_url": "https://files.example.invalid/document.pdf?signature=test",
      "filename": "referral-letter.pdf"
    }
  ],
  "city": "London",
  "clinician": {
    "id": "2b3c4d5e-6f70-489a-9bcd-ef0123456789",
    "object": "clinician",
    "created_at": "2026-01-01T09:00:00Z",
    "display_name": "Dr Alex Morgan",
    "email": "alex.morgan@example.com",
    "first_name": "Alex",
    "last_name": "Morgan",
    "links": {
      "bookings": "https://api.carebit.co/v1/bookings?clinician_id=2b3c4d5e-6f70-489a-9bcd-ef0123456789"
    },
    "medical_specialty": "Cardiology",
    "title": "Dr",
    "updated_at": "2026-01-01T09:00:00Z"
  },
  "country_code": "GB",
  "county": "Greater London",
  "created_at": "2026-01-01T09:00:00Z",
  "creation_source": "api",
  "date_of_birth": "1990-01-01",
  "display_name": "Dr Alex Morgan",
  "email": "alex.morgan@example.com",
  "first_name": "Alex",
  "gdpr_consent_granted_at": "2026-01-01T09:00:00Z",
  "gdpr_consent_withdrawn_at": "2026-01-01T09:00:00Z",
  "internal_notes": "Asked about evening appointments with Dr Smith.",
  "is_converted_to_patient": true,
  "is_lost": false,
  "is_opted_out_of_sms": false,
  "is_signed_up_to_newsletters": true,
  "last_name": "Morgan",
  "lead_type": "inquiry",
  "links": {
    "clinician": "https://api.carebit.co/v1/clinicians/2b3c4d5e-6f70-489a-9bcd-ef0123456789",
    "remote_file_import_batch": "https://api.carebit.co/v1/remote_file_import_batches/ebc38802-f219-4c7b-8136-8e963a0c69e0",
    "self": "https://api.carebit.co/v1/leads/c0b9e949-67e8-4a50-8038-6168ab7f1d70",
    "service": "https://api.carebit.co/v1/services/5e6f7081-92a3-4bcd-8ef0-123456789abc"
  },
  "mobile": "7700900123",
  "mobile_country_dial_code": "GB",
  "organization_privacy_policy_consent_granted_at": "2026-01-01T09:00:00Z",
  "patient_id": "1a2b3c4d-5e6f-4789-8abc-def012345678",
  "phone": "2071234567",
  "phone_country_dial_code": "GB",
  "postcode": "W1G 9PF",
  "presenting_problem": "Persistent right knee pain",
  "referral_notes": "Referred by Dr Patel at Riverside Medical.",
  "referral_source": "consultant",
  "remote_file_import_batch_id": "ebc38802-f219-4c7b-8136-8e963a0c69e0",
  "service": {
    "id": "5e6f7081-92a3-4bcd-8ef0-123456789abc",
    "object": "service",
    "created_at": "2026-01-01T09:00:00Z",
    "description": "An initial consultation at the Harley Street Clinic.",
    "duration_minutes": 30,
    "is_bookable_online": true,
    "name": "Initial consultation",
    "service_variants": [
      {
        "id": "6f708192-a3b4-4cde-9f01-23456789abcd",
        "clinician_id": "2b3c4d5e-6f70-489a-9bcd-ef0123456789",
        "currency": "GBP",
        "description": "An initial consultation at the Harley Street Clinic.",
        "links": {
          "clinician": "https://api.carebit.co/v1/clinicians/2b3c4d5e-6f70-489a-9bcd-ef0123456789",
          "location": "https://api.carebit.co/v1/locations/3c4d5e6f-7081-49ab-acde-f0123456789a"
        },
        "location_id": "3c4d5e6f-7081-49ab-acde-f0123456789a",
        "net_price": 1,
        "permits_remote_bookings": true
      }
    ],
    "tax_rate": {
      "id": "211b60c7-ec1b-41b4-8a29-e855209bc694",
      "description": "An initial consultation at the Harley Street Clinic.",
      "percentage": 20,
      "title": "VAT"
    },
    "updated_at": "2026-01-01T09:00:00Z"
  },
  "sex": "female",
  "stage": {
    "id": "306f78be-ffcc-472b-812e-a63d99e76e61",
    "object": "lead_stage",
    "created_at": "2026-01-01T09:00:00Z",
    "is_conversion_stage": true,
    "is_lost_stage": true,
    "name": "Initial consultation",
    "position": 1,
    "updated_at": "2026-01-01T09:00:00Z"
  },
  "title": "Dr",
  "updated_at": "2026-01-01T09:00:00Z"
}
```

## Response `400`

The `Idempotency-Key` header is missing (`idempotency_key_required`) or exceeds 255 characters (`idempotency_key_too_long`).

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `401`

The access token is missing, invalid, expired, or revoked.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `403`

The access token lacks the required scope, the project is disabled, or the Organization does not have Carebit Pro.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `404`

Error response.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `409`

A concurrent request holds the idempotency lease (`idempotency_conflict`). Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `422`

The `Idempotency-Key` was previously used with a different request body (`idempotency_key_reused`), or the request body failed validation.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `429`

Too many requests. Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Code samples

```bash
curl -X PATCH "https://api.carebit.co/v1/leads/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "presenting_problem": "Left knee pain (updated)",
  "stage_id": "00000000-0000-4000-8000-00000000000d"
}'
```

```javascript
const response = await fetch("https://api.carebit.co/v1/leads/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
  "presenting_problem": "Left knee pain (updated)",
  "stage_id": "00000000-0000-4000-8000-00000000000d"
}),
});

if (!response.ok) {
  throw new Error(`Carebit API error: ${response.status}`);
}

const data = await response.json();
```

```python
import os
import requests
import uuid

response = requests.patch(
    "https://api.carebit.co/v1/leads/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "presenting_problem": "Left knee pain (updated)",
        "stage_id": "00000000-0000-4000-8000-00000000000d"
    }
)
response.raise_for_status()
data = response.json()
```

```ruby
require "httparty"
require "json"
require "securerandom"

response = HTTParty.patch(
  "https://api.carebit.co/v1/leads/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}",
    "Idempotency-Key" => SecureRandom.uuid,
    "Content-Type" => "application/json"
  },
  body: {
    "presenting_problem" => "Left knee pain (updated)",
    "stage_id" => "00000000-0000-4000-8000-00000000000d"
  }.to_json
)
raise "Carebit API error: #{response.code}" unless response.success?
data = response.parsed_response
```

```php
<?php

$client = new GuzzleHttp\Client();

$response = $client->patch("https://api.carebit.co/v1/leads/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c", [
    "headers" => [
      "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
      "Idempotency-Key" => bin2hex(random_bytes(16)),
    ],
    "json" => [
      "presenting_problem" => "Left knee pain (updated)",
      "stage_id" => "00000000-0000-4000-8000-00000000000d"
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```


---

# Create up to 100 Letters in one request

`POST /v1/letter_batches`

Each item accepts a public HTTPS `file_url` or Base64-encoded `file_base64`. Carebit creates all Letters together. If any item fails validation, no Letters are created.

**Required API scopes:** `letters.create`

## Parameters

- `Idempotency-Key` (header, `string`) (required) - Client-generated idempotency key. Required for every POST/PATCH write. Replay of the same key with the same body returns the stored response with an `Idempotency-Replayed: true` header. Same key + different body returns `422 idempotency_key_reused`. A duplicate that arrives while the first request is still in flight returns `409 idempotency_conflict` with `Retry-After: 1`.

## Request body (`application/json`)

- `object`
  - `items` (`array`) - The letters to create. Items are processed in their submitted order.
    - `items` (`object`)
      - `automatically_create_resource_permission_for_patient` (`boolean`) - Whether Carebit should automatically share the letter with the patient after processing.
      - `booking_id` (`string | null`) - format: `uuid`; The identifier of the booking associated with the letter, or null when it is not linked to a booking.
      - `clinician_id` (`string | null`) - format: `uuid`; The identifier of the clinician associated with the letter, or null when none is assigned.
      - `description` (`string | null`) - A description of the Letter.
      - `file_base64` (`string`) - format: `byte`; The letter bytes encoded as Base64. Provide this with `filename` instead of `file_url`. The decoded file can be at most 7 MB.
      - `file_url` (`string`) - format: `uri`; The public HTTPS URL that Carebit can fetch.
      - `filename` (`string | null`) - The filename to use for the letter. Required with `file_base64`; defaults to the remote file's filename for URL sources.
      - `notify_patient_of_resource_permission` (`boolean`) - Whether Carebit should notify the patient when the letter is shared with them.
      - `patient_id` (`string`) - format: `uuid`; The identifier of the patient that the letter belongs to.
      - `status` (`string`) - enum: `awaiting_receipt`, `awaiting_review`, `awaiting_sending`, `complete`, `draft`, `reviewed`; The workflow status to assign to the letter.
      - `title` (`string`) - The display title of the letter.

### Example

```json
{
  "items": [
    {
      "automatically_create_resource_permission_for_patient": true,
      "file_url": "https://storage.example.invalid/letters/referral.pdf",
      "notify_patient_of_resource_permission": true,
      "patient_id": "00000000-0000-4000-8000-000000000004",
      "status": "complete",
      "title": "Referral letter"
    }
  ]
}
```

## Response `202`

The batch was accepted. Poll it for each file's import status.

- `object`
  - `completed_count` (`integer`) - The number of items that finished processing successfully.
  - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `failed_count` (`integer`) - The number of items that finished processing with an error.
  - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - `items` (`array`) - The import items in their original request order.
    - `items` (`object`)
      - `created_resource` (`string | null`) - format: `uri`; The URL of the resource created for a succeeded item. Null unless `status` is `succeeded`.
      - `created_resource_id` (`string | null`) - format: `uuid`; The identifier of the resource created for a succeeded item. Null unless `status` is `succeeded`.
      - `created_resource_type` (`string | null`) - enum: `null`, `Attachment`, `Letter`, `Note`, `TestResult`; The type of resource created for a succeeded item. Null unless `status` is `succeeded`.
      - `error` (`any`) - The failure details for this item. Null unless the item has failed.
      - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
      - `object` (`any`) - Always `remote_file_import_batch_item`.
      - `position` (`integer`) - The zero-based position of the item in the submitted batch.
      - `status` (`string`) - enum: `failed`, `pending`, `processing`, `succeeded`; The current download, validation, and malware-scanning status of the item.
  - `links` (`object`) - URLs to related resources.
    - `self` (`string`) - format: `uri`; The full URL of a related resource.
  - `object` (`any`) - Discriminator value emitted at `object`.
  - `resource_type` (`string`) - enum: `letter`, `note`, `test_result`; The type of resource created by every item in the batch.
  - `status` (`string`) - enum: `completed`, `pending`, `processing`; The current download, validation, and malware-scanning status of the batch.
  - `total_count` (`integer`) - The total number of items submitted in the batch.
  - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.

### Example

```json
{
  "id": "ebc38802-f219-4c7b-8136-8e963a0c69e0",
  "object": "remote_file_import_batch",
  "completed_count": 0,
  "created_at": "2026-01-01T09:00:00Z",
  "failed_count": 0,
  "items": [
    {
      "id": "57bed2bf-e2e1-463b-8a96-643e3817a8b8",
      "object": "remote_file_import_batch_item",
      "created_resource": "https://api.carebit.co/v1/letters/c3d4e5f6-0718-49ab-acde-f01234567890",
      "created_resource_id": "7e09a8e3-e3c1-4dee-863b-85d56e4329da",
      "created_resource_type": null,
      "error": null,
      "position": 0,
      "status": "failed"
    }
  ],
  "links": {
    "self": "https://api.carebit.co/v1/remote_file_import_batches/ebc38802-f219-4c7b-8136-8e963a0c69e0"
  },
  "resource_type": "letter",
  "status": "completed",
  "total_count": 1,
  "updated_at": "2026-01-01T09:00:00Z"
}
```

## Response `400`

The `Idempotency-Key` header is missing (`idempotency_key_required`) or exceeds 255 characters (`idempotency_key_too_long`).

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `401`

The access token is missing, invalid, expired, or revoked.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `403`

The access token lacks the required scope, or the project is disabled.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `404`

Error response.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `409`

A concurrent request holds the idempotency lease (`idempotency_conflict`). Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `422`

The `Idempotency-Key` was previously used with a different request body (`idempotency_key_reused`), or the request body failed validation.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `429`

Too many requests. Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Code samples

```bash
curl -X POST "https://api.carebit.co/v1/letter_batches" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "items": [
    {
      "automatically_create_resource_permission_for_patient": true,
      "file_url": "https://storage.example.invalid/letters/referral.pdf",
      "notify_patient_of_resource_permission": true,
      "patient_id": "00000000-0000-4000-8000-000000000004",
      "status": "complete",
      "title": "Referral letter"
    }
  ]
}'
```

```javascript
const response = await fetch("https://api.carebit.co/v1/letter_batches", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
  "items": [
    {
      "automatically_create_resource_permission_for_patient": true,
      "file_url": "https://storage.example.invalid/letters/referral.pdf",
      "notify_patient_of_resource_permission": true,
      "patient_id": "00000000-0000-4000-8000-000000000004",
      "status": "complete",
      "title": "Referral letter"
    }
  ]
}),
});

if (!response.ok) {
  throw new Error(`Carebit API error: ${response.status}`);
}

const data = await response.json();
```

```python
import os
import requests
import uuid

response = requests.post(
    "https://api.carebit.co/v1/letter_batches",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "items": [
            {
                "automatically_create_resource_permission_for_patient": True,
                "file_url": "https://storage.example.invalid/letters/referral.pdf",
                "notify_patient_of_resource_permission": True,
                "patient_id": "00000000-0000-4000-8000-000000000004",
                "status": "complete",
                "title": "Referral letter"
            }
        ]
    }
)
response.raise_for_status()
data = response.json()
```

```ruby
require "httparty"
require "json"
require "securerandom"

response = HTTParty.post(
  "https://api.carebit.co/v1/letter_batches",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}",
    "Idempotency-Key" => SecureRandom.uuid,
    "Content-Type" => "application/json"
  },
  body: {
    "items" => [
      {
        "automatically_create_resource_permission_for_patient" => true,
        "file_url" => "https://storage.example.invalid/letters/referral.pdf",
        "notify_patient_of_resource_permission" => true,
        "patient_id" => "00000000-0000-4000-8000-000000000004",
        "status" => "complete",
        "title" => "Referral letter"
      }
    ]
  }.to_json
)
raise "Carebit API error: #{response.code}" unless response.success?
data = response.parsed_response
```

```php
<?php

$client = new GuzzleHttp\Client();

$response = $client->post("https://api.carebit.co/v1/letter_batches", [
    "headers" => [
      "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
      "Idempotency-Key" => bin2hex(random_bytes(16)),
    ],
    "json" => [
      "items" => [
        [
          "automatically_create_resource_permission_for_patient" => true,
          "file_url" => "https://storage.example.invalid/letters/referral.pdf",
          "notify_patient_of_resource_permission" => true,
          "patient_id" => "00000000-0000-4000-8000-000000000004",
          "status" => "complete",
          "title" => "Referral letter"
        ]
      ]
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```


---

# List Letters

`GET /v1/letters`

**Required API scopes:** `letters.read`

## Parameters

- `patient_id` (query, `string`)
- `booking_id` (query, `string`)
- `status` (query, `string`)
- `created_since` (query, `string`)
- `limit` (query, `integer`) - The maximum number of items to return. Defaults to `25`; the maximum is `100`.
- `starting_after` (query, `string`) - Return items after this resource ID. You cannot use this with `cursor`.
- `cursor` (query, `string`) - The `next_cursor` value from the previous page. You cannot use this with `starting_after`.

## Response `200`

Paginated list of `Letter` objects.

- `any`

### Example

```json
{
  "object": "list",
  "data": [
    {
      "id": "c3d4e5f6-0718-49ab-acde-f01234567890",
      "object": "letter",
      "automatically_create_resource_permission_for_patient": true,
      "created_at": "2026-01-01T09:00:00Z",
      "download_url": "https://files.example.invalid/document.pdf?signature=test",
      "filename": "referral-letter.pdf",
      "links": {
        "booking": "https://api.carebit.co/v1/bookings/92a3b4c5-d6e7-4f01-8234-56789abcdef0",
        "clinician": "https://api.carebit.co/v1/clinicians/2b3c4d5e-6f70-489a-9bcd-ef0123456789",
        "patient": "https://api.carebit.co/v1/patients/1a2b3c4d-5e6f-4789-8abc-def012345678",
        "remote_file_import_batch": "https://api.carebit.co/v1/remote_file_import_batches/ebc38802-f219-4c7b-8136-8e963a0c69e0"
      },
      "notify_patient_of_resource_permission": true,
      "remote_file_import_batch_id": "ebc38802-f219-4c7b-8136-8e963a0c69e0",
      "sent_at": "2026-01-01T09:00:00Z",
      "status": "awaiting_proofreading",
      "title": "Dr",
      "updated_at": "2026-01-01T09:00:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": "eyJzdGFydF90aW1lIjoiMjAyNi0wMS0wMVQwOTowMDowMFoifQ",
  "url": "/v1/letters"
}
```

## Response `400`

A filter or pagination parameter is invalid.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `401`

The access token is missing, invalid, expired, or revoked.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `403`

The access token lacks the required scope, or the project is disabled.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `429`

Too many requests. Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Code samples

```bash
curl -X GET "https://api.carebit.co/v1/letters" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN"
```

```javascript
const response = await fetch("https://api.carebit.co/v1/letters", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
  },
});

if (!response.ok) {
  throw new Error(`Carebit API error: ${response.status}`);
}

const data = await response.json();
```

```python
import os
import requests

response = requests.get(
    "https://api.carebit.co/v1/letters",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
    }
)
response.raise_for_status()
data = response.json()
```

```ruby
require "httparty"

response = HTTParty.get(
  "https://api.carebit.co/v1/letters",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}"
  }
)
raise "Carebit API error: #{response.code}" unless response.success?
data = response.parsed_response
```

```php
<?php

$client = new GuzzleHttp\Client();

$response = $client->get("https://api.carebit.co/v1/letters", [
    "headers" => [
      "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```


---

# Create a Letter with a file

`POST /v1/letters`

Creates the Letter immediately, then imports its file in the background. Provide the file as a public HTTPS `file_url` or Base64-encoded `file_base64`. Poll `/v1/remote_file_import_batches/:remote_file_import_batch_id` for the import status.

**Required API scopes:** `letters.create`

## Parameters

- `Idempotency-Key` (header, `string`) (required) - Client-generated idempotency key. Required for every POST/PATCH write. Replay of the same key with the same body returns the stored response with an `Idempotency-Replayed: true` header. Same key + different body returns `422 idempotency_key_reused`. A duplicate that arrives while the first request is still in flight returns `409 idempotency_conflict` with `Retry-After: 1`.

## Request body (`application/json`)

- `object`
  - `automatically_create_resource_permission_for_patient` (`boolean`) - Whether Carebit should automatically share the letter with the patient after processing.
  - `booking_id` (`string | null`) - format: `uuid`; The identifier of the booking associated with the letter, or null when it is not linked to a booking.
  - `clinician_id` (`string | null`) - format: `uuid`; The identifier of the clinician associated with the letter, or null when none is assigned.
  - `description` (`string | null`) - A description of the Letter.
  - `file_base64` (`string`) - format: `byte`; The letter bytes encoded as Base64. Provide this with `filename` instead of `file_url`. The decoded file can be at most 7 MB.
  - `file_url` (`string`) - format: `uri`; The public HTTPS URL that Carebit can fetch.
  - `filename` (`string | null`) - The filename to use for the letter. Required with `file_base64`; defaults to the remote file's filename for URL sources.
  - `notify_patient_of_resource_permission` (`boolean`) - Whether Carebit should notify the patient when the letter is shared with them.
  - `patient_id` (`string`) - format: `uuid`; The identifier of the patient that the letter belongs to.
  - `status` (`string`) - enum: `awaiting_receipt`, `awaiting_review`, `awaiting_sending`, `complete`, `draft`, `reviewed`; The workflow status to assign to the letter.
  - `title` (`string`) - The display title of the letter.

### Example

```json
{
  "automatically_create_resource_permission_for_patient": true,
  "file_url": "https://storage.example.invalid/letters/referral.pdf",
  "filename": "referral.pdf",
  "notify_patient_of_resource_permission": true,
  "patient_id": "00000000-0000-4000-8000-000000000004",
  "status": "complete",
  "title": "Referral letter"
}
```

## Response `201`

The requested `Letter`.

- `object`
  - `automatically_create_resource_permission_for_patient` (`boolean`) - Whether Carebit automatically shares the letter with the patient after processing.
  - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `download_url` (`string | null`) - format: `uri`; The short-lived signed download URL for the Letter. Null until the uploaded file passes malware scanning.
  - `filename` (`string | null`) - The original filename of the letter document.
  - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - `links` (`object`) - URLs to related resources.
    - `booking` (`string | null`) - format: `uri`; The full URL of a related resource.
    - `clinician` (`string | null`) - format: `uri`; The full URL of a related resource.
    - `patient` (`string | null`) - format: `uri`; The full URL of a related resource.
    - `remote_file_import_batch` (`string`) - format: `uri`; The full URL of a related resource.
  - `notify_patient_of_resource_permission` (`boolean | null`) - Whether Carebit notifies the patient when the letter is shared with them.
  - `object` (`any`) - Discriminator value emitted at `object`.
  - `remote_file_import_batch_id` (`string`) - format: `uuid`; The identifier of the remote file import batch created for the uploaded file. Set on the create response. Poll `/v1/remote_file_import_batches/:id` for processing status.
  - `sent_at` (`string | null`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `status` (`string | null`) - enum: `awaiting_proofreading`, `awaiting_receipt`, `awaiting_review`, `awaiting_sending`, `awaiting_typing`, `complete`, `draft`, `reviewed`, `null`; The Letter's workflow status. Null while the Letter is being created.
  - `title` (`string | null`) - The display title of the letter.
  - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.

### Example

```json
{
  "id": "c3d4e5f6-0718-49ab-acde-f01234567890",
  "object": "letter",
  "automatically_create_resource_permission_for_patient": true,
  "created_at": "2026-01-01T09:00:00Z",
  "download_url": "https://files.example.invalid/document.pdf?signature=test",
  "filename": "referral-letter.pdf",
  "links": {
    "booking": "https://api.carebit.co/v1/bookings/92a3b4c5-d6e7-4f01-8234-56789abcdef0",
    "clinician": "https://api.carebit.co/v1/clinicians/2b3c4d5e-6f70-489a-9bcd-ef0123456789",
    "patient": "https://api.carebit.co/v1/patients/1a2b3c4d-5e6f-4789-8abc-def012345678",
    "remote_file_import_batch": "https://api.carebit.co/v1/remote_file_import_batches/ebc38802-f219-4c7b-8136-8e963a0c69e0"
  },
  "notify_patient_of_resource_permission": true,
  "remote_file_import_batch_id": "ebc38802-f219-4c7b-8136-8e963a0c69e0",
  "sent_at": "2026-01-01T09:00:00Z",
  "status": "awaiting_proofreading",
  "title": "Dr",
  "updated_at": "2026-01-01T09:00:00Z"
}
```

## Response `400`

The `Idempotency-Key` header is missing (`idempotency_key_required`) or exceeds 255 characters (`idempotency_key_too_long`).

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `401`

The access token is missing, invalid, expired, or revoked.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `403`

The access token lacks the required scope, or the project is disabled.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `404`

Error response.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `409`

A concurrent request holds the idempotency lease (`idempotency_conflict`). Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `422`

The `Idempotency-Key` was previously used with a different request body (`idempotency_key_reused`), or the request body failed validation.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `429`

Too many requests. Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Code samples

```bash
curl -X POST "https://api.carebit.co/v1/letters" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "automatically_create_resource_permission_for_patient": true,
  "file_url": "https://storage.example.invalid/letters/referral.pdf",
  "filename": "referral.pdf",
  "notify_patient_of_resource_permission": true,
  "patient_id": "00000000-0000-4000-8000-000000000004",
  "status": "complete",
  "title": "Referral letter"
}'
```

```javascript
const response = await fetch("https://api.carebit.co/v1/letters", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
  "automatically_create_resource_permission_for_patient": true,
  "file_url": "https://storage.example.invalid/letters/referral.pdf",
  "filename": "referral.pdf",
  "notify_patient_of_resource_permission": true,
  "patient_id": "00000000-0000-4000-8000-000000000004",
  "status": "complete",
  "title": "Referral letter"
}),
});

if (!response.ok) {
  throw new Error(`Carebit API error: ${response.status}`);
}

const data = await response.json();
```

```python
import os
import requests
import uuid

response = requests.post(
    "https://api.carebit.co/v1/letters",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "automatically_create_resource_permission_for_patient": True,
        "file_url": "https://storage.example.invalid/letters/referral.pdf",
        "filename": "referral.pdf",
        "notify_patient_of_resource_permission": True,
        "patient_id": "00000000-0000-4000-8000-000000000004",
        "status": "complete",
        "title": "Referral letter"
    }
)
response.raise_for_status()
data = response.json()
```

```ruby
require "httparty"
require "json"
require "securerandom"

response = HTTParty.post(
  "https://api.carebit.co/v1/letters",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}",
    "Idempotency-Key" => SecureRandom.uuid,
    "Content-Type" => "application/json"
  },
  body: {
    "automatically_create_resource_permission_for_patient" => true,
    "file_url" => "https://storage.example.invalid/letters/referral.pdf",
    "filename" => "referral.pdf",
    "notify_patient_of_resource_permission" => true,
    "patient_id" => "00000000-0000-4000-8000-000000000004",
    "status" => "complete",
    "title" => "Referral letter"
  }.to_json
)
raise "Carebit API error: #{response.code}" unless response.success?
data = response.parsed_response
```

```php
<?php

$client = new GuzzleHttp\Client();

$response = $client->post("https://api.carebit.co/v1/letters", [
    "headers" => [
      "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
      "Idempotency-Key" => bin2hex(random_bytes(16)),
    ],
    "json" => [
      "automatically_create_resource_permission_for_patient" => true,
      "file_url" => "https://storage.example.invalid/letters/referral.pdf",
      "filename" => "referral.pdf",
      "notify_patient_of_resource_permission" => true,
      "patient_id" => "00000000-0000-4000-8000-000000000004",
      "status" => "complete",
      "title" => "Referral letter"
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```


---

# Get a Letter

`GET /v1/letters/:id`

**Required API scopes:** `letters.read`

## Parameters

- `id` (path, `string`) (required)

## Response `200`

The requested `Letter`.

- `object`
  - `automatically_create_resource_permission_for_patient` (`boolean`) - Whether Carebit automatically shares the letter with the patient after processing.
  - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `download_url` (`string | null`) - format: `uri`; The short-lived signed download URL for the Letter. Null until the uploaded file passes malware scanning.
  - `filename` (`string | null`) - The original filename of the letter document.
  - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - `links` (`object`) - URLs to related resources.
    - `booking` (`string | null`) - format: `uri`; The full URL of a related resource.
    - `clinician` (`string | null`) - format: `uri`; The full URL of a related resource.
    - `patient` (`string | null`) - format: `uri`; The full URL of a related resource.
    - `remote_file_import_batch` (`string`) - format: `uri`; The full URL of a related resource.
  - `notify_patient_of_resource_permission` (`boolean | null`) - Whether Carebit notifies the patient when the letter is shared with them.
  - `object` (`any`) - Discriminator value emitted at `object`.
  - `remote_file_import_batch_id` (`string`) - format: `uuid`; The identifier of the remote file import batch created for the uploaded file. Set on the create response. Poll `/v1/remote_file_import_batches/:id` for processing status.
  - `sent_at` (`string | null`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `status` (`string | null`) - enum: `awaiting_proofreading`, `awaiting_receipt`, `awaiting_review`, `awaiting_sending`, `awaiting_typing`, `complete`, `draft`, `reviewed`, `null`; The Letter's workflow status. Null while the Letter is being created.
  - `title` (`string | null`) - The display title of the letter.
  - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.

### Example

```json
{
  "id": "c3d4e5f6-0718-49ab-acde-f01234567890",
  "object": "letter",
  "automatically_create_resource_permission_for_patient": true,
  "created_at": "2026-01-01T09:00:00Z",
  "download_url": "https://files.example.invalid/document.pdf?signature=test",
  "filename": "referral-letter.pdf",
  "links": {
    "booking": "https://api.carebit.co/v1/bookings/92a3b4c5-d6e7-4f01-8234-56789abcdef0",
    "clinician": "https://api.carebit.co/v1/clinicians/2b3c4d5e-6f70-489a-9bcd-ef0123456789",
    "patient": "https://api.carebit.co/v1/patients/1a2b3c4d-5e6f-4789-8abc-def012345678",
    "remote_file_import_batch": "https://api.carebit.co/v1/remote_file_import_batches/ebc38802-f219-4c7b-8136-8e963a0c69e0"
  },
  "notify_patient_of_resource_permission": true,
  "remote_file_import_batch_id": "ebc38802-f219-4c7b-8136-8e963a0c69e0",
  "sent_at": "2026-01-01T09:00:00Z",
  "status": "awaiting_proofreading",
  "title": "Dr",
  "updated_at": "2026-01-01T09:00:00Z"
}
```

## Response `401`

The access token is missing, invalid, expired, or revoked.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `403`

The access token lacks the required scope, or the project is disabled.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `404`

Error response.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `429`

Too many requests. Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Code samples

```bash
curl -X GET "https://api.carebit.co/v1/letters/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN"
```

```javascript
const response = await fetch("https://api.carebit.co/v1/letters/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
  },
});

if (!response.ok) {
  throw new Error(`Carebit API error: ${response.status}`);
}

const data = await response.json();
```

```python
import os
import requests

response = requests.get(
    "https://api.carebit.co/v1/letters/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
    }
)
response.raise_for_status()
data = response.json()
```

```ruby
require "httparty"

response = HTTParty.get(
  "https://api.carebit.co/v1/letters/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}"
  }
)
raise "Carebit API error: #{response.code}" unless response.success?
data = response.parsed_response
```

```php
<?php

$client = new GuzzleHttp\Client();

$response = $client->get("https://api.carebit.co/v1/letters/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c", [
    "headers" => [
      "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```


---

# List Lists

`GET /v1/lists`

Returns Lists in the Organization, ordered by name.

**Required API scopes:** `lists.read`

## Parameters

- `name` (query, `string`) - Filter by an exact List name, case-insensitively.
- `limit` (query, `integer`) - The maximum number of items to return. Defaults to `25`; the maximum is `100`.
- `starting_after` (query, `string`) - Return items after this resource ID. You cannot use this with `cursor`.
- `cursor` (query, `string`) - The `next_cursor` value from the previous page. You cannot use this with `starting_after`.

## Response `200`

Paginated list of `List` objects.

- `any`

### Example

```json
{
  "object": "list",
  "data": [
    {
      "id": "a1b2c3d4-e5f6-4789-8abc-def012345678",
      "object": "list",
      "clinician_id": "2b3c4d5e-6f70-489a-9bcd-ef0123456789",
      "color_hex": "#28a745",
      "created_at": "2026-01-01T09:00:00Z",
      "links": {
        "clinician": "https://api.carebit.co/v1/clinicians/2b3c4d5e-6f70-489a-9bcd-ef0123456789",
        "members": "https://api.carebit.co/v1/lists/a1b2c3d4-e5f6-4789-8abc-def012345678/members",
        "self": "https://api.carebit.co/v1/lists/a1b2c3d4-e5f6-4789-8abc-def012345678"
      },
      "name": "Cataract waiting list",
      "notes": "Please confirm the appointment by email.",
      "updated_at": "2026-01-01T09:00:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": "eyJzdGFydF90aW1lIjoiMjAyNi0wMS0wMVQwOTowMDowMFoifQ",
  "url": "/v1/lists"
}
```

## Response `400`

A pagination parameter is invalid.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `401`

The access token is missing, invalid, expired, or revoked.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `403`

The access token lacks the required scope, or the project is disabled.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `429`

Too many requests. Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Code samples

```bash
curl -X GET "https://api.carebit.co/v1/lists?name=Cataract%20waiting%20list" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN"
```

```javascript
const response = await fetch("https://api.carebit.co/v1/lists?name=Cataract%20waiting%20list", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
  },
});

if (!response.ok) {
  throw new Error(`Carebit API error: ${response.status}`);
}

const data = await response.json();
```

```python
import os
import requests

response = requests.get(
    "https://api.carebit.co/v1/lists?name=Cataract%20waiting%20list",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
    }
)
response.raise_for_status()
data = response.json()
```

```ruby
require "httparty"

response = HTTParty.get(
  "https://api.carebit.co/v1/lists?name=Cataract%20waiting%20list",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}"
  }
)
raise "Carebit API error: #{response.code}" unless response.success?
data = response.parsed_response
```

```php
<?php

$client = new GuzzleHttp\Client();

$response = $client->get("https://api.carebit.co/v1/lists?name=Cataract%20waiting%20list", [
    "headers" => [
      "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```


---

# Create a List

`POST /v1/lists`

**Required API scopes:** `lists.create`

## Parameters

- `Idempotency-Key` (header, `string`) (required) - Client-generated idempotency key. Required for every POST/PATCH write. Replay of the same key with the same body returns the stored response with an `Idempotency-Replayed: true` header. Same key + different body returns `422 idempotency_key_reused`. A duplicate that arrives while the first request is still in flight returns `409 idempotency_conflict` with `Retry-After: 1`.

## Request body (`application/json`)

- `object`
  - `clinician_id` (`string | null`) - format: `uuid`; The Clinician associated with this List. Null clears the Clinician.
  - `color_hex` (`string | null`) - The display color of the List as a hex string, for example `#28a745`.
  - `name` (`string`) - The display name of the List.
  - `notes` (`string | null`) - Internal notes about the List.

### Example

```json
{
  "clinician_id": "00000000-0000-4000-8000-000000000002",
  "color_hex": "#28a745",
  "name": "Cataract waiting list",
  "notes": "Patients waiting for a cataract assessment."
}
```

## Response `201`

The requested `List`.

- `object`
  - `clinician_id` (`string | null`) - format: `uuid`; The Clinician associated with this List, when one is set.
  - `color_hex` (`string | null`) - The display color of the List as a hex string, for example `#28a745`.
  - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - `links` (`object`) - URLs to related resources.
    - `clinician` (`string | null`) - format: `uri`; The full URL of a related resource.
    - `members` (`string`) - format: `uri`; The full URL of a related resource.
    - `self` (`string`) - format: `uri`; The full URL of a related resource.
  - `name` (`string`) - The display name of the List.
  - `notes` (`string | null`) - Internal notes about the List.
  - `object` (`any`) - Discriminator value emitted at `object`.
  - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.

### Example

```json
{
  "id": "a1b2c3d4-e5f6-4789-8abc-def012345678",
  "object": "list",
  "clinician_id": "2b3c4d5e-6f70-489a-9bcd-ef0123456789",
  "color_hex": "#28a745",
  "created_at": "2026-01-01T09:00:00Z",
  "links": {
    "clinician": "https://api.carebit.co/v1/clinicians/2b3c4d5e-6f70-489a-9bcd-ef0123456789",
    "members": "https://api.carebit.co/v1/lists/a1b2c3d4-e5f6-4789-8abc-def012345678/members",
    "self": "https://api.carebit.co/v1/lists/a1b2c3d4-e5f6-4789-8abc-def012345678"
  },
  "name": "Cataract waiting list",
  "notes": "Please confirm the appointment by email.",
  "updated_at": "2026-01-01T09:00:00Z"
}
```

## Response `400`

The `Idempotency-Key` header is missing (`idempotency_key_required`) or exceeds 255 characters (`idempotency_key_too_long`).

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `401`

The access token is missing, invalid, expired, or revoked.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `403`

The access token lacks the required scope, or the project is disabled.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `404`

The supplied Clinician was not found in the Organization.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `409`

A concurrent request holds the idempotency lease (`idempotency_conflict`). Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `422`

The `Idempotency-Key` was previously used with a different request body (`idempotency_key_reused`), or the request body failed validation.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `429`

Too many requests. Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Code samples

```bash
curl -X POST "https://api.carebit.co/v1/lists" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "clinician_id": "00000000-0000-4000-8000-000000000002",
  "color_hex": "#28a745",
  "name": "Cataract waiting list",
  "notes": "Patients waiting for a cataract assessment."
}'
```

```javascript
const response = await fetch("https://api.carebit.co/v1/lists", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
  "clinician_id": "00000000-0000-4000-8000-000000000002",
  "color_hex": "#28a745",
  "name": "Cataract waiting list",
  "notes": "Patients waiting for a cataract assessment."
}),
});

if (!response.ok) {
  throw new Error(`Carebit API error: ${response.status}`);
}

const data = await response.json();
```

```python
import os
import requests
import uuid

response = requests.post(
    "https://api.carebit.co/v1/lists",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "clinician_id": "00000000-0000-4000-8000-000000000002",
        "color_hex": "#28a745",
        "name": "Cataract waiting list",
        "notes": "Patients waiting for a cataract assessment."
    }
)
response.raise_for_status()
data = response.json()
```

```ruby
require "httparty"
require "json"
require "securerandom"

response = HTTParty.post(
  "https://api.carebit.co/v1/lists",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}",
    "Idempotency-Key" => SecureRandom.uuid,
    "Content-Type" => "application/json"
  },
  body: {
    "clinician_id" => "00000000-0000-4000-8000-000000000002",
    "color_hex" => "#28a745",
    "name" => "Cataract waiting list",
    "notes" => "Patients waiting for a cataract assessment."
  }.to_json
)
raise "Carebit API error: #{response.code}" unless response.success?
data = response.parsed_response
```

```php
<?php

$client = new GuzzleHttp\Client();

$response = $client->post("https://api.carebit.co/v1/lists", [
    "headers" => [
      "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
      "Idempotency-Key" => bin2hex(random_bytes(16)),
    ],
    "json" => [
      "clinician_id" => "00000000-0000-4000-8000-000000000002",
      "color_hex" => "#28a745",
      "name" => "Cataract waiting list",
      "notes" => "Patients waiting for a cataract assessment."
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```


---

# Get a List

`GET /v1/lists/:id`

**Required API scopes:** `lists.read`

## Parameters

- `id` (path, `string`) (required)

## Response `200`

The requested `List`.

- `object`
  - `clinician_id` (`string | null`) - format: `uuid`; The Clinician associated with this List, when one is set.
  - `color_hex` (`string | null`) - The display color of the List as a hex string, for example `#28a745`.
  - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - `links` (`object`) - URLs to related resources.
    - `clinician` (`string | null`) - format: `uri`; The full URL of a related resource.
    - `members` (`string`) - format: `uri`; The full URL of a related resource.
    - `self` (`string`) - format: `uri`; The full URL of a related resource.
  - `name` (`string`) - The display name of the List.
  - `notes` (`string | null`) - Internal notes about the List.
  - `object` (`any`) - Discriminator value emitted at `object`.
  - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.

### Example

```json
{
  "id": "a1b2c3d4-e5f6-4789-8abc-def012345678",
  "object": "list",
  "clinician_id": "2b3c4d5e-6f70-489a-9bcd-ef0123456789",
  "color_hex": "#28a745",
  "created_at": "2026-01-01T09:00:00Z",
  "links": {
    "clinician": "https://api.carebit.co/v1/clinicians/2b3c4d5e-6f70-489a-9bcd-ef0123456789",
    "members": "https://api.carebit.co/v1/lists/a1b2c3d4-e5f6-4789-8abc-def012345678/members",
    "self": "https://api.carebit.co/v1/lists/a1b2c3d4-e5f6-4789-8abc-def012345678"
  },
  "name": "Cataract waiting list",
  "notes": "Please confirm the appointment by email.",
  "updated_at": "2026-01-01T09:00:00Z"
}
```

## Response `401`

The access token is missing, invalid, expired, or revoked.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `403`

The access token lacks the required scope, or the project is disabled.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `404`

Error response.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `429`

Too many requests. Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Code samples

```bash
curl -X GET "https://api.carebit.co/v1/lists/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN"
```

```javascript
const response = await fetch("https://api.carebit.co/v1/lists/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
  },
});

if (!response.ok) {
  throw new Error(`Carebit API error: ${response.status}`);
}

const data = await response.json();
```

```python
import os
import requests

response = requests.get(
    "https://api.carebit.co/v1/lists/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
    }
)
response.raise_for_status()
data = response.json()
```

```ruby
require "httparty"

response = HTTParty.get(
  "https://api.carebit.co/v1/lists/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}"
  }
)
raise "Carebit API error: #{response.code}" unless response.success?
data = response.parsed_response
```

```php
<?php

$client = new GuzzleHttp\Client();

$response = $client->get("https://api.carebit.co/v1/lists/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c", [
    "headers" => [
      "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```


---

# Update a List

`PATCH /v1/lists/:id`

**Required API scopes:** `lists.update`

## Parameters

- `id` (path, `string`) (required)
- `Idempotency-Key` (header, `string`) (required) - Client-generated idempotency key. Required for every POST/PATCH write. Replay of the same key with the same body returns the stored response with an `Idempotency-Replayed: true` header. Same key + different body returns `422 idempotency_key_reused`. A duplicate that arrives while the first request is still in flight returns `409 idempotency_conflict` with `Retry-After: 1`.

## Request body (`application/json`)

- `object`
  - `clinician_id` (`string | null`) - format: `uuid`; The Clinician associated with this List. Null clears the Clinician.
  - `color_hex` (`string | null`) - The display color of the List as a hex string, for example `#28a745`.
  - `name` (`string`) - The display name of the List.
  - `notes` (`string | null`) - Internal notes about the List.

### Example

```json
{
  "name": "Updated cataract waiting list"
}
```

## Response `200`

The requested `List`.

- `object`
  - `clinician_id` (`string | null`) - format: `uuid`; The Clinician associated with this List, when one is set.
  - `color_hex` (`string | null`) - The display color of the List as a hex string, for example `#28a745`.
  - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - `links` (`object`) - URLs to related resources.
    - `clinician` (`string | null`) - format: `uri`; The full URL of a related resource.
    - `members` (`string`) - format: `uri`; The full URL of a related resource.
    - `self` (`string`) - format: `uri`; The full URL of a related resource.
  - `name` (`string`) - The display name of the List.
  - `notes` (`string | null`) - Internal notes about the List.
  - `object` (`any`) - Discriminator value emitted at `object`.
  - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.

### Example

```json
{
  "id": "a1b2c3d4-e5f6-4789-8abc-def012345678",
  "object": "list",
  "clinician_id": "2b3c4d5e-6f70-489a-9bcd-ef0123456789",
  "color_hex": "#28a745",
  "created_at": "2026-01-01T09:00:00Z",
  "links": {
    "clinician": "https://api.carebit.co/v1/clinicians/2b3c4d5e-6f70-489a-9bcd-ef0123456789",
    "members": "https://api.carebit.co/v1/lists/a1b2c3d4-e5f6-4789-8abc-def012345678/members",
    "self": "https://api.carebit.co/v1/lists/a1b2c3d4-e5f6-4789-8abc-def012345678"
  },
  "name": "Cataract waiting list",
  "notes": "Please confirm the appointment by email.",
  "updated_at": "2026-01-01T09:00:00Z"
}
```

## Response `400`

The `Idempotency-Key` header is missing (`idempotency_key_required`) or exceeds 255 characters (`idempotency_key_too_long`).

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `401`

The access token is missing, invalid, expired, or revoked.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `403`

The access token lacks the required scope, or the project is disabled.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `404`

Error response.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `409`

A concurrent request holds the idempotency lease (`idempotency_conflict`). Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `422`

The `Idempotency-Key` was previously used with a different request body (`idempotency_key_reused`), or the request body failed validation.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `429`

Too many requests. Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Code samples

```bash
curl -X PATCH "https://api.carebit.co/v1/lists/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Updated cataract waiting list"
}'
```

```javascript
const response = await fetch("https://api.carebit.co/v1/lists/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
  "name": "Updated cataract waiting list"
}),
});

if (!response.ok) {
  throw new Error(`Carebit API error: ${response.status}`);
}

const data = await response.json();
```

```python
import os
import requests
import uuid

response = requests.patch(
    "https://api.carebit.co/v1/lists/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "name": "Updated cataract waiting list"
    }
)
response.raise_for_status()
data = response.json()
```

```ruby
require "httparty"
require "json"
require "securerandom"

response = HTTParty.patch(
  "https://api.carebit.co/v1/lists/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}",
    "Idempotency-Key" => SecureRandom.uuid,
    "Content-Type" => "application/json"
  },
  body: {
    "name" => "Updated cataract waiting list"
  }.to_json
)
raise "Carebit API error: #{response.code}" unless response.success?
data = response.parsed_response
```

```php
<?php

$client = new GuzzleHttp\Client();

$response = $client->patch("https://api.carebit.co/v1/lists/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c", [
    "headers" => [
      "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
      "Idempotency-Key" => bin2hex(random_bytes(16)),
    ],
    "json" => [
      "name" => "Updated cataract waiting list"
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```


---

# Delete a List

`DELETE /v1/lists/:id`

Deletes a List and its members.

**Required API scopes:** `lists.delete`

## Parameters

- `id` (path, `string`) (required)

## Response `204`

No content.

## Response `401`

The access token is missing, invalid, expired, or revoked.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `403`

The access token lacks the required scope, or the project is disabled.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `404`

Error response.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `429`

Too many requests. Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Code samples

```bash
curl -X DELETE "https://api.carebit.co/v1/lists/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN"
```

```javascript
const response = await fetch("https://api.carebit.co/v1/lists/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c", {
  method: "DELETE",
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
  },
});

if (!response.ok) {
  throw new Error(`Carebit API error: ${response.status}`);
}

const data = await response.json();
```

```python
import os
import requests

response = requests.delete(
    "https://api.carebit.co/v1/lists/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
    }
)
response.raise_for_status()
data = response.json()
```

```ruby
require "httparty"

response = HTTParty.delete(
  "https://api.carebit.co/v1/lists/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}"
  }
)
raise "Carebit API error: #{response.code}" unless response.success?
data = response.parsed_response
```

```php
<?php

$client = new GuzzleHttp\Client();

$response = $client->delete("https://api.carebit.co/v1/lists/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c", [
    "headers" => [
      "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```


---

# List members of a List

`GET /v1/lists/:list_id/members`

**Required API scopes:** `lists.read`

## Parameters

- `list_id` (path, `string`) (required)
- `limit` (query, `integer`) - The maximum number of items to return. Defaults to `25`; the maximum is `100`.
- `starting_after` (query, `string`) - Return items after this resource ID. You cannot use this with `cursor`.
- `cursor` (query, `string`) - The `next_cursor` value from the previous page. You cannot use this with `starting_after`.

## Response `200`

Paginated list of `ListMember` objects.

- `any`

### Example

```json
{
  "object": "list",
  "data": [
    {
      "id": "b2c3d4e5-f607-489a-9bcd-ef0123456789",
      "object": "list_member",
      "created_at": "2026-01-01T09:00:00Z",
      "links": {
        "list": "https://api.carebit.co/v1/lists/a1b2c3d4-e5f6-4789-8abc-def012345678",
        "patient": "https://api.carebit.co/v1/patients/1a2b3c4d-5e6f-4789-8abc-def012345678",
        "self": "https://api.carebit.co/v1/lists/a1b2c3d4-e5f6-4789-8abc-def012345678/members/b2c3d4e5-f607-489a-9bcd-ef0123456789"
      },
      "list": {
        "id": "a1b2c3d4-e5f6-4789-8abc-def012345678",
        "object": "list",
        "clinician_id": "2b3c4d5e-6f70-489a-9bcd-ef0123456789",
        "color_hex": "#28a745",
        "created_at": "2026-01-01T09:00:00Z",
        "links": {
          "clinician": "https://api.carebit.co/v1/clinicians/2b3c4d5e-6f70-489a-9bcd-ef0123456789",
          "members": "https://api.carebit.co/v1/lists/a1b2c3d4-e5f6-4789-8abc-def012345678/members",
          "self": "https://api.carebit.co/v1/lists/a1b2c3d4-e5f6-4789-8abc-def012345678"
        },
        "name": "Cataract waiting list",
        "notes": "Please confirm the appointment by email.",
        "updated_at": "2026-01-01T09:00:00Z"
      },
      "member": {
        "patient": {
          "id": "1a2b3c4d-5e6f-4789-8abc-def012345678",
          "object": "patient",
          "address_line_1": "10 Harley Street",
          "address_line_2": "Marylebone",
          "city": "London",
          "country_code": "GB",
          "county": "Greater London",
          "created_at": "2026-01-01T09:00:00Z",
          "creation_source": "api",
          "date_of_birth": "1990-01-01",
          "display_name": "Dr Alex Morgan",
          "email": "alex.morgan@example.com",
          "first_name": "Alex",
          "is_opted_out_of_sms": false,
          "last_name": "Morgan",
          "mobile": "7700900123",
          "mobile_country_dial_code": "GB",
          "nhs_number": "485 777 3456",
          "phone": "2071234567",
          "phone_country_dial_code": "GB",
          "phone_number": "+44 7700 900123",
          "postcode": "W1G 9PF",
          "sex": "female",
          "title": "Dr",
          "updated_at": "2026-01-01T09:00:00Z"
        },
        "type": "patient"
      },
      "updated_at": "2026-01-01T09:00:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": "eyJzdGFydF90aW1lIjoiMjAyNi0wMS0wMVQwOTowMDowMFoifQ",
  "url": "/v1/lists/a1b2c3d4-e5f6-4789-8abc-def012345678/members"
}
```

## Response `401`

The access token is missing, invalid, expired, or revoked.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `403`

The access token lacks the required scope, or the project is disabled.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `404`

Error response.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `429`

Too many requests. Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Code samples

```bash
curl -X GET "https://api.carebit.co/v1/lists/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c/members" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN"
```

```javascript
const response = await fetch("https://api.carebit.co/v1/lists/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c/members", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
  },
});

if (!response.ok) {
  throw new Error(`Carebit API error: ${response.status}`);
}

const data = await response.json();
```

```python
import os
import requests

response = requests.get(
    "https://api.carebit.co/v1/lists/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c/members",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
    }
)
response.raise_for_status()
data = response.json()
```

```ruby
require "httparty"

response = HTTParty.get(
  "https://api.carebit.co/v1/lists/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c/members",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}"
  }
)
raise "Carebit API error: #{response.code}" unless response.success?
data = response.parsed_response
```

```php
<?php

$client = new GuzzleHttp\Client();

$response = $client->get("https://api.carebit.co/v1/lists/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c/members", [
    "headers" => [
      "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```


---

# Add a member to a List

`POST /v1/lists/:list_id/members`

Adds a member to a List. Currently `member_type` accepts only `patient`, and `member_id` must be a connected Patient. Duplicate membership returns `422`. Adding a member emits `list.member_added`.

**Required API scopes:** `lists.update`

## Parameters

- `list_id` (path, `string`) (required)
- `Idempotency-Key` (header, `string`) (required) - Client-generated idempotency key. Required for every POST/PATCH write. Replay of the same key with the same body returns the stored response with an `Idempotency-Replayed: true` header. Same key + different body returns `422 idempotency_key_reused`. A duplicate that arrives while the first request is still in flight returns `409 idempotency_conflict` with `Retry-After: 1`.

## Request body (`application/json`)

- `object`
  - `member_id` (`string`) - format: `uuid`; The identifier of the member to add. When `member_type` is `patient`, this is a connected Patient.
  - `member_type` (`string`) - enum: `patient`; The kind of member to add. Additional values may be added later.

### Example

```json
{
  "member_id": "00000000-0000-4000-8000-000000000004",
  "member_type": "patient"
}
```

## Response `201`

The requested `ListMember`.

- `object`
  - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - `links` (`object`) - URLs to related resources.
    - `list` (`string`) - format: `uri`; The full URL of a related resource.
    - `patient` (`string | null`) - format: `uri`; The full URL of a related resource.
    - `self` (`string`) - format: `uri`; The full URL of a related resource.
  - `list` (`any`) - The list that contains this member.
  - `member` (`object | null`) - The ListMember and its resource. Null when the resource has been removed.
    - `patient` (`object`)
      - `address_line_1` (`string | null`) - The primary address line of the Patient.
      - `address_line_2` (`string | null`) - The secondary address line of the Patient.
      - `city` (`string | null`) - The city in the Patient's postal address.
      - `country_code` (`string | null`) - The ISO 3166-1 alpha-2 country code for the postal address, such as `GB` for the United Kingdom.
      - `county` (`string | null`) - The county or region in the Patient's postal address.
      - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
      - `creation_source` (`string | null`) - How the Patient was created. `api` means the record was created through the Developer Platform. Read-only.
      - `date_of_birth` (`string | null`) - format: `date`; The date of birth of the patient, in ISO 8601 format (YYYY-MM-DD).
      - `display_name` (`string | null`) - The formatted display name of the patient, including their title when recorded.
      - `email` (`string | null`) - format: `email`; The email address of the patient, when recorded.
      - `first_name` (`string | null`) - The first name of the patient.
      - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
      - `is_opted_out_of_sms` (`boolean`) - Whether the Patient has opted out of SMS messages.
      - `last_name` (`string | null`) - The last name of the patient.
      - `mobile` (`string | null`) - The national mobile number without its country calling code.
      - `mobile_country_dial_code` (`string | null`) - The ISO 3166-1 alpha-2 country code used to derive the mobile calling code.
      - `nhs_number` (`string | null`) - The 10-digit NHS number of the patient, without formatting.
      - `object` (`any`) - Discriminator value emitted at `object`.
      - `phone` (`string | null`) - The national phone number without its country calling code.
      - `phone_country_dial_code` (`string | null`) - The ISO 3166-1 alpha-2 country code used to derive the phone calling code.
      - `phone_number` (`string | null`) - The Patient's preferred contact number, formatted for display and compatible with E.164.
      - `postcode` (`string | null`) - The postal code of the Patient.
      - `sex` (`string | null`) - enum: `female`, `male`, `other`, `null`; The Patient's recorded sex.
      - `title` (`string | null`) - The personal title of the patient, when recorded.
      - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
    - `type` (`string`) - enum: `patient`; The kind of member. Additional values may be added later.
  - `object` (`any`) - Discriminator value emitted at `object`.
  - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.

### Example

```json
{
  "id": "b2c3d4e5-f607-489a-9bcd-ef0123456789",
  "object": "list_member",
  "created_at": "2026-01-01T09:00:00Z",
  "links": {
    "list": "https://api.carebit.co/v1/lists/a1b2c3d4-e5f6-4789-8abc-def012345678",
    "patient": "https://api.carebit.co/v1/patients/1a2b3c4d-5e6f-4789-8abc-def012345678",
    "self": "https://api.carebit.co/v1/lists/a1b2c3d4-e5f6-4789-8abc-def012345678/members/b2c3d4e5-f607-489a-9bcd-ef0123456789"
  },
  "list": {
    "id": "a1b2c3d4-e5f6-4789-8abc-def012345678",
    "object": "list",
    "clinician_id": "2b3c4d5e-6f70-489a-9bcd-ef0123456789",
    "color_hex": "#28a745",
    "created_at": "2026-01-01T09:00:00Z",
    "links": {
      "clinician": "https://api.carebit.co/v1/clinicians/2b3c4d5e-6f70-489a-9bcd-ef0123456789",
      "members": "https://api.carebit.co/v1/lists/a1b2c3d4-e5f6-4789-8abc-def012345678/members",
      "self": "https://api.carebit.co/v1/lists/a1b2c3d4-e5f6-4789-8abc-def012345678"
    },
    "name": "Cataract waiting list",
    "notes": "Please confirm the appointment by email.",
    "updated_at": "2026-01-01T09:00:00Z"
  },
  "member": {
    "patient": {
      "id": "1a2b3c4d-5e6f-4789-8abc-def012345678",
      "object": "patient",
      "address_line_1": "10 Harley Street",
      "address_line_2": "Marylebone",
      "city": "London",
      "country_code": "GB",
      "county": "Greater London",
      "created_at": "2026-01-01T09:00:00Z",
      "creation_source": "api",
      "date_of_birth": "1990-01-01",
      "display_name": "Dr Alex Morgan",
      "email": "alex.morgan@example.com",
      "first_name": "Alex",
      "is_opted_out_of_sms": false,
      "last_name": "Morgan",
      "mobile": "7700900123",
      "mobile_country_dial_code": "GB",
      "nhs_number": "485 777 3456",
      "phone": "2071234567",
      "phone_country_dial_code": "GB",
      "phone_number": "+44 7700 900123",
      "postcode": "W1G 9PF",
      "sex": "female",
      "title": "Dr",
      "updated_at": "2026-01-01T09:00:00Z"
    },
    "type": "patient"
  },
  "updated_at": "2026-01-01T09:00:00Z"
}
```

## Response `400`

The `Idempotency-Key` header is missing (`idempotency_key_required`) or exceeds 255 characters (`idempotency_key_too_long`).

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `401`

The access token is missing, invalid, expired, or revoked.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `403`

The access token lacks the required scope, or the project is disabled.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `404`

The List or member was not found in the Organization.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `409`

A concurrent request holds the idempotency lease (`idempotency_conflict`). Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `422`

The `Idempotency-Key` was previously used with a different request body (`idempotency_key_reused`), or the request body failed validation.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `429`

Too many requests. Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Code samples

```bash
curl -X POST "https://api.carebit.co/v1/lists/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c/members" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "member_id": "00000000-0000-4000-8000-000000000004",
  "member_type": "patient"
}'
```

```javascript
const response = await fetch("https://api.carebit.co/v1/lists/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c/members", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
  "member_id": "00000000-0000-4000-8000-000000000004",
  "member_type": "patient"
}),
});

if (!response.ok) {
  throw new Error(`Carebit API error: ${response.status}`);
}

const data = await response.json();
```

```python
import os
import requests
import uuid

response = requests.post(
    "https://api.carebit.co/v1/lists/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c/members",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "member_id": "00000000-0000-4000-8000-000000000004",
        "member_type": "patient"
    }
)
response.raise_for_status()
data = response.json()
```

```ruby
require "httparty"
require "json"
require "securerandom"

response = HTTParty.post(
  "https://api.carebit.co/v1/lists/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c/members",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}",
    "Idempotency-Key" => SecureRandom.uuid,
    "Content-Type" => "application/json"
  },
  body: {
    "member_id" => "00000000-0000-4000-8000-000000000004",
    "member_type" => "patient"
  }.to_json
)
raise "Carebit API error: #{response.code}" unless response.success?
data = response.parsed_response
```

```php
<?php

$client = new GuzzleHttp\Client();

$response = $client->post("https://api.carebit.co/v1/lists/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c/members", [
    "headers" => [
      "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
      "Idempotency-Key" => bin2hex(random_bytes(16)),
    ],
    "json" => [
      "member_id" => "00000000-0000-4000-8000-000000000004",
      "member_type" => "patient"
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```


---

# Remove a member from a List

`DELETE /v1/lists/:list_id/members/:id`

Removes a member from a List. Removing a member emits `list.member_removed`.

**Required API scopes:** `lists.update`

## Parameters

- `list_id` (path, `string`) (required)
- `id` (path, `string`) (required)

## Response `204`

No content.

## Response `401`

The access token is missing, invalid, expired, or revoked.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `403`

The access token lacks the required scope, or the project is disabled.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `404`

Error response.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `429`

Too many requests. Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Code samples

```bash
curl -X DELETE "https://api.carebit.co/v1/lists/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c/members/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN"
```

```javascript
const response = await fetch("https://api.carebit.co/v1/lists/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c/members/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c", {
  method: "DELETE",
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
  },
});

if (!response.ok) {
  throw new Error(`Carebit API error: ${response.status}`);
}

const data = await response.json();
```

```python
import os
import requests

response = requests.delete(
    "https://api.carebit.co/v1/lists/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c/members/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
    }
)
response.raise_for_status()
data = response.json()
```

```ruby
require "httparty"

response = HTTParty.delete(
  "https://api.carebit.co/v1/lists/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c/members/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}"
  }
)
raise "Carebit API error: #{response.code}" unless response.success?
data = response.parsed_response
```

```php
<?php

$client = new GuzzleHttp\Client();

$response = $client->delete("https://api.carebit.co/v1/lists/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c/members/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c", [
    "headers" => [
      "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```


---

# List Locations

`GET /v1/locations`

**Required API scopes:** `locations.read`

## Parameters

- `limit` (query, `integer`) - The maximum number of items to return. Defaults to `25`; the maximum is `100`.
- `starting_after` (query, `string`) - Return items after this resource ID. You cannot use this with `cursor`.
- `cursor` (query, `string`) - The `next_cursor` value from the previous page. You cannot use this with `starting_after`.

## Response `200`

Paginated list of `Location` objects.

- `any`

### Example

```json
{
  "object": "list",
  "data": [
    {
      "id": "3c4d5e6f-7081-49ab-acde-f0123456789a",
      "object": "location",
      "address_line_1": "10 Harley Street",
      "address_line_2": "Marylebone",
      "city": "London",
      "country_code": "GB",
      "county": "Greater London",
      "created_at": "2026-01-01T09:00:00Z",
      "formatted_address": "10 Harley Street, Marylebone, London, W1G 9PF",
      "name": "Harley Street Clinic",
      "postcode": "W1G 9PF",
      "updated_at": "2026-01-01T09:00:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": "eyJzdGFydF90aW1lIjoiMjAyNi0wMS0wMVQwOTowMDowMFoifQ",
  "url": "/v1/locations"
}
```

## Response `401`

The access token is missing, invalid, expired, or revoked.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `403`

The access token lacks the required scope, or the project is disabled.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `429`

Too many requests. Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Code samples

```bash
curl -X GET "https://api.carebit.co/v1/locations" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN"
```

```javascript
const response = await fetch("https://api.carebit.co/v1/locations", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
  },
});

if (!response.ok) {
  throw new Error(`Carebit API error: ${response.status}`);
}

const data = await response.json();
```

```python
import os
import requests

response = requests.get(
    "https://api.carebit.co/v1/locations",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
    }
)
response.raise_for_status()
data = response.json()
```

```ruby
require "httparty"

response = HTTParty.get(
  "https://api.carebit.co/v1/locations",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}"
  }
)
raise "Carebit API error: #{response.code}" unless response.success?
data = response.parsed_response
```

```php
<?php

$client = new GuzzleHttp\Client();

$response = $client->get("https://api.carebit.co/v1/locations", [
    "headers" => [
      "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```


---

# Get a Location

`GET /v1/locations/:id`

**Required API scopes:** `locations.read`

## Parameters

- `id` (path, `string`) (required)

## Response `200`

The requested `Location`.

- `object`
  - `address_line_1` (`string | null`) - The primary address line of the location.
  - `address_line_2` (`string | null`) - The secondary address line of the location.
  - `city` (`string | null`) - The city in the location's postal address.
  - `country_code` (`string | null`) - The ISO 3166-1 alpha-2 country code for the postal address, such as `GB` for the United Kingdom.
  - `county` (`string | null`) - The county or region in the location's postal address.
  - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `formatted_address` (`string | null`) - The single-line address of the location, formatted for display.
  - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - `name` (`string | null`) - The display name of the location.
  - `object` (`any`) - Discriminator value emitted at `object`.
  - `postcode` (`string | null`) - The postal code of the location.
  - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.

### Example

```json
{
  "id": "3c4d5e6f-7081-49ab-acde-f0123456789a",
  "object": "location",
  "address_line_1": "10 Harley Street",
  "address_line_2": "Marylebone",
  "city": "London",
  "country_code": "GB",
  "county": "Greater London",
  "created_at": "2026-01-01T09:00:00Z",
  "formatted_address": "10 Harley Street, Marylebone, London, W1G 9PF",
  "name": "Harley Street Clinic",
  "postcode": "W1G 9PF",
  "updated_at": "2026-01-01T09:00:00Z"
}
```

## Response `401`

The access token is missing, invalid, expired, or revoked.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `403`

The access token lacks the required scope, or the project is disabled.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `404`

Error response.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `429`

Too many requests. Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Code samples

```bash
curl -X GET "https://api.carebit.co/v1/locations/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN"
```

```javascript
const response = await fetch("https://api.carebit.co/v1/locations/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
  },
});

if (!response.ok) {
  throw new Error(`Carebit API error: ${response.status}`);
}

const data = await response.json();
```

```python
import os
import requests

response = requests.get(
    "https://api.carebit.co/v1/locations/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
    }
)
response.raise_for_status()
data = response.json()
```

```ruby
require "httparty"

response = HTTParty.get(
  "https://api.carebit.co/v1/locations/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}"
  }
)
raise "Carebit API error: #{response.code}" unless response.success?
data = response.parsed_response
```

```php
<?php

$client = new GuzzleHttp\Client();

$response = $client->get("https://api.carebit.co/v1/locations/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c", [
    "headers" => [
      "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```


---

# Get the next slot that a Clinician can be booked into

`GET /v1/next_availability_slot`

Finds the next time the Clinician can be booked for the ServiceVariant, searching up to 8 months ahead. The search includes Services that patients cannot book online and does not apply the Patient Portal's minimum booking notice.

**Required API scopes:** `availability_slots.read`

## Parameters

- `clinician_id` (query, `string`) (required) - The Clinician to find the next slot for.
- `service_variant_id` (query, `string`) (required) - The ServiceVariant to find the next slot for. It determines the duration and booking rules.
- `from_date` (query, `string`) - The date from which to search, in ISO 8601 format (YYYY-MM-DD). Defaults to today.

## Response `200`

The requested `AvailabilitySlot`.

- `object` - A time when the Clinician can be booked for the requested ServiceVariant.
  - `clinician_id` (`string`) - format: `uuid`; The identifier of the Clinician who can provide the slot.
  - `end_time` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `location_id` (`string | null`) - format: `uuid`; The identifier of the Location at which the slot is available.
  - `object` (`any`) - Always `availability_slot`.
  - `resource_type` (`string`) - The type of resource that can be booked. Currently `clinician`; a future API version may also support `room`.
  - `room_id` (`string | null`) - format: `uuid`; The identifier of the Room required by the ServiceVariant, when applicable.
  - `service_id` (`string`) - format: `uuid`; The identifier of the Service provided during the slot.
  - `service_variant_id` (`string`) - format: `uuid`; The identifier of the ServiceVariant provided during the slot.
  - `start_time` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.

### Example

```json
{
  "object": "availability_slot",
  "clinician_id": "2b3c4d5e-6f70-489a-9bcd-ef0123456789",
  "end_time": "2026-01-01T10:00:00Z",
  "location_id": "3c4d5e6f-7081-49ab-acde-f0123456789a",
  "resource_type": "clinician",
  "room_id": "4d5e6f70-8192-4abc-bdef-0123456789ab",
  "service_id": "5e6f7081-92a3-4bcd-8ef0-123456789abc",
  "service_variant_id": "6f708192-a3b4-4cde-9f01-23456789abcd",
  "start_time": "2026-01-01T09:00:00Z"
}
```

## Response `400`

A required parameter is missing, malformed, or outside the permitted date range.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `401`

The access token is missing, invalid, expired, or revoked.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `403`

The access token lacks the required scope, or the project is disabled.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `404`

The Clinician or ServiceVariant was not found, or no slot was available within 8 months.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `429`

Too many requests. Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Code samples

```bash
curl -X GET "https://api.carebit.co/v1/next_availability_slot?clinician_id=8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c&service_variant_id=8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN"
```

```javascript
const response = await fetch("https://api.carebit.co/v1/next_availability_slot?clinician_id=8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c&service_variant_id=8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
  },
});

if (!response.ok) {
  throw new Error(`Carebit API error: ${response.status}`);
}

const data = await response.json();
```

```python
import os
import requests

response = requests.get(
    "https://api.carebit.co/v1/next_availability_slot?clinician_id=8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c&service_variant_id=8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
    }
)
response.raise_for_status()
data = response.json()
```

```ruby
require "httparty"

response = HTTParty.get(
  "https://api.carebit.co/v1/next_availability_slot?clinician_id=8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c&service_variant_id=8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}"
  }
)
raise "Carebit API error: #{response.code}" unless response.success?
data = response.parsed_response
```

```php
<?php

$client = new GuzzleHttp\Client();

$response = $client->get("https://api.carebit.co/v1/next_availability_slot?clinician_id=8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c&service_variant_id=8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c", [
    "headers" => [
      "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```


---

# List Notes

`GET /v1/notes`

**Required API scopes:** `notes.read`

## Parameters

- `patient_id` (query, `string`)
- `booking_id` (query, `string`)
- `updated_since` (query, `string`)
- `limit` (query, `integer`) - The maximum number of items to return. Defaults to `25`; the maximum is `100`.
- `starting_after` (query, `string`) - Return items after this resource ID. You cannot use this with `cursor`.
- `cursor` (query, `string`) - The `next_cursor` value from the previous page. You cannot use this with `starting_after`.

## Response `200`

Paginated list of `Note` objects.

- `any`

### Example

```json
{
  "object": "list",
  "data": [
    {
      "id": "e15af05d-2be0-459d-88c2-19cf18b3d0ff",
      "object": "note",
      "attachments": [
        {
          "id": "f631636b-32e2-41be-8e4f-0a34ee0d5d59",
          "download_url": "https://files.example.invalid/document.pdf?signature=test",
          "filename": "referral-letter.pdf"
        }
      ],
      "author": {
        "id": "af02fa53-0af3-48ab-83b5-82488923e84f",
        "object": "staff_member",
        "created_at": "2026-01-01T09:00:00Z",
        "email": "alex.morgan@example.com",
        "first_name": "Alex",
        "last_name": "Morgan",
        "links": {
          "self": "https://api.carebit.co/v1/staff_members/af02fa53-0af3-48ab-83b5-82488923e84f"
        },
        "name": "Initial consultation",
        "title": "Dr",
        "updated_at": "2026-01-01T09:00:00Z"
      },
      "content": "<p>The Patient reports improved symptoms.</p>",
      "created_at": "2026-01-01T09:00:00Z",
      "is_pinned": true,
      "links": {
        "booking": "https://api.carebit.co/v1/bookings/92a3b4c5-d6e7-4f01-8234-56789abcdef0",
        "patient": "https://api.carebit.co/v1/patients/1a2b3c4d-5e6f-4789-8abc-def012345678",
        "remote_file_import_batch": "https://api.carebit.co/v1/remote_file_import_batches/ebc38802-f219-4c7b-8136-8e963a0c69e0"
      },
      "remote_file_import_batch_id": "ebc38802-f219-4c7b-8136-8e963a0c69e0",
      "subject_id": "1460f5ec-fe45-4f44-80d7-8a3b86ef2864",
      "subject_type": null,
      "updated_at": "2026-01-01T09:00:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": "eyJzdGFydF90aW1lIjoiMjAyNi0wMS0wMVQwOTowMDowMFoifQ",
  "url": "/v1/notes"
}
```

## Response `400`

A filter or pagination parameter is invalid.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `401`

The access token is missing, invalid, expired, or revoked.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `403`

The access token lacks the required scope, or the project is disabled.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `429`

Too many requests. Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Code samples

```bash
curl -X GET "https://api.carebit.co/v1/notes" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN"
```

```javascript
const response = await fetch("https://api.carebit.co/v1/notes", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
  },
});

if (!response.ok) {
  throw new Error(`Carebit API error: ${response.status}`);
}

const data = await response.json();
```

```python
import os
import requests

response = requests.get(
    "https://api.carebit.co/v1/notes",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
    }
)
response.raise_for_status()
data = response.json()
```

```ruby
require "httparty"

response = HTTParty.get(
  "https://api.carebit.co/v1/notes",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}"
  }
)
raise "Carebit API error: #{response.code}" unless response.success?
data = response.parsed_response
```

```php
<?php

$client = new GuzzleHttp\Client();

$response = $client->get("https://api.carebit.co/v1/notes", [
    "headers" => [
      "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```


---

# Create a Note

`POST /v1/notes`

**Required API scopes:** `notes.create`

## Parameters

- `Idempotency-Key` (header, `string`) (required) - Client-generated idempotency key. Required for every POST/PATCH write. Replay of the same key with the same body returns the stored response with an `Idempotency-Replayed: true` header. Same key + different body returns `422 idempotency_key_reused`. A duplicate that arrives while the first request is still in flight returns `409 idempotency_conflict` with `Retry-After: 1`.

## Request body (`application/json`)

- `object`
  - `attachments` (`array`) - The files to attach to the Note. Provide either `url` or `file_base64` for each file.
    - `items` (`object`)
      - `file_base64` (`string`) - format: `byte`; The file bytes encoded as Base64. Provide this with `filename` instead of `url`. The decoded file can be at most 7 MB.
      - `filename` (`string | null`) - The filename to use for the attachment. Required with `file_base64`; defaults to the remote file's filename for URL sources.
      - `url` (`string`) - format: `uri`; The public HTTPS URL that Carebit can fetch.
  - `content` (`string`) - The sanitized HTML body of the note.
  - `is_pinned` (`boolean`) - Whether the note should be pinned for prominent display.
  - `subject_id` (`string`) - format: `uuid`; The identifier of the patient or booking that the note concerns.
  - `subject_type` (`string`) - enum: `booking`, `patient`; The type of resource that the note concerns.
  - `title` (`string | null`) - The display title of the note.

### Example

```json
{
  "content": "<p>Follow up in six weeks.</p>",
  "is_pinned": false,
  "subject_id": "00000000-0000-4000-8000-000000000004",
  "subject_type": "patient"
}
```

## Response `201`

The requested `Note`.

- `object`
  - `attachments` (`array`) - The files attached to the note.
    - `items` (`object`)
      - `download_url` (`string | null`) - format: `uri`; The short-lived signed download URL for the attachment. Null while the malware scan is not complete.
      - `filename` (`string | null`) - The original filename of the attachment.
      - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - `author` (`any`) - The staff member or Developer Platform project that created the note.
  - `content` (`string | null`) - The sanitized HTML body of the note.
  - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - `is_pinned` (`boolean`) - Whether the note is pinned for prominent display.
  - `links` (`object`) - URLs to related resources. Only the subject's link (`booking` or `patient`) is present on show/index/webhook responses. `remote_file_import_batch` is present on create/update responses when at least one attachment was submitted.
    - `booking` (`string | null`) - format: `uri`; The full URL of a related resource.
    - `patient` (`string | null`) - format: `uri`; The full URL of a related resource.
    - `remote_file_import_batch` (`string`) - format: `uri`; The full URL of a related resource.
  - `object` (`any`) - Discriminator value emitted at `object`.
  - `remote_file_import_batch_id` (`string`) - format: `uuid`; The identifier of the remote file import batch created for uploaded attachments. Set on create and update responses when at least one attachment was submitted.
  - `subject_id` (`string | null`) - format: `uuid`; The identifier of the patient or booking that the note concerns.
  - `subject_type` (`string | null`) - enum: `null`, `patient`, `booking`; The type of resource that the note concerns.
  - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.

### Example

```json
{
  "id": "e15af05d-2be0-459d-88c2-19cf18b3d0ff",
  "object": "note",
  "attachments": [
    {
      "id": "f631636b-32e2-41be-8e4f-0a34ee0d5d59",
      "download_url": "https://files.example.invalid/document.pdf?signature=test",
      "filename": "referral-letter.pdf"
    }
  ],
  "author": {
    "id": "af02fa53-0af3-48ab-83b5-82488923e84f",
    "object": "staff_member",
    "created_at": "2026-01-01T09:00:00Z",
    "email": "alex.morgan@example.com",
    "first_name": "Alex",
    "last_name": "Morgan",
    "links": {
      "self": "https://api.carebit.co/v1/staff_members/af02fa53-0af3-48ab-83b5-82488923e84f"
    },
    "name": "Initial consultation",
    "title": "Dr",
    "updated_at": "2026-01-01T09:00:00Z"
  },
  "content": "<p>The Patient reports improved symptoms.</p>",
  "created_at": "2026-01-01T09:00:00Z",
  "is_pinned": true,
  "links": {
    "booking": "https://api.carebit.co/v1/bookings/92a3b4c5-d6e7-4f01-8234-56789abcdef0",
    "patient": "https://api.carebit.co/v1/patients/1a2b3c4d-5e6f-4789-8abc-def012345678",
    "remote_file_import_batch": "https://api.carebit.co/v1/remote_file_import_batches/ebc38802-f219-4c7b-8136-8e963a0c69e0"
  },
  "remote_file_import_batch_id": "ebc38802-f219-4c7b-8136-8e963a0c69e0",
  "subject_id": "1460f5ec-fe45-4f44-80d7-8a3b86ef2864",
  "subject_type": null,
  "updated_at": "2026-01-01T09:00:00Z"
}
```

## Response `400`

The `Idempotency-Key` header is missing (`idempotency_key_required`) or exceeds 255 characters (`idempotency_key_too_long`).

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `401`

The access token is missing, invalid, expired, or revoked.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `403`

The access token lacks the required scope, or the project is disabled.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `404`

Error response.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `409`

A concurrent request holds the idempotency lease (`idempotency_conflict`). Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `422`

The `Idempotency-Key` was previously used with a different request body (`idempotency_key_reused`), or the request body failed validation.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `429`

Too many requests. Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Code samples

```bash
curl -X POST "https://api.carebit.co/v1/notes" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "content": "<p>Follow up in six weeks.</p>",
  "is_pinned": false,
  "subject_id": "00000000-0000-4000-8000-000000000004",
  "subject_type": "patient"
}'
```

```javascript
const response = await fetch("https://api.carebit.co/v1/notes", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
  "content": "<p>Follow up in six weeks.</p>",
  "is_pinned": false,
  "subject_id": "00000000-0000-4000-8000-000000000004",
  "subject_type": "patient"
}),
});

if (!response.ok) {
  throw new Error(`Carebit API error: ${response.status}`);
}

const data = await response.json();
```

```python
import os
import requests
import uuid

response = requests.post(
    "https://api.carebit.co/v1/notes",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "content": "<p>Follow up in six weeks.</p>",
        "is_pinned": False,
        "subject_id": "00000000-0000-4000-8000-000000000004",
        "subject_type": "patient"
    }
)
response.raise_for_status()
data = response.json()
```

```ruby
require "httparty"
require "json"
require "securerandom"

response = HTTParty.post(
  "https://api.carebit.co/v1/notes",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}",
    "Idempotency-Key" => SecureRandom.uuid,
    "Content-Type" => "application/json"
  },
  body: {
    "content" => "<p>Follow up in six weeks.</p>",
    "is_pinned" => false,
    "subject_id" => "00000000-0000-4000-8000-000000000004",
    "subject_type" => "patient"
  }.to_json
)
raise "Carebit API error: #{response.code}" unless response.success?
data = response.parsed_response
```

```php
<?php

$client = new GuzzleHttp\Client();

$response = $client->post("https://api.carebit.co/v1/notes", [
    "headers" => [
      "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
      "Idempotency-Key" => bin2hex(random_bytes(16)),
    ],
    "json" => [
      "content" => "<p>Follow up in six weeks.</p>",
      "is_pinned" => false,
      "subject_id" => "00000000-0000-4000-8000-000000000004",
      "subject_type" => "patient"
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```


---

# Get a Note

`GET /v1/notes/:id`

**Required API scopes:** `notes.read`

## Parameters

- `id` (path, `string`) (required)

## Response `200`

The requested `Note`.

- `object`
  - `attachments` (`array`) - The files attached to the note.
    - `items` (`object`)
      - `download_url` (`string | null`) - format: `uri`; The short-lived signed download URL for the attachment. Null while the malware scan is not complete.
      - `filename` (`string | null`) - The original filename of the attachment.
      - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - `author` (`any`) - The staff member or Developer Platform project that created the note.
  - `content` (`string | null`) - The sanitized HTML body of the note.
  - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - `is_pinned` (`boolean`) - Whether the note is pinned for prominent display.
  - `links` (`object`) - URLs to related resources. Only the subject's link (`booking` or `patient`) is present on show/index/webhook responses. `remote_file_import_batch` is present on create/update responses when at least one attachment was submitted.
    - `booking` (`string | null`) - format: `uri`; The full URL of a related resource.
    - `patient` (`string | null`) - format: `uri`; The full URL of a related resource.
    - `remote_file_import_batch` (`string`) - format: `uri`; The full URL of a related resource.
  - `object` (`any`) - Discriminator value emitted at `object`.
  - `remote_file_import_batch_id` (`string`) - format: `uuid`; The identifier of the remote file import batch created for uploaded attachments. Set on create and update responses when at least one attachment was submitted.
  - `subject_id` (`string | null`) - format: `uuid`; The identifier of the patient or booking that the note concerns.
  - `subject_type` (`string | null`) - enum: `null`, `patient`, `booking`; The type of resource that the note concerns.
  - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.

### Example

```json
{
  "id": "e15af05d-2be0-459d-88c2-19cf18b3d0ff",
  "object": "note",
  "attachments": [
    {
      "id": "f631636b-32e2-41be-8e4f-0a34ee0d5d59",
      "download_url": "https://files.example.invalid/document.pdf?signature=test",
      "filename": "referral-letter.pdf"
    }
  ],
  "author": {
    "id": "af02fa53-0af3-48ab-83b5-82488923e84f",
    "object": "staff_member",
    "created_at": "2026-01-01T09:00:00Z",
    "email": "alex.morgan@example.com",
    "first_name": "Alex",
    "last_name": "Morgan",
    "links": {
      "self": "https://api.carebit.co/v1/staff_members/af02fa53-0af3-48ab-83b5-82488923e84f"
    },
    "name": "Initial consultation",
    "title": "Dr",
    "updated_at": "2026-01-01T09:00:00Z"
  },
  "content": "<p>The Patient reports improved symptoms.</p>",
  "created_at": "2026-01-01T09:00:00Z",
  "is_pinned": true,
  "links": {
    "booking": "https://api.carebit.co/v1/bookings/92a3b4c5-d6e7-4f01-8234-56789abcdef0",
    "patient": "https://api.carebit.co/v1/patients/1a2b3c4d-5e6f-4789-8abc-def012345678",
    "remote_file_import_batch": "https://api.carebit.co/v1/remote_file_import_batches/ebc38802-f219-4c7b-8136-8e963a0c69e0"
  },
  "remote_file_import_batch_id": "ebc38802-f219-4c7b-8136-8e963a0c69e0",
  "subject_id": "1460f5ec-fe45-4f44-80d7-8a3b86ef2864",
  "subject_type": null,
  "updated_at": "2026-01-01T09:00:00Z"
}
```

## Response `401`

The access token is missing, invalid, expired, or revoked.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `403`

The access token lacks the required scope, or the project is disabled.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `404`

Error response.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `429`

Too many requests. Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Code samples

```bash
curl -X GET "https://api.carebit.co/v1/notes/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN"
```

```javascript
const response = await fetch("https://api.carebit.co/v1/notes/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
  },
});

if (!response.ok) {
  throw new Error(`Carebit API error: ${response.status}`);
}

const data = await response.json();
```

```python
import os
import requests

response = requests.get(
    "https://api.carebit.co/v1/notes/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
    }
)
response.raise_for_status()
data = response.json()
```

```ruby
require "httparty"

response = HTTParty.get(
  "https://api.carebit.co/v1/notes/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}"
  }
)
raise "Carebit API error: #{response.code}" unless response.success?
data = response.parsed_response
```

```php
<?php

$client = new GuzzleHttp\Client();

$response = $client->get("https://api.carebit.co/v1/notes/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c", [
    "headers" => [
      "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```


---

# Update an API-created Note

`PATCH /v1/notes/:id`

**Required API scopes:** `notes.update`

## Parameters

- `id` (path, `string`) (required)
- `Idempotency-Key` (header, `string`) (required) - Client-generated idempotency key. Required for every POST/PATCH write. Replay of the same key with the same body returns the stored response with an `Idempotency-Replayed: true` header. Same key + different body returns `422 idempotency_key_reused`. A duplicate that arrives while the first request is still in flight returns `409 idempotency_conflict` with `Retry-After: 1`.

## Request body (`application/json`)

- `object`
  - `attachments` (`array`) - The files to attach to the Note. Provide either `url` or `file_base64` for each file.
    - `items` (`object`)
      - `file_base64` (`string`) - format: `byte`; The file bytes encoded as Base64. Provide this with `filename` instead of `url`. The decoded file can be at most 7 MB.
      - `filename` (`string | null`) - The filename to use for the attachment. Required with `file_base64`; defaults to the remote file's filename for URL sources.
      - `url` (`string`) - format: `uri`; The public HTTPS URL that Carebit can fetch.
  - `content` (`string`) - The sanitized HTML body of the note.
  - `is_pinned` (`boolean`) - Whether the note should be pinned for prominent display.
  - `subject_id` (`string`) - format: `uuid`; The identifier of the patient or booking that the note concerns.
  - `subject_type` (`string`) - enum: `booking`, `patient`; The type of resource that the note concerns.
  - `title` (`string | null`) - The display title of the note.

### Example

```json
{
  "content": "<p>Updated body.</p>"
}
```

## Response `200`

The requested `Note`.

- `object`
  - `attachments` (`array`) - The files attached to the note.
    - `items` (`object`)
      - `download_url` (`string | null`) - format: `uri`; The short-lived signed download URL for the attachment. Null while the malware scan is not complete.
      - `filename` (`string | null`) - The original filename of the attachment.
      - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - `author` (`any`) - The staff member or Developer Platform project that created the note.
  - `content` (`string | null`) - The sanitized HTML body of the note.
  - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - `is_pinned` (`boolean`) - Whether the note is pinned for prominent display.
  - `links` (`object`) - URLs to related resources. Only the subject's link (`booking` or `patient`) is present on show/index/webhook responses. `remote_file_import_batch` is present on create/update responses when at least one attachment was submitted.
    - `booking` (`string | null`) - format: `uri`; The full URL of a related resource.
    - `patient` (`string | null`) - format: `uri`; The full URL of a related resource.
    - `remote_file_import_batch` (`string`) - format: `uri`; The full URL of a related resource.
  - `object` (`any`) - Discriminator value emitted at `object`.
  - `remote_file_import_batch_id` (`string`) - format: `uuid`; The identifier of the remote file import batch created for uploaded attachments. Set on create and update responses when at least one attachment was submitted.
  - `subject_id` (`string | null`) - format: `uuid`; The identifier of the patient or booking that the note concerns.
  - `subject_type` (`string | null`) - enum: `null`, `patient`, `booking`; The type of resource that the note concerns.
  - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.

### Example

```json
{
  "id": "e15af05d-2be0-459d-88c2-19cf18b3d0ff",
  "object": "note",
  "attachments": [
    {
      "id": "f631636b-32e2-41be-8e4f-0a34ee0d5d59",
      "download_url": "https://files.example.invalid/document.pdf?signature=test",
      "filename": "referral-letter.pdf"
    }
  ],
  "author": {
    "id": "af02fa53-0af3-48ab-83b5-82488923e84f",
    "object": "staff_member",
    "created_at": "2026-01-01T09:00:00Z",
    "email": "alex.morgan@example.com",
    "first_name": "Alex",
    "last_name": "Morgan",
    "links": {
      "self": "https://api.carebit.co/v1/staff_members/af02fa53-0af3-48ab-83b5-82488923e84f"
    },
    "name": "Initial consultation",
    "title": "Dr",
    "updated_at": "2026-01-01T09:00:00Z"
  },
  "content": "<p>The Patient reports improved symptoms.</p>",
  "created_at": "2026-01-01T09:00:00Z",
  "is_pinned": true,
  "links": {
    "booking": "https://api.carebit.co/v1/bookings/92a3b4c5-d6e7-4f01-8234-56789abcdef0",
    "patient": "https://api.carebit.co/v1/patients/1a2b3c4d-5e6f-4789-8abc-def012345678",
    "remote_file_import_batch": "https://api.carebit.co/v1/remote_file_import_batches/ebc38802-f219-4c7b-8136-8e963a0c69e0"
  },
  "remote_file_import_batch_id": "ebc38802-f219-4c7b-8136-8e963a0c69e0",
  "subject_id": "1460f5ec-fe45-4f44-80d7-8a3b86ef2864",
  "subject_type": null,
  "updated_at": "2026-01-01T09:00:00Z"
}
```

## Response `400`

The `Idempotency-Key` header is missing (`idempotency_key_required`) or exceeds 255 characters (`idempotency_key_too_long`).

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `401`

The access token is missing, invalid, expired, or revoked.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `403`

The Note was not created through the API for your Organization.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `404`

Error response.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `409`

A concurrent request holds the idempotency lease (`idempotency_conflict`). Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `422`

The `Idempotency-Key` was previously used with a different request body (`idempotency_key_reused`), or the request body failed validation.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `429`

Too many requests. Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Code samples

```bash
curl -X PATCH "https://api.carebit.co/v1/notes/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "content": "<p>Updated body.</p>"
}'
```

```javascript
const response = await fetch("https://api.carebit.co/v1/notes/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
  "content": "<p>Updated body.</p>"
}),
});

if (!response.ok) {
  throw new Error(`Carebit API error: ${response.status}`);
}

const data = await response.json();
```

```python
import os
import requests
import uuid

response = requests.patch(
    "https://api.carebit.co/v1/notes/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "content": "<p>Updated body.</p>"
    }
)
response.raise_for_status()
data = response.json()
```

```ruby
require "httparty"
require "json"
require "securerandom"

response = HTTParty.patch(
  "https://api.carebit.co/v1/notes/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}",
    "Idempotency-Key" => SecureRandom.uuid,
    "Content-Type" => "application/json"
  },
  body: {
    "content" => "<p>Updated body.</p>"
  }.to_json
)
raise "Carebit API error: #{response.code}" unless response.success?
data = response.parsed_response
```

```php
<?php

$client = new GuzzleHttp\Client();

$response = $client->patch("https://api.carebit.co/v1/notes/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c", [
    "headers" => [
      "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
      "Idempotency-Key" => bin2hex(random_bytes(16)),
    ],
    "json" => [
      "content" => "<p>Updated body.</p>"
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```


---

# Get the Organization for this access token

`GET /v1/organization`

**Required API scopes:** `organization.read`

## Response `200`

The requested `Organization`.

- `object`
  - `address_line_1` (`string | null`) - The primary address line of the organization.
  - `address_line_2` (`string | null`) - The secondary address line of the organization.
  - `city` (`string | null`) - The city in the organization's postal address.
  - `country_code` (`string | null`) - The ISO 3166-1 alpha-2 country code for the postal address, such as `GB` for the United Kingdom.
  - `county` (`string | null`) - The county or region in the organization's postal address.
  - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `currency` (`string | null`) - The ISO 4217 currency code used by the organization. Must be one of `chf`, `eur`, `gbp`, or `usd`. Null when this Organization is returned from `GET /v1/organizations` or nested on a PatientConnection.
  - `email` (`string | null`) - format: `email`; The contact email address of the organization. Null when this Organization is returned from `GET /v1/organizations` or nested on a PatientConnection.
  - `formatted_address` (`string | null`) - The single-line address of the organization, formatted for display.
  - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - `name` (`string`) - The display name of the organization, for example `Acme Healthcare`.
  - `object` (`any`) - Discriminator value emitted at `object`.
  - `organization_type` (`string | null`) - enum: `consultant`, `gp_practice`, `hospital`, `laboratory`, `legal`, `other`, `pharmacy`, `private_practice`, `null`; The kind of organization. Use `gp_practice` when attaching a GP.
  - `phone` (`string | null`) - The formatted contact phone number of the organization. Null when this Organization is returned from `GET /v1/organizations` or nested on a PatientConnection.
  - `postcode` (`string | null`) - The postal code in the organization's postal address.
  - `subdomain` (`string | null`) - The URL-safe subdomain that identifies the organization. Null when this Organization is returned from `GET /v1/organizations` or nested on a PatientConnection.
  - `time_zone` (`string | null`) - The IANA time zone used to interpret scheduling dates and display appointment times. Always `Europe/London` when present. Null when this Organization is returned from `GET /v1/organizations` or nested on a PatientConnection.
  - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.

### Example

```json
{
  "id": "8192a3b4-c5d6-4ef0-9123-456789abcdef",
  "object": "organization",
  "address_line_1": "10 Harley Street",
  "address_line_2": "Marylebone",
  "city": "London",
  "country_code": "GB",
  "county": "Greater London",
  "created_at": "2026-01-01T09:00:00Z",
  "currency": "GBP",
  "email": "alex.morgan@example.com",
  "formatted_address": "10 Harley Street, Marylebone, London, W1G 9PF",
  "name": "Harley Street Clinic",
  "organization_type": "consultant",
  "phone": "2071234567",
  "postcode": "W1G 9PF",
  "subdomain": "harley-street-clinic",
  "time_zone": "Example time zone",
  "updated_at": "2026-01-01T09:00:00Z"
}
```

## Response `401`

The access token is missing, invalid, expired, or revoked.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `403`

The access token lacks the required scope, or the project is disabled.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `429`

Too many requests. Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Code samples

```bash
curl -X GET "https://api.carebit.co/v1/organization" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN"
```

```javascript
const response = await fetch("https://api.carebit.co/v1/organization", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
  },
});

if (!response.ok) {
  throw new Error(`Carebit API error: ${response.status}`);
}

const data = await response.json();
```

```python
import os
import requests

response = requests.get(
    "https://api.carebit.co/v1/organization",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
    }
)
response.raise_for_status()
data = response.json()
```

```ruby
require "httparty"

response = HTTParty.get(
  "https://api.carebit.co/v1/organization",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}"
  }
)
raise "Carebit API error: #{response.code}" unless response.success?
data = response.parsed_response
```

```php
<?php

$client = new GuzzleHttp\Client();

$response = $client->get("https://api.carebit.co/v1/organization", [
    "headers" => [
      "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```


---

# Search Organizations

`GET /v1/organizations`

Searches active Organizations by name or postcode so you can attach a PatientConnection, such as a GP practice. This endpoint does not create Organizations. At least one of `name` or `postcode` is required. The response uses the Organization object. Email, subdomain, phone, currency, and time_zone are null so a search cannot harvest contact details.

**Required API scopes:** `organization.search`

## Parameters

- `name` (query, `string`) - Case-insensitive partial match on the Organization name. At least two characters. Provide `name` or `postcode`.
- `postcode` (query, `string`) - Case-insensitive partial match on the postal code. At least two characters. Provide `name` or `postcode`.
- `organization_type` (query, `string`) - Return only Organizations of this type. Use `gp_practice` when searching for a GP.
- `limit` (query, `integer`) - The maximum number of items to return. Defaults to `25`; the maximum is `100`.
- `starting_after` (query, `string`) - Return items after this resource ID. You cannot use this with `cursor`.
- `cursor` (query, `string`) - The `next_cursor` value from the previous page. You cannot use this with `starting_after`.

## Response `200`

Paginated list of `Organization` objects.

- `any`

### Example

```json
{
  "object": "list",
  "data": [
    {
      "id": "8192a3b4-c5d6-4ef0-9123-456789abcdef",
      "object": "organization",
      "address_line_1": "10 Harley Street",
      "address_line_2": "Marylebone",
      "city": "London",
      "country_code": "GB",
      "county": "Greater London",
      "created_at": "2026-01-01T09:00:00Z",
      "currency": "GBP",
      "email": "alex.morgan@example.com",
      "formatted_address": "10 Harley Street, Marylebone, London, W1G 9PF",
      "name": "Harley Street Clinic",
      "organization_type": "consultant",
      "phone": "2071234567",
      "postcode": "W1G 9PF",
      "subdomain": "harley-street-clinic",
      "time_zone": "Example time zone",
      "updated_at": "2026-01-01T09:00:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": "eyJzdGFydF90aW1lIjoiMjAyNi0wMS0wMVQwOTowMDowMFoifQ",
  "url": "/v1/organizations"
}
```

## Response `400`

The search is missing `name` and `postcode`, a value is too short, or `organization_type` is not a documented value.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `401`

The access token is missing, invalid, expired, or revoked.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `403`

The access token lacks the required scope, or the project is disabled.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `429`

Too many requests. Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Code samples

```bash
curl -X GET "https://api.carebit.co/v1/organizations?name=High%20Street%20Surgery&postcode=SW1A&organization_type=gp_practice" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN"
```

```javascript
const response = await fetch("https://api.carebit.co/v1/organizations?name=High%20Street%20Surgery&postcode=SW1A&organization_type=gp_practice", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
  },
});

if (!response.ok) {
  throw new Error(`Carebit API error: ${response.status}`);
}

const data = await response.json();
```

```python
import os
import requests

response = requests.get(
    "https://api.carebit.co/v1/organizations?name=High%20Street%20Surgery&postcode=SW1A&organization_type=gp_practice",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
    }
)
response.raise_for_status()
data = response.json()
```

```ruby
require "httparty"

response = HTTParty.get(
  "https://api.carebit.co/v1/organizations?name=High%20Street%20Surgery&postcode=SW1A&organization_type=gp_practice",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}"
  }
)
raise "Carebit API error: #{response.code}" unless response.success?
data = response.parsed_response
```

```php
<?php

$client = new GuzzleHttp\Client();

$response = $client->get("https://api.carebit.co/v1/organizations?name=High%20Street%20Surgery&postcode=SW1A&organization_type=gp_practice", [
    "headers" => [
      "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```


---

# List Patients connected to the Organization

`GET /v1/patients`

**Required API scopes:** `patients.read`

## Parameters

- `ids[]` (query, `array`) - Return only these Patients. Maximum 25 identifiers. Identifiers without an active PatientConnection to the Organization are omitted.
- `email` (query, `string`) - Filter by an exact email address, case-insensitively.
- `phone_number` (query, `string`) - Filter by an exact phone or mobile number. Use the international E.164 format where possible: a plus sign, the country calling code, and the national number with no spaces, for example `+447700900123`. A number without a `+` or `00` prefix is treated as a UK number.
- `first_name` (query, `string`) - Filter by an exact first name, case-insensitively.
- `last_name` (query, `string`) - Filter by an exact last name, case-insensitively.
- `date_of_birth` (query, `string`) - Filter by an exact date of birth in ISO 8601 format (YYYY-MM-DD).
- `limit` (query, `integer`) - The maximum number of items to return. Defaults to `25`; the maximum is `100`.
- `starting_after` (query, `string`) - Return items after this resource ID. You cannot use this with `cursor`.
- `cursor` (query, `string`) - The `next_cursor` value from the previous page. You cannot use this with `starting_after`.

## Response `200`

Paginated list of `Patient` objects.

- `any`

### Example

```json
{
  "object": "list",
  "data": [
    {
      "id": "1a2b3c4d-5e6f-4789-8abc-def012345678",
      "object": "patient",
      "address_line_1": "10 Harley Street",
      "address_line_2": "Marylebone",
      "city": "London",
      "country_code": "GB",
      "county": "Greater London",
      "created_at": "2026-01-01T09:00:00Z",
      "creation_source": "api",
      "date_of_birth": "1990-01-01",
      "display_name": "Dr Alex Morgan",
      "email": "alex.morgan@example.com",
      "first_name": "Alex",
      "is_opted_out_of_sms": false,
      "last_name": "Morgan",
      "mobile": "7700900123",
      "mobile_country_dial_code": "GB",
      "nhs_number": "485 777 3456",
      "phone": "2071234567",
      "phone_country_dial_code": "GB",
      "phone_number": "+44 7700 900123",
      "postcode": "W1G 9PF",
      "sex": "female",
      "title": "Dr",
      "updated_at": "2026-01-01T09:00:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": "eyJzdGFydF90aW1lIjoiMjAyNi0wMS0wMVQwOTowMDowMFoifQ",
  "url": "/v1/patients"
}
```

## Response `400`

A filter or pagination parameter is invalid.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `401`

The access token is missing, invalid, expired, or revoked.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `403`

The access token lacks the required scope, or the project is disabled.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `429`

Too many requests. Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Code samples

```bash
curl -X GET "https://api.carebit.co/v1/patients?first_name=John&last_name=Smith" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN"
```

```javascript
const response = await fetch("https://api.carebit.co/v1/patients?first_name=John&last_name=Smith", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
  },
});

if (!response.ok) {
  throw new Error(`Carebit API error: ${response.status}`);
}

const data = await response.json();
```

```python
import os
import requests

response = requests.get(
    "https://api.carebit.co/v1/patients?first_name=John&last_name=Smith",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
    }
)
response.raise_for_status()
data = response.json()
```

```ruby
require "httparty"

response = HTTParty.get(
  "https://api.carebit.co/v1/patients?first_name=John&last_name=Smith",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}"
  }
)
raise "Carebit API error: #{response.code}" unless response.success?
data = response.parsed_response
```

```php
<?php

$client = new GuzzleHttp\Client();

$response = $client->get("https://api.carebit.co/v1/patients?first_name=John&last_name=Smith", [
    "headers" => [
      "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```


---

# Create or find a Patient

`POST /v1/patients`

Creates and registers a Patient with the Organization. If the details match a connected Patient, returns that Patient without changing their record. A match elsewhere in Carebit returns a conflict for review. This endpoint allows 10 requests per access token per minute to limit automated searches for existing Patients.

**Required API scopes:** `patients.create`

## Parameters

- `Idempotency-Key` (header, `string`) (required) - Client-generated idempotency key. Required for every POST/PATCH write. Replay of the same key with the same body returns the stored response with an `Idempotency-Replayed: true` header. Same key + different body returns `422 idempotency_key_reused`. A duplicate that arrives while the first request is still in flight returns `409 idempotency_conflict` with `Retry-After: 1`.

## Request body (`application/json`)

- `object`
  - `address_line_1` (`string | null`) - The primary address line of the Patient.
  - `address_line_2` (`string | null`) - The secondary address line of the Patient.
  - `city` (`string | null`) - The city in the Patient's postal address.
  - `country_code` (`string | null`) - The uppercase ISO 3166-1 alpha-2 country code for the Patient's address.
  - `county` (`string | null`) - The county or region in the Patient's postal address.
  - `date_of_birth` (`string | null`) - format: `date`; The Patient's date of birth in ISO 8601 format.
  - `email` (`string | null`) - format: `email`; The Patient's email address.
  - `first_name` (`string | null`) - The Patient's first name.
  - `is_opted_out_of_sms` (`boolean`) - Whether the Patient has opted out of SMS messages.
  - `last_name` (`string | null`) - The Patient's last name.
  - `mobile` (`string | null`) - The national mobile number without its country calling code.
  - `mobile_country_dial_code` (`string | null`) - The country code used to derive the mobile calling code.
  - `phone` (`string | null`) - The national phone number without its country calling code.
  - `phone_country_dial_code` (`string | null`) - The country code used to derive the phone calling code.
  - `postcode` (`string | null`) - The Patient's postal code.
  - `sex` (`string | null`) - enum: `female`, `male`, `other`, `null`; The Patient's recorded sex.
  - `title` (`string | null`) - The Patient's personal title.

### Example

```json
{
  "date_of_birth": "1990-01-01",
  "email": "alex.morgan@example.com",
  "first_name": "Alex",
  "last_name": "Morgan",
  "mobile": "7700900123",
  "mobile_country_dial_code": "GB",
  "postcode": "SW1A 1AA",
  "sex": "female"
}
```

## Response `200`

An existing Patient connected to the Organization matched the supplied demographics. No Patient data was overwritten.

- `object`
  - `address_line_1` (`string | null`) - The primary address line of the Patient.
  - `address_line_2` (`string | null`) - The secondary address line of the Patient.
  - `city` (`string | null`) - The city in the Patient's postal address.
  - `country_code` (`string | null`) - The ISO 3166-1 alpha-2 country code for the postal address, such as `GB` for the United Kingdom.
  - `county` (`string | null`) - The county or region in the Patient's postal address.
  - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `creation_source` (`string | null`) - How the Patient was created. `api` means the record was created through the Developer Platform. Read-only.
  - `date_of_birth` (`string | null`) - format: `date`; The date of birth of the patient, in ISO 8601 format (YYYY-MM-DD).
  - `display_name` (`string | null`) - The formatted display name of the patient, including their title when recorded.
  - `email` (`string | null`) - format: `email`; The email address of the patient, when recorded.
  - `first_name` (`string | null`) - The first name of the patient.
  - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - `is_opted_out_of_sms` (`boolean`) - Whether the Patient has opted out of SMS messages.
  - `last_name` (`string | null`) - The last name of the patient.
  - `mobile` (`string | null`) - The national mobile number without its country calling code.
  - `mobile_country_dial_code` (`string | null`) - The ISO 3166-1 alpha-2 country code used to derive the mobile calling code.
  - `nhs_number` (`string | null`) - The 10-digit NHS number of the patient, without formatting.
  - `object` (`any`) - Discriminator value emitted at `object`.
  - `phone` (`string | null`) - The national phone number without its country calling code.
  - `phone_country_dial_code` (`string | null`) - The ISO 3166-1 alpha-2 country code used to derive the phone calling code.
  - `phone_number` (`string | null`) - The Patient's preferred contact number, formatted for display and compatible with E.164.
  - `postcode` (`string | null`) - The postal code of the Patient.
  - `sex` (`string | null`) - enum: `female`, `male`, `other`, `null`; The Patient's recorded sex.
  - `title` (`string | null`) - The personal title of the patient, when recorded.
  - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.

### Example

```json
{
  "id": "1a2b3c4d-5e6f-4789-8abc-def012345678",
  "object": "patient",
  "address_line_1": "10 Harley Street",
  "address_line_2": "Marylebone",
  "city": "London",
  "country_code": "GB",
  "county": "Greater London",
  "created_at": "2026-01-01T09:00:00Z",
  "creation_source": "api",
  "date_of_birth": "1990-01-01",
  "display_name": "Dr Alex Morgan",
  "email": "alex.morgan@example.com",
  "first_name": "Alex",
  "is_opted_out_of_sms": false,
  "last_name": "Morgan",
  "mobile": "7700900123",
  "mobile_country_dial_code": "GB",
  "nhs_number": "485 777 3456",
  "phone": "2071234567",
  "phone_country_dial_code": "GB",
  "phone_number": "+44 7700 900123",
  "postcode": "W1G 9PF",
  "sex": "female",
  "title": "Dr",
  "updated_at": "2026-01-01T09:00:00Z"
}
```

## Response `201`

Patient created and registered with the Organization.

- `object`
  - `address_line_1` (`string | null`) - The primary address line of the Patient.
  - `address_line_2` (`string | null`) - The secondary address line of the Patient.
  - `city` (`string | null`) - The city in the Patient's postal address.
  - `country_code` (`string | null`) - The ISO 3166-1 alpha-2 country code for the postal address, such as `GB` for the United Kingdom.
  - `county` (`string | null`) - The county or region in the Patient's postal address.
  - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `creation_source` (`string | null`) - How the Patient was created. `api` means the record was created through the Developer Platform. Read-only.
  - `date_of_birth` (`string | null`) - format: `date`; The date of birth of the patient, in ISO 8601 format (YYYY-MM-DD).
  - `display_name` (`string | null`) - The formatted display name of the patient, including their title when recorded.
  - `email` (`string | null`) - format: `email`; The email address of the patient, when recorded.
  - `first_name` (`string | null`) - The first name of the patient.
  - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - `is_opted_out_of_sms` (`boolean`) - Whether the Patient has opted out of SMS messages.
  - `last_name` (`string | null`) - The last name of the patient.
  - `mobile` (`string | null`) - The national mobile number without its country calling code.
  - `mobile_country_dial_code` (`string | null`) - The ISO 3166-1 alpha-2 country code used to derive the mobile calling code.
  - `nhs_number` (`string | null`) - The 10-digit NHS number of the patient, without formatting.
  - `object` (`any`) - Discriminator value emitted at `object`.
  - `phone` (`string | null`) - The national phone number without its country calling code.
  - `phone_country_dial_code` (`string | null`) - The ISO 3166-1 alpha-2 country code used to derive the phone calling code.
  - `phone_number` (`string | null`) - The Patient's preferred contact number, formatted for display and compatible with E.164.
  - `postcode` (`string | null`) - The postal code of the Patient.
  - `sex` (`string | null`) - enum: `female`, `male`, `other`, `null`; The Patient's recorded sex.
  - `title` (`string | null`) - The personal title of the patient, when recorded.
  - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.

### Example

```json
{
  "id": "1a2b3c4d-5e6f-4789-8abc-def012345678",
  "object": "patient",
  "address_line_1": "10 Harley Street",
  "address_line_2": "Marylebone",
  "city": "London",
  "country_code": "GB",
  "county": "Greater London",
  "created_at": "2026-01-01T09:00:00Z",
  "creation_source": "api",
  "date_of_birth": "1990-01-01",
  "display_name": "Dr Alex Morgan",
  "email": "alex.morgan@example.com",
  "first_name": "Alex",
  "is_opted_out_of_sms": false,
  "last_name": "Morgan",
  "mobile": "7700900123",
  "mobile_country_dial_code": "GB",
  "nhs_number": "485 777 3456",
  "phone": "2071234567",
  "phone_country_dial_code": "GB",
  "phone_number": "+44 7700 900123",
  "postcode": "W1G 9PF",
  "sex": "female",
  "title": "Dr",
  "updated_at": "2026-01-01T09:00:00Z"
}
```

## Response `400`

The `Idempotency-Key` header is missing (`idempotency_key_required`) or exceeds 255 characters (`idempotency_key_too_long`).

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `401`

The access token is missing, invalid, expired, or revoked.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `403`

The access token lacks the required scope, or the project is disabled.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `409`

A matching Patient exists elsewhere in Carebit and requires review before connection, or another request currently holds the IdempotencyKey.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `422`

The `Idempotency-Key` was previously used with a different request body (`idempotency_key_reused`), or the request body failed validation.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `429`

Too many requests. Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Code samples

```bash
curl -X POST "https://api.carebit.co/v1/patients" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "date_of_birth": "1990-01-01",
  "email": "alex.morgan@example.com",
  "first_name": "Alex",
  "last_name": "Morgan",
  "mobile": "7700900123",
  "mobile_country_dial_code": "GB",
  "postcode": "SW1A 1AA",
  "sex": "female"
}'
```

```javascript
const response = await fetch("https://api.carebit.co/v1/patients", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
  "date_of_birth": "1990-01-01",
  "email": "alex.morgan@example.com",
  "first_name": "Alex",
  "last_name": "Morgan",
  "mobile": "7700900123",
  "mobile_country_dial_code": "GB",
  "postcode": "SW1A 1AA",
  "sex": "female"
}),
});

if (!response.ok) {
  throw new Error(`Carebit API error: ${response.status}`);
}

const data = await response.json();
```

```python
import os
import requests
import uuid

response = requests.post(
    "https://api.carebit.co/v1/patients",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "date_of_birth": "1990-01-01",
        "email": "alex.morgan@example.com",
        "first_name": "Alex",
        "last_name": "Morgan",
        "mobile": "7700900123",
        "mobile_country_dial_code": "GB",
        "postcode": "SW1A 1AA",
        "sex": "female"
    }
)
response.raise_for_status()
data = response.json()
```

```ruby
require "httparty"
require "json"
require "securerandom"

response = HTTParty.post(
  "https://api.carebit.co/v1/patients",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}",
    "Idempotency-Key" => SecureRandom.uuid,
    "Content-Type" => "application/json"
  },
  body: {
    "date_of_birth" => "1990-01-01",
    "email" => "alex.morgan@example.com",
    "first_name" => "Alex",
    "last_name" => "Morgan",
    "mobile" => "7700900123",
    "mobile_country_dial_code" => "GB",
    "postcode" => "SW1A 1AA",
    "sex" => "female"
  }.to_json
)
raise "Carebit API error: #{response.code}" unless response.success?
data = response.parsed_response
```

```php
<?php

$client = new GuzzleHttp\Client();

$response = $client->post("https://api.carebit.co/v1/patients", [
    "headers" => [
      "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
      "Idempotency-Key" => bin2hex(random_bytes(16)),
    ],
    "json" => [
      "date_of_birth" => "1990-01-01",
      "email" => "alex.morgan@example.com",
      "first_name" => "Alex",
      "last_name" => "Morgan",
      "mobile" => "7700900123",
      "mobile_country_dial_code" => "GB",
      "postcode" => "SW1A 1AA",
      "sex" => "female"
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```


---

# Get a Patient

`GET /v1/patients/:id`

**Required API scopes:** `patients.read`

## Parameters

- `id` (path, `string`) (required)

## Response `200`

The requested `Patient`.

- `object`
  - `address_line_1` (`string | null`) - The primary address line of the Patient.
  - `address_line_2` (`string | null`) - The secondary address line of the Patient.
  - `city` (`string | null`) - The city in the Patient's postal address.
  - `country_code` (`string | null`) - The ISO 3166-1 alpha-2 country code for the postal address, such as `GB` for the United Kingdom.
  - `county` (`string | null`) - The county or region in the Patient's postal address.
  - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `creation_source` (`string | null`) - How the Patient was created. `api` means the record was created through the Developer Platform. Read-only.
  - `date_of_birth` (`string | null`) - format: `date`; The date of birth of the patient, in ISO 8601 format (YYYY-MM-DD).
  - `display_name` (`string | null`) - The formatted display name of the patient, including their title when recorded.
  - `email` (`string | null`) - format: `email`; The email address of the patient, when recorded.
  - `first_name` (`string | null`) - The first name of the patient.
  - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - `is_opted_out_of_sms` (`boolean`) - Whether the Patient has opted out of SMS messages.
  - `last_name` (`string | null`) - The last name of the patient.
  - `mobile` (`string | null`) - The national mobile number without its country calling code.
  - `mobile_country_dial_code` (`string | null`) - The ISO 3166-1 alpha-2 country code used to derive the mobile calling code.
  - `nhs_number` (`string | null`) - The 10-digit NHS number of the patient, without formatting.
  - `object` (`any`) - Discriminator value emitted at `object`.
  - `phone` (`string | null`) - The national phone number without its country calling code.
  - `phone_country_dial_code` (`string | null`) - The ISO 3166-1 alpha-2 country code used to derive the phone calling code.
  - `phone_number` (`string | null`) - The Patient's preferred contact number, formatted for display and compatible with E.164.
  - `postcode` (`string | null`) - The postal code of the Patient.
  - `sex` (`string | null`) - enum: `female`, `male`, `other`, `null`; The Patient's recorded sex.
  - `title` (`string | null`) - The personal title of the patient, when recorded.
  - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.

### Example

```json
{
  "id": "1a2b3c4d-5e6f-4789-8abc-def012345678",
  "object": "patient",
  "address_line_1": "10 Harley Street",
  "address_line_2": "Marylebone",
  "city": "London",
  "country_code": "GB",
  "county": "Greater London",
  "created_at": "2026-01-01T09:00:00Z",
  "creation_source": "api",
  "date_of_birth": "1990-01-01",
  "display_name": "Dr Alex Morgan",
  "email": "alex.morgan@example.com",
  "first_name": "Alex",
  "is_opted_out_of_sms": false,
  "last_name": "Morgan",
  "mobile": "7700900123",
  "mobile_country_dial_code": "GB",
  "nhs_number": "485 777 3456",
  "phone": "2071234567",
  "phone_country_dial_code": "GB",
  "phone_number": "+44 7700 900123",
  "postcode": "W1G 9PF",
  "sex": "female",
  "title": "Dr",
  "updated_at": "2026-01-01T09:00:00Z"
}
```

## Response `401`

The access token is missing, invalid, expired, or revoked.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `403`

The access token lacks the required scope, or the project is disabled.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `404`

Error response.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `429`

Too many requests. Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Code samples

```bash
curl -X GET "https://api.carebit.co/v1/patients/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN"
```

```javascript
const response = await fetch("https://api.carebit.co/v1/patients/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
  },
});

if (!response.ok) {
  throw new Error(`Carebit API error: ${response.status}`);
}

const data = await response.json();
```

```python
import os
import requests

response = requests.get(
    "https://api.carebit.co/v1/patients/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
    }
)
response.raise_for_status()
data = response.json()
```

```ruby
require "httparty"

response = HTTParty.get(
  "https://api.carebit.co/v1/patients/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}"
  }
)
raise "Carebit API error: #{response.code}" unless response.success?
data = response.parsed_response
```

```php
<?php

$client = new GuzzleHttp\Client();

$response = $client->get("https://api.carebit.co/v1/patients/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c", [
    "headers" => [
      "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```


---

# Update a Patient

`PATCH /v1/patients/:id`

**Required API scopes:** `patients.update`

## Parameters

- `id` (path, `string`) (required)
- `Idempotency-Key` (header, `string`) (required) - Client-generated idempotency key. Required for every POST/PATCH write. Replay of the same key with the same body returns the stored response with an `Idempotency-Replayed: true` header. Same key + different body returns `422 idempotency_key_reused`. A duplicate that arrives while the first request is still in flight returns `409 idempotency_conflict` with `Retry-After: 1`.

## Request body (`application/json`)

- `object`
  - `address_line_1` (`string | null`) - The primary address line of the Patient.
  - `address_line_2` (`string | null`) - The secondary address line of the Patient.
  - `city` (`string | null`) - The city in the Patient's postal address.
  - `country_code` (`string | null`) - The uppercase ISO 3166-1 alpha-2 country code for the Patient's address.
  - `county` (`string | null`) - The county or region in the Patient's postal address.
  - `date_of_birth` (`string | null`) - format: `date`; The Patient's date of birth in ISO 8601 format.
  - `email` (`string | null`) - format: `email`; The Patient's email address.
  - `first_name` (`string | null`) - The Patient's first name.
  - `is_opted_out_of_sms` (`boolean`) - Whether the Patient has opted out of SMS messages.
  - `last_name` (`string | null`) - The Patient's last name.
  - `mobile` (`string | null`) - The national mobile number without its country calling code.
  - `mobile_country_dial_code` (`string | null`) - The country code used to derive the mobile calling code.
  - `phone` (`string | null`) - The national phone number without its country calling code.
  - `phone_country_dial_code` (`string | null`) - The country code used to derive the phone calling code.
  - `postcode` (`string | null`) - The Patient's postal code.
  - `sex` (`string | null`) - enum: `female`, `male`, `other`, `null`; The Patient's recorded sex.
  - `title` (`string | null`) - The Patient's personal title.

### Example

```json
{
  "mobile": "7700900123",
  "mobile_country_dial_code": "GB"
}
```

## Response `200`

The requested `Patient`.

- `object`
  - `address_line_1` (`string | null`) - The primary address line of the Patient.
  - `address_line_2` (`string | null`) - The secondary address line of the Patient.
  - `city` (`string | null`) - The city in the Patient's postal address.
  - `country_code` (`string | null`) - The ISO 3166-1 alpha-2 country code for the postal address, such as `GB` for the United Kingdom.
  - `county` (`string | null`) - The county or region in the Patient's postal address.
  - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `creation_source` (`string | null`) - How the Patient was created. `api` means the record was created through the Developer Platform. Read-only.
  - `date_of_birth` (`string | null`) - format: `date`; The date of birth of the patient, in ISO 8601 format (YYYY-MM-DD).
  - `display_name` (`string | null`) - The formatted display name of the patient, including their title when recorded.
  - `email` (`string | null`) - format: `email`; The email address of the patient, when recorded.
  - `first_name` (`string | null`) - The first name of the patient.
  - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - `is_opted_out_of_sms` (`boolean`) - Whether the Patient has opted out of SMS messages.
  - `last_name` (`string | null`) - The last name of the patient.
  - `mobile` (`string | null`) - The national mobile number without its country calling code.
  - `mobile_country_dial_code` (`string | null`) - The ISO 3166-1 alpha-2 country code used to derive the mobile calling code.
  - `nhs_number` (`string | null`) - The 10-digit NHS number of the patient, without formatting.
  - `object` (`any`) - Discriminator value emitted at `object`.
  - `phone` (`string | null`) - The national phone number without its country calling code.
  - `phone_country_dial_code` (`string | null`) - The ISO 3166-1 alpha-2 country code used to derive the phone calling code.
  - `phone_number` (`string | null`) - The Patient's preferred contact number, formatted for display and compatible with E.164.
  - `postcode` (`string | null`) - The postal code of the Patient.
  - `sex` (`string | null`) - enum: `female`, `male`, `other`, `null`; The Patient's recorded sex.
  - `title` (`string | null`) - The personal title of the patient, when recorded.
  - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.

### Example

```json
{
  "id": "1a2b3c4d-5e6f-4789-8abc-def012345678",
  "object": "patient",
  "address_line_1": "10 Harley Street",
  "address_line_2": "Marylebone",
  "city": "London",
  "country_code": "GB",
  "county": "Greater London",
  "created_at": "2026-01-01T09:00:00Z",
  "creation_source": "api",
  "date_of_birth": "1990-01-01",
  "display_name": "Dr Alex Morgan",
  "email": "alex.morgan@example.com",
  "first_name": "Alex",
  "is_opted_out_of_sms": false,
  "last_name": "Morgan",
  "mobile": "7700900123",
  "mobile_country_dial_code": "GB",
  "nhs_number": "485 777 3456",
  "phone": "2071234567",
  "phone_country_dial_code": "GB",
  "phone_number": "+44 7700 900123",
  "postcode": "W1G 9PF",
  "sex": "female",
  "title": "Dr",
  "updated_at": "2026-01-01T09:00:00Z"
}
```

## Response `400`

The `Idempotency-Key` header is missing (`idempotency_key_required`) or exceeds 255 characters (`idempotency_key_too_long`).

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `401`

The access token is missing, invalid, expired, or revoked.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `403`

The access token lacks the required scope, or the project is disabled.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `404`

Error response.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `409`

A concurrent request holds the idempotency lease (`idempotency_conflict`). Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `422`

The `Idempotency-Key` was previously used with a different request body (`idempotency_key_reused`), or the request body failed validation.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `429`

Too many requests. Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Code samples

```bash
curl -X PATCH "https://api.carebit.co/v1/patients/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "mobile": "7700900123",
  "mobile_country_dial_code": "GB"
}'
```

```javascript
const response = await fetch("https://api.carebit.co/v1/patients/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
  "mobile": "7700900123",
  "mobile_country_dial_code": "GB"
}),
});

if (!response.ok) {
  throw new Error(`Carebit API error: ${response.status}`);
}

const data = await response.json();
```

```python
import os
import requests
import uuid

response = requests.patch(
    "https://api.carebit.co/v1/patients/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "mobile": "7700900123",
        "mobile_country_dial_code": "GB"
    }
)
response.raise_for_status()
data = response.json()
```

```ruby
require "httparty"
require "json"
require "securerandom"

response = HTTParty.patch(
  "https://api.carebit.co/v1/patients/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}",
    "Idempotency-Key" => SecureRandom.uuid,
    "Content-Type" => "application/json"
  },
  body: {
    "mobile" => "7700900123",
    "mobile_country_dial_code" => "GB"
  }.to_json
)
raise "Carebit API error: #{response.code}" unless response.success?
data = response.parsed_response
```

```php
<?php

$client = new GuzzleHttp\Client();

$response = $client->patch("https://api.carebit.co/v1/patients/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c", [
    "headers" => [
      "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
      "Idempotency-Key" => bin2hex(random_bytes(16)),
    ],
    "json" => [
      "mobile" => "7700900123",
      "mobile_country_dial_code" => "GB"
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```


---

# List a Patient's unlocked PatientConnections

`GET /v1/patients/:patient_id/connections`

Returns PatientConnections this Organization already has ResourcePermissions for. Locked connections, including a GP that has not been unlocked in Carebit, are omitted.

**Required API scopes:** `patient_connections.read`

## Parameters

- `patient_id` (path, `string`) (required)
- `limit` (query, `integer`) - The maximum number of items to return. Defaults to `25`; the maximum is `100`.
- `starting_after` (query, `string`) - Return items after this resource ID. You cannot use this with `cursor`.
- `cursor` (query, `string`) - The `next_cursor` value from the previous page. You cannot use this with `starting_after`.

## Response `200`

Paginated list of `PatientConnection` objects.

- `any`

### Example

```json
{
  "object": "list",
  "data": [
    {
      "id": "fcdd446b-eef0-4bf2-83d1-35764265817d",
      "object": "patient_connection",
      "clinician_id": "2b3c4d5e-6f70-489a-9bcd-ef0123456789",
      "created_at": "2026-01-01T09:00:00Z",
      "gp_status": "none_or_omitted",
      "is_active": true,
      "links": {
        "patient": "https://api.carebit.co/v1/patients/1a2b3c4d-5e6f-4789-8abc-def012345678",
        "payor": "https://api.carebit.co/v1/payors/708192a3-b4c5-4def-8012-3456789abcde"
      },
      "organization": {
        "id": "8192a3b4-c5d6-4ef0-9123-456789abcdef",
        "object": "organization",
        "address_line_1": "10 Harley Street",
        "address_line_2": "Marylebone",
        "city": "London",
        "country_code": "GB",
        "county": "Greater London",
        "created_at": "2026-01-01T09:00:00Z",
        "currency": "GBP",
        "email": "alex.morgan@example.com",
        "formatted_address": "10 Harley Street, Marylebone, London, W1G 9PF",
        "name": "Harley Street Clinic",
        "organization_type": "consultant",
        "phone": "2071234567",
        "postcode": "W1G 9PF",
        "subdomain": "harley-street-clinic",
        "time_zone": "Example time zone",
        "updated_at": "2026-01-01T09:00:00Z"
      },
      "organization_id": "8192a3b4-c5d6-4ef0-9123-456789abcdef",
      "patient": {
        "id": "1a2b3c4d-5e6f-4789-8abc-def012345678",
        "object": "patient",
        "address_line_1": "10 Harley Street",
        "address_line_2": "Marylebone",
        "city": "London",
        "country_code": "GB",
        "county": "Greater London",
        "created_at": "2026-01-01T09:00:00Z",
        "creation_source": "api",
        "date_of_birth": "1990-01-01",
        "display_name": "Dr Alex Morgan",
        "email": "alex.morgan@example.com",
        "first_name": "Alex",
        "is_opted_out_of_sms": false,
        "last_name": "Morgan",
        "mobile": "7700900123",
        "mobile_country_dial_code": "GB",
        "nhs_number": "485 777 3456",
        "phone": "2071234567",
        "phone_country_dial_code": "GB",
        "phone_number": "+44 7700 900123",
        "postcode": "W1G 9PF",
        "sex": "female",
        "title": "Dr",
        "updated_at": "2026-01-01T09:00:00Z"
      },
      "payor_id": "708192a3-b4c5-4def-8012-3456789abcde",
      "updated_at": "2026-01-01T09:00:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": "eyJzdGFydF90aW1lIjoiMjAyNi0wMS0wMVQwOTowMDowMFoifQ",
  "url": "/v1/patient_connections"
}
```

## Response `401`

The access token is missing, invalid, expired, or revoked.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `403`

The access token lacks the required scope, or the project is disabled.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `404`

Error response.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `429`

Too many requests. Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Code samples

```bash
curl -X GET "https://api.carebit.co/v1/patients/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c/connections" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN"
```

```javascript
const response = await fetch("https://api.carebit.co/v1/patients/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c/connections", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
  },
});

if (!response.ok) {
  throw new Error(`Carebit API error: ${response.status}`);
}

const data = await response.json();
```

```python
import os
import requests

response = requests.get(
    "https://api.carebit.co/v1/patients/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c/connections",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
    }
)
response.raise_for_status()
data = response.json()
```

```ruby
require "httparty"

response = HTTParty.get(
  "https://api.carebit.co/v1/patients/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c/connections",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}"
  }
)
raise "Carebit API error: #{response.code}" unless response.success?
data = response.parsed_response
```

```php
<?php

$client = new GuzzleHttp\Client();

$response = $client->get("https://api.carebit.co/v1/patients/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c/connections", [
    "headers" => [
      "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```


---

# Create a PatientConnection

`POST /v1/patients/:patient_id/connections`

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 endpoint does not create Organizations. Search with `GET /v1/organizations` first.

**Required API scopes:** `patient_connections.create`

## Parameters

- `patient_id` (path, `string`) (required)
- `Idempotency-Key` (header, `string`) (required) - Client-generated idempotency key. Required for every POST/PATCH write. Replay of the same key with the same body returns the stored response with an `Idempotency-Replayed: true` header. Same key + different body returns `422 idempotency_key_reused`. A duplicate that arrives while the first request is still in flight returns `409 idempotency_conflict` with `Retry-After: 1`.

## Request body (`application/json`)

- `object`
  - `clinician_id` (`string | null`) - format: `uuid`; The Clinician at the target Organization. The Clinician must already belong to that Organization. Pass `null` on update to remove the Clinician.
  - `gp_status` (`string | null`) - enum: `none_or_omitted`, `has_gp`, `no_gp_required`, `null`; Whether this Organization has recorded a GP for the Patient.
  - `is_active` (`boolean`) - Whether the PatientConnection is active. Defaults to `true` on create.
  - `organization_id` (`string`) - format: `uuid`; The existing Organization to connect the Patient to. Required on create. This endpoint does not create Organizations.
  - `payor_id` (`string`) - format: `uuid`; The Patient's Payor this Organization should use as the default billing party. The Payor must belong to the Patient.

### Example

```json
{
  "organization_id": "00000000-0000-4000-8000-000000000018"
}
```

## Response `200`

The Patient was already connected to the Organization. Carebit returned the existing PatientConnection.

- `object`
  - `clinician_id` (`string | null`) - format: `uuid`; The Clinician associated with this registration, when one is assigned.
  - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `gp_status` (`string | null`) - enum: `none_or_omitted`, `has_gp`, `no_gp_required`, `null`; Whether this Organization has recorded a GP for the Patient. `has_gp` means a GP PatientConnection is expected. `no_gp_required` means the Patient does not need a GP. `none_or_omitted` means no GP has been recorded.
  - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - `is_active` (`boolean`) - Whether the Patient registration is active.
  - `links` (`object`) - URLs to related resources.
    - `patient` (`string`) - format: `uri`; The full URL of a related resource.
    - `payor` (`string | null`) - format: `uri`; The full URL of a related resource.
  - `object` (`any`) - Discriminator value emitted at `object`.
  - `organization` (`object`)
    - `address_line_1` (`string | null`) - The primary address line of the organization.
    - `address_line_2` (`string | null`) - The secondary address line of the organization.
    - `city` (`string | null`) - The city in the organization's postal address.
    - `country_code` (`string | null`) - The ISO 3166-1 alpha-2 country code for the postal address, such as `GB` for the United Kingdom.
    - `county` (`string | null`) - The county or region in the organization's postal address.
    - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
    - `currency` (`string | null`) - The ISO 4217 currency code used by the organization. Must be one of `chf`, `eur`, `gbp`, or `usd`. Null when this Organization is returned from `GET /v1/organizations` or nested on a PatientConnection.
    - `email` (`string | null`) - format: `email`; The contact email address of the organization. Null when this Organization is returned from `GET /v1/organizations` or nested on a PatientConnection.
    - `formatted_address` (`string | null`) - The single-line address of the organization, formatted for display.
    - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
    - `name` (`string`) - The display name of the organization, for example `Acme Healthcare`.
    - `object` (`any`) - Discriminator value emitted at `object`.
    - `organization_type` (`string | null`) - enum: `consultant`, `gp_practice`, `hospital`, `laboratory`, `legal`, `other`, `pharmacy`, `private_practice`, `null`; The kind of organization. Use `gp_practice` when attaching a GP.
    - `phone` (`string | null`) - The formatted contact phone number of the organization. Null when this Organization is returned from `GET /v1/organizations` or nested on a PatientConnection.
    - `postcode` (`string | null`) - The postal code in the organization's postal address.
    - `subdomain` (`string | null`) - The URL-safe subdomain that identifies the organization. Null when this Organization is returned from `GET /v1/organizations` or nested on a PatientConnection.
    - `time_zone` (`string | null`) - The IANA time zone used to interpret scheduling dates and display appointment times. Always `Europe/London` when present. Null when this Organization is returned from `GET /v1/organizations` or nested on a PatientConnection.
    - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `organization_id` (`string`) - format: `uuid`; The Organization with which the Patient was registered.
  - `patient` (`object`)
    - `address_line_1` (`string | null`) - The primary address line of the Patient.
    - `address_line_2` (`string | null`) - The secondary address line of the Patient.
    - `city` (`string | null`) - The city in the Patient's postal address.
    - `country_code` (`string | null`) - The ISO 3166-1 alpha-2 country code for the postal address, such as `GB` for the United Kingdom.
    - `county` (`string | null`) - The county or region in the Patient's postal address.
    - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
    - `creation_source` (`string | null`) - How the Patient was created. `api` means the record was created through the Developer Platform. Read-only.
    - `date_of_birth` (`string | null`) - format: `date`; The date of birth of the patient, in ISO 8601 format (YYYY-MM-DD).
    - `display_name` (`string | null`) - The formatted display name of the patient, including their title when recorded.
    - `email` (`string | null`) - format: `email`; The email address of the patient, when recorded.
    - `first_name` (`string | null`) - The first name of the patient.
    - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
    - `is_opted_out_of_sms` (`boolean`) - Whether the Patient has opted out of SMS messages.
    - `last_name` (`string | null`) - The last name of the patient.
    - `mobile` (`string | null`) - The national mobile number without its country calling code.
    - `mobile_country_dial_code` (`string | null`) - The ISO 3166-1 alpha-2 country code used to derive the mobile calling code.
    - `nhs_number` (`string | null`) - The 10-digit NHS number of the patient, without formatting.
    - `object` (`any`) - Discriminator value emitted at `object`.
    - `phone` (`string | null`) - The national phone number without its country calling code.
    - `phone_country_dial_code` (`string | null`) - The ISO 3166-1 alpha-2 country code used to derive the phone calling code.
    - `phone_number` (`string | null`) - The Patient's preferred contact number, formatted for display and compatible with E.164.
    - `postcode` (`string | null`) - The postal code of the Patient.
    - `sex` (`string | null`) - enum: `female`, `male`, `other`, `null`; The Patient's recorded sex.
    - `title` (`string | null`) - The personal title of the patient, when recorded.
    - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `payor_id` (`string | null`) - format: `uuid`; The Payor this Organization uses as the default billing party for the Patient.
  - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.

### Example

```json
{
  "id": "fcdd446b-eef0-4bf2-83d1-35764265817d",
  "object": "patient_connection",
  "clinician_id": "2b3c4d5e-6f70-489a-9bcd-ef0123456789",
  "created_at": "2026-01-01T09:00:00Z",
  "gp_status": "none_or_omitted",
  "is_active": true,
  "links": {
    "patient": "https://api.carebit.co/v1/patients/1a2b3c4d-5e6f-4789-8abc-def012345678",
    "payor": "https://api.carebit.co/v1/payors/708192a3-b4c5-4def-8012-3456789abcde"
  },
  "organization": {
    "id": "8192a3b4-c5d6-4ef0-9123-456789abcdef",
    "object": "organization",
    "address_line_1": "10 Harley Street",
    "address_line_2": "Marylebone",
    "city": "London",
    "country_code": "GB",
    "county": "Greater London",
    "created_at": "2026-01-01T09:00:00Z",
    "currency": "GBP",
    "email": "alex.morgan@example.com",
    "formatted_address": "10 Harley Street, Marylebone, London, W1G 9PF",
    "name": "Harley Street Clinic",
    "organization_type": "consultant",
    "phone": "2071234567",
    "postcode": "W1G 9PF",
    "subdomain": "harley-street-clinic",
    "time_zone": "Example time zone",
    "updated_at": "2026-01-01T09:00:00Z"
  },
  "organization_id": "8192a3b4-c5d6-4ef0-9123-456789abcdef",
  "patient": {
    "id": "1a2b3c4d-5e6f-4789-8abc-def012345678",
    "object": "patient",
    "address_line_1": "10 Harley Street",
    "address_line_2": "Marylebone",
    "city": "London",
    "country_code": "GB",
    "county": "Greater London",
    "created_at": "2026-01-01T09:00:00Z",
    "creation_source": "api",
    "date_of_birth": "1990-01-01",
    "display_name": "Dr Alex Morgan",
    "email": "alex.morgan@example.com",
    "first_name": "Alex",
    "is_opted_out_of_sms": false,
    "last_name": "Morgan",
    "mobile": "7700900123",
    "mobile_country_dial_code": "GB",
    "nhs_number": "485 777 3456",
    "phone": "2071234567",
    "phone_country_dial_code": "GB",
    "phone_number": "+44 7700 900123",
    "postcode": "W1G 9PF",
    "sex": "female",
    "title": "Dr",
    "updated_at": "2026-01-01T09:00:00Z"
  },
  "payor_id": "708192a3-b4c5-4def-8012-3456789abcde",
  "updated_at": "2026-01-01T09:00:00Z"
}
```

## Response `201`

PatientConnection created.

- `object`
  - `clinician_id` (`string | null`) - format: `uuid`; The Clinician associated with this registration, when one is assigned.
  - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `gp_status` (`string | null`) - enum: `none_or_omitted`, `has_gp`, `no_gp_required`, `null`; Whether this Organization has recorded a GP for the Patient. `has_gp` means a GP PatientConnection is expected. `no_gp_required` means the Patient does not need a GP. `none_or_omitted` means no GP has been recorded.
  - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - `is_active` (`boolean`) - Whether the Patient registration is active.
  - `links` (`object`) - URLs to related resources.
    - `patient` (`string`) - format: `uri`; The full URL of a related resource.
    - `payor` (`string | null`) - format: `uri`; The full URL of a related resource.
  - `object` (`any`) - Discriminator value emitted at `object`.
  - `organization` (`object`)
    - `address_line_1` (`string | null`) - The primary address line of the organization.
    - `address_line_2` (`string | null`) - The secondary address line of the organization.
    - `city` (`string | null`) - The city in the organization's postal address.
    - `country_code` (`string | null`) - The ISO 3166-1 alpha-2 country code for the postal address, such as `GB` for the United Kingdom.
    - `county` (`string | null`) - The county or region in the organization's postal address.
    - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
    - `currency` (`string | null`) - The ISO 4217 currency code used by the organization. Must be one of `chf`, `eur`, `gbp`, or `usd`. Null when this Organization is returned from `GET /v1/organizations` or nested on a PatientConnection.
    - `email` (`string | null`) - format: `email`; The contact email address of the organization. Null when this Organization is returned from `GET /v1/organizations` or nested on a PatientConnection.
    - `formatted_address` (`string | null`) - The single-line address of the organization, formatted for display.
    - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
    - `name` (`string`) - The display name of the organization, for example `Acme Healthcare`.
    - `object` (`any`) - Discriminator value emitted at `object`.
    - `organization_type` (`string | null`) - enum: `consultant`, `gp_practice`, `hospital`, `laboratory`, `legal`, `other`, `pharmacy`, `private_practice`, `null`; The kind of organization. Use `gp_practice` when attaching a GP.
    - `phone` (`string | null`) - The formatted contact phone number of the organization. Null when this Organization is returned from `GET /v1/organizations` or nested on a PatientConnection.
    - `postcode` (`string | null`) - The postal code in the organization's postal address.
    - `subdomain` (`string | null`) - The URL-safe subdomain that identifies the organization. Null when this Organization is returned from `GET /v1/organizations` or nested on a PatientConnection.
    - `time_zone` (`string | null`) - The IANA time zone used to interpret scheduling dates and display appointment times. Always `Europe/London` when present. Null when this Organization is returned from `GET /v1/organizations` or nested on a PatientConnection.
    - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `organization_id` (`string`) - format: `uuid`; The Organization with which the Patient was registered.
  - `patient` (`object`)
    - `address_line_1` (`string | null`) - The primary address line of the Patient.
    - `address_line_2` (`string | null`) - The secondary address line of the Patient.
    - `city` (`string | null`) - The city in the Patient's postal address.
    - `country_code` (`string | null`) - The ISO 3166-1 alpha-2 country code for the postal address, such as `GB` for the United Kingdom.
    - `county` (`string | null`) - The county or region in the Patient's postal address.
    - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
    - `creation_source` (`string | null`) - How the Patient was created. `api` means the record was created through the Developer Platform. Read-only.
    - `date_of_birth` (`string | null`) - format: `date`; The date of birth of the patient, in ISO 8601 format (YYYY-MM-DD).
    - `display_name` (`string | null`) - The formatted display name of the patient, including their title when recorded.
    - `email` (`string | null`) - format: `email`; The email address of the patient, when recorded.
    - `first_name` (`string | null`) - The first name of the patient.
    - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
    - `is_opted_out_of_sms` (`boolean`) - Whether the Patient has opted out of SMS messages.
    - `last_name` (`string | null`) - The last name of the patient.
    - `mobile` (`string | null`) - The national mobile number without its country calling code.
    - `mobile_country_dial_code` (`string | null`) - The ISO 3166-1 alpha-2 country code used to derive the mobile calling code.
    - `nhs_number` (`string | null`) - The 10-digit NHS number of the patient, without formatting.
    - `object` (`any`) - Discriminator value emitted at `object`.
    - `phone` (`string | null`) - The national phone number without its country calling code.
    - `phone_country_dial_code` (`string | null`) - The ISO 3166-1 alpha-2 country code used to derive the phone calling code.
    - `phone_number` (`string | null`) - The Patient's preferred contact number, formatted for display and compatible with E.164.
    - `postcode` (`string | null`) - The postal code of the Patient.
    - `sex` (`string | null`) - enum: `female`, `male`, `other`, `null`; The Patient's recorded sex.
    - `title` (`string | null`) - The personal title of the patient, when recorded.
    - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `payor_id` (`string | null`) - format: `uuid`; The Payor this Organization uses as the default billing party for the Patient.
  - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.

### Example

```json
{
  "id": "fcdd446b-eef0-4bf2-83d1-35764265817d",
  "object": "patient_connection",
  "clinician_id": "2b3c4d5e-6f70-489a-9bcd-ef0123456789",
  "created_at": "2026-01-01T09:00:00Z",
  "gp_status": "none_or_omitted",
  "is_active": true,
  "links": {
    "patient": "https://api.carebit.co/v1/patients/1a2b3c4d-5e6f-4789-8abc-def012345678",
    "payor": "https://api.carebit.co/v1/payors/708192a3-b4c5-4def-8012-3456789abcde"
  },
  "organization": {
    "id": "8192a3b4-c5d6-4ef0-9123-456789abcdef",
    "object": "organization",
    "address_line_1": "10 Harley Street",
    "address_line_2": "Marylebone",
    "city": "London",
    "country_code": "GB",
    "county": "Greater London",
    "created_at": "2026-01-01T09:00:00Z",
    "currency": "GBP",
    "email": "alex.morgan@example.com",
    "formatted_address": "10 Harley Street, Marylebone, London, W1G 9PF",
    "name": "Harley Street Clinic",
    "organization_type": "consultant",
    "phone": "2071234567",
    "postcode": "W1G 9PF",
    "subdomain": "harley-street-clinic",
    "time_zone": "Example time zone",
    "updated_at": "2026-01-01T09:00:00Z"
  },
  "organization_id": "8192a3b4-c5d6-4ef0-9123-456789abcdef",
  "patient": {
    "id": "1a2b3c4d-5e6f-4789-8abc-def012345678",
    "object": "patient",
    "address_line_1": "10 Harley Street",
    "address_line_2": "Marylebone",
    "city": "London",
    "country_code": "GB",
    "county": "Greater London",
    "created_at": "2026-01-01T09:00:00Z",
    "creation_source": "api",
    "date_of_birth": "1990-01-01",
    "display_name": "Dr Alex Morgan",
    "email": "alex.morgan@example.com",
    "first_name": "Alex",
    "is_opted_out_of_sms": false,
    "last_name": "Morgan",
    "mobile": "7700900123",
    "mobile_country_dial_code": "GB",
    "nhs_number": "485 777 3456",
    "phone": "2071234567",
    "phone_country_dial_code": "GB",
    "phone_number": "+44 7700 900123",
    "postcode": "W1G 9PF",
    "sex": "female",
    "title": "Dr",
    "updated_at": "2026-01-01T09:00:00Z"
  },
  "payor_id": "708192a3-b4c5-4def-8012-3456789abcde",
  "updated_at": "2026-01-01T09:00:00Z"
}
```

## Response `400`

The `Idempotency-Key` header is missing (`idempotency_key_required`) or exceeds 255 characters (`idempotency_key_too_long`).

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `401`

The access token is missing, invalid, expired, or revoked.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `403`

The access token lacks the required scope, or the project is disabled.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `404`

The Patient, Organization, Clinician, or Payor was not found.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `409`

A concurrent request holds the idempotency lease (`idempotency_conflict`). Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `422`

The `Idempotency-Key` was previously used with a different request body (`idempotency_key_reused`), or the request body failed validation.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `429`

Too many requests. Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Code samples

```bash
curl -X POST "https://api.carebit.co/v1/patients/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c/connections" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "organization_id": "00000000-0000-4000-8000-000000000018"
}'
```

```javascript
const response = await fetch("https://api.carebit.co/v1/patients/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c/connections", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
  "organization_id": "00000000-0000-4000-8000-000000000018"
}),
});

if (!response.ok) {
  throw new Error(`Carebit API error: ${response.status}`);
}

const data = await response.json();
```

```python
import os
import requests
import uuid

response = requests.post(
    "https://api.carebit.co/v1/patients/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c/connections",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "organization_id": "00000000-0000-4000-8000-000000000018"
    }
)
response.raise_for_status()
data = response.json()
```

```ruby
require "httparty"
require "json"
require "securerandom"

response = HTTParty.post(
  "https://api.carebit.co/v1/patients/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c/connections",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}",
    "Idempotency-Key" => SecureRandom.uuid,
    "Content-Type" => "application/json"
  },
  body: {
    "organization_id" => "00000000-0000-4000-8000-000000000018"
  }.to_json
)
raise "Carebit API error: #{response.code}" unless response.success?
data = response.parsed_response
```

```php
<?php

$client = new GuzzleHttp\Client();

$response = $client->post("https://api.carebit.co/v1/patients/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c/connections", [
    "headers" => [
      "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
      "Idempotency-Key" => bin2hex(random_bytes(16)),
    ],
    "json" => [
      "organization_id" => "00000000-0000-4000-8000-000000000018"
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```


---

# Get an unlocked PatientConnection

`GET /v1/patients/:patient_id/connections/:id`

**Required API scopes:** `patient_connections.read`

## Parameters

- `patient_id` (path, `string`) (required)
- `id` (path, `string`) (required)

## Response `200`

The requested `PatientConnection`.

- `object`
  - `clinician_id` (`string | null`) - format: `uuid`; The Clinician associated with this registration, when one is assigned.
  - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `gp_status` (`string | null`) - enum: `none_or_omitted`, `has_gp`, `no_gp_required`, `null`; Whether this Organization has recorded a GP for the Patient. `has_gp` means a GP PatientConnection is expected. `no_gp_required` means the Patient does not need a GP. `none_or_omitted` means no GP has been recorded.
  - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - `is_active` (`boolean`) - Whether the Patient registration is active.
  - `links` (`object`) - URLs to related resources.
    - `patient` (`string`) - format: `uri`; The full URL of a related resource.
    - `payor` (`string | null`) - format: `uri`; The full URL of a related resource.
  - `object` (`any`) - Discriminator value emitted at `object`.
  - `organization` (`object`)
    - `address_line_1` (`string | null`) - The primary address line of the organization.
    - `address_line_2` (`string | null`) - The secondary address line of the organization.
    - `city` (`string | null`) - The city in the organization's postal address.
    - `country_code` (`string | null`) - The ISO 3166-1 alpha-2 country code for the postal address, such as `GB` for the United Kingdom.
    - `county` (`string | null`) - The county or region in the organization's postal address.
    - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
    - `currency` (`string | null`) - The ISO 4217 currency code used by the organization. Must be one of `chf`, `eur`, `gbp`, or `usd`. Null when this Organization is returned from `GET /v1/organizations` or nested on a PatientConnection.
    - `email` (`string | null`) - format: `email`; The contact email address of the organization. Null when this Organization is returned from `GET /v1/organizations` or nested on a PatientConnection.
    - `formatted_address` (`string | null`) - The single-line address of the organization, formatted for display.
    - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
    - `name` (`string`) - The display name of the organization, for example `Acme Healthcare`.
    - `object` (`any`) - Discriminator value emitted at `object`.
    - `organization_type` (`string | null`) - enum: `consultant`, `gp_practice`, `hospital`, `laboratory`, `legal`, `other`, `pharmacy`, `private_practice`, `null`; The kind of organization. Use `gp_practice` when attaching a GP.
    - `phone` (`string | null`) - The formatted contact phone number of the organization. Null when this Organization is returned from `GET /v1/organizations` or nested on a PatientConnection.
    - `postcode` (`string | null`) - The postal code in the organization's postal address.
    - `subdomain` (`string | null`) - The URL-safe subdomain that identifies the organization. Null when this Organization is returned from `GET /v1/organizations` or nested on a PatientConnection.
    - `time_zone` (`string | null`) - The IANA time zone used to interpret scheduling dates and display appointment times. Always `Europe/London` when present. Null when this Organization is returned from `GET /v1/organizations` or nested on a PatientConnection.
    - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `organization_id` (`string`) - format: `uuid`; The Organization with which the Patient was registered.
  - `patient` (`object`)
    - `address_line_1` (`string | null`) - The primary address line of the Patient.
    - `address_line_2` (`string | null`) - The secondary address line of the Patient.
    - `city` (`string | null`) - The city in the Patient's postal address.
    - `country_code` (`string | null`) - The ISO 3166-1 alpha-2 country code for the postal address, such as `GB` for the United Kingdom.
    - `county` (`string | null`) - The county or region in the Patient's postal address.
    - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
    - `creation_source` (`string | null`) - How the Patient was created. `api` means the record was created through the Developer Platform. Read-only.
    - `date_of_birth` (`string | null`) - format: `date`; The date of birth of the patient, in ISO 8601 format (YYYY-MM-DD).
    - `display_name` (`string | null`) - The formatted display name of the patient, including their title when recorded.
    - `email` (`string | null`) - format: `email`; The email address of the patient, when recorded.
    - `first_name` (`string | null`) - The first name of the patient.
    - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
    - `is_opted_out_of_sms` (`boolean`) - Whether the Patient has opted out of SMS messages.
    - `last_name` (`string | null`) - The last name of the patient.
    - `mobile` (`string | null`) - The national mobile number without its country calling code.
    - `mobile_country_dial_code` (`string | null`) - The ISO 3166-1 alpha-2 country code used to derive the mobile calling code.
    - `nhs_number` (`string | null`) - The 10-digit NHS number of the patient, without formatting.
    - `object` (`any`) - Discriminator value emitted at `object`.
    - `phone` (`string | null`) - The national phone number without its country calling code.
    - `phone_country_dial_code` (`string | null`) - The ISO 3166-1 alpha-2 country code used to derive the phone calling code.
    - `phone_number` (`string | null`) - The Patient's preferred contact number, formatted for display and compatible with E.164.
    - `postcode` (`string | null`) - The postal code of the Patient.
    - `sex` (`string | null`) - enum: `female`, `male`, `other`, `null`; The Patient's recorded sex.
    - `title` (`string | null`) - The personal title of the patient, when recorded.
    - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `payor_id` (`string | null`) - format: `uuid`; The Payor this Organization uses as the default billing party for the Patient.
  - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.

### Example

```json
{
  "id": "fcdd446b-eef0-4bf2-83d1-35764265817d",
  "object": "patient_connection",
  "clinician_id": "2b3c4d5e-6f70-489a-9bcd-ef0123456789",
  "created_at": "2026-01-01T09:00:00Z",
  "gp_status": "none_or_omitted",
  "is_active": true,
  "links": {
    "patient": "https://api.carebit.co/v1/patients/1a2b3c4d-5e6f-4789-8abc-def012345678",
    "payor": "https://api.carebit.co/v1/payors/708192a3-b4c5-4def-8012-3456789abcde"
  },
  "organization": {
    "id": "8192a3b4-c5d6-4ef0-9123-456789abcdef",
    "object": "organization",
    "address_line_1": "10 Harley Street",
    "address_line_2": "Marylebone",
    "city": "London",
    "country_code": "GB",
    "county": "Greater London",
    "created_at": "2026-01-01T09:00:00Z",
    "currency": "GBP",
    "email": "alex.morgan@example.com",
    "formatted_address": "10 Harley Street, Marylebone, London, W1G 9PF",
    "name": "Harley Street Clinic",
    "organization_type": "consultant",
    "phone": "2071234567",
    "postcode": "W1G 9PF",
    "subdomain": "harley-street-clinic",
    "time_zone": "Example time zone",
    "updated_at": "2026-01-01T09:00:00Z"
  },
  "organization_id": "8192a3b4-c5d6-4ef0-9123-456789abcdef",
  "patient": {
    "id": "1a2b3c4d-5e6f-4789-8abc-def012345678",
    "object": "patient",
    "address_line_1": "10 Harley Street",
    "address_line_2": "Marylebone",
    "city": "London",
    "country_code": "GB",
    "county": "Greater London",
    "created_at": "2026-01-01T09:00:00Z",
    "creation_source": "api",
    "date_of_birth": "1990-01-01",
    "display_name": "Dr Alex Morgan",
    "email": "alex.morgan@example.com",
    "first_name": "Alex",
    "is_opted_out_of_sms": false,
    "last_name": "Morgan",
    "mobile": "7700900123",
    "mobile_country_dial_code": "GB",
    "nhs_number": "485 777 3456",
    "phone": "2071234567",
    "phone_country_dial_code": "GB",
    "phone_number": "+44 7700 900123",
    "postcode": "W1G 9PF",
    "sex": "female",
    "title": "Dr",
    "updated_at": "2026-01-01T09:00:00Z"
  },
  "payor_id": "708192a3-b4c5-4def-8012-3456789abcde",
  "updated_at": "2026-01-01T09:00:00Z"
}
```

## Response `401`

The access token is missing, invalid, expired, or revoked.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `403`

The access token lacks the required scope, or the project is disabled.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `404`

Error response.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `429`

Too many requests. Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Code samples

```bash
curl -X GET "https://api.carebit.co/v1/patients/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c/connections/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN"
```

```javascript
const response = await fetch("https://api.carebit.co/v1/patients/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c/connections/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
  },
});

if (!response.ok) {
  throw new Error(`Carebit API error: ${response.status}`);
}

const data = await response.json();
```

```python
import os
import requests

response = requests.get(
    "https://api.carebit.co/v1/patients/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c/connections/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
    }
)
response.raise_for_status()
data = response.json()
```

```ruby
require "httparty"

response = HTTParty.get(
  "https://api.carebit.co/v1/patients/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c/connections/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}"
  }
)
raise "Carebit API error: #{response.code}" unless response.success?
data = response.parsed_response
```

```php
<?php

$client = new GuzzleHttp\Client();

$response = $client->get("https://api.carebit.co/v1/patients/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c/connections/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c", [
    "headers" => [
      "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```


---

# Update this Organization's PatientConnection

`PATCH /v1/patients/:patient_id/connections/:id`

Updates this Organization's PatientConnection for the Patient. Unlocked connections to other Organizations, such as a GP, can be listed and retrieved but not updated. Use `payor_id` to select the default billing party this Organization uses for the Patient. You cannot change `organization_id`; connect the Patient to a different Organization with POST instead.

**Required API scopes:** `patient_connections.update`

## Parameters

- `patient_id` (path, `string`) (required)
- `id` (path, `string`) (required)
- `Idempotency-Key` (header, `string`) (required) - Client-generated idempotency key. Required for every POST/PATCH write. Replay of the same key with the same body returns the stored response with an `Idempotency-Replayed: true` header. Same key + different body returns `422 idempotency_key_reused`. A duplicate that arrives while the first request is still in flight returns `409 idempotency_conflict` with `Retry-After: 1`.

## Request body (`application/json`)

- `object`
  - `clinician_id` (`string | null`) - format: `uuid`; The Clinician at the target Organization. The Clinician must already belong to that Organization. Pass `null` to remove the Clinician.
  - `gp_status` (`string | null`) - enum: `none_or_omitted`, `has_gp`, `no_gp_required`, `null`; Whether this Organization has recorded a GP for the Patient.
  - `is_active` (`boolean`) - Whether the PatientConnection is active.
  - `payor_id` (`string`) - format: `uuid`; The Patient's Payor this Organization should use as the default billing party. The Payor must belong to the Patient.

### Example

```json
{
  "payor_id": "00000000-0000-4000-8000-00000000000e"
}
```

## Response `200`

The requested `PatientConnection`.

- `object`
  - `clinician_id` (`string | null`) - format: `uuid`; The Clinician associated with this registration, when one is assigned.
  - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `gp_status` (`string | null`) - enum: `none_or_omitted`, `has_gp`, `no_gp_required`, `null`; Whether this Organization has recorded a GP for the Patient. `has_gp` means a GP PatientConnection is expected. `no_gp_required` means the Patient does not need a GP. `none_or_omitted` means no GP has been recorded.
  - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - `is_active` (`boolean`) - Whether the Patient registration is active.
  - `links` (`object`) - URLs to related resources.
    - `patient` (`string`) - format: `uri`; The full URL of a related resource.
    - `payor` (`string | null`) - format: `uri`; The full URL of a related resource.
  - `object` (`any`) - Discriminator value emitted at `object`.
  - `organization` (`object`)
    - `address_line_1` (`string | null`) - The primary address line of the organization.
    - `address_line_2` (`string | null`) - The secondary address line of the organization.
    - `city` (`string | null`) - The city in the organization's postal address.
    - `country_code` (`string | null`) - The ISO 3166-1 alpha-2 country code for the postal address, such as `GB` for the United Kingdom.
    - `county` (`string | null`) - The county or region in the organization's postal address.
    - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
    - `currency` (`string | null`) - The ISO 4217 currency code used by the organization. Must be one of `chf`, `eur`, `gbp`, or `usd`. Null when this Organization is returned from `GET /v1/organizations` or nested on a PatientConnection.
    - `email` (`string | null`) - format: `email`; The contact email address of the organization. Null when this Organization is returned from `GET /v1/organizations` or nested on a PatientConnection.
    - `formatted_address` (`string | null`) - The single-line address of the organization, formatted for display.
    - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
    - `name` (`string`) - The display name of the organization, for example `Acme Healthcare`.
    - `object` (`any`) - Discriminator value emitted at `object`.
    - `organization_type` (`string | null`) - enum: `consultant`, `gp_practice`, `hospital`, `laboratory`, `legal`, `other`, `pharmacy`, `private_practice`, `null`; The kind of organization. Use `gp_practice` when attaching a GP.
    - `phone` (`string | null`) - The formatted contact phone number of the organization. Null when this Organization is returned from `GET /v1/organizations` or nested on a PatientConnection.
    - `postcode` (`string | null`) - The postal code in the organization's postal address.
    - `subdomain` (`string | null`) - The URL-safe subdomain that identifies the organization. Null when this Organization is returned from `GET /v1/organizations` or nested on a PatientConnection.
    - `time_zone` (`string | null`) - The IANA time zone used to interpret scheduling dates and display appointment times. Always `Europe/London` when present. Null when this Organization is returned from `GET /v1/organizations` or nested on a PatientConnection.
    - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `organization_id` (`string`) - format: `uuid`; The Organization with which the Patient was registered.
  - `patient` (`object`)
    - `address_line_1` (`string | null`) - The primary address line of the Patient.
    - `address_line_2` (`string | null`) - The secondary address line of the Patient.
    - `city` (`string | null`) - The city in the Patient's postal address.
    - `country_code` (`string | null`) - The ISO 3166-1 alpha-2 country code for the postal address, such as `GB` for the United Kingdom.
    - `county` (`string | null`) - The county or region in the Patient's postal address.
    - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
    - `creation_source` (`string | null`) - How the Patient was created. `api` means the record was created through the Developer Platform. Read-only.
    - `date_of_birth` (`string | null`) - format: `date`; The date of birth of the patient, in ISO 8601 format (YYYY-MM-DD).
    - `display_name` (`string | null`) - The formatted display name of the patient, including their title when recorded.
    - `email` (`string | null`) - format: `email`; The email address of the patient, when recorded.
    - `first_name` (`string | null`) - The first name of the patient.
    - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
    - `is_opted_out_of_sms` (`boolean`) - Whether the Patient has opted out of SMS messages.
    - `last_name` (`string | null`) - The last name of the patient.
    - `mobile` (`string | null`) - The national mobile number without its country calling code.
    - `mobile_country_dial_code` (`string | null`) - The ISO 3166-1 alpha-2 country code used to derive the mobile calling code.
    - `nhs_number` (`string | null`) - The 10-digit NHS number of the patient, without formatting.
    - `object` (`any`) - Discriminator value emitted at `object`.
    - `phone` (`string | null`) - The national phone number without its country calling code.
    - `phone_country_dial_code` (`string | null`) - The ISO 3166-1 alpha-2 country code used to derive the phone calling code.
    - `phone_number` (`string | null`) - The Patient's preferred contact number, formatted for display and compatible with E.164.
    - `postcode` (`string | null`) - The postal code of the Patient.
    - `sex` (`string | null`) - enum: `female`, `male`, `other`, `null`; The Patient's recorded sex.
    - `title` (`string | null`) - The personal title of the patient, when recorded.
    - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `payor_id` (`string | null`) - format: `uuid`; The Payor this Organization uses as the default billing party for the Patient.
  - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.

### Example

```json
{
  "id": "fcdd446b-eef0-4bf2-83d1-35764265817d",
  "object": "patient_connection",
  "clinician_id": "2b3c4d5e-6f70-489a-9bcd-ef0123456789",
  "created_at": "2026-01-01T09:00:00Z",
  "gp_status": "none_or_omitted",
  "is_active": true,
  "links": {
    "patient": "https://api.carebit.co/v1/patients/1a2b3c4d-5e6f-4789-8abc-def012345678",
    "payor": "https://api.carebit.co/v1/payors/708192a3-b4c5-4def-8012-3456789abcde"
  },
  "organization": {
    "id": "8192a3b4-c5d6-4ef0-9123-456789abcdef",
    "object": "organization",
    "address_line_1": "10 Harley Street",
    "address_line_2": "Marylebone",
    "city": "London",
    "country_code": "GB",
    "county": "Greater London",
    "created_at": "2026-01-01T09:00:00Z",
    "currency": "GBP",
    "email": "alex.morgan@example.com",
    "formatted_address": "10 Harley Street, Marylebone, London, W1G 9PF",
    "name": "Harley Street Clinic",
    "organization_type": "consultant",
    "phone": "2071234567",
    "postcode": "W1G 9PF",
    "subdomain": "harley-street-clinic",
    "time_zone": "Example time zone",
    "updated_at": "2026-01-01T09:00:00Z"
  },
  "organization_id": "8192a3b4-c5d6-4ef0-9123-456789abcdef",
  "patient": {
    "id": "1a2b3c4d-5e6f-4789-8abc-def012345678",
    "object": "patient",
    "address_line_1": "10 Harley Street",
    "address_line_2": "Marylebone",
    "city": "London",
    "country_code": "GB",
    "county": "Greater London",
    "created_at": "2026-01-01T09:00:00Z",
    "creation_source": "api",
    "date_of_birth": "1990-01-01",
    "display_name": "Dr Alex Morgan",
    "email": "alex.morgan@example.com",
    "first_name": "Alex",
    "is_opted_out_of_sms": false,
    "last_name": "Morgan",
    "mobile": "7700900123",
    "mobile_country_dial_code": "GB",
    "nhs_number": "485 777 3456",
    "phone": "2071234567",
    "phone_country_dial_code": "GB",
    "phone_number": "+44 7700 900123",
    "postcode": "W1G 9PF",
    "sex": "female",
    "title": "Dr",
    "updated_at": "2026-01-01T09:00:00Z"
  },
  "payor_id": "708192a3-b4c5-4def-8012-3456789abcde",
  "updated_at": "2026-01-01T09:00:00Z"
}
```

## Response `400`

The `Idempotency-Key` header is missing (`idempotency_key_required`) or exceeds 255 characters (`idempotency_key_too_long`).

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `401`

The access token is missing, invalid, expired, or revoked.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `403`

The access token lacks the required scope, or the project is disabled.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `404`

Error response.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `409`

A concurrent request holds the idempotency lease (`idempotency_conflict`). Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `422`

The `Idempotency-Key` was previously used with a different request body (`idempotency_key_reused`), or the request body failed validation.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `429`

Too many requests. Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Code samples

```bash
curl -X PATCH "https://api.carebit.co/v1/patients/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c/connections/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "payor_id": "00000000-0000-4000-8000-00000000000e"
}'
```

```javascript
const response = await fetch("https://api.carebit.co/v1/patients/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c/connections/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
  "payor_id": "00000000-0000-4000-8000-00000000000e"
}),
});

if (!response.ok) {
  throw new Error(`Carebit API error: ${response.status}`);
}

const data = await response.json();
```

```python
import os
import requests
import uuid

response = requests.patch(
    "https://api.carebit.co/v1/patients/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c/connections/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "payor_id": "00000000-0000-4000-8000-00000000000e"
    }
)
response.raise_for_status()
data = response.json()
```

```ruby
require "httparty"
require "json"
require "securerandom"

response = HTTParty.patch(
  "https://api.carebit.co/v1/patients/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c/connections/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}",
    "Idempotency-Key" => SecureRandom.uuid,
    "Content-Type" => "application/json"
  },
  body: {
    "payor_id" => "00000000-0000-4000-8000-00000000000e"
  }.to_json
)
raise "Carebit API error: #{response.code}" unless response.success?
data = response.parsed_response
```

```php
<?php

$client = new GuzzleHttp\Client();

$response = $client->patch("https://api.carebit.co/v1/patients/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c/connections/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c", [
    "headers" => [
      "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
      "Idempotency-Key" => bin2hex(random_bytes(16)),
    ],
    "json" => [
      "payor_id" => "00000000-0000-4000-8000-00000000000e"
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```


---

# List a Patient's Payors

`GET /v1/patients/:patient_id/payors`

**Required API scopes:** `payors.read`

## Parameters

- `patient_id` (path, `string`) (required)
- `limit` (query, `integer`) - The maximum number of items to return. Defaults to `25`; the maximum is `100`.
- `starting_after` (query, `string`) - Return items after this resource ID. You cannot use this with `cursor`.
- `cursor` (query, `string`) - The `next_cursor` value from the previous page. You cannot use this with `starting_after`.

## Response `200`

Paginated list of `Payor` objects.

- `any`

### Example

```json
{
  "object": "list",
  "data": [
    {
      "id": "708192a3-b4c5-4def-8012-3456789abcde",
      "object": "payor",
      "address_line_1": "10 Harley Street",
      "address_line_2": "Marylebone",
      "alternative_payor_id": null,
      "city": "London",
      "country_code": "GB",
      "county": "Greater London",
      "created_at": "2026-01-01T09:00:00Z",
      "first_name": "Alex",
      "formatted_name": "Dr Alex Morgan",
      "formatted_payor_name": "Bupa",
      "insurance_authorization_code": "AUTH123",
      "insurance_company_id": "855e25b0-b138-48da-86ea-15162ce81f14",
      "insurance_policy_end_date": "2026-12-31",
      "insurance_policy_number": "POLICY123",
      "insurance_policy_start_date": "2026-01-01",
      "last_name": "Morgan",
      "notes": "Please confirm the appointment by email.",
      "payor_type": "insurance_company",
      "postcode": "W1G 9PF",
      "title": "Dr",
      "updated_at": "2026-01-01T09:00:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": "eyJzdGFydF90aW1lIjoiMjAyNi0wMS0wMVQwOTowMDowMFoifQ",
  "url": "/v1/payors"
}
```

## Response `401`

The access token is missing, invalid, expired, or revoked.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `403`

The access token lacks the required scope, or the project is disabled.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `404`

Error response.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `429`

Too many requests. Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Code samples

```bash
curl -X GET "https://api.carebit.co/v1/patients/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c/payors" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN"
```

```javascript
const response = await fetch("https://api.carebit.co/v1/patients/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c/payors", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
  },
});

if (!response.ok) {
  throw new Error(`Carebit API error: ${response.status}`);
}

const data = await response.json();
```

```python
import os
import requests

response = requests.get(
    "https://api.carebit.co/v1/patients/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c/payors",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
    }
)
response.raise_for_status()
data = response.json()
```

```ruby
require "httparty"

response = HTTParty.get(
  "https://api.carebit.co/v1/patients/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c/payors",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}"
  }
)
raise "Carebit API error: #{response.code}" unless response.success?
data = response.parsed_response
```

```php
<?php

$client = new GuzzleHttp\Client();

$response = $client->get("https://api.carebit.co/v1/patients/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c/payors", [
    "headers" => [
      "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```


---

# Create a Patient Payor

`POST /v1/patients/:patient_id/payors`

Creates an insurance or alternative Payor. Provide exactly one of `insurance_company_id` or `alternative_payor_id`. Set `set_as_default_payor` to `true` to also select this Payor on this Organization's PatientConnection. Carebit creates a self-pay Payor automatically when it creates the Patient.

**Required API scopes:** `payors.create`

## Parameters

- `patient_id` (path, `string`) (required)
- `Idempotency-Key` (header, `string`) (required) - Client-generated idempotency key. Required for every POST/PATCH write. Replay of the same key with the same body returns the stored response with an `Idempotency-Replayed: true` header. Same key + different body returns `422 idempotency_key_reused`. A duplicate that arrives while the first request is still in flight returns `409 idempotency_conflict` with `Retry-After: 1`.

## Request body (`application/json`)

- `object`
  - `address_line_1` (`string | null`) - The primary policyholder address line.
  - `address_line_2` (`string | null`) - The secondary policyholder address line.
  - `alternative_payor_id` (`string`) - format: `uuid`; The Organization-owned AlternativePayor responsible for payment.
  - `city` (`string | null`) - The city in the policyholder address.
  - `country_code` (`string | null`) - The uppercase ISO 3166-1 alpha-2 country code for the policyholder address.
  - `county` (`string | null`) - The county or region in the policyholder address.
  - `first_name` (`string | null`) - The policyholder's first name override.
  - `insurance_authorization_code` (`string | null`) - The insurer authorization code.
  - `insurance_company_id` (`string`) - format: `uuid`; The active InsuranceCompany responsible for payment.
  - `insurance_policy_end_date` (`string | null`) - format: `date`; The insurance policy end date.
  - `insurance_policy_number` (`string | null`) - The insurance policy or membership number.
  - `insurance_policy_start_date` (`string | null`) - format: `date`; The insurance policy start date.
  - `last_name` (`string | null`) - The policyholder's last name override.
  - `notes` (`string | null`) - Additional billing or insurance information.
  - `postcode` (`string | null`) - The postal code in the policyholder address.
  - `set_as_default_payor` (`boolean`) - When `true` on create, Carebit also sets this Payor as the default billing party on this Organization's PatientConnection. Nested GP connections are not changed. Omit or pass `false` to leave the selected Payor unchanged.
  - `title` (`string | null`) - The policyholder's personal title override.

### Example

```json
{
  "insurance_company_id": "00000000-0000-4000-8000-00000000000e",
  "insurance_policy_number": "POLICY123",
  "set_as_default_payor": true
}
```

## Response `201`

The requested `Payor`.

- `object`
  - `address_line_1` (`string | null`) - The primary address line of the payor.
  - `address_line_2` (`string | null`) - The secondary address line of the payor.
  - `alternative_payor_id` (`string | null`) - format: `uuid`; The identifier of the alternative payor responsible for payment, when `payor_type` is `alternative_payor`.
  - `city` (`string | null`) - The city in the payor's postal address.
  - `country_code` (`string | null`) - The ISO 3166-1 alpha-2 country code for the postal address, such as `GB` for the United Kingdom.
  - `county` (`string | null`) - The county or region in the payor's postal address.
  - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `first_name` (`string | null`) - The first name of the person responsible for payment, when applicable.
  - `formatted_name` (`string | null`) - The formatted name of the person responsible for payment.
  - `formatted_payor_name` (`string | null`) - The display name of the patient, insurer, or alternative payor responsible for payment.
  - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - `insurance_authorization_code` (`string | null`) - The insurer's authorization code.
  - `insurance_company_id` (`string | null`) - format: `uuid`; The identifier of the insurance company responsible for payment, when `payor_type` is `insurance_company`.
  - `insurance_policy_end_date` (`string | null`) - format: `date`; The end date of the insurance policy, when recorded.
  - `insurance_policy_number` (`string | null`) - The policy or membership number supplied by the insurer.
  - `insurance_policy_start_date` (`string | null`) - format: `date`; The start date of the insurance policy, when recorded.
  - `last_name` (`string | null`) - The last name of the person responsible for payment, when applicable.
  - `notes` (`string | null`) - The additional payment or insurance information recorded for this payor.
  - `object` (`any`) - Discriminator value emitted at `object`.
  - `payor_type` (`string`) - enum: `patient`, `insurance_company`, `alternative_payor`; The type of party responsible for payment.
  - `postcode` (`string | null`) - The postal code of the payor.
  - `title` (`string | null`) - The personal title of the person responsible for payment, when applicable.
  - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.

### Example

```json
{
  "id": "708192a3-b4c5-4def-8012-3456789abcde",
  "object": "payor",
  "address_line_1": "10 Harley Street",
  "address_line_2": "Marylebone",
  "alternative_payor_id": null,
  "city": "London",
  "country_code": "GB",
  "county": "Greater London",
  "created_at": "2026-01-01T09:00:00Z",
  "first_name": "Alex",
  "formatted_name": "Dr Alex Morgan",
  "formatted_payor_name": "Bupa",
  "insurance_authorization_code": "AUTH123",
  "insurance_company_id": "855e25b0-b138-48da-86ea-15162ce81f14",
  "insurance_policy_end_date": "2026-12-31",
  "insurance_policy_number": "POLICY123",
  "insurance_policy_start_date": "2026-01-01",
  "last_name": "Morgan",
  "notes": "Please confirm the appointment by email.",
  "payor_type": "insurance_company",
  "postcode": "W1G 9PF",
  "title": "Dr",
  "updated_at": "2026-01-01T09:00:00Z"
}
```

## Response `400`

The `Idempotency-Key` header is missing (`idempotency_key_required`) or exceeds 255 characters (`idempotency_key_too_long`).

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `401`

The access token is missing, invalid, expired, or revoked.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `403`

The access token lacks the required scope, or the project is disabled.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `404`

Error response.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `409`

A concurrent request holds the idempotency lease (`idempotency_conflict`). Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `422`

The `Idempotency-Key` was previously used with a different request body (`idempotency_key_reused`), or the request body failed validation.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `429`

Too many requests. Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Code samples

```bash
curl -X POST "https://api.carebit.co/v1/patients/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c/payors" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "insurance_company_id": "00000000-0000-4000-8000-00000000000e",
  "insurance_policy_number": "POLICY123",
  "set_as_default_payor": true
}'
```

```javascript
const response = await fetch("https://api.carebit.co/v1/patients/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c/payors", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
  "insurance_company_id": "00000000-0000-4000-8000-00000000000e",
  "insurance_policy_number": "POLICY123",
  "set_as_default_payor": true
}),
});

if (!response.ok) {
  throw new Error(`Carebit API error: ${response.status}`);
}

const data = await response.json();
```

```python
import os
import requests
import uuid

response = requests.post(
    "https://api.carebit.co/v1/patients/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c/payors",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "insurance_company_id": "00000000-0000-4000-8000-00000000000e",
        "insurance_policy_number": "POLICY123",
        "set_as_default_payor": True
    }
)
response.raise_for_status()
data = response.json()
```

```ruby
require "httparty"
require "json"
require "securerandom"

response = HTTParty.post(
  "https://api.carebit.co/v1/patients/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c/payors",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}",
    "Idempotency-Key" => SecureRandom.uuid,
    "Content-Type" => "application/json"
  },
  body: {
    "insurance_company_id" => "00000000-0000-4000-8000-00000000000e",
    "insurance_policy_number" => "POLICY123",
    "set_as_default_payor" => true
  }.to_json
)
raise "Carebit API error: #{response.code}" unless response.success?
data = response.parsed_response
```

```php
<?php

$client = new GuzzleHttp\Client();

$response = $client->post("https://api.carebit.co/v1/patients/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c/payors", [
    "headers" => [
      "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
      "Idempotency-Key" => bin2hex(random_bytes(16)),
    ],
    "json" => [
      "insurance_company_id" => "00000000-0000-4000-8000-00000000000e",
      "insurance_policy_number" => "POLICY123",
      "set_as_default_payor" => true
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```


---

# Get a Patient Payor

`GET /v1/patients/:patient_id/payors/:id`

**Required API scopes:** `payors.read`

## Parameters

- `patient_id` (path, `string`) (required)
- `id` (path, `string`) (required)

## Response `200`

The requested `Payor`.

- `object`
  - `address_line_1` (`string | null`) - The primary address line of the payor.
  - `address_line_2` (`string | null`) - The secondary address line of the payor.
  - `alternative_payor_id` (`string | null`) - format: `uuid`; The identifier of the alternative payor responsible for payment, when `payor_type` is `alternative_payor`.
  - `city` (`string | null`) - The city in the payor's postal address.
  - `country_code` (`string | null`) - The ISO 3166-1 alpha-2 country code for the postal address, such as `GB` for the United Kingdom.
  - `county` (`string | null`) - The county or region in the payor's postal address.
  - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `first_name` (`string | null`) - The first name of the person responsible for payment, when applicable.
  - `formatted_name` (`string | null`) - The formatted name of the person responsible for payment.
  - `formatted_payor_name` (`string | null`) - The display name of the patient, insurer, or alternative payor responsible for payment.
  - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - `insurance_authorization_code` (`string | null`) - The insurer's authorization code.
  - `insurance_company_id` (`string | null`) - format: `uuid`; The identifier of the insurance company responsible for payment, when `payor_type` is `insurance_company`.
  - `insurance_policy_end_date` (`string | null`) - format: `date`; The end date of the insurance policy, when recorded.
  - `insurance_policy_number` (`string | null`) - The policy or membership number supplied by the insurer.
  - `insurance_policy_start_date` (`string | null`) - format: `date`; The start date of the insurance policy, when recorded.
  - `last_name` (`string | null`) - The last name of the person responsible for payment, when applicable.
  - `notes` (`string | null`) - The additional payment or insurance information recorded for this payor.
  - `object` (`any`) - Discriminator value emitted at `object`.
  - `payor_type` (`string`) - enum: `patient`, `insurance_company`, `alternative_payor`; The type of party responsible for payment.
  - `postcode` (`string | null`) - The postal code of the payor.
  - `title` (`string | null`) - The personal title of the person responsible for payment, when applicable.
  - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.

### Example

```json
{
  "id": "708192a3-b4c5-4def-8012-3456789abcde",
  "object": "payor",
  "address_line_1": "10 Harley Street",
  "address_line_2": "Marylebone",
  "alternative_payor_id": null,
  "city": "London",
  "country_code": "GB",
  "county": "Greater London",
  "created_at": "2026-01-01T09:00:00Z",
  "first_name": "Alex",
  "formatted_name": "Dr Alex Morgan",
  "formatted_payor_name": "Bupa",
  "insurance_authorization_code": "AUTH123",
  "insurance_company_id": "855e25b0-b138-48da-86ea-15162ce81f14",
  "insurance_policy_end_date": "2026-12-31",
  "insurance_policy_number": "POLICY123",
  "insurance_policy_start_date": "2026-01-01",
  "last_name": "Morgan",
  "notes": "Please confirm the appointment by email.",
  "payor_type": "insurance_company",
  "postcode": "W1G 9PF",
  "title": "Dr",
  "updated_at": "2026-01-01T09:00:00Z"
}
```

## Response `401`

The access token is missing, invalid, expired, or revoked.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `403`

The access token lacks the required scope, or the project is disabled.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `404`

Error response.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `429`

Too many requests. Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Code samples

```bash
curl -X GET "https://api.carebit.co/v1/patients/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c/payors/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN"
```

```javascript
const response = await fetch("https://api.carebit.co/v1/patients/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c/payors/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
  },
});

if (!response.ok) {
  throw new Error(`Carebit API error: ${response.status}`);
}

const data = await response.json();
```

```python
import os
import requests

response = requests.get(
    "https://api.carebit.co/v1/patients/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c/payors/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
    }
)
response.raise_for_status()
data = response.json()
```

```ruby
require "httparty"

response = HTTParty.get(
  "https://api.carebit.co/v1/patients/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c/payors/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}"
  }
)
raise "Carebit API error: #{response.code}" unless response.success?
data = response.parsed_response
```

```php
<?php

$client = new GuzzleHttp\Client();

$response = $client->get("https://api.carebit.co/v1/patients/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c/payors/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c", [
    "headers" => [
      "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```


---

# Update a Patient Payor

`PATCH /v1/patients/:patient_id/payors/:id`

Updates a Payor. To change its type, provide one non-null `insurance_company_id` or `alternative_payor_id`. Once set, the Payor type cannot be cleared.

**Required API scopes:** `payors.update`

## Parameters

- `patient_id` (path, `string`) (required)
- `id` (path, `string`) (required)
- `Idempotency-Key` (header, `string`) (required) - Client-generated idempotency key. Required for every POST/PATCH write. Replay of the same key with the same body returns the stored response with an `Idempotency-Replayed: true` header. Same key + different body returns `422 idempotency_key_reused`. A duplicate that arrives while the first request is still in flight returns `409 idempotency_conflict` with `Retry-After: 1`.

## Request body (`application/json`)

- `object`
  - `address_line_1` (`string | null`) - The primary policyholder address line.
  - `address_line_2` (`string | null`) - The secondary policyholder address line.
  - `alternative_payor_id` (`string`) - format: `uuid`; The Organization-owned AlternativePayor responsible for payment.
  - `city` (`string | null`) - The city in the policyholder address.
  - `country_code` (`string | null`) - The uppercase ISO 3166-1 alpha-2 country code for the policyholder address.
  - `county` (`string | null`) - The county or region in the policyholder address.
  - `first_name` (`string | null`) - The policyholder's first name override.
  - `insurance_authorization_code` (`string | null`) - The insurer authorization code.
  - `insurance_company_id` (`string`) - format: `uuid`; The active InsuranceCompany responsible for payment.
  - `insurance_policy_end_date` (`string | null`) - format: `date`; The insurance policy end date.
  - `insurance_policy_number` (`string | null`) - The insurance policy or membership number.
  - `insurance_policy_start_date` (`string | null`) - format: `date`; The insurance policy start date.
  - `last_name` (`string | null`) - The policyholder's last name override.
  - `notes` (`string | null`) - Additional billing or insurance information.
  - `postcode` (`string | null`) - The postal code in the policyholder address.
  - `title` (`string | null`) - The policyholder's personal title override.

### Example

```json
{
  "insurance_authorization_code": "AUTH123"
}
```

## Response `200`

The requested `Payor`.

- `object`
  - `address_line_1` (`string | null`) - The primary address line of the payor.
  - `address_line_2` (`string | null`) - The secondary address line of the payor.
  - `alternative_payor_id` (`string | null`) - format: `uuid`; The identifier of the alternative payor responsible for payment, when `payor_type` is `alternative_payor`.
  - `city` (`string | null`) - The city in the payor's postal address.
  - `country_code` (`string | null`) - The ISO 3166-1 alpha-2 country code for the postal address, such as `GB` for the United Kingdom.
  - `county` (`string | null`) - The county or region in the payor's postal address.
  - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `first_name` (`string | null`) - The first name of the person responsible for payment, when applicable.
  - `formatted_name` (`string | null`) - The formatted name of the person responsible for payment.
  - `formatted_payor_name` (`string | null`) - The display name of the patient, insurer, or alternative payor responsible for payment.
  - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - `insurance_authorization_code` (`string | null`) - The insurer's authorization code.
  - `insurance_company_id` (`string | null`) - format: `uuid`; The identifier of the insurance company responsible for payment, when `payor_type` is `insurance_company`.
  - `insurance_policy_end_date` (`string | null`) - format: `date`; The end date of the insurance policy, when recorded.
  - `insurance_policy_number` (`string | null`) - The policy or membership number supplied by the insurer.
  - `insurance_policy_start_date` (`string | null`) - format: `date`; The start date of the insurance policy, when recorded.
  - `last_name` (`string | null`) - The last name of the person responsible for payment, when applicable.
  - `notes` (`string | null`) - The additional payment or insurance information recorded for this payor.
  - `object` (`any`) - Discriminator value emitted at `object`.
  - `payor_type` (`string`) - enum: `patient`, `insurance_company`, `alternative_payor`; The type of party responsible for payment.
  - `postcode` (`string | null`) - The postal code of the payor.
  - `title` (`string | null`) - The personal title of the person responsible for payment, when applicable.
  - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.

### Example

```json
{
  "id": "708192a3-b4c5-4def-8012-3456789abcde",
  "object": "payor",
  "address_line_1": "10 Harley Street",
  "address_line_2": "Marylebone",
  "alternative_payor_id": null,
  "city": "London",
  "country_code": "GB",
  "county": "Greater London",
  "created_at": "2026-01-01T09:00:00Z",
  "first_name": "Alex",
  "formatted_name": "Dr Alex Morgan",
  "formatted_payor_name": "Bupa",
  "insurance_authorization_code": "AUTH123",
  "insurance_company_id": "855e25b0-b138-48da-86ea-15162ce81f14",
  "insurance_policy_end_date": "2026-12-31",
  "insurance_policy_number": "POLICY123",
  "insurance_policy_start_date": "2026-01-01",
  "last_name": "Morgan",
  "notes": "Please confirm the appointment by email.",
  "payor_type": "insurance_company",
  "postcode": "W1G 9PF",
  "title": "Dr",
  "updated_at": "2026-01-01T09:00:00Z"
}
```

## Response `400`

The `Idempotency-Key` header is missing (`idempotency_key_required`) or exceeds 255 characters (`idempotency_key_too_long`).

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `401`

The access token is missing, invalid, expired, or revoked.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `403`

The access token lacks the required scope, or the project is disabled.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `404`

Error response.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `409`

A concurrent request holds the idempotency lease (`idempotency_conflict`). Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `422`

The `Idempotency-Key` was previously used with a different request body (`idempotency_key_reused`), or the request body failed validation.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `429`

Too many requests. Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Code samples

```bash
curl -X PATCH "https://api.carebit.co/v1/patients/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c/payors/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "insurance_authorization_code": "AUTH123"
}'
```

```javascript
const response = await fetch("https://api.carebit.co/v1/patients/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c/payors/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
  "insurance_authorization_code": "AUTH123"
}),
});

if (!response.ok) {
  throw new Error(`Carebit API error: ${response.status}`);
}

const data = await response.json();
```

```python
import os
import requests
import uuid

response = requests.patch(
    "https://api.carebit.co/v1/patients/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c/payors/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "insurance_authorization_code": "AUTH123"
    }
)
response.raise_for_status()
data = response.json()
```

```ruby
require "httparty"
require "json"
require "securerandom"

response = HTTParty.patch(
  "https://api.carebit.co/v1/patients/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c/payors/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}",
    "Idempotency-Key" => SecureRandom.uuid,
    "Content-Type" => "application/json"
  },
  body: {
    "insurance_authorization_code" => "AUTH123"
  }.to_json
)
raise "Carebit API error: #{response.code}" unless response.success?
data = response.parsed_response
```

```php
<?php

$client = new GuzzleHttp\Client();

$response = $client->patch("https://api.carebit.co/v1/patients/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c/payors/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c", [
    "headers" => [
      "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
      "Idempotency-Key" => bin2hex(random_bytes(16)),
    ],
    "json" => [
      "insurance_authorization_code" => "AUTH123"
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```


---

# List Payments

`GET /v1/payments`

Returns Payments in the authenticated Organization. Filter optionally by `patient_id` and by a `paid_at` window. Each Payment includes `invoice_id`, `patient_id`, and nested `refunds`.

**Required API scopes:** `payments.read`

## Parameters

- `patient_id` (query, `string`) - Filter by a Patient with an active connection to the Organization.
- `paid_at_from` (query, `string`) - Inclusive lower bound for `paid_at` in UTC ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ). Payments with a null `paid_at` are omitted when this filter is set.
- `paid_at_to` (query, `string`) - Inclusive upper bound for `paid_at` in UTC ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ). Payments with a null `paid_at` are omitted when this filter is set.
- `limit` (query, `integer`) - The maximum number of items to return. Defaults to `25`; the maximum is `100`.
- `starting_after` (query, `string`) - Return items after this resource ID. You cannot use this with `cursor`.
- `cursor` (query, `string`) - The `next_cursor` value from the previous page. You cannot use this with `starting_after`.

## Response `200`

Paginated list of `Payment` objects.

- `any`

### Example

```json
{
  "object": "list",
  "data": [
    {
      "id": "947c03a0-35f4-43b4-8df0-60c048915a10",
      "object": "payment",
      "amount": 25000,
      "created_at": "2026-01-01T09:00:00Z",
      "currency": "GBP",
      "internal_notes": "Asked about evening appointments with Dr Smith.",
      "invoice_id": "2fc3a636-66c0-4677-86be-032dd32125e1",
      "links": {
        "patient": "https://api.carebit.co/v1/patients/1a2b3c4d-5e6f-4789-8abc-def012345678"
      },
      "paid_at": "2026-01-01T09:00:00Z",
      "patient_id": "1a2b3c4d-5e6f-4789-8abc-def012345678",
      "payment_method_type": "bacs_debit",
      "payor_type": "insurance_company",
      "refunds": [
        {
          "id": "d3d1640d-4d73-43b4-81cb-c0dd11bb3a12",
          "object": "refund",
          "amount": 25000,
          "created_at": "2026-01-01T09:00:00Z",
          "currency": "GBP",
          "error": "The destination payment account declined the refund.",
          "invoice_id": "2fc3a636-66c0-4677-86be-032dd32125e1",
          "links": {
            "patient": "https://api.carebit.co/v1/patients/1a2b3c4d-5e6f-4789-8abc-def012345678"
          },
          "notes": "Please confirm the appointment by email.",
          "patient_id": "1a2b3c4d-5e6f-4789-8abc-def012345678",
          "payment_id": "947c03a0-35f4-43b4-8df0-60c048915a10",
          "reason": "other",
          "refund_source": "bank_account",
          "status": "canceled",
          "succeeded_at": "2026-01-01T09:00:00Z",
          "updated_at": "2026-01-01T09:00:00Z"
        }
      ],
      "status": "awaiting_authentication",
      "updated_at": "2026-01-01T09:00:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": "eyJzdGFydF90aW1lIjoiMjAyNi0wMS0wMVQwOTowMDowMFoifQ",
  "url": "/v1/payments"
}
```

## Response `400`

A time filter or pagination parameter is invalid.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `401`

The access token is missing, invalid, expired, or revoked.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `403`

The access token lacks the required scope, or the project is disabled.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `404`

The Patient was not found in the Organization.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `429`

Too many requests. Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Code samples

```bash
curl -X GET "https://api.carebit.co/v1/payments" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN"
```

```javascript
const response = await fetch("https://api.carebit.co/v1/payments", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
  },
});

if (!response.ok) {
  throw new Error(`Carebit API error: ${response.status}`);
}

const data = await response.json();
```

```python
import os
import requests

response = requests.get(
    "https://api.carebit.co/v1/payments",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
    }
)
response.raise_for_status()
data = response.json()
```

```ruby
require "httparty"

response = HTTParty.get(
  "https://api.carebit.co/v1/payments",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}"
  }
)
raise "Carebit API error: #{response.code}" unless response.success?
data = response.parsed_response
```

```php
<?php

$client = new GuzzleHttp\Client();

$response = $client->get("https://api.carebit.co/v1/payments", [
    "headers" => [
      "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```


---

# Get a remote file import batch

`GET /v1/remote_file_import_batches/:id`

Requires the write scope for the batch's resource type: `letters.create`, `test_results.create`, or `notes.create`. A request with the wrong scope returns `404` without revealing whether the batch exists.

## Parameters

- `id` (path, `string`) (required)

## Response `200`

The requested `RemoteFileImportBatch`.

- `object`
  - `completed_count` (`integer`) - The number of items that finished processing successfully.
  - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `failed_count` (`integer`) - The number of items that finished processing with an error.
  - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - `items` (`array`) - The import items in their original request order.
    - `items` (`object`)
      - `created_resource` (`string | null`) - format: `uri`; The URL of the resource created for a succeeded item. Null unless `status` is `succeeded`.
      - `created_resource_id` (`string | null`) - format: `uuid`; The identifier of the resource created for a succeeded item. Null unless `status` is `succeeded`.
      - `created_resource_type` (`string | null`) - enum: `null`, `Attachment`, `Letter`, `Note`, `TestResult`; The type of resource created for a succeeded item. Null unless `status` is `succeeded`.
      - `error` (`any`) - The failure details for this item. Null unless the item has failed.
      - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
      - `object` (`any`) - Always `remote_file_import_batch_item`.
      - `position` (`integer`) - The zero-based position of the item in the submitted batch.
      - `status` (`string`) - enum: `failed`, `pending`, `processing`, `succeeded`; The current download, validation, and malware-scanning status of the item.
  - `links` (`object`) - URLs to related resources.
    - `self` (`string`) - format: `uri`; The full URL of a related resource.
  - `object` (`any`) - Discriminator value emitted at `object`.
  - `resource_type` (`string`) - enum: `letter`, `note`, `test_result`; The type of resource created by every item in the batch.
  - `status` (`string`) - enum: `completed`, `pending`, `processing`; The current download, validation, and malware-scanning status of the batch.
  - `total_count` (`integer`) - The total number of items submitted in the batch.
  - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.

### Example

```json
{
  "id": "ebc38802-f219-4c7b-8136-8e963a0c69e0",
  "object": "remote_file_import_batch",
  "completed_count": 0,
  "created_at": "2026-01-01T09:00:00Z",
  "failed_count": 0,
  "items": [
    {
      "id": "57bed2bf-e2e1-463b-8a96-643e3817a8b8",
      "object": "remote_file_import_batch_item",
      "created_resource": "https://api.carebit.co/v1/letters/c3d4e5f6-0718-49ab-acde-f01234567890",
      "created_resource_id": "7e09a8e3-e3c1-4dee-863b-85d56e4329da",
      "created_resource_type": null,
      "error": null,
      "position": 0,
      "status": "failed"
    }
  ],
  "links": {
    "self": "https://api.carebit.co/v1/remote_file_import_batches/ebc38802-f219-4c7b-8136-8e963a0c69e0"
  },
  "resource_type": "letter",
  "status": "completed",
  "total_count": 1,
  "updated_at": "2026-01-01T09:00:00Z"
}
```

## Response `401`

The access token is missing, invalid, expired, or revoked.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `403`

The access token is disabled or the project cannot access this endpoint.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `404`

The batch does not exist for your Organization, or your access token lacks the write scope for the batch's resource type.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `429`

Too many requests.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Code samples

```bash
curl -X GET "https://api.carebit.co/v1/remote_file_import_batches/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN"
```

```javascript
const response = await fetch("https://api.carebit.co/v1/remote_file_import_batches/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
  },
});

if (!response.ok) {
  throw new Error(`Carebit API error: ${response.status}`);
}

const data = await response.json();
```

```python
import os
import requests

response = requests.get(
    "https://api.carebit.co/v1/remote_file_import_batches/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
    }
)
response.raise_for_status()
data = response.json()
```

```ruby
require "httparty"

response = HTTParty.get(
  "https://api.carebit.co/v1/remote_file_import_batches/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}"
  }
)
raise "Carebit API error: #{response.code}" unless response.success?
data = response.parsed_response
```

```php
<?php

$client = new GuzzleHttp\Client();

$response = $client->get("https://api.carebit.co/v1/remote_file_import_batches/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c", [
    "headers" => [
      "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```


---

# Create a report

`POST /v1/reports`

Queues an asynchronous report and returns an ExpirableFile. Poll that ExpirableFile or subscribe to `expirable_file.available`.

**Required API scopes:** `reports.create`

## Parameters

- `Idempotency-Key` (header, `string`) (required) - Client-generated idempotency key. Required for every POST/PATCH write. Replay of the same key with the same body returns the stored response with an `Idempotency-Replayed: true` header. Same key + different body returns `422 idempotency_key_reused`. A duplicate that arrives while the first request is still in flight returns `409 idempotency_conflict` with `Retry-After: 1`.

## Request body (`application/json`)

- `object`
  - `age_range` (`string | null`) - enum: `under_18`, `over_18`, `null`; The optional Patient age range used by supported reports.
  - `clinician_id` (`string | null`) - format: `uuid`; The optional Clinician used to restrict supported reports.
  - `end_time` (`string`) - format: `date-time`; The inclusive end of the reporting period.
  - `report_type` (`string`) - enum: `account_balances`, `audio_recordings`, `billing_codes`, `booked_services`, `bookings`, `bookings_summary_for_child_organizations`, `bookings_with_invoices`, `bookings_without_invoices`, `care_episodes`, `cari_credits_usage`, `credit_notes`, `creditors`, `debtors`, `debtors_per_invoice`, `end_of_year_accounts_zip`, `expenses`, `financial_summary`, `indemnity_bookings`, `indemnity_income`, `invoice_line_items`, `issued_invoices`, `issued_invoices_summary_for_child_organizations`, `leads_and_enquiries`, `patient_referrals`, `patient_registrations`, `prescriptions_report`, `product_sales_audit_log`, `product_sales_report`, `product_stock_levels_report`, `profit_and_loss`, `recall_bookings`, `received_payments`, `received_payments_for_invoice_line_items`, `received_payments_summary_for_child_organizations`, `referral_summary`, `refunds`, `remittance_adjustments`, `service_variants`, `tasks_due_per_staff_member`, `tasks_raised`; The type of report to create.
  - `start_time` (`string`) - format: `date-time`; The inclusive start of the reporting period.
  - `time_range_query_column` (`string | null`) - enum: `bookings.created_at`, `bookings.start_time`, `expenses.created_at`, `expenses.paid_at`, `invoices.created_at`, `invoices.supply_date`, `null`; The optional date field used by supported Booking, Expense, and Invoice reports.

### Example

```json
{
  "clinician_id": "00000000-0000-4000-8000-000000000002",
  "end_time": "2026-01-31T23:59:59Z",
  "report_type": "bookings",
  "start_time": "2026-01-01T00:00:00Z"
}
```

## Response `202`

The report was accepted for processing.

- `object`
  - `attachment_url` (`string | null`) - format: `uri`; The temporary signed download URL, or null while Carebit generates the file and download URL.
  - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `expires_at` (`string`) - format: `date-time`; The time after which Carebit can delete the file.
  - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - `object` (`any`) - Discriminator value emitted at `object`.
  - `status` (`string`) - enum: `processing`, `succeeded`; Whether Carebit is still creating the report or the file is ready to download.
  - `title` (`string`) - enum: `account_balances`, `audio_recordings`, `billing_codes`, `booked_services`, `bookings`, `bookings_summary_for_child_organizations`, `bookings_with_invoices`, `bookings_without_invoices`, `care_episodes`, `cari_credits_usage`, `credit_notes`, `creditors`, `debtors`, `debtors_per_invoice`, `end_of_year_accounts_zip`, `expenses`, `financial_summary`, `indemnity_bookings`, `indemnity_income`, `invoice_line_items`, `issued_invoices`, `issued_invoices_summary_for_child_organizations`, `leads_and_enquiries`, `patient_referrals`, `patient_registrations`, `prescriptions_report`, `product_sales_audit_log`, `product_sales_report`, `product_stock_levels_report`, `profit_and_loss`, `recall_bookings`, `received_payments`, `received_payments_for_invoice_line_items`, `received_payments_summary_for_child_organizations`, `referral_summary`, `refunds`, `remittance_adjustments`, `service_variants`, `tasks_due_per_staff_member`, `tasks_raised`; The report type used as the title of the ExpirableFile.
  - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.

### Example

```json
{
  "id": "08bbb801-b197-40de-8865-f2d3086221f2",
  "object": "expirable_file",
  "attachment_url": "https://files.example.invalid/document.pdf?signature=test",
  "created_at": "2026-01-01T09:00:00Z",
  "expires_at": "2026-01-01T09:00:00Z",
  "status": "processing",
  "title": "account_balances",
  "updated_at": "2026-01-01T09:00:00Z"
}
```

## Response `400`

A required parameter is missing or invalid.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `401`

The access token is missing, invalid, expired, or revoked.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `403`

The access token lacks the required scope, or the project is disabled.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `404`

The supplied Clinician was not found in the authenticated Organization.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `409`

A concurrent request holds the idempotency lease (`idempotency_conflict`). Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `422`

The `Idempotency-Key` was previously used with a different request body (`idempotency_key_reused`), or the request body failed validation.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `429`

Too many requests. Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Code samples

```bash
curl -X POST "https://api.carebit.co/v1/reports" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "clinician_id": "00000000-0000-4000-8000-000000000002",
  "end_time": "2026-01-31T23:59:59Z",
  "report_type": "bookings",
  "start_time": "2026-01-01T00:00:00Z"
}'
```

```javascript
const response = await fetch("https://api.carebit.co/v1/reports", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
  "clinician_id": "00000000-0000-4000-8000-000000000002",
  "end_time": "2026-01-31T23:59:59Z",
  "report_type": "bookings",
  "start_time": "2026-01-01T00:00:00Z"
}),
});

if (!response.ok) {
  throw new Error(`Carebit API error: ${response.status}`);
}

const data = await response.json();
```

```python
import os
import requests
import uuid

response = requests.post(
    "https://api.carebit.co/v1/reports",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "clinician_id": "00000000-0000-4000-8000-000000000002",
        "end_time": "2026-01-31T23:59:59Z",
        "report_type": "bookings",
        "start_time": "2026-01-01T00:00:00Z"
    }
)
response.raise_for_status()
data = response.json()
```

```ruby
require "httparty"
require "json"
require "securerandom"

response = HTTParty.post(
  "https://api.carebit.co/v1/reports",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}",
    "Idempotency-Key" => SecureRandom.uuid,
    "Content-Type" => "application/json"
  },
  body: {
    "clinician_id" => "00000000-0000-4000-8000-000000000002",
    "end_time" => "2026-01-31T23:59:59Z",
    "report_type" => "bookings",
    "start_time" => "2026-01-01T00:00:00Z"
  }.to_json
)
raise "Carebit API error: #{response.code}" unless response.success?
data = response.parsed_response
```

```php
<?php

$client = new GuzzleHttp\Client();

$response = $client->post("https://api.carebit.co/v1/reports", [
    "headers" => [
      "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
      "Idempotency-Key" => bin2hex(random_bytes(16)),
    ],
    "json" => [
      "clinician_id" => "00000000-0000-4000-8000-000000000002",
      "end_time" => "2026-01-31T23:59:59Z",
      "report_type" => "bookings",
      "start_time" => "2026-01-01T00:00:00Z"
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```


---

# List the Organization's Services

`GET /v1/services`

**Required API scopes:** `services.read`

## Parameters

- `is_bookable_online` (query, `boolean`) - Only return Services that patients can book online.
- `limit` (query, `integer`) - The maximum number of items to return. Defaults to `25`; the maximum is `100`.
- `starting_after` (query, `string`) - Return items after this resource ID. You cannot use this with `cursor`.
- `cursor` (query, `string`) - The `next_cursor` value from the previous page. You cannot use this with `starting_after`.

## Response `200`

Paginated list of `Service` objects.

- `any`

### Example

```json
{
  "object": "list",
  "data": [
    {
      "id": "5e6f7081-92a3-4bcd-8ef0-123456789abc",
      "object": "service",
      "created_at": "2026-01-01T09:00:00Z",
      "description": "An initial consultation at the Harley Street Clinic.",
      "duration_minutes": 30,
      "is_bookable_online": true,
      "name": "Initial consultation",
      "service_variants": [
        {
          "id": "6f708192-a3b4-4cde-9f01-23456789abcd",
          "clinician_id": "2b3c4d5e-6f70-489a-9bcd-ef0123456789",
          "currency": "GBP",
          "description": "An initial consultation at the Harley Street Clinic.",
          "links": {
            "clinician": "https://api.carebit.co/v1/clinicians/2b3c4d5e-6f70-489a-9bcd-ef0123456789",
            "location": "https://api.carebit.co/v1/locations/3c4d5e6f-7081-49ab-acde-f0123456789a"
          },
          "location_id": "3c4d5e6f-7081-49ab-acde-f0123456789a",
          "net_price": 1,
          "permits_remote_bookings": true
        }
      ],
      "tax_rate": {
        "id": "211b60c7-ec1b-41b4-8a29-e855209bc694",
        "description": "An initial consultation at the Harley Street Clinic.",
        "percentage": 20,
        "title": "VAT"
      },
      "updated_at": "2026-01-01T09:00:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": "eyJzdGFydF90aW1lIjoiMjAyNi0wMS0wMVQwOTowMDowMFoifQ",
  "url": "/v1/services"
}
```

## Response `400`

A filter or pagination parameter is invalid.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `401`

The access token is missing, invalid, expired, or revoked.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `403`

The access token lacks the required scope, or the project is disabled.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `429`

Too many requests. Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Code samples

```bash
curl -X GET "https://api.carebit.co/v1/services" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN"
```

```javascript
const response = await fetch("https://api.carebit.co/v1/services", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
  },
});

if (!response.ok) {
  throw new Error(`Carebit API error: ${response.status}`);
}

const data = await response.json();
```

```python
import os
import requests

response = requests.get(
    "https://api.carebit.co/v1/services",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
    }
)
response.raise_for_status()
data = response.json()
```

```ruby
require "httparty"

response = HTTParty.get(
  "https://api.carebit.co/v1/services",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}"
  }
)
raise "Carebit API error: #{response.code}" unless response.success?
data = response.parsed_response
```

```php
<?php

$client = new GuzzleHttp\Client();

$response = $client->get("https://api.carebit.co/v1/services", [
    "headers" => [
      "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```


---

# Get a Service

`GET /v1/services/:id`

**Required API scopes:** `services.read`

## Parameters

- `id` (path, `string`) (required)

## Response `200`

The requested `Service`.

- `object`
  - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `description` (`string | null`) - The description of the service shown to staff members and patients.
  - `duration_minutes` (`integer | null`) - The scheduled duration of the service, in minutes.
  - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - `is_bookable_online` (`boolean`) - Whether patients can book this service online in the Patient Portal.
  - `name` (`string`) - The display name of the service.
  - `object` (`any`) - Discriminator value emitted at `object`.
  - `service_variants` (`array`) - The bookable variants of this service.
    - `items` (`object`)
      - `clinician_id` (`string | null`) - format: `uuid`; The identifier of the clinician assigned to this service variant, when the variant is clinician-specific.
      - `currency` (`string | null`) - The ISO 4217 currency code used for this service variant. Must be one of `chf`, `eur`, `gbp`, or `usd`.
      - `description` (`string | null`) - The description of this service variant.
      - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
      - `links` (`object`) - URLs to related resources.
        - `clinician` (`string | null`) - format: `uri`; The full URL of a related resource.
        - `location` (`string | null`) - format: `uri`; The full URL of a related resource.
      - `location_id` (`string | null`) - format: `uuid`; The identifier of the location assigned to this service variant, when the variant is location-specific.
      - `net_price` (`integer | null`) - The net price of this service variant, before tax, in the currency's minor units.
      - `permits_remote_bookings` (`boolean`) - Whether this service variant can be used for remote bookings.
  - `tax_rate` (`any`) - The tax rate applied to this service. Null when no tax rate is set.
  - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.

### Example

```json
{
  "id": "5e6f7081-92a3-4bcd-8ef0-123456789abc",
  "object": "service",
  "created_at": "2026-01-01T09:00:00Z",
  "description": "An initial consultation at the Harley Street Clinic.",
  "duration_minutes": 30,
  "is_bookable_online": true,
  "name": "Initial consultation",
  "service_variants": [
    {
      "id": "6f708192-a3b4-4cde-9f01-23456789abcd",
      "clinician_id": "2b3c4d5e-6f70-489a-9bcd-ef0123456789",
      "currency": "GBP",
      "description": "An initial consultation at the Harley Street Clinic.",
      "links": {
        "clinician": "https://api.carebit.co/v1/clinicians/2b3c4d5e-6f70-489a-9bcd-ef0123456789",
        "location": "https://api.carebit.co/v1/locations/3c4d5e6f-7081-49ab-acde-f0123456789a"
      },
      "location_id": "3c4d5e6f-7081-49ab-acde-f0123456789a",
      "net_price": 1,
      "permits_remote_bookings": true
    }
  ],
  "tax_rate": {
    "id": "211b60c7-ec1b-41b4-8a29-e855209bc694",
    "description": "An initial consultation at the Harley Street Clinic.",
    "percentage": 20,
    "title": "VAT"
  },
  "updated_at": "2026-01-01T09:00:00Z"
}
```

## Response `401`

The access token is missing, invalid, expired, or revoked.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `403`

The access token lacks the required scope, or the project is disabled.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `404`

Error response.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `429`

Too many requests. Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Code samples

```bash
curl -X GET "https://api.carebit.co/v1/services/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN"
```

```javascript
const response = await fetch("https://api.carebit.co/v1/services/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
  },
});

if (!response.ok) {
  throw new Error(`Carebit API error: ${response.status}`);
}

const data = await response.json();
```

```python
import os
import requests

response = requests.get(
    "https://api.carebit.co/v1/services/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
    }
)
response.raise_for_status()
data = response.json()
```

```ruby
require "httparty"

response = HTTParty.get(
  "https://api.carebit.co/v1/services/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}"
  }
)
raise "Carebit API error: #{response.code}" unless response.success?
data = response.parsed_response
```

```php
<?php

$client = new GuzzleHttp\Client();

$response = $client->get("https://api.carebit.co/v1/services/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c", [
    "headers" => [
      "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```


---

# List the Organization's StaffMembers

`GET /v1/staff_members`

Returns confirmed StaffMembers who have an enabled access profile for the authenticated Organization. Results are ordered by first name, then last name. Use these identifiers as HumanTask `assignees`.

**Required API scopes:** `staff_members.read`

## Parameters

- `first_name` (query, `string`) - Filter by an exact first name, case-insensitively.
- `last_name` (query, `string`) - Filter by an exact last name, case-insensitively.
- `limit` (query, `integer`) - The maximum number of items to return. Defaults to `25`; the maximum is `100`.
- `starting_after` (query, `string`) - Return items after this resource ID. You cannot use this with `cursor`.
- `cursor` (query, `string`) - The `next_cursor` value from the previous page. You cannot use this with `starting_after`.

## Response `200`

Paginated list of `StaffMember` objects.

- `any`

### Example

```json
{
  "object": "list",
  "data": [
    {
      "id": "af02fa53-0af3-48ab-83b5-82488923e84f",
      "object": "staff_member",
      "created_at": "2026-01-01T09:00:00Z",
      "email": "alex.morgan@example.com",
      "first_name": "Alex",
      "last_name": "Morgan",
      "links": {
        "self": "https://api.carebit.co/v1/staff_members/af02fa53-0af3-48ab-83b5-82488923e84f"
      },
      "name": "Initial consultation",
      "title": "Dr",
      "updated_at": "2026-01-01T09:00:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": "eyJzdGFydF90aW1lIjoiMjAyNi0wMS0wMVQwOTowMDowMFoifQ",
  "url": "/v1/staff_members"
}
```

## Response `400`

A pagination parameter is invalid.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `401`

The access token is missing, invalid, expired, or revoked.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `403`

The access token lacks the required scope, or the project is disabled.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `429`

Too many requests. Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Code samples

```bash
curl -X GET "https://api.carebit.co/v1/staff_members?first_name=John&last_name=Smith" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN"
```

```javascript
const response = await fetch("https://api.carebit.co/v1/staff_members?first_name=John&last_name=Smith", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
  },
});

if (!response.ok) {
  throw new Error(`Carebit API error: ${response.status}`);
}

const data = await response.json();
```

```python
import os
import requests

response = requests.get(
    "https://api.carebit.co/v1/staff_members?first_name=John&last_name=Smith",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
    }
)
response.raise_for_status()
data = response.json()
```

```ruby
require "httparty"

response = HTTParty.get(
  "https://api.carebit.co/v1/staff_members?first_name=John&last_name=Smith",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}"
  }
)
raise "Carebit API error: #{response.code}" unless response.success?
data = response.parsed_response
```

```php
<?php

$client = new GuzzleHttp\Client();

$response = $client->get("https://api.carebit.co/v1/staff_members?first_name=John&last_name=Smith", [
    "headers" => [
      "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```


---

# Get a StaffMember

`GET /v1/staff_members/:id`

Returns one confirmed StaffMember who has an enabled access profile for the authenticated Organization.

**Required API scopes:** `staff_members.read`

## Parameters

- `id` (path, `string`) (required)

## Response `200`

The requested `StaffMember`.

- `object`
  - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `email` (`string`) - format: `email`; The sign-in email address of the staff member.
  - `first_name` (`string`) - The first name of the staff member.
  - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - `last_name` (`string`) - The last name of the staff member.
  - `links` (`object`) - URLs to related resources.
    - `self` (`string`) - format: `uri`; URL to retrieve this StaffMember.
  - `name` (`string`) - The display name of the staff member, including title.
  - `object` (`any`) - Discriminator value emitted at `object`.
  - `title` (`string`) - The professional or personal title of the staff member, such as `Dr`.
  - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.

### Example

```json
{
  "id": "af02fa53-0af3-48ab-83b5-82488923e84f",
  "object": "staff_member",
  "created_at": "2026-01-01T09:00:00Z",
  "email": "alex.morgan@example.com",
  "first_name": "Alex",
  "last_name": "Morgan",
  "links": {
    "self": "https://api.carebit.co/v1/staff_members/af02fa53-0af3-48ab-83b5-82488923e84f"
  },
  "name": "Initial consultation",
  "title": "Dr",
  "updated_at": "2026-01-01T09:00:00Z"
}
```

## Response `401`

The access token is missing, invalid, expired, or revoked.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `403`

The access token lacks the required scope, or the project is disabled.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `404`

Error response.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `429`

Too many requests. Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Code samples

```bash
curl -X GET "https://api.carebit.co/v1/staff_members/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN"
```

```javascript
const response = await fetch("https://api.carebit.co/v1/staff_members/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
  },
});

if (!response.ok) {
  throw new Error(`Carebit API error: ${response.status}`);
}

const data = await response.json();
```

```python
import os
import requests

response = requests.get(
    "https://api.carebit.co/v1/staff_members/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
    }
)
response.raise_for_status()
data = response.json()
```

```ruby
require "httparty"

response = HTTParty.get(
  "https://api.carebit.co/v1/staff_members/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}"
  }
)
raise "Carebit API error: #{response.code}" unless response.success?
data = response.parsed_response
```

```php
<?php

$client = new GuzzleHttp\Client();

$response = $client->get("https://api.carebit.co/v1/staff_members/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c", [
    "headers" => [
      "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```


---

# Create up to 100 Test Results in one request

`POST /v1/test_result_batches`

Returns `201` when every TestResult is created immediately. Returns `202` when at least one item includes `file_url` or `file_base64`; poll `remote_file_import_batch` for each file's import status. Both responses use `TestResultBatchResponse`.

**Required API scopes:** `test_results.create`

## Parameters

- `Idempotency-Key` (header, `string`) (required) - Client-generated idempotency key. Required for every POST/PATCH write. Replay of the same key with the same body returns the stored response with an `Idempotency-Replayed: true` header. Same key + different body returns `422 idempotency_key_reused`. A duplicate that arrives while the first request is still in flight returns `409 idempotency_conflict` with `Retry-After: 1`.

## Request body (`application/json`)

- `object`
  - `items` (`array`) - The test results to create. Items are processed in their submitted order.
    - `items` (`object`)
      - `automatically_create_resource_permission_for_patient` (`boolean`) - Whether Carebit should automatically share the test result with the patient after processing.
      - `booking_id` (`string | null`) - format: `uuid`; The identifier of the booking associated with the test result, or null when it is not linked to a booking.
      - `clinician_id` (`string | null`) - format: `uuid`; The identifier of the clinician associated with the test result, or null when none is assigned.
      - `description` (`string | null`) - A description of the TestResult.
      - `file_base64` (`string | null`) - format: `byte`; The test result bytes encoded as Base64. Provide this with `filename` instead of `file_url`. The decoded file can be at most 7 MB.
      - `file_url` (`string | null`) - format: `uri`; The public HTTPS URL of a test result document that Carebit should download.
      - `filename` (`string | null`) - The filename to use for the test result. Required with `file_base64`; defaults to the remote file's filename for URL sources.
      - `notify_patient_of_resource_permission` (`boolean`) - Whether Carebit should notify the patient when the test result is shared with them.
      - `patient_id` (`string`) - format: `uuid`; The identifier of the patient that the test result belongs to.
      - `status` (`string`) - enum: `awaiting_review`, `complete`, `draft`, `reviewed`; The workflow status to assign to the test result.
      - `test_result_items` (`array`) - The structured clinical observations to include in the test result.
        - `items` (`object`)
          - `is_abnormal` (`boolean | null`) - Whether the observation falls outside its reference range, when known.
          - `notes` (`string | null`) - Additional clinical notes about the observation.
          - `observation_code` (`string | null`) - The laboratory or clinical code that identifies the observation.
          - `observation_name` (`string | null`) - The observation's display name.
          - `observation_text` (`string | null`) - The textual observation value, when the result is not represented numerically.
          - `observation_value` (`number | null`) - The numeric value of the observation, when applicable.
          - `observation_value_precision` (`string | null`) - enum: `<`, `=`, `>`, `null`; The qualifier that indicates whether `observation_value` is exact or a boundary.
          - `observation_value_units` (`string | null`) - The unit used for `observation_value`.
          - `observed_at` (`string | null`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
          - `reference_range_lower_bound` (`number | null`) - The lower bound of the expected reference range, when supplied.
          - `reference_range_upper_bound` (`number | null`) - The upper bound of the expected reference range, when supplied.
          - `status` (`string | null`) - enum: `corrected`, `final`, `pending`, `null`; The clinical workflow status to assign to the observation.
      - `title` (`string`) - The display title of the test result.

### Example

```json
{
  "items": [
    {
      "automatically_create_resource_permission_for_patient": true,
      "notify_patient_of_resource_permission": true,
      "patient_id": "00000000-0000-4000-8000-000000000004",
      "status": "complete",
      "test_result_items": [
        {
          "observation_name": "Haemoglobin",
          "observation_value": 14.5,
          "observation_value_units": "g/dL",
          "status": "final"
        }
      ],
      "title": "Full blood count"
    }
  ]
}
```

## Response `201`

Every TestResult was created immediately.

- `object` - The response from `POST /v1/test_result_batches`. `remote_file_import_batch` is null when every TestResult was created immediately (`201`). It contains the import batch when at least one item includes `file_url` or `file_base64` (`202`).
  - `items` (`array`) - The per-item outcomes in their original request order.
    - `items` (`object`) - The result of one item in a Test Result batch. `test_result` contains the created TestResult when processing finishes immediately. For an imported file, it is null and `remote_file_import_batch_item_id` identifies the item being processed.
      - `object` (`any`) - Always `test_result_batch_item`.
      - `position` (`integer`) - The zero-based position of the item in the request `items` array.
      - `remote_file_import_batch_item_id` (`string | null`) - format: `uuid`; The import item identifier for a file that is still being processed. Null when the TestResult was created immediately. Poll the parent `remote_file_import_batch` for status.
      - `status` (`string`) - enum: `failed`, `pending`, `processing`, `succeeded`; The item's processing status. `succeeded` when the TestResult was created immediately; otherwise the current file import status.
      - `test_result` (`any`) - The created TestResult, or null while an imported file is being processed.
  - `object` (`any`) - Always `test_result_batch`.
  - `remote_file_import_batch` (`any`) - The file import batch to poll, or null when every TestResult was created immediately.

### Example

```json
{
  "object": "test_result_batch",
  "items": [
    {
      "object": "test_result_batch_item",
      "position": 0,
      "remote_file_import_batch_item_id": "57bed2bf-e2e1-463b-8a96-643e3817a8b8",
      "status": "failed",
      "test_result": {
        "id": "9d4a13e1-0eea-4669-88c4-03316c092c77",
        "object": "test_result",
        "automatically_create_resource_permission_for_patient": true,
        "created_at": "2026-01-01T09:00:00Z",
        "download_url": "https://files.example.invalid/document.pdf?signature=test",
        "filename": "referral-letter.pdf",
        "links": {
          "booking": "https://api.carebit.co/v1/bookings/92a3b4c5-d6e7-4f01-8234-56789abcdef0",
          "clinician": "https://api.carebit.co/v1/clinicians/2b3c4d5e-6f70-489a-9bcd-ef0123456789",
          "patient": "https://api.carebit.co/v1/patients/1a2b3c4d-5e6f-4789-8abc-def012345678",
          "remote_file_import_batch": "https://api.carebit.co/v1/remote_file_import_batches/ebc38802-f219-4c7b-8136-8e963a0c69e0"
        },
        "notify_patient_of_resource_permission": true,
        "remote_file_import_batch_id": "ebc38802-f219-4c7b-8136-8e963a0c69e0",
        "status": "awaiting_proofreading",
        "test_result_items": [
          {
            "id": "7592f451-4733-44f1-8560-1bb6075fa552",
            "object": "test_result_item",
            "created_at": "2026-01-01T09:00:00Z",
            "is_abnormal": false,
            "notes": "Please confirm the appointment by email.",
            "observation_code": "718-7",
            "observation_name": "Haemoglobin",
            "observation_text": "Within the expected range",
            "observation_value": 14.5,
            "observation_value_precision": "<",
            "observation_value_units": "g/dL",
            "observed_at": "2026-01-01T09:00:00Z",
            "reference_range_lower_bound": 12,
            "reference_range_upper_bound": 16,
            "status": "corrected",
            "updated_at": "2026-01-01T09:00:00Z"
          }
        ],
        "title": "Dr",
        "updated_at": "2026-01-01T09:00:00Z"
      }
    }
  ],
  "remote_file_import_batch": {
    "id": "ebc38802-f219-4c7b-8136-8e963a0c69e0",
    "object": "remote_file_import_batch",
    "completed_count": 0,
    "created_at": "2026-01-01T09:00:00Z",
    "failed_count": 0,
    "items": [
      {
        "id": "57bed2bf-e2e1-463b-8a96-643e3817a8b8",
        "object": "remote_file_import_batch_item",
        "created_resource": "https://api.carebit.co/v1/letters/c3d4e5f6-0718-49ab-acde-f01234567890",
        "created_resource_id": "7e09a8e3-e3c1-4dee-863b-85d56e4329da",
        "created_resource_type": null,
        "error": null,
        "position": 0,
        "status": "failed"
      }
    ],
    "links": {
      "self": "https://api.carebit.co/v1/remote_file_import_batches/ebc38802-f219-4c7b-8136-8e963a0c69e0"
    },
    "resource_type": "letter",
    "status": "completed",
    "total_count": 1,
    "updated_at": "2026-01-01T09:00:00Z"
  }
}
```

## Response `202`

At least one file is being imported. Poll `remote_file_import_batch` for each item's status.

- `object` - The response from `POST /v1/test_result_batches`. `remote_file_import_batch` is null when every TestResult was created immediately (`201`). It contains the import batch when at least one item includes `file_url` or `file_base64` (`202`).
  - `items` (`array`) - The per-item outcomes in their original request order.
    - `items` (`object`) - The result of one item in a Test Result batch. `test_result` contains the created TestResult when processing finishes immediately. For an imported file, it is null and `remote_file_import_batch_item_id` identifies the item being processed.
      - `object` (`any`) - Always `test_result_batch_item`.
      - `position` (`integer`) - The zero-based position of the item in the request `items` array.
      - `remote_file_import_batch_item_id` (`string | null`) - format: `uuid`; The import item identifier for a file that is still being processed. Null when the TestResult was created immediately. Poll the parent `remote_file_import_batch` for status.
      - `status` (`string`) - enum: `failed`, `pending`, `processing`, `succeeded`; The item's processing status. `succeeded` when the TestResult was created immediately; otherwise the current file import status.
      - `test_result` (`any`) - The created TestResult, or null while an imported file is being processed.
  - `object` (`any`) - Always `test_result_batch`.
  - `remote_file_import_batch` (`any`) - The file import batch to poll, or null when every TestResult was created immediately.

### Example

```json
{
  "object": "test_result_batch",
  "items": [
    {
      "object": "test_result_batch_item",
      "position": 0,
      "remote_file_import_batch_item_id": "57bed2bf-e2e1-463b-8a96-643e3817a8b8",
      "status": "failed",
      "test_result": {
        "id": "9d4a13e1-0eea-4669-88c4-03316c092c77",
        "object": "test_result",
        "automatically_create_resource_permission_for_patient": true,
        "created_at": "2026-01-01T09:00:00Z",
        "download_url": "https://files.example.invalid/document.pdf?signature=test",
        "filename": "referral-letter.pdf",
        "links": {
          "booking": "https://api.carebit.co/v1/bookings/92a3b4c5-d6e7-4f01-8234-56789abcdef0",
          "clinician": "https://api.carebit.co/v1/clinicians/2b3c4d5e-6f70-489a-9bcd-ef0123456789",
          "patient": "https://api.carebit.co/v1/patients/1a2b3c4d-5e6f-4789-8abc-def012345678",
          "remote_file_import_batch": "https://api.carebit.co/v1/remote_file_import_batches/ebc38802-f219-4c7b-8136-8e963a0c69e0"
        },
        "notify_patient_of_resource_permission": true,
        "remote_file_import_batch_id": "ebc38802-f219-4c7b-8136-8e963a0c69e0",
        "status": "awaiting_proofreading",
        "test_result_items": [
          {
            "id": "7592f451-4733-44f1-8560-1bb6075fa552",
            "object": "test_result_item",
            "created_at": "2026-01-01T09:00:00Z",
            "is_abnormal": false,
            "notes": "Please confirm the appointment by email.",
            "observation_code": "718-7",
            "observation_name": "Haemoglobin",
            "observation_text": "Within the expected range",
            "observation_value": 14.5,
            "observation_value_precision": "<",
            "observation_value_units": "g/dL",
            "observed_at": "2026-01-01T09:00:00Z",
            "reference_range_lower_bound": 12,
            "reference_range_upper_bound": 16,
            "status": "corrected",
            "updated_at": "2026-01-01T09:00:00Z"
          }
        ],
        "title": "Dr",
        "updated_at": "2026-01-01T09:00:00Z"
      }
    }
  ],
  "remote_file_import_batch": {
    "id": "ebc38802-f219-4c7b-8136-8e963a0c69e0",
    "object": "remote_file_import_batch",
    "completed_count": 0,
    "created_at": "2026-01-01T09:00:00Z",
    "failed_count": 0,
    "items": [
      {
        "id": "57bed2bf-e2e1-463b-8a96-643e3817a8b8",
        "object": "remote_file_import_batch_item",
        "created_resource": "https://api.carebit.co/v1/letters/c3d4e5f6-0718-49ab-acde-f01234567890",
        "created_resource_id": "7e09a8e3-e3c1-4dee-863b-85d56e4329da",
        "created_resource_type": null,
        "error": null,
        "position": 0,
        "status": "failed"
      }
    ],
    "links": {
      "self": "https://api.carebit.co/v1/remote_file_import_batches/ebc38802-f219-4c7b-8136-8e963a0c69e0"
    },
    "resource_type": "letter",
    "status": "completed",
    "total_count": 1,
    "updated_at": "2026-01-01T09:00:00Z"
  }
}
```

## Response `400`

The `Idempotency-Key` header is missing (`idempotency_key_required`) or exceeds 255 characters (`idempotency_key_too_long`).

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `401`

The access token is missing, invalid, expired, or revoked.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `403`

The access token lacks the required scope, or the project is disabled.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `404`

Error response.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `409`

A concurrent request holds the idempotency lease (`idempotency_conflict`). Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `422`

The `Idempotency-Key` was previously used with a different request body (`idempotency_key_reused`), or the request body failed validation.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `429`

Too many requests. Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Code samples

```bash
curl -X POST "https://api.carebit.co/v1/test_result_batches" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "items": [
    {
      "automatically_create_resource_permission_for_patient": true,
      "notify_patient_of_resource_permission": true,
      "patient_id": "00000000-0000-4000-8000-000000000004",
      "status": "complete",
      "test_result_items": [
        {
          "observation_name": "Haemoglobin",
          "observation_value": 14.5,
          "observation_value_units": "g/dL",
          "status": "final"
        }
      ],
      "title": "Full blood count"
    }
  ]
}'
```

```javascript
const response = await fetch("https://api.carebit.co/v1/test_result_batches", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
  "items": [
    {
      "automatically_create_resource_permission_for_patient": true,
      "notify_patient_of_resource_permission": true,
      "patient_id": "00000000-0000-4000-8000-000000000004",
      "status": "complete",
      "test_result_items": [
        {
          "observation_name": "Haemoglobin",
          "observation_value": 14.5,
          "observation_value_units": "g/dL",
          "status": "final"
        }
      ],
      "title": "Full blood count"
    }
  ]
}),
});

if (!response.ok) {
  throw new Error(`Carebit API error: ${response.status}`);
}

const data = await response.json();
```

```python
import os
import requests
import uuid

response = requests.post(
    "https://api.carebit.co/v1/test_result_batches",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "items": [
            {
                "automatically_create_resource_permission_for_patient": True,
                "notify_patient_of_resource_permission": True,
                "patient_id": "00000000-0000-4000-8000-000000000004",
                "status": "complete",
                "test_result_items": [
                    {
                        "observation_name": "Haemoglobin",
                        "observation_value": 14.5,
                        "observation_value_units": "g/dL",
                        "status": "final"
                    }
                ],
                "title": "Full blood count"
            }
        ]
    }
)
response.raise_for_status()
data = response.json()
```

```ruby
require "httparty"
require "json"
require "securerandom"

response = HTTParty.post(
  "https://api.carebit.co/v1/test_result_batches",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}",
    "Idempotency-Key" => SecureRandom.uuid,
    "Content-Type" => "application/json"
  },
  body: {
    "items" => [
      {
        "automatically_create_resource_permission_for_patient" => true,
        "notify_patient_of_resource_permission" => true,
        "patient_id" => "00000000-0000-4000-8000-000000000004",
        "status" => "complete",
        "test_result_items" => [
          {
            "observation_name" => "Haemoglobin",
            "observation_value" => 14.5,
            "observation_value_units" => "g/dL",
            "status" => "final"
          }
        ],
        "title" => "Full blood count"
      }
    ]
  }.to_json
)
raise "Carebit API error: #{response.code}" unless response.success?
data = response.parsed_response
```

```php
<?php

$client = new GuzzleHttp\Client();

$response = $client->post("https://api.carebit.co/v1/test_result_batches", [
    "headers" => [
      "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
      "Idempotency-Key" => bin2hex(random_bytes(16)),
    ],
    "json" => [
      "items" => [
        [
          "automatically_create_resource_permission_for_patient" => true,
          "notify_patient_of_resource_permission" => true,
          "patient_id" => "00000000-0000-4000-8000-000000000004",
          "status" => "complete",
          "test_result_items" => [
            [
              "observation_name" => "Haemoglobin",
              "observation_value" => 14.5,
              "observation_value_units" => "g/dL",
              "status" => "final"
            ]
          ],
          "title" => "Full blood count"
        ]
      ]
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```


---

# List Test Results

`GET /v1/test_results`

**Required API scopes:** `test_results.read`

## Parameters

- `patient_id` (query, `string`)
- `booking_id` (query, `string`)
- `status` (query, `string`)
- `created_since` (query, `string`)
- `limit` (query, `integer`) - The maximum number of items to return. Defaults to `25`; the maximum is `100`.
- `starting_after` (query, `string`) - Return items after this resource ID. You cannot use this with `cursor`.
- `cursor` (query, `string`) - The `next_cursor` value from the previous page. You cannot use this with `starting_after`.

## Response `200`

Paginated list of `TestResult` objects.

- `any`

### Example

```json
{
  "object": "list",
  "data": [
    {
      "id": "9d4a13e1-0eea-4669-88c4-03316c092c77",
      "object": "test_result",
      "automatically_create_resource_permission_for_patient": true,
      "created_at": "2026-01-01T09:00:00Z",
      "download_url": "https://files.example.invalid/document.pdf?signature=test",
      "filename": "referral-letter.pdf",
      "links": {
        "booking": "https://api.carebit.co/v1/bookings/92a3b4c5-d6e7-4f01-8234-56789abcdef0",
        "clinician": "https://api.carebit.co/v1/clinicians/2b3c4d5e-6f70-489a-9bcd-ef0123456789",
        "patient": "https://api.carebit.co/v1/patients/1a2b3c4d-5e6f-4789-8abc-def012345678",
        "remote_file_import_batch": "https://api.carebit.co/v1/remote_file_import_batches/ebc38802-f219-4c7b-8136-8e963a0c69e0"
      },
      "notify_patient_of_resource_permission": true,
      "remote_file_import_batch_id": "ebc38802-f219-4c7b-8136-8e963a0c69e0",
      "status": "awaiting_proofreading",
      "test_result_items": [
        {
          "id": "7592f451-4733-44f1-8560-1bb6075fa552",
          "object": "test_result_item",
          "created_at": "2026-01-01T09:00:00Z",
          "is_abnormal": false,
          "notes": "Please confirm the appointment by email.",
          "observation_code": "718-7",
          "observation_name": "Haemoglobin",
          "observation_text": "Within the expected range",
          "observation_value": 14.5,
          "observation_value_precision": "<",
          "observation_value_units": "g/dL",
          "observed_at": "2026-01-01T09:00:00Z",
          "reference_range_lower_bound": 12,
          "reference_range_upper_bound": 16,
          "status": "corrected",
          "updated_at": "2026-01-01T09:00:00Z"
        }
      ],
      "title": "Dr",
      "updated_at": "2026-01-01T09:00:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": "eyJzdGFydF90aW1lIjoiMjAyNi0wMS0wMVQwOTowMDowMFoifQ",
  "url": "/v1/test_results"
}
```

## Response `400`

A filter or pagination parameter is invalid.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `401`

The access token is missing, invalid, expired, or revoked.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `403`

The access token lacks the required scope, or the project is disabled.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `429`

Too many requests. Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Code samples

```bash
curl -X GET "https://api.carebit.co/v1/test_results" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN"
```

```javascript
const response = await fetch("https://api.carebit.co/v1/test_results", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
  },
});

if (!response.ok) {
  throw new Error(`Carebit API error: ${response.status}`);
}

const data = await response.json();
```

```python
import os
import requests

response = requests.get(
    "https://api.carebit.co/v1/test_results",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
    }
)
response.raise_for_status()
data = response.json()
```

```ruby
require "httparty"

response = HTTParty.get(
  "https://api.carebit.co/v1/test_results",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}"
  }
)
raise "Carebit API error: #{response.code}" unless response.success?
data = response.parsed_response
```

```php
<?php

$client = new GuzzleHttp\Client();

$response = $client->get("https://api.carebit.co/v1/test_results", [
    "headers" => [
      "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```


---

# Create a Test Result

`POST /v1/test_results`

Returns the created TestResult with status `201`. If you provide `file_url` or `file_base64`, the response also identifies a remote file import batch. Poll that batch for the file's import status.

**Required API scopes:** `test_results.create`

## Parameters

- `Idempotency-Key` (header, `string`) (required) - Client-generated idempotency key. Required for every POST/PATCH write. Replay of the same key with the same body returns the stored response with an `Idempotency-Replayed: true` header. Same key + different body returns `422 idempotency_key_reused`. A duplicate that arrives while the first request is still in flight returns `409 idempotency_conflict` with `Retry-After: 1`.

## Request body (`application/json`)

- `object`
  - `automatically_create_resource_permission_for_patient` (`boolean`) - Whether Carebit should automatically share the test result with the patient after processing.
  - `booking_id` (`string | null`) - format: `uuid`; The identifier of the booking associated with the test result, or null when it is not linked to a booking.
  - `clinician_id` (`string | null`) - format: `uuid`; The identifier of the clinician associated with the test result, or null when none is assigned.
  - `description` (`string | null`) - A description of the TestResult.
  - `file_base64` (`string | null`) - format: `byte`; The test result bytes encoded as Base64. Provide this with `filename` instead of `file_url`. The decoded file can be at most 7 MB.
  - `file_url` (`string | null`) - format: `uri`; The public HTTPS URL of a test result document that Carebit should download.
  - `filename` (`string | null`) - The filename to use for the test result. Required with `file_base64`; defaults to the remote file's filename for URL sources.
  - `notify_patient_of_resource_permission` (`boolean`) - Whether Carebit should notify the patient when the test result is shared with them.
  - `patient_id` (`string`) - format: `uuid`; The identifier of the patient that the test result belongs to.
  - `status` (`string`) - enum: `awaiting_review`, `complete`, `draft`, `reviewed`; The workflow status to assign to the test result.
  - `test_result_items` (`array`) - The structured clinical observations to include in the test result.
    - `items` (`object`)
      - `is_abnormal` (`boolean | null`) - Whether the observation falls outside its reference range, when known.
      - `notes` (`string | null`) - Additional clinical notes about the observation.
      - `observation_code` (`string | null`) - The laboratory or clinical code that identifies the observation.
      - `observation_name` (`string | null`) - The observation's display name.
      - `observation_text` (`string | null`) - The textual observation value, when the result is not represented numerically.
      - `observation_value` (`number | null`) - The numeric value of the observation, when applicable.
      - `observation_value_precision` (`string | null`) - enum: `<`, `=`, `>`, `null`; The qualifier that indicates whether `observation_value` is exact or a boundary.
      - `observation_value_units` (`string | null`) - The unit used for `observation_value`.
      - `observed_at` (`string | null`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
      - `reference_range_lower_bound` (`number | null`) - The lower bound of the expected reference range, when supplied.
      - `reference_range_upper_bound` (`number | null`) - The upper bound of the expected reference range, when supplied.
      - `status` (`string | null`) - enum: `corrected`, `final`, `pending`, `null`; The clinical workflow status to assign to the observation.
  - `title` (`string`) - The display title of the test result.

### Example

```json
{
  "automatically_create_resource_permission_for_patient": true,
  "notify_patient_of_resource_permission": true,
  "patient_id": "00000000-0000-4000-8000-000000000004",
  "status": "complete",
  "test_result_items": [
    {
      "is_abnormal": false,
      "observation_code": "718-7",
      "observation_name": "Haemoglobin",
      "observation_value": 14.5,
      "observation_value_units": "g/dL",
      "reference_range_lower_bound": 12,
      "reference_range_upper_bound": 16,
      "status": "final"
    }
  ],
  "title": "Full blood count"
}
```

## Response `201`

The requested `TestResult`.

- `object`
  - `automatically_create_resource_permission_for_patient` (`boolean`) - Whether Carebit automatically shares the test result with the patient after processing.
  - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `download_url` (`string | null`) - format: `uri`; The short-lived signed download URL for the TestResult. Null until the uploaded file passes malware scanning.
  - `filename` (`string | null`) - The original filename of the test result document, when one was supplied.
  - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - `links` (`object`) - URLs to related resources.
    - `booking` (`string | null`) - format: `uri`; The full URL of a related resource.
    - `clinician` (`string | null`) - format: `uri`; The full URL of a related resource.
    - `patient` (`string | null`) - format: `uri`; The full URL of a related resource.
    - `remote_file_import_batch` (`string`) - format: `uri`; The full URL of a related resource.
  - `notify_patient_of_resource_permission` (`boolean | null`) - Whether Carebit notifies the patient when the test result is shared with them.
  - `object` (`any`) - Discriminator value emitted at `object`.
  - `remote_file_import_batch_id` (`string`) - format: `uuid`; The identifier of the remote file import batch created for the uploaded file. Set on the create response when `file_url` or `file_base64` was submitted.
  - `status` (`string | null`) - enum: `awaiting_proofreading`, `awaiting_receipt`, `awaiting_review`, `awaiting_sending`, `awaiting_typing`, `complete`, `draft`, `reviewed`, `null`; The workflow status of the test result.
  - `test_result_items` (`array`) - The structured clinical observations included in the test result.
    - `items` (`object`)
      - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
      - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
      - `is_abnormal` (`boolean | null`) - Whether the observation falls outside its reference range, when known.
      - `notes` (`string | null`) - Additional clinical notes about the observation.
      - `object` (`any`) - Discriminator value emitted at `object`.
      - `observation_code` (`string | null`) - The laboratory or clinical code that identifies the observation.
      - `observation_name` (`string | null`) - The observation's display name.
      - `observation_text` (`string | null`) - The textual observation value, when the result is not represented numerically.
      - `observation_value` (`number | null`) - The numeric value of the observation, when applicable.
      - `observation_value_precision` (`string | null`) - enum: `<`, `=`, `>`, `null`; The precision qualifier for `observation_value`. `<` and `>` denote a bound, and `=` denotes an exact value.
      - `observation_value_units` (`string | null`) - The unit used for `observation_value`.
      - `observed_at` (`string | null`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
      - `reference_range_lower_bound` (`number | null`) - The lower bound of the expected reference range, when supplied.
      - `reference_range_upper_bound` (`number | null`) - The upper bound of the expected reference range, when supplied.
      - `status` (`string | null`) - enum: `corrected`, `final`, `pending`, `null`; The clinical workflow status of the observation.
      - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `title` (`string | null`) - The display title of the test result.
  - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.

### Example

```json
{
  "id": "9d4a13e1-0eea-4669-88c4-03316c092c77",
  "object": "test_result",
  "automatically_create_resource_permission_for_patient": true,
  "created_at": "2026-01-01T09:00:00Z",
  "download_url": "https://files.example.invalid/document.pdf?signature=test",
  "filename": "referral-letter.pdf",
  "links": {
    "booking": "https://api.carebit.co/v1/bookings/92a3b4c5-d6e7-4f01-8234-56789abcdef0",
    "clinician": "https://api.carebit.co/v1/clinicians/2b3c4d5e-6f70-489a-9bcd-ef0123456789",
    "patient": "https://api.carebit.co/v1/patients/1a2b3c4d-5e6f-4789-8abc-def012345678",
    "remote_file_import_batch": "https://api.carebit.co/v1/remote_file_import_batches/ebc38802-f219-4c7b-8136-8e963a0c69e0"
  },
  "notify_patient_of_resource_permission": true,
  "remote_file_import_batch_id": "ebc38802-f219-4c7b-8136-8e963a0c69e0",
  "status": "awaiting_proofreading",
  "test_result_items": [
    {
      "id": "7592f451-4733-44f1-8560-1bb6075fa552",
      "object": "test_result_item",
      "created_at": "2026-01-01T09:00:00Z",
      "is_abnormal": false,
      "notes": "Please confirm the appointment by email.",
      "observation_code": "718-7",
      "observation_name": "Haemoglobin",
      "observation_text": "Within the expected range",
      "observation_value": 14.5,
      "observation_value_precision": "<",
      "observation_value_units": "g/dL",
      "observed_at": "2026-01-01T09:00:00Z",
      "reference_range_lower_bound": 12,
      "reference_range_upper_bound": 16,
      "status": "corrected",
      "updated_at": "2026-01-01T09:00:00Z"
    }
  ],
  "title": "Dr",
  "updated_at": "2026-01-01T09:00:00Z"
}
```

## Response `400`

The request contains more test result items than the per-request limit permits.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `401`

The access token is missing, invalid, expired, or revoked.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `403`

The access token lacks the required scope, or the project is disabled.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `404`

Error response.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `409`

A concurrent request holds the idempotency lease (`idempotency_conflict`). Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `422`

The `Idempotency-Key` was previously used with a different request body (`idempotency_key_reused`), or the request body failed validation.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `429`

Too many requests. Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Code samples

```bash
curl -X POST "https://api.carebit.co/v1/test_results" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "automatically_create_resource_permission_for_patient": true,
  "notify_patient_of_resource_permission": true,
  "patient_id": "00000000-0000-4000-8000-000000000004",
  "status": "complete",
  "test_result_items": [
    {
      "is_abnormal": false,
      "observation_code": "718-7",
      "observation_name": "Haemoglobin",
      "observation_value": 14.5,
      "observation_value_units": "g/dL",
      "reference_range_lower_bound": 12,
      "reference_range_upper_bound": 16,
      "status": "final"
    }
  ],
  "title": "Full blood count"
}'
```

```javascript
const response = await fetch("https://api.carebit.co/v1/test_results", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
  "automatically_create_resource_permission_for_patient": true,
  "notify_patient_of_resource_permission": true,
  "patient_id": "00000000-0000-4000-8000-000000000004",
  "status": "complete",
  "test_result_items": [
    {
      "is_abnormal": false,
      "observation_code": "718-7",
      "observation_name": "Haemoglobin",
      "observation_value": 14.5,
      "observation_value_units": "g/dL",
      "reference_range_lower_bound": 12,
      "reference_range_upper_bound": 16,
      "status": "final"
    }
  ],
  "title": "Full blood count"
}),
});

if (!response.ok) {
  throw new Error(`Carebit API error: ${response.status}`);
}

const data = await response.json();
```

```python
import os
import requests
import uuid

response = requests.post(
    "https://api.carebit.co/v1/test_results",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "automatically_create_resource_permission_for_patient": True,
        "notify_patient_of_resource_permission": True,
        "patient_id": "00000000-0000-4000-8000-000000000004",
        "status": "complete",
        "test_result_items": [
            {
                "is_abnormal": False,
                "observation_code": "718-7",
                "observation_name": "Haemoglobin",
                "observation_value": 14.5,
                "observation_value_units": "g/dL",
                "reference_range_lower_bound": 12,
                "reference_range_upper_bound": 16,
                "status": "final"
            }
        ],
        "title": "Full blood count"
    }
)
response.raise_for_status()
data = response.json()
```

```ruby
require "httparty"
require "json"
require "securerandom"

response = HTTParty.post(
  "https://api.carebit.co/v1/test_results",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}",
    "Idempotency-Key" => SecureRandom.uuid,
    "Content-Type" => "application/json"
  },
  body: {
    "automatically_create_resource_permission_for_patient" => true,
    "notify_patient_of_resource_permission" => true,
    "patient_id" => "00000000-0000-4000-8000-000000000004",
    "status" => "complete",
    "test_result_items" => [
      {
        "is_abnormal" => false,
        "observation_code" => "718-7",
        "observation_name" => "Haemoglobin",
        "observation_value" => 14.5,
        "observation_value_units" => "g/dL",
        "reference_range_lower_bound" => 12,
        "reference_range_upper_bound" => 16,
        "status" => "final"
      }
    ],
    "title" => "Full blood count"
  }.to_json
)
raise "Carebit API error: #{response.code}" unless response.success?
data = response.parsed_response
```

```php
<?php

$client = new GuzzleHttp\Client();

$response = $client->post("https://api.carebit.co/v1/test_results", [
    "headers" => [
      "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
      "Idempotency-Key" => bin2hex(random_bytes(16)),
    ],
    "json" => [
      "automatically_create_resource_permission_for_patient" => true,
      "notify_patient_of_resource_permission" => true,
      "patient_id" => "00000000-0000-4000-8000-000000000004",
      "status" => "complete",
      "test_result_items" => [
        [
          "is_abnormal" => false,
          "observation_code" => "718-7",
          "observation_name" => "Haemoglobin",
          "observation_value" => 14.5,
          "observation_value_units" => "g/dL",
          "reference_range_lower_bound" => 12,
          "reference_range_upper_bound" => 16,
          "status" => "final"
        ]
      ],
      "title" => "Full blood count"
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```


---

# Get a Test Result

`GET /v1/test_results/:id`

**Required API scopes:** `test_results.read`

## Parameters

- `id` (path, `string`) (required)

## Response `200`

The requested `TestResult`.

- `object`
  - `automatically_create_resource_permission_for_patient` (`boolean`) - Whether Carebit automatically shares the test result with the patient after processing.
  - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `download_url` (`string | null`) - format: `uri`; The short-lived signed download URL for the TestResult. Null until the uploaded file passes malware scanning.
  - `filename` (`string | null`) - The original filename of the test result document, when one was supplied.
  - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - `links` (`object`) - URLs to related resources.
    - `booking` (`string | null`) - format: `uri`; The full URL of a related resource.
    - `clinician` (`string | null`) - format: `uri`; The full URL of a related resource.
    - `patient` (`string | null`) - format: `uri`; The full URL of a related resource.
    - `remote_file_import_batch` (`string`) - format: `uri`; The full URL of a related resource.
  - `notify_patient_of_resource_permission` (`boolean | null`) - Whether Carebit notifies the patient when the test result is shared with them.
  - `object` (`any`) - Discriminator value emitted at `object`.
  - `remote_file_import_batch_id` (`string`) - format: `uuid`; The identifier of the remote file import batch created for the uploaded file. Set on the create response when `file_url` or `file_base64` was submitted.
  - `status` (`string | null`) - enum: `awaiting_proofreading`, `awaiting_receipt`, `awaiting_review`, `awaiting_sending`, `awaiting_typing`, `complete`, `draft`, `reviewed`, `null`; The workflow status of the test result.
  - `test_result_items` (`array`) - The structured clinical observations included in the test result.
    - `items` (`object`)
      - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
      - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
      - `is_abnormal` (`boolean | null`) - Whether the observation falls outside its reference range, when known.
      - `notes` (`string | null`) - Additional clinical notes about the observation.
      - `object` (`any`) - Discriminator value emitted at `object`.
      - `observation_code` (`string | null`) - The laboratory or clinical code that identifies the observation.
      - `observation_name` (`string | null`) - The observation's display name.
      - `observation_text` (`string | null`) - The textual observation value, when the result is not represented numerically.
      - `observation_value` (`number | null`) - The numeric value of the observation, when applicable.
      - `observation_value_precision` (`string | null`) - enum: `<`, `=`, `>`, `null`; The precision qualifier for `observation_value`. `<` and `>` denote a bound, and `=` denotes an exact value.
      - `observation_value_units` (`string | null`) - The unit used for `observation_value`.
      - `observed_at` (`string | null`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
      - `reference_range_lower_bound` (`number | null`) - The lower bound of the expected reference range, when supplied.
      - `reference_range_upper_bound` (`number | null`) - The upper bound of the expected reference range, when supplied.
      - `status` (`string | null`) - enum: `corrected`, `final`, `pending`, `null`; The clinical workflow status of the observation.
      - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `title` (`string | null`) - The display title of the test result.
  - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.

### Example

```json
{
  "id": "9d4a13e1-0eea-4669-88c4-03316c092c77",
  "object": "test_result",
  "automatically_create_resource_permission_for_patient": true,
  "created_at": "2026-01-01T09:00:00Z",
  "download_url": "https://files.example.invalid/document.pdf?signature=test",
  "filename": "referral-letter.pdf",
  "links": {
    "booking": "https://api.carebit.co/v1/bookings/92a3b4c5-d6e7-4f01-8234-56789abcdef0",
    "clinician": "https://api.carebit.co/v1/clinicians/2b3c4d5e-6f70-489a-9bcd-ef0123456789",
    "patient": "https://api.carebit.co/v1/patients/1a2b3c4d-5e6f-4789-8abc-def012345678",
    "remote_file_import_batch": "https://api.carebit.co/v1/remote_file_import_batches/ebc38802-f219-4c7b-8136-8e963a0c69e0"
  },
  "notify_patient_of_resource_permission": true,
  "remote_file_import_batch_id": "ebc38802-f219-4c7b-8136-8e963a0c69e0",
  "status": "awaiting_proofreading",
  "test_result_items": [
    {
      "id": "7592f451-4733-44f1-8560-1bb6075fa552",
      "object": "test_result_item",
      "created_at": "2026-01-01T09:00:00Z",
      "is_abnormal": false,
      "notes": "Please confirm the appointment by email.",
      "observation_code": "718-7",
      "observation_name": "Haemoglobin",
      "observation_text": "Within the expected range",
      "observation_value": 14.5,
      "observation_value_precision": "<",
      "observation_value_units": "g/dL",
      "observed_at": "2026-01-01T09:00:00Z",
      "reference_range_lower_bound": 12,
      "reference_range_upper_bound": 16,
      "status": "corrected",
      "updated_at": "2026-01-01T09:00:00Z"
    }
  ],
  "title": "Dr",
  "updated_at": "2026-01-01T09:00:00Z"
}
```

## Response `401`

The access token is missing, invalid, expired, or revoked.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `403`

The access token lacks the required scope, or the project is disabled.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `404`

Error response.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `429`

Too many requests. Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Code samples

```bash
curl -X GET "https://api.carebit.co/v1/test_results/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN"
```

```javascript
const response = await fetch("https://api.carebit.co/v1/test_results/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
  },
});

if (!response.ok) {
  throw new Error(`Carebit API error: ${response.status}`);
}

const data = await response.json();
```

```python
import os
import requests

response = requests.get(
    "https://api.carebit.co/v1/test_results/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
    }
)
response.raise_for_status()
data = response.json()
```

```ruby
require "httparty"

response = HTTParty.get(
  "https://api.carebit.co/v1/test_results/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}"
  }
)
raise "Carebit API error: #{response.code}" unless response.success?
data = response.parsed_response
```

```php
<?php

$client = new GuzzleHttp\Client();

$response = $client->get("https://api.carebit.co/v1/test_results/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c", [
    "headers" => [
      "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```


---

# Get the access token used on this request

`GET /v1/token`

Returns the current access token, the Organization and project it belongs to, and the granted scopes. Any valid access token can call this endpoint. It does not require `organization.read`. The response does not include the token secret.

## Response `200`

The requested `Token`.

- `object`
  - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `expires_at` (`string`) - format: `date-time`; The time after which this access token is no longer valid, as an ISO 8601 timestamp in UTC.
  - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - `links` (`object`) - URLs to related resources.
    - `organization` (`string`) - format: `uri`; The Organization this access token belongs to. Reading that resource requires `organization.read`.
    - `self` (`string`) - format: `uri`; This access token.
  - `livemode` (`boolean`) - `true` when the token was issued in the live Carebit environment. `false` for test tokens.
  - `object` (`any`) - Discriminator value emitted at `object`.
  - `organization` (`object`) - A summary of the Organization this access token belongs to. Address, email, and phone are omitted so a token without `organization.read` cannot read those fields.
    - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
    - `name` (`string`) - The display name of the Organization.
    - `object` (`any`) - Discriminator value emitted at `object`.
  - `project` (`object`) - A summary of the developer project that issued this access token.
    - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
    - `name` (`string`) - The display name of the developer project.
    - `object` (`any`) - Discriminator value emitted at `object`.
  - `scopes` (`array`) - The OAuth scopes granted to this access token, sorted alphabetically. This is a subset of the developer project's scopes.
    - `items` (`string`) - enum: `availability_periods.create`, `availability_periods.delete`, `availability_periods.update`, `availability_slots.read`, `bookings.cancel`, `bookings.create`, `bookings.read`, `bookings.update`, `clinician_agenda.read`, `clinicians.read`, `digital_form_responses.create`, `digital_form_responses.read`, `digital_forms.read`, `expirable_files.read`, `human_tasks.create`, `invoices.read`, `leads.create`, `leads.read`, `leads.update`, `letters.create`, `letters.read`, `lists.create`, `lists.delete`, `lists.read`, `lists.update`, `locations.read`, `notes.create`, `notes.read`, `notes.update`, `organization.read`, `organization.search`, `patient_connections.create`, `patient_connections.read`, `patient_connections.update`, `patients.create`, `patients.read`, `patients.update`, `payments.read`, `payors.create`, `payors.read`, `payors.update`, `reports.create`, `services.read`, `staff_members.read`, `test_results.create`, `test_results.read`, `transmissions.read`, `webhook_endpoints.create`, `webhook_endpoints.delete`, `webhook_endpoints.read`, `webhook_endpoints.update`; An OAuth scope granted to this access token.

### Example

```json
{
  "id": "50d3e61c-c488-42b5-850c-230f3df82fb1",
  "object": "token",
  "created_at": "2026-01-01T09:00:00Z",
  "expires_at": "2026-01-01T09:00:00Z",
  "links": {
    "organization": "https://api.carebit.co/v1/organization",
    "self": "https://api.carebit.co/v1/token"
  },
  "livemode": false,
  "organization": {
    "id": "8192a3b4-c5d6-4ef0-9123-456789abcdef",
    "object": "organization",
    "name": "Harley Street Clinic"
  },
  "project": {
    "id": "ba8dcd0b-5f84-45e2-8e82-ef825ee8db00",
    "object": "project",
    "name": "Referral portal"
  },
  "scopes": [
    "leads.create",
    "leads.read"
  ]
}
```

## Response `401`

The access token is missing, invalid, expired, or revoked.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `403`

The project is disabled or archived, or the Organization does not have the developer_platform entitlement.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `429`

Too many requests.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Code samples

```bash
curl -X GET "https://api.carebit.co/v1/token" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN"
```

```javascript
const response = await fetch("https://api.carebit.co/v1/token", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
  },
});

if (!response.ok) {
  throw new Error(`Carebit API error: ${response.status}`);
}

const data = await response.json();
```

```python
import os
import requests

response = requests.get(
    "https://api.carebit.co/v1/token",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
    }
)
response.raise_for_status()
data = response.json()
```

```ruby
require "httparty"

response = HTTParty.get(
  "https://api.carebit.co/v1/token",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}"
  }
)
raise "Carebit API error: #{response.code}" unless response.success?
data = response.parsed_response
```

```php
<?php

$client = new GuzzleHttp\Client();

$response = $client->get("https://api.carebit.co/v1/token", [
    "headers" => [
      "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```


---

# List Transmissions

`GET /v1/transmissions`

Returns the email delivery log for allowlisted resources. At least one of `patient_id` or `resource_type` must be supplied. When both are supplied, a Transmission must match both filters. Currently `resource_type` accepts only `digital_form_response`. Omitting `resource_type` still returns only those allowlisted types.

**Required API scopes:** `transmissions.read`

## Parameters

- `patient_id` (query, `string`) - Filter by a Patient with an active connection to the Organization.
- `resource_type` (query, `string`) - The type of resource whose Transmissions should be returned. Currently only `digital_form_response` is supported.
- `limit` (query, `integer`) - The maximum number of items to return. Defaults to `25`; the maximum is `100`.
- `starting_after` (query, `string`) - Return items after this resource ID. You cannot use this with `cursor`.
- `cursor` (query, `string`) - The `next_cursor` value from the previous page. You cannot use this with `starting_after`.

## Response `200`

Paginated list of `Transmission` objects.

- `any`

### Example

```json
{
  "object": "list",
  "data": [
    {
      "id": "17b62f19-f7c6-4155-85fa-e0e1be128239",
      "object": "transmission",
      "created_at": "2026-01-01T09:00:00Z",
      "digital_form_response_id": "4262fdc0-c7a1-4856-83c4-16ed34cb8773",
      "direction": "outbound",
      "error_message": "The recipient email address was rejected.",
      "links": {
        "digital_form_response": "https://api.carebit.co/v1/digital_form_responses/4262fdc0-c7a1-4856-83c4-16ed34cb8773",
        "patient": "https://api.carebit.co/v1/patients/1a2b3c4d-5e6f-4789-8abc-def012345678"
      },
      "resource_type": "digital_form_response",
      "sent_at": "2026-01-01T09:00:00Z",
      "status": "queued",
      "subject": "Please complete your pre-operative consent form",
      "to": "alex.morgan@example.com",
      "transmission_method": "email",
      "updated_at": "2026-01-01T09:00:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": "eyJzdGFydF90aW1lIjoiMjAyNi0wMS0wMVQwOTowMDowMFoifQ",
  "url": "/v1/transmissions"
}
```

## Response `400`

Neither `patient_id` nor `resource_type` was supplied, `resource_type` is not allowlisted, or a pagination parameter is invalid.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `401`

The access token is missing, invalid, expired, or revoked.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `403`

The access token lacks the required scope, or the project is disabled.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `404`

Error response.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `429`

Too many requests. Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Code samples

```bash
curl -X GET "https://api.carebit.co/v1/transmissions" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN"
```

```javascript
const response = await fetch("https://api.carebit.co/v1/transmissions", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
  },
});

if (!response.ok) {
  throw new Error(`Carebit API error: ${response.status}`);
}

const data = await response.json();
```

```python
import os
import requests

response = requests.get(
    "https://api.carebit.co/v1/transmissions",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
    }
)
response.raise_for_status()
data = response.json()
```

```ruby
require "httparty"

response = HTTParty.get(
  "https://api.carebit.co/v1/transmissions",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}"
  }
)
raise "Carebit API error: #{response.code}" unless response.success?
data = response.parsed_response
```

```php
<?php

$client = new GuzzleHttp\Client();

$response = $client->get("https://api.carebit.co/v1/transmissions", [
    "headers" => [
      "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```


---

# Webhook events

# booking.arrived

A Patient arrived for a Booking.

## Payload schema

- `object`
  - `api_version` (`any`)
  - `context` (`object`) - Present only when `source` is `api`. Identifies the acting project and API key.
    - `developer_platform_api_key_id` (`string | null`) - format: `uuid`
    - `developer_platform_project_id` (`string | null`) - format: `uuid`
  - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `data` (`object`)
    - `object` (`object`)
      - `canceled_at` (`string | null`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
      - `cancellation_information` (`string | null`) - Additional notes recorded with the cancellation.
      - `cancellation_reason` (`string | null`) - enum: `abusive_behavior`, `booked_in_error`, `childcare_issues`, `clinician_annual_leave`, `clinician_emergency`, `clinician_schedule_change`, `colleague_unavailable`, `double_booked`, `duplicate_booking`, `equipment_issue`, `facility_unavailable`, `failed_to_pay_in_advance`, `family_emergency_illness`, `fear_or_anxiety`, `financial_concerns`, `financial_requirements_not_met`, `forgot_to_attend`, `insurance_company_not_permitted`, `insurance_coverage_issues`, `insurance_verification_failed`, `language_barrier`, `medication_interference`, `no_longer_required`, `no_response_to_recall`, `other`, `patient_deceased`, `patient_not_permitted`, `personal_emergency_illness`, `pre_booking_steps_not_completed`, `professional_discretion`, `referral_not_provided`, `relocated`, `rescheduled`, `scheduling_conflict`, `staff_issue`, `switched_to_another_clinician`, `symptoms_resolved`, `too_unwell`, `transportation_issues`, `unable_failed_to_prepare_for_booking`, `unknown`, `weather_conditions`, `wrong_clinician`, `wrong_location`, `wrong_service_type`, `null`; The reason the Booking was canceled. Required by Organizations that enforce cancellation reasons.
      - `cancellation_source` (`string | null`) - enum: `api`, `app`, `automation`, `patient`, `staff_member`, `null`; Who canceled the Booking. API cancellations use `api`.
      - `clinician` (`any`) - The clinician assigned to the booking.
      - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
      - `end_time` (`string | null`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
      - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
      - `information_for_patient` (`string | null`) - The sanitized HTML shown to the patient.
      - `information_for_staff_members` (`string | null`) - The sanitized HTML shown only to staff members.
      - `is_remote` (`boolean`) - Whether the Booking takes place remotely.
      - `links` (`object`) - URLs to related resources.
        - `clinician` (`string | null`) - format: `uri`; The full URL of a related resource.
        - `invoices` (`string`) - format: `uri`; The full URL of a related resource.
        - `letters` (`string`) - format: `uri`; The full URL of a related resource.
        - `notes` (`string`) - format: `uri`; The full URL of a related resource.
        - `service` (`string | null`) - format: `uri`; The full URL of a related resource.
        - `test_results` (`string`) - format: `uri`; The full URL of a related resource.
      - `location` (`any`) - The location where the booking takes place, or null for a remote booking.
      - `object` (`any`) - Discriminator value emitted at `object`.
      - `patient` (`any`) - The patient attending the booking.
      - `payor` (`any`) - The payor responsible for the booking's charges.
      - `recall_due_date` (`string | null`) - format: `date`; The date the Patient is due to return, in ISO 8601 format (YYYY-MM-DD). Present on recall Bookings. Null on diary Bookings.
      - `remote_method` (`string | null`) - enum: `native_video`, `null`; The remote consultation method. `native_video` uses Carebit Video.
      - `service` (`any`) - The service being provided during the booking.
      - `service_variants` (`array`) - The service variants selected for the booking.
        - `items` (`object`)
          - `clinician_id` (`string | null`) - format: `uuid`; The identifier of the clinician assigned to this service variant, when the variant is clinician-specific.
          - `currency` (`string | null`) - The ISO 4217 currency code used for this service variant. Must be one of `chf`, `eur`, `gbp`, or `usd`.
          - `description` (`string | null`) - The description of this service variant.
          - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
          - `links` (`object`) - URLs to related resources.
            - `clinician` (`string | null`) - format: `uri`; The full URL of a related resource.
            - `location` (`string | null`) - format: `uri`; The full URL of a related resource.
          - `location_id` (`string | null`) - format: `uuid`; The identifier of the location assigned to this service variant, when the variant is location-specific.
          - `net_price` (`integer | null`) - The net price of this service variant, before tax, in the currency's minor units.
          - `permits_remote_bookings` (`boolean`) - Whether this service variant can be used for remote bookings.
      - `start_time` (`string | null`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
      - `status` (`string | null`) - enum: `arrived`, `awaiting_payment`, `awaiting_recall`, `canceled`, `confirmed`, `did_not_attend`, `overdue_for_recall`, `prepared`, `recall_canceled`, `recall_expired`, `unconfirmed`, `null`; The Booking's current status. Null while Carebit is creating the record.
      - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `developer_platform_project_id` (`string | null`) - format: `uuid`; The project ID whose credential caused the change. Null for `dashboard` events.
  - `id` (`string`) - Event identifier prefixed with `evt_`.
  - `livemode` (`boolean`) - `false` for test-event deliveries.
  - `object` (`any`)
  - `source` (`string`) - enum: `api`, `dashboard`; Origin of the change. `api` means a Developer Platform mutation; `dashboard` means a Carebit-initiated change.
  - `type` (`any`)

### Example payload

```json
{
  "id": "evt_00000000-0000-4000-8000-000000000012",
  "object": "event",
  "api_version": "v1",
  "created_at": "2026-01-01T09:00:00Z",
  "data": {
    "object": {
      "id": "00000000-0000-4000-8000-000000000001",
      "object": "booking",
      "canceled_at": null,
      "cancellation_information": null,
      "cancellation_reason": null,
      "cancellation_source": null,
      "clinician": {
        "id": "00000000-0000-4000-8000-000000000002",
        "object": "clinician",
        "created_at": "2026-01-01T09:00:00Z",
        "display_name": "Dr Ada Lovelace",
        "email": "ada.lovelace@example.invalid",
        "first_name": "Ada",
        "last_name": "Lovelace",
        "links": {
          "bookings": "https://api.carebit.co/v1/bookings?clinician_id=00000000-0000-4000-8000-000000000002"
        },
        "medical_specialty": "General Medicine",
        "title": "Dr",
        "updated_at": "2026-01-01T09:00:00Z"
      },
      "created_at": "2026-01-01T09:00:00Z",
      "end_time": "2026-01-01T10:30:00Z",
      "information_for_patient": "This is a test booking. Please ignore.",
      "information_for_staff_members": "This is a test booking.",
      "is_remote": false,
      "links": {
        "clinician": "https://api.carebit.co/v1/clinicians/00000000-0000-4000-8000-000000000002",
        "invoices": "https://api.carebit.co/v1/invoices?booking_id=00000000-0000-4000-8000-000000000001",
        "letters": "https://api.carebit.co/v1/letters?booking_id=00000000-0000-4000-8000-000000000001",
        "notes": "https://api.carebit.co/v1/notes?booking_id=00000000-0000-4000-8000-000000000001",
        "service": "https://api.carebit.co/v1/services/00000000-0000-4000-8000-000000000005",
        "test_results": "https://api.carebit.co/v1/test_results?booking_id=00000000-0000-4000-8000-000000000001"
      },
      "location": {
        "id": "00000000-0000-4000-8000-000000000003",
        "object": "location",
        "address_line_1": "1 Test Street",
        "address_line_2": null,
        "city": "Test City",
        "country_code": "GB",
        "county": "Testshire",
        "created_at": "2026-01-01T09:00:00Z",
        "formatted_address": "1 Test Street, Test City, GB, TE1 1ST",
        "name": "Test Location",
        "postcode": "TE1 1ST",
        "updated_at": "2026-01-01T09:00:00Z"
      },
      "patient": {
        "id": "00000000-0000-4000-8000-000000000004",
        "object": "patient",
        "address_line_1": "1 Test Street",
        "address_line_2": null,
        "city": "Test City",
        "country_code": "GB",
        "county": "Testshire",
        "created_at": "2026-01-01T09:00:00Z",
        "creation_source": "api",
        "date_of_birth": "1970-01-01",
        "display_name": "Ms Test Patient",
        "email": "test.patient@example.invalid",
        "first_name": "Test",
        "is_opted_out_of_sms": false,
        "last_name": "Patient",
        "mobile": "7700900123",
        "mobile_country_dial_code": "GB",
        "nhs_number": "9990000000",
        "phone": "1234567890",
        "phone_country_dial_code": "GB",
        "phone_number": "+441234567890",
        "postcode": "TE1 1ST",
        "sex": "female",
        "title": "Ms",
        "updated_at": "2026-01-01T09:00:00Z"
      },
      "payor": null,
      "recall_due_date": null,
      "remote_method": null,
      "service": {
        "id": "00000000-0000-4000-8000-000000000005",
        "object": "service",
        "created_at": "2026-01-01T09:00:00Z",
        "description": "Test consultation service.",
        "duration_minutes": 30,
        "is_bookable_online": true,
        "name": "Test consultation",
        "service_variants": [
          {
            "id": "00000000-0000-4000-8000-000000000006",
            "clinician_id": "00000000-0000-4000-8000-000000000002",
            "currency": "GBP",
            "description": "Standard consultation variant.",
            "links": {
              "clinician": "https://api.carebit.co/v1/clinicians/00000000-0000-4000-8000-000000000002",
              "location": "https://api.carebit.co/v1/locations/00000000-0000-4000-8000-000000000003"
            },
            "location_id": "00000000-0000-4000-8000-000000000003",
            "net_price": 6200,
            "permits_remote_bookings": false
          }
        ],
        "tax_rate": null,
        "updated_at": "2026-01-01T09:00:00Z"
      },
      "service_variants": [
        {
          "id": "00000000-0000-4000-8000-000000000006",
          "clinician_id": "00000000-0000-4000-8000-000000000002",
          "currency": "GBP",
          "description": "Standard consultation variant.",
          "links": {
            "clinician": "https://api.carebit.co/v1/clinicians/00000000-0000-4000-8000-000000000002",
            "location": "https://api.carebit.co/v1/locations/00000000-0000-4000-8000-000000000003"
          },
          "location_id": "00000000-0000-4000-8000-000000000003",
          "net_price": 6200,
          "permits_remote_bookings": false
        }
      ],
      "start_time": "2026-01-01T10:00:00Z",
      "status": "arrived",
      "updated_at": "2026-01-01T09:00:00Z"
    }
  },
  "developer_platform_project_id": null,
  "livemode": false,
  "source": "dashboard",
  "type": "booking.arrived"
}
```


---

# booking.canceled

A Booking was canceled.

## Payload schema

- `object`
  - `api_version` (`any`)
  - `context` (`object`) - Present only when `source` is `api`. Identifies the acting project and API key.
    - `developer_platform_api_key_id` (`string | null`) - format: `uuid`
    - `developer_platform_project_id` (`string | null`) - format: `uuid`
  - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `data` (`object`)
    - `object` (`object`)
      - `canceled_at` (`string | null`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
      - `cancellation_information` (`string | null`) - Additional notes recorded with the cancellation.
      - `cancellation_reason` (`string | null`) - enum: `abusive_behavior`, `booked_in_error`, `childcare_issues`, `clinician_annual_leave`, `clinician_emergency`, `clinician_schedule_change`, `colleague_unavailable`, `double_booked`, `duplicate_booking`, `equipment_issue`, `facility_unavailable`, `failed_to_pay_in_advance`, `family_emergency_illness`, `fear_or_anxiety`, `financial_concerns`, `financial_requirements_not_met`, `forgot_to_attend`, `insurance_company_not_permitted`, `insurance_coverage_issues`, `insurance_verification_failed`, `language_barrier`, `medication_interference`, `no_longer_required`, `no_response_to_recall`, `other`, `patient_deceased`, `patient_not_permitted`, `personal_emergency_illness`, `pre_booking_steps_not_completed`, `professional_discretion`, `referral_not_provided`, `relocated`, `rescheduled`, `scheduling_conflict`, `staff_issue`, `switched_to_another_clinician`, `symptoms_resolved`, `too_unwell`, `transportation_issues`, `unable_failed_to_prepare_for_booking`, `unknown`, `weather_conditions`, `wrong_clinician`, `wrong_location`, `wrong_service_type`, `null`; The reason the Booking was canceled. Required by Organizations that enforce cancellation reasons.
      - `cancellation_source` (`string | null`) - enum: `api`, `app`, `automation`, `patient`, `staff_member`, `null`; Who canceled the Booking. API cancellations use `api`.
      - `clinician` (`any`) - The clinician assigned to the booking.
      - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
      - `end_time` (`string | null`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
      - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
      - `information_for_patient` (`string | null`) - The sanitized HTML shown to the patient.
      - `information_for_staff_members` (`string | null`) - The sanitized HTML shown only to staff members.
      - `is_remote` (`boolean`) - Whether the Booking takes place remotely.
      - `links` (`object`) - URLs to related resources.
        - `clinician` (`string | null`) - format: `uri`; The full URL of a related resource.
        - `invoices` (`string`) - format: `uri`; The full URL of a related resource.
        - `letters` (`string`) - format: `uri`; The full URL of a related resource.
        - `notes` (`string`) - format: `uri`; The full URL of a related resource.
        - `service` (`string | null`) - format: `uri`; The full URL of a related resource.
        - `test_results` (`string`) - format: `uri`; The full URL of a related resource.
      - `location` (`any`) - The location where the booking takes place, or null for a remote booking.
      - `object` (`any`) - Discriminator value emitted at `object`.
      - `patient` (`any`) - The patient attending the booking.
      - `payor` (`any`) - The payor responsible for the booking's charges.
      - `recall_due_date` (`string | null`) - format: `date`; The date the Patient is due to return, in ISO 8601 format (YYYY-MM-DD). Present on recall Bookings. Null on diary Bookings.
      - `remote_method` (`string | null`) - enum: `native_video`, `null`; The remote consultation method. `native_video` uses Carebit Video.
      - `service` (`any`) - The service being provided during the booking.
      - `service_variants` (`array`) - The service variants selected for the booking.
        - `items` (`object`)
          - `clinician_id` (`string | null`) - format: `uuid`; The identifier of the clinician assigned to this service variant, when the variant is clinician-specific.
          - `currency` (`string | null`) - The ISO 4217 currency code used for this service variant. Must be one of `chf`, `eur`, `gbp`, or `usd`.
          - `description` (`string | null`) - The description of this service variant.
          - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
          - `links` (`object`) - URLs to related resources.
            - `clinician` (`string | null`) - format: `uri`; The full URL of a related resource.
            - `location` (`string | null`) - format: `uri`; The full URL of a related resource.
          - `location_id` (`string | null`) - format: `uuid`; The identifier of the location assigned to this service variant, when the variant is location-specific.
          - `net_price` (`integer | null`) - The net price of this service variant, before tax, in the currency's minor units.
          - `permits_remote_bookings` (`boolean`) - Whether this service variant can be used for remote bookings.
      - `start_time` (`string | null`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
      - `status` (`string | null`) - enum: `arrived`, `awaiting_payment`, `awaiting_recall`, `canceled`, `confirmed`, `did_not_attend`, `overdue_for_recall`, `prepared`, `recall_canceled`, `recall_expired`, `unconfirmed`, `null`; The Booking's current status. Null while Carebit is creating the record.
      - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `developer_platform_project_id` (`string | null`) - format: `uuid`; The project ID whose credential caused the change. Null for `dashboard` events.
  - `id` (`string`) - Event identifier prefixed with `evt_`.
  - `livemode` (`boolean`) - `false` for test-event deliveries.
  - `object` (`any`)
  - `source` (`string`) - enum: `api`, `dashboard`; Origin of the change. `api` means a Developer Platform mutation; `dashboard` means a Carebit-initiated change.
  - `type` (`any`)

### Example payload

```json
{
  "id": "evt_00000000-0000-4000-8000-000000000012",
  "object": "event",
  "api_version": "v1",
  "created_at": "2026-01-01T09:00:00Z",
  "data": {
    "object": {
      "id": "00000000-0000-4000-8000-000000000001",
      "object": "booking",
      "canceled_at": "2026-01-01T09:00:00Z",
      "cancellation_information": null,
      "cancellation_reason": "booked_in_error",
      "cancellation_source": "api",
      "clinician": {
        "id": "00000000-0000-4000-8000-000000000002",
        "object": "clinician",
        "created_at": "2026-01-01T09:00:00Z",
        "display_name": "Dr Ada Lovelace",
        "email": "ada.lovelace@example.invalid",
        "first_name": "Ada",
        "last_name": "Lovelace",
        "links": {
          "bookings": "https://api.carebit.co/v1/bookings?clinician_id=00000000-0000-4000-8000-000000000002"
        },
        "medical_specialty": "General Medicine",
        "title": "Dr",
        "updated_at": "2026-01-01T09:00:00Z"
      },
      "created_at": "2026-01-01T09:00:00Z",
      "end_time": "2026-01-01T10:30:00Z",
      "information_for_patient": "This is a test booking. Please ignore.",
      "information_for_staff_members": "This is a test booking.",
      "is_remote": false,
      "links": {
        "clinician": "https://api.carebit.co/v1/clinicians/00000000-0000-4000-8000-000000000002",
        "invoices": "https://api.carebit.co/v1/invoices?booking_id=00000000-0000-4000-8000-000000000001",
        "letters": "https://api.carebit.co/v1/letters?booking_id=00000000-0000-4000-8000-000000000001",
        "notes": "https://api.carebit.co/v1/notes?booking_id=00000000-0000-4000-8000-000000000001",
        "service": "https://api.carebit.co/v1/services/00000000-0000-4000-8000-000000000005",
        "test_results": "https://api.carebit.co/v1/test_results?booking_id=00000000-0000-4000-8000-000000000001"
      },
      "location": {
        "id": "00000000-0000-4000-8000-000000000003",
        "object": "location",
        "address_line_1": "1 Test Street",
        "address_line_2": null,
        "city": "Test City",
        "country_code": "GB",
        "county": "Testshire",
        "created_at": "2026-01-01T09:00:00Z",
        "formatted_address": "1 Test Street, Test City, GB, TE1 1ST",
        "name": "Test Location",
        "postcode": "TE1 1ST",
        "updated_at": "2026-01-01T09:00:00Z"
      },
      "patient": {
        "id": "00000000-0000-4000-8000-000000000004",
        "object": "patient",
        "address_line_1": "1 Test Street",
        "address_line_2": null,
        "city": "Test City",
        "country_code": "GB",
        "county": "Testshire",
        "created_at": "2026-01-01T09:00:00Z",
        "creation_source": "api",
        "date_of_birth": "1970-01-01",
        "display_name": "Ms Test Patient",
        "email": "test.patient@example.invalid",
        "first_name": "Test",
        "is_opted_out_of_sms": false,
        "last_name": "Patient",
        "mobile": "7700900123",
        "mobile_country_dial_code": "GB",
        "nhs_number": "9990000000",
        "phone": "1234567890",
        "phone_country_dial_code": "GB",
        "phone_number": "+441234567890",
        "postcode": "TE1 1ST",
        "sex": "female",
        "title": "Ms",
        "updated_at": "2026-01-01T09:00:00Z"
      },
      "payor": null,
      "recall_due_date": null,
      "remote_method": null,
      "service": {
        "id": "00000000-0000-4000-8000-000000000005",
        "object": "service",
        "created_at": "2026-01-01T09:00:00Z",
        "description": "Test consultation service.",
        "duration_minutes": 30,
        "is_bookable_online": true,
        "name": "Test consultation",
        "service_variants": [
          {
            "id": "00000000-0000-4000-8000-000000000006",
            "clinician_id": "00000000-0000-4000-8000-000000000002",
            "currency": "GBP",
            "description": "Standard consultation variant.",
            "links": {
              "clinician": "https://api.carebit.co/v1/clinicians/00000000-0000-4000-8000-000000000002",
              "location": "https://api.carebit.co/v1/locations/00000000-0000-4000-8000-000000000003"
            },
            "location_id": "00000000-0000-4000-8000-000000000003",
            "net_price": 6200,
            "permits_remote_bookings": false
          }
        ],
        "tax_rate": null,
        "updated_at": "2026-01-01T09:00:00Z"
      },
      "service_variants": [
        {
          "id": "00000000-0000-4000-8000-000000000006",
          "clinician_id": "00000000-0000-4000-8000-000000000002",
          "currency": "GBP",
          "description": "Standard consultation variant.",
          "links": {
            "clinician": "https://api.carebit.co/v1/clinicians/00000000-0000-4000-8000-000000000002",
            "location": "https://api.carebit.co/v1/locations/00000000-0000-4000-8000-000000000003"
          },
          "location_id": "00000000-0000-4000-8000-000000000003",
          "net_price": 6200,
          "permits_remote_bookings": false
        }
      ],
      "start_time": "2026-01-01T10:00:00Z",
      "status": "canceled",
      "updated_at": "2026-01-01T09:00:00Z"
    }
  },
  "developer_platform_project_id": null,
  "livemode": false,
  "source": "dashboard",
  "type": "booking.canceled"
}
```


---

# booking.confirmed

A Booking was confirmed.

## Payload schema

- `object`
  - `api_version` (`any`)
  - `context` (`object`) - Present only when `source` is `api`. Identifies the acting project and API key.
    - `developer_platform_api_key_id` (`string | null`) - format: `uuid`
    - `developer_platform_project_id` (`string | null`) - format: `uuid`
  - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `data` (`object`)
    - `object` (`object`)
      - `canceled_at` (`string | null`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
      - `cancellation_information` (`string | null`) - Additional notes recorded with the cancellation.
      - `cancellation_reason` (`string | null`) - enum: `abusive_behavior`, `booked_in_error`, `childcare_issues`, `clinician_annual_leave`, `clinician_emergency`, `clinician_schedule_change`, `colleague_unavailable`, `double_booked`, `duplicate_booking`, `equipment_issue`, `facility_unavailable`, `failed_to_pay_in_advance`, `family_emergency_illness`, `fear_or_anxiety`, `financial_concerns`, `financial_requirements_not_met`, `forgot_to_attend`, `insurance_company_not_permitted`, `insurance_coverage_issues`, `insurance_verification_failed`, `language_barrier`, `medication_interference`, `no_longer_required`, `no_response_to_recall`, `other`, `patient_deceased`, `patient_not_permitted`, `personal_emergency_illness`, `pre_booking_steps_not_completed`, `professional_discretion`, `referral_not_provided`, `relocated`, `rescheduled`, `scheduling_conflict`, `staff_issue`, `switched_to_another_clinician`, `symptoms_resolved`, `too_unwell`, `transportation_issues`, `unable_failed_to_prepare_for_booking`, `unknown`, `weather_conditions`, `wrong_clinician`, `wrong_location`, `wrong_service_type`, `null`; The reason the Booking was canceled. Required by Organizations that enforce cancellation reasons.
      - `cancellation_source` (`string | null`) - enum: `api`, `app`, `automation`, `patient`, `staff_member`, `null`; Who canceled the Booking. API cancellations use `api`.
      - `clinician` (`any`) - The clinician assigned to the booking.
      - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
      - `end_time` (`string | null`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
      - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
      - `information_for_patient` (`string | null`) - The sanitized HTML shown to the patient.
      - `information_for_staff_members` (`string | null`) - The sanitized HTML shown only to staff members.
      - `is_remote` (`boolean`) - Whether the Booking takes place remotely.
      - `links` (`object`) - URLs to related resources.
        - `clinician` (`string | null`) - format: `uri`; The full URL of a related resource.
        - `invoices` (`string`) - format: `uri`; The full URL of a related resource.
        - `letters` (`string`) - format: `uri`; The full URL of a related resource.
        - `notes` (`string`) - format: `uri`; The full URL of a related resource.
        - `service` (`string | null`) - format: `uri`; The full URL of a related resource.
        - `test_results` (`string`) - format: `uri`; The full URL of a related resource.
      - `location` (`any`) - The location where the booking takes place, or null for a remote booking.
      - `object` (`any`) - Discriminator value emitted at `object`.
      - `patient` (`any`) - The patient attending the booking.
      - `payor` (`any`) - The payor responsible for the booking's charges.
      - `recall_due_date` (`string | null`) - format: `date`; The date the Patient is due to return, in ISO 8601 format (YYYY-MM-DD). Present on recall Bookings. Null on diary Bookings.
      - `remote_method` (`string | null`) - enum: `native_video`, `null`; The remote consultation method. `native_video` uses Carebit Video.
      - `service` (`any`) - The service being provided during the booking.
      - `service_variants` (`array`) - The service variants selected for the booking.
        - `items` (`object`)
          - `clinician_id` (`string | null`) - format: `uuid`; The identifier of the clinician assigned to this service variant, when the variant is clinician-specific.
          - `currency` (`string | null`) - The ISO 4217 currency code used for this service variant. Must be one of `chf`, `eur`, `gbp`, or `usd`.
          - `description` (`string | null`) - The description of this service variant.
          - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
          - `links` (`object`) - URLs to related resources.
            - `clinician` (`string | null`) - format: `uri`; The full URL of a related resource.
            - `location` (`string | null`) - format: `uri`; The full URL of a related resource.
          - `location_id` (`string | null`) - format: `uuid`; The identifier of the location assigned to this service variant, when the variant is location-specific.
          - `net_price` (`integer | null`) - The net price of this service variant, before tax, in the currency's minor units.
          - `permits_remote_bookings` (`boolean`) - Whether this service variant can be used for remote bookings.
      - `start_time` (`string | null`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
      - `status` (`string | null`) - enum: `arrived`, `awaiting_payment`, `awaiting_recall`, `canceled`, `confirmed`, `did_not_attend`, `overdue_for_recall`, `prepared`, `recall_canceled`, `recall_expired`, `unconfirmed`, `null`; The Booking's current status. Null while Carebit is creating the record.
      - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `developer_platform_project_id` (`string | null`) - format: `uuid`; The project ID whose credential caused the change. Null for `dashboard` events.
  - `id` (`string`) - Event identifier prefixed with `evt_`.
  - `livemode` (`boolean`) - `false` for test-event deliveries.
  - `object` (`any`)
  - `source` (`string`) - enum: `api`, `dashboard`; Origin of the change. `api` means a Developer Platform mutation; `dashboard` means a Carebit-initiated change.
  - `type` (`any`)

### Example payload

```json
{
  "id": "evt_00000000-0000-4000-8000-000000000012",
  "object": "event",
  "api_version": "v1",
  "created_at": "2026-01-01T09:00:00Z",
  "data": {
    "object": {
      "id": "00000000-0000-4000-8000-000000000001",
      "object": "booking",
      "canceled_at": null,
      "cancellation_information": null,
      "cancellation_reason": null,
      "cancellation_source": null,
      "clinician": {
        "id": "00000000-0000-4000-8000-000000000002",
        "object": "clinician",
        "created_at": "2026-01-01T09:00:00Z",
        "display_name": "Dr Ada Lovelace",
        "email": "ada.lovelace@example.invalid",
        "first_name": "Ada",
        "last_name": "Lovelace",
        "links": {
          "bookings": "https://api.carebit.co/v1/bookings?clinician_id=00000000-0000-4000-8000-000000000002"
        },
        "medical_specialty": "General Medicine",
        "title": "Dr",
        "updated_at": "2026-01-01T09:00:00Z"
      },
      "created_at": "2026-01-01T09:00:00Z",
      "end_time": "2026-01-01T10:30:00Z",
      "information_for_patient": "This is a test booking. Please ignore.",
      "information_for_staff_members": "This is a test booking.",
      "is_remote": false,
      "links": {
        "clinician": "https://api.carebit.co/v1/clinicians/00000000-0000-4000-8000-000000000002",
        "invoices": "https://api.carebit.co/v1/invoices?booking_id=00000000-0000-4000-8000-000000000001",
        "letters": "https://api.carebit.co/v1/letters?booking_id=00000000-0000-4000-8000-000000000001",
        "notes": "https://api.carebit.co/v1/notes?booking_id=00000000-0000-4000-8000-000000000001",
        "service": "https://api.carebit.co/v1/services/00000000-0000-4000-8000-000000000005",
        "test_results": "https://api.carebit.co/v1/test_results?booking_id=00000000-0000-4000-8000-000000000001"
      },
      "location": {
        "id": "00000000-0000-4000-8000-000000000003",
        "object": "location",
        "address_line_1": "1 Test Street",
        "address_line_2": null,
        "city": "Test City",
        "country_code": "GB",
        "county": "Testshire",
        "created_at": "2026-01-01T09:00:00Z",
        "formatted_address": "1 Test Street, Test City, GB, TE1 1ST",
        "name": "Test Location",
        "postcode": "TE1 1ST",
        "updated_at": "2026-01-01T09:00:00Z"
      },
      "patient": {
        "id": "00000000-0000-4000-8000-000000000004",
        "object": "patient",
        "address_line_1": "1 Test Street",
        "address_line_2": null,
        "city": "Test City",
        "country_code": "GB",
        "county": "Testshire",
        "created_at": "2026-01-01T09:00:00Z",
        "creation_source": "api",
        "date_of_birth": "1970-01-01",
        "display_name": "Ms Test Patient",
        "email": "test.patient@example.invalid",
        "first_name": "Test",
        "is_opted_out_of_sms": false,
        "last_name": "Patient",
        "mobile": "7700900123",
        "mobile_country_dial_code": "GB",
        "nhs_number": "9990000000",
        "phone": "1234567890",
        "phone_country_dial_code": "GB",
        "phone_number": "+441234567890",
        "postcode": "TE1 1ST",
        "sex": "female",
        "title": "Ms",
        "updated_at": "2026-01-01T09:00:00Z"
      },
      "payor": null,
      "recall_due_date": null,
      "remote_method": null,
      "service": {
        "id": "00000000-0000-4000-8000-000000000005",
        "object": "service",
        "created_at": "2026-01-01T09:00:00Z",
        "description": "Test consultation service.",
        "duration_minutes": 30,
        "is_bookable_online": true,
        "name": "Test consultation",
        "service_variants": [
          {
            "id": "00000000-0000-4000-8000-000000000006",
            "clinician_id": "00000000-0000-4000-8000-000000000002",
            "currency": "GBP",
            "description": "Standard consultation variant.",
            "links": {
              "clinician": "https://api.carebit.co/v1/clinicians/00000000-0000-4000-8000-000000000002",
              "location": "https://api.carebit.co/v1/locations/00000000-0000-4000-8000-000000000003"
            },
            "location_id": "00000000-0000-4000-8000-000000000003",
            "net_price": 6200,
            "permits_remote_bookings": false
          }
        ],
        "tax_rate": null,
        "updated_at": "2026-01-01T09:00:00Z"
      },
      "service_variants": [
        {
          "id": "00000000-0000-4000-8000-000000000006",
          "clinician_id": "00000000-0000-4000-8000-000000000002",
          "currency": "GBP",
          "description": "Standard consultation variant.",
          "links": {
            "clinician": "https://api.carebit.co/v1/clinicians/00000000-0000-4000-8000-000000000002",
            "location": "https://api.carebit.co/v1/locations/00000000-0000-4000-8000-000000000003"
          },
          "location_id": "00000000-0000-4000-8000-000000000003",
          "net_price": 6200,
          "permits_remote_bookings": false
        }
      ],
      "start_time": "2026-01-01T10:00:00Z",
      "status": "confirmed",
      "updated_at": "2026-01-01T09:00:00Z"
    }
  },
  "developer_platform_project_id": null,
  "livemode": false,
  "source": "dashboard",
  "type": "booking.confirmed"
}
```


---

# booking.did_not_attend

A Booking was marked as did not attend.

## Payload schema

- `object`
  - `api_version` (`any`)
  - `context` (`object`) - Present only when `source` is `api`. Identifies the acting project and API key.
    - `developer_platform_api_key_id` (`string | null`) - format: `uuid`
    - `developer_platform_project_id` (`string | null`) - format: `uuid`
  - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `data` (`object`)
    - `object` (`object`)
      - `canceled_at` (`string | null`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
      - `cancellation_information` (`string | null`) - Additional notes recorded with the cancellation.
      - `cancellation_reason` (`string | null`) - enum: `abusive_behavior`, `booked_in_error`, `childcare_issues`, `clinician_annual_leave`, `clinician_emergency`, `clinician_schedule_change`, `colleague_unavailable`, `double_booked`, `duplicate_booking`, `equipment_issue`, `facility_unavailable`, `failed_to_pay_in_advance`, `family_emergency_illness`, `fear_or_anxiety`, `financial_concerns`, `financial_requirements_not_met`, `forgot_to_attend`, `insurance_company_not_permitted`, `insurance_coverage_issues`, `insurance_verification_failed`, `language_barrier`, `medication_interference`, `no_longer_required`, `no_response_to_recall`, `other`, `patient_deceased`, `patient_not_permitted`, `personal_emergency_illness`, `pre_booking_steps_not_completed`, `professional_discretion`, `referral_not_provided`, `relocated`, `rescheduled`, `scheduling_conflict`, `staff_issue`, `switched_to_another_clinician`, `symptoms_resolved`, `too_unwell`, `transportation_issues`, `unable_failed_to_prepare_for_booking`, `unknown`, `weather_conditions`, `wrong_clinician`, `wrong_location`, `wrong_service_type`, `null`; The reason the Booking was canceled. Required by Organizations that enforce cancellation reasons.
      - `cancellation_source` (`string | null`) - enum: `api`, `app`, `automation`, `patient`, `staff_member`, `null`; Who canceled the Booking. API cancellations use `api`.
      - `clinician` (`any`) - The clinician assigned to the booking.
      - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
      - `end_time` (`string | null`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
      - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
      - `information_for_patient` (`string | null`) - The sanitized HTML shown to the patient.
      - `information_for_staff_members` (`string | null`) - The sanitized HTML shown only to staff members.
      - `is_remote` (`boolean`) - Whether the Booking takes place remotely.
      - `links` (`object`) - URLs to related resources.
        - `clinician` (`string | null`) - format: `uri`; The full URL of a related resource.
        - `invoices` (`string`) - format: `uri`; The full URL of a related resource.
        - `letters` (`string`) - format: `uri`; The full URL of a related resource.
        - `notes` (`string`) - format: `uri`; The full URL of a related resource.
        - `service` (`string | null`) - format: `uri`; The full URL of a related resource.
        - `test_results` (`string`) - format: `uri`; The full URL of a related resource.
      - `location` (`any`) - The location where the booking takes place, or null for a remote booking.
      - `object` (`any`) - Discriminator value emitted at `object`.
      - `patient` (`any`) - The patient attending the booking.
      - `payor` (`any`) - The payor responsible for the booking's charges.
      - `recall_due_date` (`string | null`) - format: `date`; The date the Patient is due to return, in ISO 8601 format (YYYY-MM-DD). Present on recall Bookings. Null on diary Bookings.
      - `remote_method` (`string | null`) - enum: `native_video`, `null`; The remote consultation method. `native_video` uses Carebit Video.
      - `service` (`any`) - The service being provided during the booking.
      - `service_variants` (`array`) - The service variants selected for the booking.
        - `items` (`object`)
          - `clinician_id` (`string | null`) - format: `uuid`; The identifier of the clinician assigned to this service variant, when the variant is clinician-specific.
          - `currency` (`string | null`) - The ISO 4217 currency code used for this service variant. Must be one of `chf`, `eur`, `gbp`, or `usd`.
          - `description` (`string | null`) - The description of this service variant.
          - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
          - `links` (`object`) - URLs to related resources.
            - `clinician` (`string | null`) - format: `uri`; The full URL of a related resource.
            - `location` (`string | null`) - format: `uri`; The full URL of a related resource.
          - `location_id` (`string | null`) - format: `uuid`; The identifier of the location assigned to this service variant, when the variant is location-specific.
          - `net_price` (`integer | null`) - The net price of this service variant, before tax, in the currency's minor units.
          - `permits_remote_bookings` (`boolean`) - Whether this service variant can be used for remote bookings.
      - `start_time` (`string | null`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
      - `status` (`string | null`) - enum: `arrived`, `awaiting_payment`, `awaiting_recall`, `canceled`, `confirmed`, `did_not_attend`, `overdue_for_recall`, `prepared`, `recall_canceled`, `recall_expired`, `unconfirmed`, `null`; The Booking's current status. Null while Carebit is creating the record.
      - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `developer_platform_project_id` (`string | null`) - format: `uuid`; The project ID whose credential caused the change. Null for `dashboard` events.
  - `id` (`string`) - Event identifier prefixed with `evt_`.
  - `livemode` (`boolean`) - `false` for test-event deliveries.
  - `object` (`any`)
  - `source` (`string`) - enum: `api`, `dashboard`; Origin of the change. `api` means a Developer Platform mutation; `dashboard` means a Carebit-initiated change.
  - `type` (`any`)

### Example payload

```json
{
  "id": "evt_00000000-0000-4000-8000-000000000012",
  "object": "event",
  "api_version": "v1",
  "created_at": "2026-01-01T09:00:00Z",
  "data": {
    "object": {
      "id": "00000000-0000-4000-8000-000000000001",
      "object": "booking",
      "canceled_at": null,
      "cancellation_information": null,
      "cancellation_reason": null,
      "cancellation_source": null,
      "clinician": {
        "id": "00000000-0000-4000-8000-000000000002",
        "object": "clinician",
        "created_at": "2026-01-01T09:00:00Z",
        "display_name": "Dr Ada Lovelace",
        "email": "ada.lovelace@example.invalid",
        "first_name": "Ada",
        "last_name": "Lovelace",
        "links": {
          "bookings": "https://api.carebit.co/v1/bookings?clinician_id=00000000-0000-4000-8000-000000000002"
        },
        "medical_specialty": "General Medicine",
        "title": "Dr",
        "updated_at": "2026-01-01T09:00:00Z"
      },
      "created_at": "2026-01-01T09:00:00Z",
      "end_time": "2026-01-01T08:30:00Z",
      "information_for_patient": "This is a test booking. Please ignore.",
      "information_for_staff_members": "This is a test booking.",
      "is_remote": false,
      "links": {
        "clinician": "https://api.carebit.co/v1/clinicians/00000000-0000-4000-8000-000000000002",
        "invoices": "https://api.carebit.co/v1/invoices?booking_id=00000000-0000-4000-8000-000000000001",
        "letters": "https://api.carebit.co/v1/letters?booking_id=00000000-0000-4000-8000-000000000001",
        "notes": "https://api.carebit.co/v1/notes?booking_id=00000000-0000-4000-8000-000000000001",
        "service": "https://api.carebit.co/v1/services/00000000-0000-4000-8000-000000000005",
        "test_results": "https://api.carebit.co/v1/test_results?booking_id=00000000-0000-4000-8000-000000000001"
      },
      "location": {
        "id": "00000000-0000-4000-8000-000000000003",
        "object": "location",
        "address_line_1": "1 Test Street",
        "address_line_2": null,
        "city": "Test City",
        "country_code": "GB",
        "county": "Testshire",
        "created_at": "2026-01-01T09:00:00Z",
        "formatted_address": "1 Test Street, Test City, GB, TE1 1ST",
        "name": "Test Location",
        "postcode": "TE1 1ST",
        "updated_at": "2026-01-01T09:00:00Z"
      },
      "patient": {
        "id": "00000000-0000-4000-8000-000000000004",
        "object": "patient",
        "address_line_1": "1 Test Street",
        "address_line_2": null,
        "city": "Test City",
        "country_code": "GB",
        "county": "Testshire",
        "created_at": "2026-01-01T09:00:00Z",
        "creation_source": "api",
        "date_of_birth": "1970-01-01",
        "display_name": "Ms Test Patient",
        "email": "test.patient@example.invalid",
        "first_name": "Test",
        "is_opted_out_of_sms": false,
        "last_name": "Patient",
        "mobile": "7700900123",
        "mobile_country_dial_code": "GB",
        "nhs_number": "9990000000",
        "phone": "1234567890",
        "phone_country_dial_code": "GB",
        "phone_number": "+441234567890",
        "postcode": "TE1 1ST",
        "sex": "female",
        "title": "Ms",
        "updated_at": "2026-01-01T09:00:00Z"
      },
      "payor": null,
      "recall_due_date": null,
      "remote_method": null,
      "service": {
        "id": "00000000-0000-4000-8000-000000000005",
        "object": "service",
        "created_at": "2026-01-01T09:00:00Z",
        "description": "Test consultation service.",
        "duration_minutes": 30,
        "is_bookable_online": true,
        "name": "Test consultation",
        "service_variants": [
          {
            "id": "00000000-0000-4000-8000-000000000006",
            "clinician_id": "00000000-0000-4000-8000-000000000002",
            "currency": "GBP",
            "description": "Standard consultation variant.",
            "links": {
              "clinician": "https://api.carebit.co/v1/clinicians/00000000-0000-4000-8000-000000000002",
              "location": "https://api.carebit.co/v1/locations/00000000-0000-4000-8000-000000000003"
            },
            "location_id": "00000000-0000-4000-8000-000000000003",
            "net_price": 6200,
            "permits_remote_bookings": false
          }
        ],
        "tax_rate": null,
        "updated_at": "2026-01-01T09:00:00Z"
      },
      "service_variants": [
        {
          "id": "00000000-0000-4000-8000-000000000006",
          "clinician_id": "00000000-0000-4000-8000-000000000002",
          "currency": "GBP",
          "description": "Standard consultation variant.",
          "links": {
            "clinician": "https://api.carebit.co/v1/clinicians/00000000-0000-4000-8000-000000000002",
            "location": "https://api.carebit.co/v1/locations/00000000-0000-4000-8000-000000000003"
          },
          "location_id": "00000000-0000-4000-8000-000000000003",
          "net_price": 6200,
          "permits_remote_bookings": false
        }
      ],
      "start_time": "2026-01-01T08:00:00Z",
      "status": "did_not_attend",
      "updated_at": "2026-01-01T09:00:00Z"
    }
  },
  "developer_platform_project_id": null,
  "livemode": false,
  "source": "dashboard",
  "type": "booking.did_not_attend"
}
```


---

# booking.end_time_reached

A Booking reached its scheduled end time.

## Payload schema

- `object`
  - `api_version` (`any`)
  - `context` (`object`) - Present only when `source` is `api`. Identifies the acting project and API key.
    - `developer_platform_api_key_id` (`string | null`) - format: `uuid`
    - `developer_platform_project_id` (`string | null`) - format: `uuid`
  - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `data` (`object`)
    - `object` (`object`)
      - `canceled_at` (`string | null`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
      - `cancellation_information` (`string | null`) - Additional notes recorded with the cancellation.
      - `cancellation_reason` (`string | null`) - enum: `abusive_behavior`, `booked_in_error`, `childcare_issues`, `clinician_annual_leave`, `clinician_emergency`, `clinician_schedule_change`, `colleague_unavailable`, `double_booked`, `duplicate_booking`, `equipment_issue`, `facility_unavailable`, `failed_to_pay_in_advance`, `family_emergency_illness`, `fear_or_anxiety`, `financial_concerns`, `financial_requirements_not_met`, `forgot_to_attend`, `insurance_company_not_permitted`, `insurance_coverage_issues`, `insurance_verification_failed`, `language_barrier`, `medication_interference`, `no_longer_required`, `no_response_to_recall`, `other`, `patient_deceased`, `patient_not_permitted`, `personal_emergency_illness`, `pre_booking_steps_not_completed`, `professional_discretion`, `referral_not_provided`, `relocated`, `rescheduled`, `scheduling_conflict`, `staff_issue`, `switched_to_another_clinician`, `symptoms_resolved`, `too_unwell`, `transportation_issues`, `unable_failed_to_prepare_for_booking`, `unknown`, `weather_conditions`, `wrong_clinician`, `wrong_location`, `wrong_service_type`, `null`; The reason the Booking was canceled. Required by Organizations that enforce cancellation reasons.
      - `cancellation_source` (`string | null`) - enum: `api`, `app`, `automation`, `patient`, `staff_member`, `null`; Who canceled the Booking. API cancellations use `api`.
      - `clinician` (`any`) - The clinician assigned to the booking.
      - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
      - `end_time` (`string | null`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
      - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
      - `information_for_patient` (`string | null`) - The sanitized HTML shown to the patient.
      - `information_for_staff_members` (`string | null`) - The sanitized HTML shown only to staff members.
      - `is_remote` (`boolean`) - Whether the Booking takes place remotely.
      - `links` (`object`) - URLs to related resources.
        - `clinician` (`string | null`) - format: `uri`; The full URL of a related resource.
        - `invoices` (`string`) - format: `uri`; The full URL of a related resource.
        - `letters` (`string`) - format: `uri`; The full URL of a related resource.
        - `notes` (`string`) - format: `uri`; The full URL of a related resource.
        - `service` (`string | null`) - format: `uri`; The full URL of a related resource.
        - `test_results` (`string`) - format: `uri`; The full URL of a related resource.
      - `location` (`any`) - The location where the booking takes place, or null for a remote booking.
      - `object` (`any`) - Discriminator value emitted at `object`.
      - `patient` (`any`) - The patient attending the booking.
      - `payor` (`any`) - The payor responsible for the booking's charges.
      - `recall_due_date` (`string | null`) - format: `date`; The date the Patient is due to return, in ISO 8601 format (YYYY-MM-DD). Present on recall Bookings. Null on diary Bookings.
      - `remote_method` (`string | null`) - enum: `native_video`, `null`; The remote consultation method. `native_video` uses Carebit Video.
      - `service` (`any`) - The service being provided during the booking.
      - `service_variants` (`array`) - The service variants selected for the booking.
        - `items` (`object`)
          - `clinician_id` (`string | null`) - format: `uuid`; The identifier of the clinician assigned to this service variant, when the variant is clinician-specific.
          - `currency` (`string | null`) - The ISO 4217 currency code used for this service variant. Must be one of `chf`, `eur`, `gbp`, or `usd`.
          - `description` (`string | null`) - The description of this service variant.
          - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
          - `links` (`object`) - URLs to related resources.
            - `clinician` (`string | null`) - format: `uri`; The full URL of a related resource.
            - `location` (`string | null`) - format: `uri`; The full URL of a related resource.
          - `location_id` (`string | null`) - format: `uuid`; The identifier of the location assigned to this service variant, when the variant is location-specific.
          - `net_price` (`integer | null`) - The net price of this service variant, before tax, in the currency's minor units.
          - `permits_remote_bookings` (`boolean`) - Whether this service variant can be used for remote bookings.
      - `start_time` (`string | null`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
      - `status` (`string | null`) - enum: `arrived`, `awaiting_payment`, `awaiting_recall`, `canceled`, `confirmed`, `did_not_attend`, `overdue_for_recall`, `prepared`, `recall_canceled`, `recall_expired`, `unconfirmed`, `null`; The Booking's current status. Null while Carebit is creating the record.
      - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `developer_platform_project_id` (`string | null`) - format: `uuid`; The project ID whose credential caused the change. Null for `dashboard` events.
  - `id` (`string`) - Event identifier prefixed with `evt_`.
  - `livemode` (`boolean`) - `false` for test-event deliveries.
  - `object` (`any`)
  - `source` (`string`) - enum: `api`, `dashboard`; Origin of the change. `api` means a Developer Platform mutation; `dashboard` means a Carebit-initiated change.
  - `type` (`any`)

### Example payload

```json
{
  "id": "evt_00000000-0000-4000-8000-000000000012",
  "object": "event",
  "api_version": "v1",
  "created_at": "2026-01-01T09:00:00Z",
  "data": {
    "object": {
      "id": "00000000-0000-4000-8000-000000000001",
      "object": "booking",
      "canceled_at": null,
      "cancellation_information": null,
      "cancellation_reason": null,
      "cancellation_source": null,
      "clinician": {
        "id": "00000000-0000-4000-8000-000000000002",
        "object": "clinician",
        "created_at": "2026-01-01T09:00:00Z",
        "display_name": "Dr Ada Lovelace",
        "email": "ada.lovelace@example.invalid",
        "first_name": "Ada",
        "last_name": "Lovelace",
        "links": {
          "bookings": "https://api.carebit.co/v1/bookings?clinician_id=00000000-0000-4000-8000-000000000002"
        },
        "medical_specialty": "General Medicine",
        "title": "Dr",
        "updated_at": "2026-01-01T09:00:00Z"
      },
      "created_at": "2026-01-01T09:00:00Z",
      "end_time": "2026-01-01T10:30:00Z",
      "information_for_patient": "This is a test booking. Please ignore.",
      "information_for_staff_members": "This is a test booking.",
      "is_remote": false,
      "links": {
        "clinician": "https://api.carebit.co/v1/clinicians/00000000-0000-4000-8000-000000000002",
        "invoices": "https://api.carebit.co/v1/invoices?booking_id=00000000-0000-4000-8000-000000000001",
        "letters": "https://api.carebit.co/v1/letters?booking_id=00000000-0000-4000-8000-000000000001",
        "notes": "https://api.carebit.co/v1/notes?booking_id=00000000-0000-4000-8000-000000000001",
        "service": "https://api.carebit.co/v1/services/00000000-0000-4000-8000-000000000005",
        "test_results": "https://api.carebit.co/v1/test_results?booking_id=00000000-0000-4000-8000-000000000001"
      },
      "location": {
        "id": "00000000-0000-4000-8000-000000000003",
        "object": "location",
        "address_line_1": "1 Test Street",
        "address_line_2": null,
        "city": "Test City",
        "country_code": "GB",
        "county": "Testshire",
        "created_at": "2026-01-01T09:00:00Z",
        "formatted_address": "1 Test Street, Test City, GB, TE1 1ST",
        "name": "Test Location",
        "postcode": "TE1 1ST",
        "updated_at": "2026-01-01T09:00:00Z"
      },
      "patient": {
        "id": "00000000-0000-4000-8000-000000000004",
        "object": "patient",
        "address_line_1": "1 Test Street",
        "address_line_2": null,
        "city": "Test City",
        "country_code": "GB",
        "county": "Testshire",
        "created_at": "2026-01-01T09:00:00Z",
        "creation_source": "api",
        "date_of_birth": "1970-01-01",
        "display_name": "Ms Test Patient",
        "email": "test.patient@example.invalid",
        "first_name": "Test",
        "is_opted_out_of_sms": false,
        "last_name": "Patient",
        "mobile": "7700900123",
        "mobile_country_dial_code": "GB",
        "nhs_number": "9990000000",
        "phone": "1234567890",
        "phone_country_dial_code": "GB",
        "phone_number": "+441234567890",
        "postcode": "TE1 1ST",
        "sex": "female",
        "title": "Ms",
        "updated_at": "2026-01-01T09:00:00Z"
      },
      "payor": null,
      "recall_due_date": null,
      "remote_method": null,
      "service": {
        "id": "00000000-0000-4000-8000-000000000005",
        "object": "service",
        "created_at": "2026-01-01T09:00:00Z",
        "description": "Test consultation service.",
        "duration_minutes": 30,
        "is_bookable_online": true,
        "name": "Test consultation",
        "service_variants": [
          {
            "id": "00000000-0000-4000-8000-000000000006",
            "clinician_id": "00000000-0000-4000-8000-000000000002",
            "currency": "GBP",
            "description": "Standard consultation variant.",
            "links": {
              "clinician": "https://api.carebit.co/v1/clinicians/00000000-0000-4000-8000-000000000002",
              "location": "https://api.carebit.co/v1/locations/00000000-0000-4000-8000-000000000003"
            },
            "location_id": "00000000-0000-4000-8000-000000000003",
            "net_price": 6200,
            "permits_remote_bookings": false
          }
        ],
        "tax_rate": null,
        "updated_at": "2026-01-01T09:00:00Z"
      },
      "service_variants": [
        {
          "id": "00000000-0000-4000-8000-000000000006",
          "clinician_id": "00000000-0000-4000-8000-000000000002",
          "currency": "GBP",
          "description": "Standard consultation variant.",
          "links": {
            "clinician": "https://api.carebit.co/v1/clinicians/00000000-0000-4000-8000-000000000002",
            "location": "https://api.carebit.co/v1/locations/00000000-0000-4000-8000-000000000003"
          },
          "location_id": "00000000-0000-4000-8000-000000000003",
          "net_price": 6200,
          "permits_remote_bookings": false
        }
      ],
      "start_time": "2026-01-01T10:00:00Z",
      "status": "confirmed",
      "updated_at": "2026-01-01T09:00:00Z"
    }
  },
  "developer_platform_project_id": null,
  "livemode": false,
  "source": "dashboard",
  "type": "booking.end_time_reached"
}
```


---

# booking.updated

A Booking's schedule, service, or metadata changed.

## Payload schema

- `object`
  - `api_version` (`any`)
  - `context` (`object`) - Present only when `source` is `api`. Identifies the acting project and API key.
    - `developer_platform_api_key_id` (`string | null`) - format: `uuid`
    - `developer_platform_project_id` (`string | null`) - format: `uuid`
  - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `data` (`object`)
    - `object` (`object`)
      - `canceled_at` (`string | null`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
      - `cancellation_information` (`string | null`) - Additional notes recorded with the cancellation.
      - `cancellation_reason` (`string | null`) - enum: `abusive_behavior`, `booked_in_error`, `childcare_issues`, `clinician_annual_leave`, `clinician_emergency`, `clinician_schedule_change`, `colleague_unavailable`, `double_booked`, `duplicate_booking`, `equipment_issue`, `facility_unavailable`, `failed_to_pay_in_advance`, `family_emergency_illness`, `fear_or_anxiety`, `financial_concerns`, `financial_requirements_not_met`, `forgot_to_attend`, `insurance_company_not_permitted`, `insurance_coverage_issues`, `insurance_verification_failed`, `language_barrier`, `medication_interference`, `no_longer_required`, `no_response_to_recall`, `other`, `patient_deceased`, `patient_not_permitted`, `personal_emergency_illness`, `pre_booking_steps_not_completed`, `professional_discretion`, `referral_not_provided`, `relocated`, `rescheduled`, `scheduling_conflict`, `staff_issue`, `switched_to_another_clinician`, `symptoms_resolved`, `too_unwell`, `transportation_issues`, `unable_failed_to_prepare_for_booking`, `unknown`, `weather_conditions`, `wrong_clinician`, `wrong_location`, `wrong_service_type`, `null`; The reason the Booking was canceled. Required by Organizations that enforce cancellation reasons.
      - `cancellation_source` (`string | null`) - enum: `api`, `app`, `automation`, `patient`, `staff_member`, `null`; Who canceled the Booking. API cancellations use `api`.
      - `clinician` (`any`) - The clinician assigned to the booking.
      - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
      - `end_time` (`string | null`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
      - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
      - `information_for_patient` (`string | null`) - The sanitized HTML shown to the patient.
      - `information_for_staff_members` (`string | null`) - The sanitized HTML shown only to staff members.
      - `is_remote` (`boolean`) - Whether the Booking takes place remotely.
      - `links` (`object`) - URLs to related resources.
        - `clinician` (`string | null`) - format: `uri`; The full URL of a related resource.
        - `invoices` (`string`) - format: `uri`; The full URL of a related resource.
        - `letters` (`string`) - format: `uri`; The full URL of a related resource.
        - `notes` (`string`) - format: `uri`; The full URL of a related resource.
        - `service` (`string | null`) - format: `uri`; The full URL of a related resource.
        - `test_results` (`string`) - format: `uri`; The full URL of a related resource.
      - `location` (`any`) - The location where the booking takes place, or null for a remote booking.
      - `object` (`any`) - Discriminator value emitted at `object`.
      - `patient` (`any`) - The patient attending the booking.
      - `payor` (`any`) - The payor responsible for the booking's charges.
      - `recall_due_date` (`string | null`) - format: `date`; The date the Patient is due to return, in ISO 8601 format (YYYY-MM-DD). Present on recall Bookings. Null on diary Bookings.
      - `remote_method` (`string | null`) - enum: `native_video`, `null`; The remote consultation method. `native_video` uses Carebit Video.
      - `service` (`any`) - The service being provided during the booking.
      - `service_variants` (`array`) - The service variants selected for the booking.
        - `items` (`object`)
          - `clinician_id` (`string | null`) - format: `uuid`; The identifier of the clinician assigned to this service variant, when the variant is clinician-specific.
          - `currency` (`string | null`) - The ISO 4217 currency code used for this service variant. Must be one of `chf`, `eur`, `gbp`, or `usd`.
          - `description` (`string | null`) - The description of this service variant.
          - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
          - `links` (`object`) - URLs to related resources.
            - `clinician` (`string | null`) - format: `uri`; The full URL of a related resource.
            - `location` (`string | null`) - format: `uri`; The full URL of a related resource.
          - `location_id` (`string | null`) - format: `uuid`; The identifier of the location assigned to this service variant, when the variant is location-specific.
          - `net_price` (`integer | null`) - The net price of this service variant, before tax, in the currency's minor units.
          - `permits_remote_bookings` (`boolean`) - Whether this service variant can be used for remote bookings.
      - `start_time` (`string | null`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
      - `status` (`string | null`) - enum: `arrived`, `awaiting_payment`, `awaiting_recall`, `canceled`, `confirmed`, `did_not_attend`, `overdue_for_recall`, `prepared`, `recall_canceled`, `recall_expired`, `unconfirmed`, `null`; The Booking's current status. Null while Carebit is creating the record.
      - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `developer_platform_project_id` (`string | null`) - format: `uuid`; The project ID whose credential caused the change. Null for `dashboard` events.
  - `id` (`string`) - Event identifier prefixed with `evt_`.
  - `livemode` (`boolean`) - `false` for test-event deliveries.
  - `object` (`any`)
  - `source` (`string`) - enum: `api`, `dashboard`; Origin of the change. `api` means a Developer Platform mutation; `dashboard` means a Carebit-initiated change.
  - `type` (`any`)

### Example payload

```json
{
  "id": "evt_00000000-0000-4000-8000-000000000012",
  "object": "event",
  "api_version": "v1",
  "created_at": "2026-01-01T09:00:00Z",
  "data": {
    "object": {
      "id": "00000000-0000-4000-8000-000000000001",
      "object": "booking",
      "canceled_at": null,
      "cancellation_information": null,
      "cancellation_reason": null,
      "cancellation_source": null,
      "clinician": {
        "id": "00000000-0000-4000-8000-000000000002",
        "object": "clinician",
        "created_at": "2026-01-01T09:00:00Z",
        "display_name": "Dr Ada Lovelace",
        "email": "ada.lovelace@example.invalid",
        "first_name": "Ada",
        "last_name": "Lovelace",
        "links": {
          "bookings": "https://api.carebit.co/v1/bookings?clinician_id=00000000-0000-4000-8000-000000000002"
        },
        "medical_specialty": "General Medicine",
        "title": "Dr",
        "updated_at": "2026-01-01T09:00:00Z"
      },
      "created_at": "2026-01-01T09:00:00Z",
      "end_time": "2026-01-01T10:30:00Z",
      "information_for_patient": "This is a test booking. Please ignore.",
      "information_for_staff_members": "This is a test booking.",
      "is_remote": false,
      "links": {
        "clinician": "https://api.carebit.co/v1/clinicians/00000000-0000-4000-8000-000000000002",
        "invoices": "https://api.carebit.co/v1/invoices?booking_id=00000000-0000-4000-8000-000000000001",
        "letters": "https://api.carebit.co/v1/letters?booking_id=00000000-0000-4000-8000-000000000001",
        "notes": "https://api.carebit.co/v1/notes?booking_id=00000000-0000-4000-8000-000000000001",
        "service": "https://api.carebit.co/v1/services/00000000-0000-4000-8000-000000000005",
        "test_results": "https://api.carebit.co/v1/test_results?booking_id=00000000-0000-4000-8000-000000000001"
      },
      "location": {
        "id": "00000000-0000-4000-8000-000000000003",
        "object": "location",
        "address_line_1": "1 Test Street",
        "address_line_2": null,
        "city": "Test City",
        "country_code": "GB",
        "county": "Testshire",
        "created_at": "2026-01-01T09:00:00Z",
        "formatted_address": "1 Test Street, Test City, GB, TE1 1ST",
        "name": "Test Location",
        "postcode": "TE1 1ST",
        "updated_at": "2026-01-01T09:00:00Z"
      },
      "patient": {
        "id": "00000000-0000-4000-8000-000000000004",
        "object": "patient",
        "address_line_1": "1 Test Street",
        "address_line_2": null,
        "city": "Test City",
        "country_code": "GB",
        "county": "Testshire",
        "created_at": "2026-01-01T09:00:00Z",
        "creation_source": "api",
        "date_of_birth": "1970-01-01",
        "display_name": "Ms Test Patient",
        "email": "test.patient@example.invalid",
        "first_name": "Test",
        "is_opted_out_of_sms": false,
        "last_name": "Patient",
        "mobile": "7700900123",
        "mobile_country_dial_code": "GB",
        "nhs_number": "9990000000",
        "phone": "1234567890",
        "phone_country_dial_code": "GB",
        "phone_number": "+441234567890",
        "postcode": "TE1 1ST",
        "sex": "female",
        "title": "Ms",
        "updated_at": "2026-01-01T09:00:00Z"
      },
      "payor": null,
      "recall_due_date": null,
      "remote_method": null,
      "service": {
        "id": "00000000-0000-4000-8000-000000000005",
        "object": "service",
        "created_at": "2026-01-01T09:00:00Z",
        "description": "Test consultation service.",
        "duration_minutes": 30,
        "is_bookable_online": true,
        "name": "Test consultation",
        "service_variants": [
          {
            "id": "00000000-0000-4000-8000-000000000006",
            "clinician_id": "00000000-0000-4000-8000-000000000002",
            "currency": "GBP",
            "description": "Standard consultation variant.",
            "links": {
              "clinician": "https://api.carebit.co/v1/clinicians/00000000-0000-4000-8000-000000000002",
              "location": "https://api.carebit.co/v1/locations/00000000-0000-4000-8000-000000000003"
            },
            "location_id": "00000000-0000-4000-8000-000000000003",
            "net_price": 6200,
            "permits_remote_bookings": false
          }
        ],
        "tax_rate": null,
        "updated_at": "2026-01-01T09:00:00Z"
      },
      "service_variants": [
        {
          "id": "00000000-0000-4000-8000-000000000006",
          "clinician_id": "00000000-0000-4000-8000-000000000002",
          "currency": "GBP",
          "description": "Standard consultation variant.",
          "links": {
            "clinician": "https://api.carebit.co/v1/clinicians/00000000-0000-4000-8000-000000000002",
            "location": "https://api.carebit.co/v1/locations/00000000-0000-4000-8000-000000000003"
          },
          "location_id": "00000000-0000-4000-8000-000000000003",
          "net_price": 6200,
          "permits_remote_bookings": false
        }
      ],
      "start_time": "2026-01-01T10:00:00Z",
      "status": "confirmed",
      "updated_at": "2026-01-01T09:00:00Z"
    }
  },
  "developer_platform_project_id": null,
  "livemode": false,
  "source": "dashboard",
  "type": "booking.updated"
}
```


---

# digital_form_response.completed

A Patient completed a DigitalFormResponse.

## Payload schema

- `object`
  - `api_version` (`any`)
  - `context` (`object`) - Present only when `source` is `api`. Identifies the acting project and API key.
    - `developer_platform_api_key_id` (`string | null`) - format: `uuid`
    - `developer_platform_project_id` (`string | null`) - format: `uuid`
  - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `data` (`object`)
    - `object` (`object`)
      - `answers` (`array`) - The answers currently recorded for the DigitalFormResponse.
        - `items` (`object`)
          - `attachment_url` (`string | null`) - format: `uri`; The temporary URL for an attached answer.
          - `date_value` (`string | null`) - format: `date`; The date supplied for a date question.
          - `digital_form_question` (`object`) - A question on a DigitalForm. Embedded on DigitalForm and on each DigitalFormResponse answer.
            - `choices` (`array`) - The choices available for a choice question.
              - `items` (`object`)
                - `id` (`string`) - format: `uuid`; The identifier of the DigitalFormQuestionChoice.
                - `numerical_value` (`number | null`) - The optional numerical value assigned to the choice.
                - `text_value` (`string | null`) - The optional machine-readable text value assigned to the choice.
                - `title` (`string`) - The choice shown to the Patient.
            - `help_text` (`string | null`) - The supplementary guidance shown with the question.
            - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
            - `is_answer_required` (`boolean`) - Whether the Patient must answer the question.
            - `list_order_number` (`integer | null`) - The position of the question in the DigitalForm.
            - `question_type` (`string`) - enum: `consent_required`, `information_statement`, `multiple_choice_input`, `single_choice_input`, `text_input`, `number_input`, `date_input`, `signature_input`; The input and consent behavior of the question.
            - `title` (`string`) - The question shown to the Patient.
          - `digital_form_question_choice_id` (`string | null`) - format: `uuid`; The selected DigitalFormQuestionChoice.
          - `digital_form_question_id` (`string`) - format: `uuid`; The DigitalFormQuestion answered.
          - `has_consented` (`boolean | null`) - Whether the Patient granted the requested consent.
          - `id` (`string`) - format: `uuid`; The identifier of the DigitalFormQuestionAnswer.
          - `numerical_value` (`number | null`) - The numerical answer.
          - `text_value` (`string | null`) - The text answer or selected choice title.
      - `booking_id` (`string | null`) - format: `uuid`; The Booking associated with the response.
      - `completed_at` (`string | null`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
      - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
      - `digital_form` (`object`)
        - `attachment_url` (`string | null`) - format: `uri`; The temporary URL for the attachment displayed with the DigitalForm.
        - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
        - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
        - `object` (`any`) - Discriminator value emitted at `object`.
        - `patient_instructions` (`string | null`) - The sanitized instructions shown to the Patient.
        - `questions` (`array`) - The ordered questions included in the DigitalForm.
          - `items` (`object`) - A question on a DigitalForm. Embedded on DigitalForm and on each DigitalFormResponse answer.
            - `choices` (`array`) - The choices available for a choice question.
              - `items` (`object`)
                - `id` (`string`) - format: `uuid`; The identifier of the DigitalFormQuestionChoice.
                - `numerical_value` (`number | null`) - The optional numerical value assigned to the choice.
                - `text_value` (`string | null`) - The optional machine-readable text value assigned to the choice.
                - `title` (`string`) - The choice shown to the Patient.
            - `help_text` (`string | null`) - The supplementary guidance shown with the question.
            - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
            - `is_answer_required` (`boolean`) - Whether the Patient must answer the question.
            - `list_order_number` (`integer | null`) - The position of the question in the DigitalForm.
            - `question_type` (`string`) - enum: `consent_required`, `information_statement`, `multiple_choice_input`, `single_choice_input`, `text_input`, `number_input`, `date_input`, `signature_input`; The input and consent behavior of the question.
            - `title` (`string`) - The question shown to the Patient.
        - `title` (`string`) - The title of the DigitalForm.
        - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
      - `due_at` (`string | null`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
      - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
      - `links` (`object`) - URLs to related resources.
        - `patient` (`string`) - format: `uri`; The full URL of a related resource.
        - `transmissions` (`string`) - format: `uri`; The full URL of a related resource.
      - `object` (`any`) - Discriminator value emitted at `object`.
      - `patient_id` (`string`) - format: `uuid`; The Patient asked to complete the DigitalForm.
      - `status` (`string`) - enum: `awaiting_completion`, `partially_completed`, `overdue`, `completed`; The completion status of the DigitalFormResponse.
      - `total_score` (`integer | null`) - The sum of numerical answers configured to contribute to the score.
      - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `developer_platform_project_id` (`string | null`) - format: `uuid`; The project ID whose credential caused the change. Null for `dashboard` events.
  - `id` (`string`) - Event identifier prefixed with `evt_`.
  - `livemode` (`boolean`) - `false` for test-event deliveries.
  - `object` (`any`)
  - `source` (`string`) - enum: `api`, `dashboard`; Origin of the change. `api` means a Developer Platform mutation; `dashboard` means a Carebit-initiated change.
  - `type` (`any`)

### Example payload

```json
{
  "id": "evt_00000000-0000-4000-8000-000000000012",
  "object": "event",
  "api_version": "v1",
  "created_at": "2026-01-01T09:00:00Z",
  "data": {
    "object": {
      "id": "00000000-0000-4000-8000-000000000021",
      "object": "digital_form_response",
      "answers": [
        {
          "id": "00000000-0000-4000-8000-000000000024",
          "attachment_url": null,
          "date_value": null,
          "digital_form_question": {
            "id": "00000000-0000-4000-8000-000000000022",
            "choices": [
              {
                "id": "00000000-0000-4000-8000-000000000023",
                "numerical_value": 1,
                "text_value": "yes",
                "title": "Yes"
              }
            ],
            "help_text": "Select every option that applies.",
            "is_answer_required": true,
            "list_order_number": 1,
            "question_type": "single_choice_input",
            "title": "Do you consent to the procedure?"
          },
          "digital_form_question_choice_id": "00000000-0000-4000-8000-000000000023",
          "digital_form_question_id": "00000000-0000-4000-8000-000000000022",
          "has_consented": null,
          "numerical_value": 1,
          "text_value": "Yes"
        }
      ],
      "booking_id": "00000000-0000-4000-8000-000000000001",
      "completed_at": "2026-01-01T09:00:00Z",
      "created_at": "2026-01-01T09:00:00Z",
      "digital_form": {
        "id": "00000000-0000-4000-8000-000000000020",
        "object": "digital_form",
        "attachment_url": null,
        "created_at": "2026-01-01T09:00:00Z",
        "patient_instructions": "Please complete this consent form.",
        "questions": [
          {
            "id": "00000000-0000-4000-8000-000000000022",
            "choices": [
              {
                "id": "00000000-0000-4000-8000-000000000023",
                "numerical_value": 1,
                "text_value": "yes",
                "title": "Yes"
              }
            ],
            "help_text": "Select every option that applies.",
            "is_answer_required": true,
            "list_order_number": 1,
            "question_type": "single_choice_input",
            "title": "Do you consent to the procedure?"
          }
        ],
        "title": "Pre-operative consent",
        "updated_at": "2026-01-01T09:00:00Z"
      },
      "due_at": "2026-01-01T08:30:00Z",
      "links": {
        "patient": "https://api.carebit.co/v1/patients/00000000-0000-4000-8000-000000000004",
        "transmissions": "https://api.carebit.co/v1/transmissions?patient_id=00000000-0000-4000-8000-000000000004&resource_type=digital_form_response"
      },
      "patient_id": "00000000-0000-4000-8000-000000000004",
      "status": "completed",
      "total_score": 0,
      "updated_at": "2026-01-01T09:00:00Z"
    }
  },
  "developer_platform_project_id": null,
  "livemode": false,
  "source": "dashboard",
  "type": "digital_form_response.completed"
}
```


---

# expirable_file.available

An ExpirableFile is available to download.

## Payload schema

- `object`
  - `api_version` (`any`)
  - `context` (`object`) - Present only when `source` is `api`. Identifies the acting project and API key.
    - `developer_platform_api_key_id` (`string | null`) - format: `uuid`
    - `developer_platform_project_id` (`string | null`) - format: `uuid`
  - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `data` (`object`)
    - `object` (`object`)
      - `attachment_url` (`string | null`) - format: `uri`; The temporary signed download URL, or null while Carebit generates the file and download URL.
      - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
      - `expires_at` (`string`) - format: `date-time`; The time after which Carebit can delete the file.
      - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
      - `object` (`any`) - Discriminator value emitted at `object`.
      - `status` (`string`) - enum: `processing`, `succeeded`; Whether Carebit is still creating the report or the file is ready to download.
      - `title` (`string`) - enum: `account_balances`, `audio_recordings`, `billing_codes`, `booked_services`, `bookings`, `bookings_summary_for_child_organizations`, `bookings_with_invoices`, `bookings_without_invoices`, `care_episodes`, `cari_credits_usage`, `credit_notes`, `creditors`, `debtors`, `debtors_per_invoice`, `end_of_year_accounts_zip`, `expenses`, `financial_summary`, `indemnity_bookings`, `indemnity_income`, `invoice_line_items`, `issued_invoices`, `issued_invoices_summary_for_child_organizations`, `leads_and_enquiries`, `patient_referrals`, `patient_registrations`, `prescriptions_report`, `product_sales_audit_log`, `product_sales_report`, `product_stock_levels_report`, `profit_and_loss`, `recall_bookings`, `received_payments`, `received_payments_for_invoice_line_items`, `received_payments_summary_for_child_organizations`, `referral_summary`, `refunds`, `remittance_adjustments`, `service_variants`, `tasks_due_per_staff_member`, `tasks_raised`; The report type used as the title of the ExpirableFile.
      - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `developer_platform_project_id` (`string | null`) - format: `uuid`; The project ID whose credential caused the change. Null for `dashboard` events.
  - `id` (`string`) - Event identifier prefixed with `evt_`.
  - `livemode` (`boolean`) - `false` for test-event deliveries.
  - `object` (`any`)
  - `source` (`string`) - enum: `api`, `dashboard`; Origin of the change. `api` means a Developer Platform mutation; `dashboard` means a Carebit-initiated change.
  - `type` (`any`)

### Example payload

```json
{
  "id": "evt_00000000-0000-4000-8000-000000000012",
  "object": "event",
  "api_version": "v1",
  "created_at": "2026-01-01T09:00:00Z",
  "data": {
    "object": {
      "id": "00000000-0000-4000-8000-000000000019",
      "object": "expirable_file",
      "attachment_url": "https://files.example.invalid/reports/bookings.csv?signature=test",
      "created_at": "2026-01-01T09:00:00Z",
      "expires_at": "2026-01-02T09:00:00Z",
      "status": "succeeded",
      "title": "bookings",
      "updated_at": "2026-01-01T09:00:00Z"
    }
  },
  "developer_platform_project_id": null,
  "livemode": false,
  "source": "dashboard",
  "type": "expirable_file.available"
}
```


---

# lead.converted_to_patient

A Lead was converted to a Patient.

## Payload schema

- `object`
  - `api_version` (`any`)
  - `context` (`object`) - Present only when `source` is `api`. Identifies the acting project and API key.
    - `developer_platform_api_key_id` (`string | null`) - format: `uuid`
    - `developer_platform_project_id` (`string | null`) - format: `uuid`
  - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `data` (`object`)
    - `object` (`object`)
      - `address_line_1` (`string | null`) - The primary address line of the lead.
      - `address_line_2` (`string | null`) - The secondary address line of the lead.
      - `attachments` (`array`) - The files attached to the lead.
        - `items` (`object`)
          - `download_url` (`string | null`) - format: `uri`; The short-lived signed download URL for the attachment. Null while the malware scan is not complete.
          - `filename` (`string | null`) - The original filename of the attachment.
          - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
      - `city` (`string | null`) - The city in the lead's postal address.
      - `clinician` (`any`) - The clinician the lead is assigned to, when recorded.
      - `country_code` (`string | null`) - The ISO 3166-1 alpha-2 country code for the postal address, such as `GB` for the United Kingdom.
      - `county` (`string | null`) - The county or region in the lead's postal address.
      - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
      - `creation_source` (`string | null`) - How the Lead was created. `api` means the record was created through the Developer Platform. Read-only.
      - `date_of_birth` (`string | null`) - format: `date`; The date of birth of the lead, in ISO 8601 format (YYYY-MM-DD).
      - `display_name` (`string | null`) - The formatted display name of the lead, including their title when recorded.
      - `email` (`string | null`) - format: `email`; The contact email address of the lead.
      - `first_name` (`string`) - The first name of the lead.
      - `gdpr_consent_granted_at` (`string | null`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
      - `gdpr_consent_withdrawn_at` (`string | null`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
      - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
      - `internal_notes` (`string | null`) - Internal notes shown in the Notes box next to presenting problem on the Carebit lead enquiry screen. Distinct from `referral_notes`.
      - `is_converted_to_patient` (`boolean`) - Whether the lead has been converted to a patient. Read-only.
      - `is_lost` (`boolean`) - Whether the lead has been marked as lost. Read-only.
      - `is_opted_out_of_sms` (`boolean`) - Whether the lead has opted out of SMS communication.
      - `is_signed_up_to_newsletters` (`boolean`) - Whether the lead has signed up to receive newsletters.
      - `last_name` (`string`) - The last name of the lead.
      - `lead_type` (`string`) - enum: `inquiry`, `referral`; Whether the record is a patient inquiry or a referral.
      - `links` (`object`) - URLs to related resources. `remote_file_import_batch` is present on create responses when at least one attachment was submitted.
        - `clinician` (`string | null`) - format: `uri`; The full URL of a related resource.
        - `remote_file_import_batch` (`string`) - format: `uri`; The full URL of a related resource.
        - `self` (`string`) - format: `uri`; The full URL of a related resource.
        - `service` (`string | null`) - format: `uri`; The full URL of a related resource.
      - `mobile` (`string | null`) - The mobile phone number of the lead, without the country dial code.
      - `mobile_country_dial_code` (`string | null`) - The ISO 3166-1 alpha-2 country code that selects the international dial code for `mobile`, for example `GB` selects `+44`.
      - `object` (`any`) - Discriminator value emitted at `object`.
      - `organization_privacy_policy_consent_granted_at` (`string | null`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
      - `patient_id` (`string | null`) - format: `uuid`; The identifier of the Patient this Lead was converted to. Null until conversion. Read-only.
      - `phone` (`string | null`) - The landline phone number of the lead, without the country dial code.
      - `phone_country_dial_code` (`string | null`) - The ISO 3166-1 alpha-2 country code that selects the international dial code for `phone`, for example `GB` selects `+44`.
      - `postcode` (`string | null`) - The postal code in the lead's postal address.
      - `presenting_problem` (`string | null`) - The presenting problem the lead described. Shown next to Notes on the Carebit lead enquiry screen.
      - `referral_notes` (`string | null`) - The referral notes shown on the Carebit lead enquiry screen.
      - `referral_source` (`string | null`) - enum: `consultant`, `embassy`, `family_or_friend`, `gp_practice`, `hospital`, `insurance_company`, `physiotherapist`, `presentation_talk`, `previous_patient`, `private_practice`, `search_engine`, `self_referral`, `social_media`, `website`, `other`, `null`; The referral source shown on the Carebit lead enquiry screen.
      - `remote_file_import_batch_id` (`string`) - format: `uuid`; The identifier of the remote file import batch created for the submitted attachments. Present on create responses when at least one attachment was submitted.
      - `service` (`any`) - The Service the Lead is inquiring about, when recorded.
      - `sex` (`string | null`) - The sex of the Lead as supplied on the inquiry.
      - `stage` (`any`) - The current pipeline stage of the lead. Read-only; use `stage_id` when updating the lead.
      - `title` (`string | null`) - The personal title of the lead, when recorded.
      - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `developer_platform_project_id` (`string | null`) - format: `uuid`; The project ID whose credential caused the change. Null for `dashboard` events.
  - `id` (`string`) - Event identifier prefixed with `evt_`.
  - `livemode` (`boolean`) - `false` for test-event deliveries.
  - `object` (`any`)
  - `source` (`string`) - enum: `api`, `dashboard`; Origin of the change. `api` means a Developer Platform mutation; `dashboard` means a Carebit-initiated change.
  - `type` (`any`)

### Example payload

```json
{
  "id": "evt_00000000-0000-4000-8000-000000000012",
  "object": "event",
  "api_version": "v1",
  "created_at": "2026-01-01T09:00:00Z",
  "data": {
    "object": {
      "id": "00000000-0000-4000-8000-000000000013",
      "object": "lead",
      "address_line_1": "1 Test Street",
      "address_line_2": null,
      "attachments": [],
      "city": "Test City",
      "clinician": {
        "id": "00000000-0000-4000-8000-000000000002",
        "object": "clinician",
        "created_at": "2026-01-01T09:00:00Z",
        "display_name": "Dr Ada Lovelace",
        "email": "ada.lovelace@example.invalid",
        "first_name": "Ada",
        "last_name": "Lovelace",
        "links": {
          "bookings": "https://api.carebit.co/v1/bookings?clinician_id=00000000-0000-4000-8000-000000000002"
        },
        "medical_specialty": "General Medicine",
        "title": "Dr",
        "updated_at": "2026-01-01T09:00:00Z"
      },
      "country_code": "GB",
      "county": "Testshire",
      "created_at": "2026-01-01T09:00:00Z",
      "creation_source": "api",
      "date_of_birth": "1990-01-01",
      "display_name": "Ms Test Lead",
      "email": "test.lead@example.invalid",
      "first_name": "Test",
      "gdpr_consent_granted_at": "2026-01-01T09:00:00Z",
      "gdpr_consent_withdrawn_at": null,
      "internal_notes": "Asked about evening appointments with Dr Smith.",
      "is_converted_to_patient": true,
      "is_lost": false,
      "is_opted_out_of_sms": false,
      "is_signed_up_to_newsletters": false,
      "last_name": "Lead",
      "lead_type": "inquiry",
      "links": {
        "clinician": "https://api.carebit.co/v1/clinicians/00000000-0000-4000-8000-000000000002",
        "self": "https://api.carebit.co/v1/leads/00000000-0000-4000-8000-000000000013",
        "service": "https://api.carebit.co/v1/services/00000000-0000-4000-8000-000000000005"
      },
      "mobile": "7700900123",
      "mobile_country_dial_code": "GB",
      "organization_privacy_policy_consent_granted_at": "2026-01-01T09:00:00Z",
      "patient_id": "00000000-0000-4000-8000-000000000004",
      "phone": null,
      "phone_country_dial_code": null,
      "postcode": "TE1 1ST",
      "presenting_problem": "Persistent knee pain",
      "referral_notes": "Referred by Dr Patel at Riverside Medical.",
      "referral_source": "gp_practice",
      "service": {
        "id": "00000000-0000-4000-8000-000000000005",
        "object": "service",
        "created_at": "2026-01-01T09:00:00Z",
        "description": "Test consultation service.",
        "duration_minutes": 30,
        "is_bookable_online": true,
        "name": "Test consultation",
        "service_variants": [
          {
            "id": "00000000-0000-4000-8000-000000000006",
            "clinician_id": "00000000-0000-4000-8000-000000000002",
            "currency": "GBP",
            "description": "Standard consultation variant.",
            "links": {
              "clinician": "https://api.carebit.co/v1/clinicians/00000000-0000-4000-8000-000000000002",
              "location": "https://api.carebit.co/v1/locations/00000000-0000-4000-8000-000000000003"
            },
            "location_id": "00000000-0000-4000-8000-000000000003",
            "net_price": 6200,
            "permits_remote_bookings": false
          }
        ],
        "tax_rate": null,
        "updated_at": "2026-01-01T09:00:00Z"
      },
      "sex": "female",
      "stage": {
        "id": "00000000-0000-4000-8000-000000000015",
        "object": "lead_stage",
        "created_at": "2026-01-01T09:00:00Z",
        "is_conversion_stage": false,
        "is_lost_stage": false,
        "name": "Contact made",
        "position": 5,
        "updated_at": "2026-01-01T09:00:00Z"
      },
      "title": "Ms",
      "updated_at": "2026-01-01T09:00:00Z"
    }
  },
  "developer_platform_project_id": null,
  "livemode": false,
  "source": "dashboard",
  "type": "lead.converted_to_patient"
}
```


---

# lead.created

A Lead was created.

## Payload schema

- `object`
  - `api_version` (`any`)
  - `context` (`object`) - Present only when `source` is `api`. Identifies the acting project and API key.
    - `developer_platform_api_key_id` (`string | null`) - format: `uuid`
    - `developer_platform_project_id` (`string | null`) - format: `uuid`
  - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `data` (`object`)
    - `object` (`object`)
      - `address_line_1` (`string | null`) - The primary address line of the lead.
      - `address_line_2` (`string | null`) - The secondary address line of the lead.
      - `attachments` (`array`) - The files attached to the lead.
        - `items` (`object`)
          - `download_url` (`string | null`) - format: `uri`; The short-lived signed download URL for the attachment. Null while the malware scan is not complete.
          - `filename` (`string | null`) - The original filename of the attachment.
          - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
      - `city` (`string | null`) - The city in the lead's postal address.
      - `clinician` (`any`) - The clinician the lead is assigned to, when recorded.
      - `country_code` (`string | null`) - The ISO 3166-1 alpha-2 country code for the postal address, such as `GB` for the United Kingdom.
      - `county` (`string | null`) - The county or region in the lead's postal address.
      - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
      - `creation_source` (`string | null`) - How the Lead was created. `api` means the record was created through the Developer Platform. Read-only.
      - `date_of_birth` (`string | null`) - format: `date`; The date of birth of the lead, in ISO 8601 format (YYYY-MM-DD).
      - `display_name` (`string | null`) - The formatted display name of the lead, including their title when recorded.
      - `email` (`string | null`) - format: `email`; The contact email address of the lead.
      - `first_name` (`string`) - The first name of the lead.
      - `gdpr_consent_granted_at` (`string | null`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
      - `gdpr_consent_withdrawn_at` (`string | null`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
      - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
      - `internal_notes` (`string | null`) - Internal notes shown in the Notes box next to presenting problem on the Carebit lead enquiry screen. Distinct from `referral_notes`.
      - `is_converted_to_patient` (`boolean`) - Whether the lead has been converted to a patient. Read-only.
      - `is_lost` (`boolean`) - Whether the lead has been marked as lost. Read-only.
      - `is_opted_out_of_sms` (`boolean`) - Whether the lead has opted out of SMS communication.
      - `is_signed_up_to_newsletters` (`boolean`) - Whether the lead has signed up to receive newsletters.
      - `last_name` (`string`) - The last name of the lead.
      - `lead_type` (`string`) - enum: `inquiry`, `referral`; Whether the record is a patient inquiry or a referral.
      - `links` (`object`) - URLs to related resources. `remote_file_import_batch` is present on create responses when at least one attachment was submitted.
        - `clinician` (`string | null`) - format: `uri`; The full URL of a related resource.
        - `remote_file_import_batch` (`string`) - format: `uri`; The full URL of a related resource.
        - `self` (`string`) - format: `uri`; The full URL of a related resource.
        - `service` (`string | null`) - format: `uri`; The full URL of a related resource.
      - `mobile` (`string | null`) - The mobile phone number of the lead, without the country dial code.
      - `mobile_country_dial_code` (`string | null`) - The ISO 3166-1 alpha-2 country code that selects the international dial code for `mobile`, for example `GB` selects `+44`.
      - `object` (`any`) - Discriminator value emitted at `object`.
      - `organization_privacy_policy_consent_granted_at` (`string | null`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
      - `patient_id` (`string | null`) - format: `uuid`; The identifier of the Patient this Lead was converted to. Null until conversion. Read-only.
      - `phone` (`string | null`) - The landline phone number of the lead, without the country dial code.
      - `phone_country_dial_code` (`string | null`) - The ISO 3166-1 alpha-2 country code that selects the international dial code for `phone`, for example `GB` selects `+44`.
      - `postcode` (`string | null`) - The postal code in the lead's postal address.
      - `presenting_problem` (`string | null`) - The presenting problem the lead described. Shown next to Notes on the Carebit lead enquiry screen.
      - `referral_notes` (`string | null`) - The referral notes shown on the Carebit lead enquiry screen.
      - `referral_source` (`string | null`) - enum: `consultant`, `embassy`, `family_or_friend`, `gp_practice`, `hospital`, `insurance_company`, `physiotherapist`, `presentation_talk`, `previous_patient`, `private_practice`, `search_engine`, `self_referral`, `social_media`, `website`, `other`, `null`; The referral source shown on the Carebit lead enquiry screen.
      - `remote_file_import_batch_id` (`string`) - format: `uuid`; The identifier of the remote file import batch created for the submitted attachments. Present on create responses when at least one attachment was submitted.
      - `service` (`any`) - The Service the Lead is inquiring about, when recorded.
      - `sex` (`string | null`) - The sex of the Lead as supplied on the inquiry.
      - `stage` (`any`) - The current pipeline stage of the lead. Read-only; use `stage_id` when updating the lead.
      - `title` (`string | null`) - The personal title of the lead, when recorded.
      - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `developer_platform_project_id` (`string | null`) - format: `uuid`; The project ID whose credential caused the change. Null for `dashboard` events.
  - `id` (`string`) - Event identifier prefixed with `evt_`.
  - `livemode` (`boolean`) - `false` for test-event deliveries.
  - `object` (`any`)
  - `source` (`string`) - enum: `api`, `dashboard`; Origin of the change. `api` means a Developer Platform mutation; `dashboard` means a Carebit-initiated change.
  - `type` (`any`)

### Example payload

```json
{
  "id": "evt_00000000-0000-4000-8000-000000000012",
  "object": "event",
  "api_version": "v1",
  "created_at": "2026-01-01T09:00:00Z",
  "data": {
    "object": {
      "id": "00000000-0000-4000-8000-000000000013",
      "object": "lead",
      "address_line_1": "1 Test Street",
      "address_line_2": null,
      "attachments": [],
      "city": "Test City",
      "clinician": {
        "id": "00000000-0000-4000-8000-000000000002",
        "object": "clinician",
        "created_at": "2026-01-01T09:00:00Z",
        "display_name": "Dr Ada Lovelace",
        "email": "ada.lovelace@example.invalid",
        "first_name": "Ada",
        "last_name": "Lovelace",
        "links": {
          "bookings": "https://api.carebit.co/v1/bookings?clinician_id=00000000-0000-4000-8000-000000000002"
        },
        "medical_specialty": "General Medicine",
        "title": "Dr",
        "updated_at": "2026-01-01T09:00:00Z"
      },
      "country_code": "GB",
      "county": "Testshire",
      "created_at": "2026-01-01T09:00:00Z",
      "creation_source": "api",
      "date_of_birth": "1990-01-01",
      "display_name": "Ms Test Lead",
      "email": "test.lead@example.invalid",
      "first_name": "Test",
      "gdpr_consent_granted_at": "2026-01-01T09:00:00Z",
      "gdpr_consent_withdrawn_at": null,
      "internal_notes": "Asked about evening appointments with Dr Smith.",
      "is_converted_to_patient": false,
      "is_lost": false,
      "is_opted_out_of_sms": false,
      "is_signed_up_to_newsletters": false,
      "last_name": "Lead",
      "lead_type": "inquiry",
      "links": {
        "clinician": "https://api.carebit.co/v1/clinicians/00000000-0000-4000-8000-000000000002",
        "self": "https://api.carebit.co/v1/leads/00000000-0000-4000-8000-000000000013",
        "service": "https://api.carebit.co/v1/services/00000000-0000-4000-8000-000000000005"
      },
      "mobile": "7700900123",
      "mobile_country_dial_code": "GB",
      "organization_privacy_policy_consent_granted_at": "2026-01-01T09:00:00Z",
      "patient_id": null,
      "phone": null,
      "phone_country_dial_code": null,
      "postcode": "TE1 1ST",
      "presenting_problem": "Persistent knee pain",
      "referral_notes": "Referred by Dr Patel at Riverside Medical.",
      "referral_source": "gp_practice",
      "service": {
        "id": "00000000-0000-4000-8000-000000000005",
        "object": "service",
        "created_at": "2026-01-01T09:00:00Z",
        "description": "Test consultation service.",
        "duration_minutes": 30,
        "is_bookable_online": true,
        "name": "Test consultation",
        "service_variants": [
          {
            "id": "00000000-0000-4000-8000-000000000006",
            "clinician_id": "00000000-0000-4000-8000-000000000002",
            "currency": "GBP",
            "description": "Standard consultation variant.",
            "links": {
              "clinician": "https://api.carebit.co/v1/clinicians/00000000-0000-4000-8000-000000000002",
              "location": "https://api.carebit.co/v1/locations/00000000-0000-4000-8000-000000000003"
            },
            "location_id": "00000000-0000-4000-8000-000000000003",
            "net_price": 6200,
            "permits_remote_bookings": false
          }
        ],
        "tax_rate": null,
        "updated_at": "2026-01-01T09:00:00Z"
      },
      "sex": "female",
      "stage": {
        "id": "00000000-0000-4000-8000-000000000015",
        "object": "lead_stage",
        "created_at": "2026-01-01T09:00:00Z",
        "is_conversion_stage": false,
        "is_lost_stage": false,
        "name": "Contact made",
        "position": 5,
        "updated_at": "2026-01-01T09:00:00Z"
      },
      "title": "Ms",
      "updated_at": "2026-01-01T09:00:00Z"
    }
  },
  "developer_platform_project_id": null,
  "livemode": false,
  "source": "dashboard",
  "type": "lead.created"
}
```


---

# lead.stage_changed

A Lead moved between pipeline stages.

## Payload schema

- `object`
  - `api_version` (`any`)
  - `context` (`object`) - Present only when `source` is `api`. Identifies the acting project and API key.
    - `developer_platform_api_key_id` (`string | null`) - format: `uuid`
    - `developer_platform_project_id` (`string | null`) - format: `uuid`
  - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `data` (`object`)
    - `object` (`object`)
      - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
      - `current_stage` (`object`)
        - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
        - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
        - `is_conversion_stage` (`boolean`) - Whether moving a Lead into this stage can start the Organization's Lead conversion workflow.
        - `is_lost_stage` (`boolean`) - Whether moving a lead into this stage marks it as lost or rejected.
        - `name` (`string`) - The display name of the stage.
        - `object` (`any`) - Discriminator value emitted at `object`.
        - `position` (`integer | null`) - The stage's display order within its pipeline.
        - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
      - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
      - `lead` (`object`)
        - `address_line_1` (`string | null`) - The primary address line of the lead.
        - `address_line_2` (`string | null`) - The secondary address line of the lead.
        - `attachments` (`array`) - The files attached to the lead.
          - `items` (`object`)
            - `download_url` (`string | null`) - format: `uri`; The short-lived signed download URL for the attachment. Null while the malware scan is not complete.
            - `filename` (`string | null`) - The original filename of the attachment.
            - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
        - `city` (`string | null`) - The city in the lead's postal address.
        - `clinician` (`any`) - The clinician the lead is assigned to, when recorded.
        - `country_code` (`string | null`) - The ISO 3166-1 alpha-2 country code for the postal address, such as `GB` for the United Kingdom.
        - `county` (`string | null`) - The county or region in the lead's postal address.
        - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
        - `creation_source` (`string | null`) - How the Lead was created. `api` means the record was created through the Developer Platform. Read-only.
        - `date_of_birth` (`string | null`) - format: `date`; The date of birth of the lead, in ISO 8601 format (YYYY-MM-DD).
        - `display_name` (`string | null`) - The formatted display name of the lead, including their title when recorded.
        - `email` (`string | null`) - format: `email`; The contact email address of the lead.
        - `first_name` (`string`) - The first name of the lead.
        - `gdpr_consent_granted_at` (`string | null`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
        - `gdpr_consent_withdrawn_at` (`string | null`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
        - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
        - `internal_notes` (`string | null`) - Internal notes shown in the Notes box next to presenting problem on the Carebit lead enquiry screen. Distinct from `referral_notes`.
        - `is_converted_to_patient` (`boolean`) - Whether the lead has been converted to a patient. Read-only.
        - `is_lost` (`boolean`) - Whether the lead has been marked as lost. Read-only.
        - `is_opted_out_of_sms` (`boolean`) - Whether the lead has opted out of SMS communication.
        - `is_signed_up_to_newsletters` (`boolean`) - Whether the lead has signed up to receive newsletters.
        - `last_name` (`string`) - The last name of the lead.
        - `lead_type` (`string`) - enum: `inquiry`, `referral`; Whether the record is a patient inquiry or a referral.
        - `links` (`object`) - URLs to related resources. `remote_file_import_batch` is present on create responses when at least one attachment was submitted.
          - `clinician` (`string | null`) - format: `uri`; The full URL of a related resource.
          - `remote_file_import_batch` (`string`) - format: `uri`; The full URL of a related resource.
          - `self` (`string`) - format: `uri`; The full URL of a related resource.
          - `service` (`string | null`) - format: `uri`; The full URL of a related resource.
        - `mobile` (`string | null`) - The mobile phone number of the lead, without the country dial code.
        - `mobile_country_dial_code` (`string | null`) - The ISO 3166-1 alpha-2 country code that selects the international dial code for `mobile`, for example `GB` selects `+44`.
        - `object` (`any`) - Discriminator value emitted at `object`.
        - `organization_privacy_policy_consent_granted_at` (`string | null`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
        - `patient_id` (`string | null`) - format: `uuid`; The identifier of the Patient this Lead was converted to. Null until conversion. Read-only.
        - `phone` (`string | null`) - The landline phone number of the lead, without the country dial code.
        - `phone_country_dial_code` (`string | null`) - The ISO 3166-1 alpha-2 country code that selects the international dial code for `phone`, for example `GB` selects `+44`.
        - `postcode` (`string | null`) - The postal code in the lead's postal address.
        - `presenting_problem` (`string | null`) - The presenting problem the lead described. Shown next to Notes on the Carebit lead enquiry screen.
        - `referral_notes` (`string | null`) - The referral notes shown on the Carebit lead enquiry screen.
        - `referral_source` (`string | null`) - enum: `consultant`, `embassy`, `family_or_friend`, `gp_practice`, `hospital`, `insurance_company`, `physiotherapist`, `presentation_talk`, `previous_patient`, `private_practice`, `search_engine`, `self_referral`, `social_media`, `website`, `other`, `null`; The referral source shown on the Carebit lead enquiry screen.
        - `remote_file_import_batch_id` (`string`) - format: `uuid`; The identifier of the remote file import batch created for the submitted attachments. Present on create responses when at least one attachment was submitted.
        - `service` (`any`) - The Service the Lead is inquiring about, when recorded.
        - `sex` (`string | null`) - The sex of the Lead as supplied on the inquiry.
        - `stage` (`any`) - The current pipeline stage of the lead. Read-only; use `stage_id` when updating the lead.
        - `title` (`string | null`) - The personal title of the lead, when recorded.
        - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
      - `links` (`object`) - URLs to related resources.
        - `lead` (`string`) - format: `uri`; The full URL of a related resource.
      - `object` (`any`) - Discriminator value emitted at `object`.
      - `previous_stage` (`any`) - The stage the lead moved from.
      - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `developer_platform_project_id` (`string | null`) - format: `uuid`; The project ID whose credential caused the change. Null for `dashboard` events.
  - `id` (`string`) - Event identifier prefixed with `evt_`.
  - `livemode` (`boolean`) - `false` for test-event deliveries.
  - `object` (`any`)
  - `source` (`string`) - enum: `api`, `dashboard`; Origin of the change. `api` means a Developer Platform mutation; `dashboard` means a Carebit-initiated change.
  - `type` (`any`)

### Example payload

```json
{
  "id": "evt_00000000-0000-4000-8000-000000000012",
  "object": "event",
  "api_version": "v1",
  "created_at": "2026-01-01T09:00:00Z",
  "data": {
    "object": {
      "id": "00000000-0000-4000-8000-000000000016",
      "object": "lead_stage_transition",
      "created_at": "2026-01-01T09:00:00Z",
      "current_stage": {
        "id": "00000000-0000-4000-8000-000000000015",
        "object": "lead_stage",
        "created_at": "2026-01-01T09:00:00Z",
        "is_conversion_stage": false,
        "is_lost_stage": false,
        "name": "Contact made",
        "position": 5,
        "updated_at": "2026-01-01T09:00:00Z"
      },
      "lead": {
        "id": "00000000-0000-4000-8000-000000000013",
        "object": "lead",
        "address_line_1": "1 Test Street",
        "address_line_2": null,
        "attachments": [],
        "city": "Test City",
        "clinician": {
          "id": "00000000-0000-4000-8000-000000000002",
          "object": "clinician",
          "created_at": "2026-01-01T09:00:00Z",
          "display_name": "Dr Ada Lovelace",
          "email": "ada.lovelace@example.invalid",
          "first_name": "Ada",
          "last_name": "Lovelace",
          "links": {
            "bookings": "https://api.carebit.co/v1/bookings?clinician_id=00000000-0000-4000-8000-000000000002"
          },
          "medical_specialty": "General Medicine",
          "title": "Dr",
          "updated_at": "2026-01-01T09:00:00Z"
        },
        "country_code": "GB",
        "county": "Testshire",
        "created_at": "2026-01-01T09:00:00Z",
        "creation_source": "api",
        "date_of_birth": "1990-01-01",
        "display_name": "Ms Test Lead",
        "email": "test.lead@example.invalid",
        "first_name": "Test",
        "gdpr_consent_granted_at": "2026-01-01T09:00:00Z",
        "gdpr_consent_withdrawn_at": null,
        "internal_notes": "Asked about evening appointments with Dr Smith.",
        "is_converted_to_patient": false,
        "is_lost": false,
        "is_opted_out_of_sms": false,
        "is_signed_up_to_newsletters": false,
        "last_name": "Lead",
        "lead_type": "inquiry",
        "links": {
          "clinician": "https://api.carebit.co/v1/clinicians/00000000-0000-4000-8000-000000000002",
          "self": "https://api.carebit.co/v1/leads/00000000-0000-4000-8000-000000000013",
          "service": "https://api.carebit.co/v1/services/00000000-0000-4000-8000-000000000005"
        },
        "mobile": "7700900123",
        "mobile_country_dial_code": "GB",
        "organization_privacy_policy_consent_granted_at": "2026-01-01T09:00:00Z",
        "patient_id": null,
        "phone": null,
        "phone_country_dial_code": null,
        "postcode": "TE1 1ST",
        "presenting_problem": "Persistent knee pain",
        "referral_notes": "Referred by Dr Patel at Riverside Medical.",
        "referral_source": "gp_practice",
        "service": {
          "id": "00000000-0000-4000-8000-000000000005",
          "object": "service",
          "created_at": "2026-01-01T09:00:00Z",
          "description": "Test consultation service.",
          "duration_minutes": 30,
          "is_bookable_online": true,
          "name": "Test consultation",
          "service_variants": [
            {
              "id": "00000000-0000-4000-8000-000000000006",
              "clinician_id": "00000000-0000-4000-8000-000000000002",
              "currency": "GBP",
              "description": "Standard consultation variant.",
              "links": {
                "clinician": "https://api.carebit.co/v1/clinicians/00000000-0000-4000-8000-000000000002",
                "location": "https://api.carebit.co/v1/locations/00000000-0000-4000-8000-000000000003"
              },
              "location_id": "00000000-0000-4000-8000-000000000003",
              "net_price": 6200,
              "permits_remote_bookings": false
            }
          ],
          "tax_rate": null,
          "updated_at": "2026-01-01T09:00:00Z"
        },
        "sex": "female",
        "stage": {
          "id": "00000000-0000-4000-8000-000000000015",
          "object": "lead_stage",
          "created_at": "2026-01-01T09:00:00Z",
          "is_conversion_stage": false,
          "is_lost_stage": false,
          "name": "Contact made",
          "position": 5,
          "updated_at": "2026-01-01T09:00:00Z"
        },
        "title": "Ms",
        "updated_at": "2026-01-01T09:00:00Z"
      },
      "links": {
        "lead": "https://api.carebit.co/v1/leads/00000000-0000-4000-8000-000000000013"
      },
      "previous_stage": {
        "id": "00000000-0000-4000-8000-000000000014",
        "object": "lead_stage",
        "created_at": "2026-01-01T09:00:00Z",
        "is_conversion_stage": false,
        "is_lost_stage": false,
        "name": "Enquiry",
        "position": 0,
        "updated_at": "2026-01-01T09:00:00Z"
      },
      "updated_at": "2026-01-01T09:00:00Z"
    }
  },
  "developer_platform_project_id": null,
  "livemode": false,
  "source": "dashboard",
  "type": "lead.stage_changed"
}
```


---

# lead.updated

A Lead's profile or lifecycle data changed.

## Payload schema

- `object`
  - `api_version` (`any`)
  - `context` (`object`) - Present only when `source` is `api`. Identifies the acting project and API key.
    - `developer_platform_api_key_id` (`string | null`) - format: `uuid`
    - `developer_platform_project_id` (`string | null`) - format: `uuid`
  - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `data` (`object`)
    - `object` (`object`)
      - `address_line_1` (`string | null`) - The primary address line of the lead.
      - `address_line_2` (`string | null`) - The secondary address line of the lead.
      - `attachments` (`array`) - The files attached to the lead.
        - `items` (`object`)
          - `download_url` (`string | null`) - format: `uri`; The short-lived signed download URL for the attachment. Null while the malware scan is not complete.
          - `filename` (`string | null`) - The original filename of the attachment.
          - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
      - `city` (`string | null`) - The city in the lead's postal address.
      - `clinician` (`any`) - The clinician the lead is assigned to, when recorded.
      - `country_code` (`string | null`) - The ISO 3166-1 alpha-2 country code for the postal address, such as `GB` for the United Kingdom.
      - `county` (`string | null`) - The county or region in the lead's postal address.
      - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
      - `creation_source` (`string | null`) - How the Lead was created. `api` means the record was created through the Developer Platform. Read-only.
      - `date_of_birth` (`string | null`) - format: `date`; The date of birth of the lead, in ISO 8601 format (YYYY-MM-DD).
      - `display_name` (`string | null`) - The formatted display name of the lead, including their title when recorded.
      - `email` (`string | null`) - format: `email`; The contact email address of the lead.
      - `first_name` (`string`) - The first name of the lead.
      - `gdpr_consent_granted_at` (`string | null`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
      - `gdpr_consent_withdrawn_at` (`string | null`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
      - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
      - `internal_notes` (`string | null`) - Internal notes shown in the Notes box next to presenting problem on the Carebit lead enquiry screen. Distinct from `referral_notes`.
      - `is_converted_to_patient` (`boolean`) - Whether the lead has been converted to a patient. Read-only.
      - `is_lost` (`boolean`) - Whether the lead has been marked as lost. Read-only.
      - `is_opted_out_of_sms` (`boolean`) - Whether the lead has opted out of SMS communication.
      - `is_signed_up_to_newsletters` (`boolean`) - Whether the lead has signed up to receive newsletters.
      - `last_name` (`string`) - The last name of the lead.
      - `lead_type` (`string`) - enum: `inquiry`, `referral`; Whether the record is a patient inquiry or a referral.
      - `links` (`object`) - URLs to related resources. `remote_file_import_batch` is present on create responses when at least one attachment was submitted.
        - `clinician` (`string | null`) - format: `uri`; The full URL of a related resource.
        - `remote_file_import_batch` (`string`) - format: `uri`; The full URL of a related resource.
        - `self` (`string`) - format: `uri`; The full URL of a related resource.
        - `service` (`string | null`) - format: `uri`; The full URL of a related resource.
      - `mobile` (`string | null`) - The mobile phone number of the lead, without the country dial code.
      - `mobile_country_dial_code` (`string | null`) - The ISO 3166-1 alpha-2 country code that selects the international dial code for `mobile`, for example `GB` selects `+44`.
      - `object` (`any`) - Discriminator value emitted at `object`.
      - `organization_privacy_policy_consent_granted_at` (`string | null`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
      - `patient_id` (`string | null`) - format: `uuid`; The identifier of the Patient this Lead was converted to. Null until conversion. Read-only.
      - `phone` (`string | null`) - The landline phone number of the lead, without the country dial code.
      - `phone_country_dial_code` (`string | null`) - The ISO 3166-1 alpha-2 country code that selects the international dial code for `phone`, for example `GB` selects `+44`.
      - `postcode` (`string | null`) - The postal code in the lead's postal address.
      - `presenting_problem` (`string | null`) - The presenting problem the lead described. Shown next to Notes on the Carebit lead enquiry screen.
      - `referral_notes` (`string | null`) - The referral notes shown on the Carebit lead enquiry screen.
      - `referral_source` (`string | null`) - enum: `consultant`, `embassy`, `family_or_friend`, `gp_practice`, `hospital`, `insurance_company`, `physiotherapist`, `presentation_talk`, `previous_patient`, `private_practice`, `search_engine`, `self_referral`, `social_media`, `website`, `other`, `null`; The referral source shown on the Carebit lead enquiry screen.
      - `remote_file_import_batch_id` (`string`) - format: `uuid`; The identifier of the remote file import batch created for the submitted attachments. Present on create responses when at least one attachment was submitted.
      - `service` (`any`) - The Service the Lead is inquiring about, when recorded.
      - `sex` (`string | null`) - The sex of the Lead as supplied on the inquiry.
      - `stage` (`any`) - The current pipeline stage of the lead. Read-only; use `stage_id` when updating the lead.
      - `title` (`string | null`) - The personal title of the lead, when recorded.
      - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `developer_platform_project_id` (`string | null`) - format: `uuid`; The project ID whose credential caused the change. Null for `dashboard` events.
  - `id` (`string`) - Event identifier prefixed with `evt_`.
  - `livemode` (`boolean`) - `false` for test-event deliveries.
  - `object` (`any`)
  - `source` (`string`) - enum: `api`, `dashboard`; Origin of the change. `api` means a Developer Platform mutation; `dashboard` means a Carebit-initiated change.
  - `type` (`any`)

### Example payload

```json
{
  "id": "evt_00000000-0000-4000-8000-000000000012",
  "object": "event",
  "api_version": "v1",
  "created_at": "2026-01-01T09:00:00Z",
  "data": {
    "object": {
      "id": "00000000-0000-4000-8000-000000000013",
      "object": "lead",
      "address_line_1": "1 Test Street",
      "address_line_2": null,
      "attachments": [],
      "city": "Test City",
      "clinician": {
        "id": "00000000-0000-4000-8000-000000000002",
        "object": "clinician",
        "created_at": "2026-01-01T09:00:00Z",
        "display_name": "Dr Ada Lovelace",
        "email": "ada.lovelace@example.invalid",
        "first_name": "Ada",
        "last_name": "Lovelace",
        "links": {
          "bookings": "https://api.carebit.co/v1/bookings?clinician_id=00000000-0000-4000-8000-000000000002"
        },
        "medical_specialty": "General Medicine",
        "title": "Dr",
        "updated_at": "2026-01-01T09:00:00Z"
      },
      "country_code": "GB",
      "county": "Testshire",
      "created_at": "2026-01-01T09:00:00Z",
      "creation_source": "api",
      "date_of_birth": "1990-01-01",
      "display_name": "Ms Test Lead",
      "email": "test.lead@example.invalid",
      "first_name": "Test",
      "gdpr_consent_granted_at": "2026-01-01T09:00:00Z",
      "gdpr_consent_withdrawn_at": null,
      "internal_notes": "Asked about evening appointments with Dr Smith.",
      "is_converted_to_patient": false,
      "is_lost": false,
      "is_opted_out_of_sms": false,
      "is_signed_up_to_newsletters": false,
      "last_name": "Lead",
      "lead_type": "inquiry",
      "links": {
        "clinician": "https://api.carebit.co/v1/clinicians/00000000-0000-4000-8000-000000000002",
        "self": "https://api.carebit.co/v1/leads/00000000-0000-4000-8000-000000000013",
        "service": "https://api.carebit.co/v1/services/00000000-0000-4000-8000-000000000005"
      },
      "mobile": "7700900123",
      "mobile_country_dial_code": "GB",
      "organization_privacy_policy_consent_granted_at": "2026-01-01T09:00:00Z",
      "patient_id": null,
      "phone": null,
      "phone_country_dial_code": null,
      "postcode": "TE1 1ST",
      "presenting_problem": "Persistent knee pain",
      "referral_notes": "Referred by Dr Patel at Riverside Medical.",
      "referral_source": "gp_practice",
      "service": {
        "id": "00000000-0000-4000-8000-000000000005",
        "object": "service",
        "created_at": "2026-01-01T09:00:00Z",
        "description": "Test consultation service.",
        "duration_minutes": 30,
        "is_bookable_online": true,
        "name": "Test consultation",
        "service_variants": [
          {
            "id": "00000000-0000-4000-8000-000000000006",
            "clinician_id": "00000000-0000-4000-8000-000000000002",
            "currency": "GBP",
            "description": "Standard consultation variant.",
            "links": {
              "clinician": "https://api.carebit.co/v1/clinicians/00000000-0000-4000-8000-000000000002",
              "location": "https://api.carebit.co/v1/locations/00000000-0000-4000-8000-000000000003"
            },
            "location_id": "00000000-0000-4000-8000-000000000003",
            "net_price": 6200,
            "permits_remote_bookings": false
          }
        ],
        "tax_rate": null,
        "updated_at": "2026-01-01T09:00:00Z"
      },
      "sex": "female",
      "stage": {
        "id": "00000000-0000-4000-8000-000000000015",
        "object": "lead_stage",
        "created_at": "2026-01-01T09:00:00Z",
        "is_conversion_stage": false,
        "is_lost_stage": false,
        "name": "Contact made",
        "position": 5,
        "updated_at": "2026-01-01T09:00:00Z"
      },
      "title": "Ms",
      "updated_at": "2026-01-01T09:00:00Z"
    }
  },
  "developer_platform_project_id": null,
  "livemode": false,
  "source": "dashboard",
  "type": "lead.updated"
}
```


---

# list.member_added

A Patient was added to a List.

## Payload schema

- `object`
  - `api_version` (`any`)
  - `context` (`object`) - Present only when `source` is `api`. Identifies the acting project and API key.
    - `developer_platform_api_key_id` (`string | null`) - format: `uuid`
    - `developer_platform_project_id` (`string | null`) - format: `uuid`
  - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `data` (`object`)
    - `object` (`object`)
      - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
      - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
      - `links` (`object`) - URLs to related resources.
        - `list` (`string`) - format: `uri`; The full URL of a related resource.
        - `patient` (`string | null`) - format: `uri`; The full URL of a related resource.
        - `self` (`string`) - format: `uri`; The full URL of a related resource.
      - `list` (`any`) - The list that contains this member.
      - `member` (`object | null`) - The ListMember and its resource. Null when the resource has been removed.
        - `patient` (`object`)
          - `address_line_1` (`string | null`) - The primary address line of the Patient.
          - `address_line_2` (`string | null`) - The secondary address line of the Patient.
          - `city` (`string | null`) - The city in the Patient's postal address.
          - `country_code` (`string | null`) - The ISO 3166-1 alpha-2 country code for the postal address, such as `GB` for the United Kingdom.
          - `county` (`string | null`) - The county or region in the Patient's postal address.
          - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
          - `creation_source` (`string | null`) - How the Patient was created. `api` means the record was created through the Developer Platform. Read-only.
          - `date_of_birth` (`string | null`) - format: `date`; The date of birth of the patient, in ISO 8601 format (YYYY-MM-DD).
          - `display_name` (`string | null`) - The formatted display name of the patient, including their title when recorded.
          - `email` (`string | null`) - format: `email`; The email address of the patient, when recorded.
          - `first_name` (`string | null`) - The first name of the patient.
          - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
          - `is_opted_out_of_sms` (`boolean`) - Whether the Patient has opted out of SMS messages.
          - `last_name` (`string | null`) - The last name of the patient.
          - `mobile` (`string | null`) - The national mobile number without its country calling code.
          - `mobile_country_dial_code` (`string | null`) - The ISO 3166-1 alpha-2 country code used to derive the mobile calling code.
          - `nhs_number` (`string | null`) - The 10-digit NHS number of the patient, without formatting.
          - `object` (`any`) - Discriminator value emitted at `object`.
          - `phone` (`string | null`) - The national phone number without its country calling code.
          - `phone_country_dial_code` (`string | null`) - The ISO 3166-1 alpha-2 country code used to derive the phone calling code.
          - `phone_number` (`string | null`) - The Patient's preferred contact number, formatted for display and compatible with E.164.
          - `postcode` (`string | null`) - The postal code of the Patient.
          - `sex` (`string | null`) - enum: `female`, `male`, `other`, `null`; The Patient's recorded sex.
          - `title` (`string | null`) - The personal title of the patient, when recorded.
          - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
        - `type` (`string`) - enum: `patient`; The kind of member. Additional values may be added later.
      - `object` (`any`) - Discriminator value emitted at `object`.
      - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `developer_platform_project_id` (`string | null`) - format: `uuid`; The project ID whose credential caused the change. Null for `dashboard` events.
  - `id` (`string`) - Event identifier prefixed with `evt_`.
  - `livemode` (`boolean`) - `false` for test-event deliveries.
  - `object` (`any`)
  - `source` (`string`) - enum: `api`, `dashboard`; Origin of the change. `api` means a Developer Platform mutation; `dashboard` means a Carebit-initiated change.
  - `type` (`any`)

### Example payload

```json
{
  "id": "evt_00000000-0000-4000-8000-000000000012",
  "object": "event",
  "api_version": "v1",
  "created_at": "2026-01-01T09:00:00Z",
  "data": {
    "object": {
      "id": "00000000-0000-4000-8000-000000000010",
      "object": "list_member",
      "created_at": "2026-01-01T09:00:00Z",
      "links": {
        "list": "https://api.carebit.co/v1/lists/00000000-0000-4000-8000-000000000011",
        "patient": "https://api.carebit.co/v1/patients/00000000-0000-4000-8000-000000000004",
        "self": "https://api.carebit.co/v1/lists/00000000-0000-4000-8000-000000000011/members/00000000-0000-4000-8000-000000000010"
      },
      "list": {
        "id": "00000000-0000-4000-8000-000000000011",
        "object": "list",
        "clinician_id": "00000000-0000-4000-8000-000000000002",
        "color_hex": "#28a745",
        "created_at": "2026-01-01T09:00:00Z",
        "links": {
          "clinician": "https://api.carebit.co/v1/clinicians/00000000-0000-4000-8000-000000000002",
          "members": "https://api.carebit.co/v1/lists/00000000-0000-4000-8000-000000000011/members",
          "self": "https://api.carebit.co/v1/lists/00000000-0000-4000-8000-000000000011"
        },
        "name": "Test list",
        "notes": "Some notes",
        "updated_at": "2026-01-01T09:00:00Z"
      },
      "member": {
        "patient": {
          "id": "00000000-0000-4000-8000-000000000004",
          "object": "patient",
          "address_line_1": "1 Test Street",
          "address_line_2": null,
          "city": "Test City",
          "country_code": "GB",
          "county": "Testshire",
          "created_at": "2026-01-01T09:00:00Z",
          "creation_source": "api",
          "date_of_birth": "1970-01-01",
          "display_name": "Ms Test Patient",
          "email": "test.patient@example.invalid",
          "first_name": "Test",
          "is_opted_out_of_sms": false,
          "last_name": "Patient",
          "mobile": "7700900123",
          "mobile_country_dial_code": "GB",
          "nhs_number": "9990000000",
          "phone": "1234567890",
          "phone_country_dial_code": "GB",
          "phone_number": "+441234567890",
          "postcode": "TE1 1ST",
          "sex": "female",
          "title": "Ms",
          "updated_at": "2026-01-01T09:00:00Z"
        },
        "type": "patient"
      },
      "updated_at": "2026-01-01T09:00:00Z"
    }
  },
  "developer_platform_project_id": null,
  "livemode": false,
  "source": "dashboard",
  "type": "list.member_added"
}
```


---

# list.member_removed

A Patient was removed from a List.

## Payload schema

- `object`
  - `api_version` (`any`)
  - `context` (`object`) - Present only when `source` is `api`. Identifies the acting project and API key.
    - `developer_platform_api_key_id` (`string | null`) - format: `uuid`
    - `developer_platform_project_id` (`string | null`) - format: `uuid`
  - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `data` (`object`)
    - `object` (`object`)
      - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
      - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
      - `links` (`object`) - URLs to related resources.
        - `list` (`string`) - format: `uri`; The full URL of a related resource.
        - `patient` (`string | null`) - format: `uri`; The full URL of a related resource.
        - `self` (`string`) - format: `uri`; The full URL of a related resource.
      - `list` (`any`) - The list that contains this member.
      - `member` (`object | null`) - The ListMember and its resource. Null when the resource has been removed.
        - `patient` (`object`)
          - `address_line_1` (`string | null`) - The primary address line of the Patient.
          - `address_line_2` (`string | null`) - The secondary address line of the Patient.
          - `city` (`string | null`) - The city in the Patient's postal address.
          - `country_code` (`string | null`) - The ISO 3166-1 alpha-2 country code for the postal address, such as `GB` for the United Kingdom.
          - `county` (`string | null`) - The county or region in the Patient's postal address.
          - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
          - `creation_source` (`string | null`) - How the Patient was created. `api` means the record was created through the Developer Platform. Read-only.
          - `date_of_birth` (`string | null`) - format: `date`; The date of birth of the patient, in ISO 8601 format (YYYY-MM-DD).
          - `display_name` (`string | null`) - The formatted display name of the patient, including their title when recorded.
          - `email` (`string | null`) - format: `email`; The email address of the patient, when recorded.
          - `first_name` (`string | null`) - The first name of the patient.
          - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
          - `is_opted_out_of_sms` (`boolean`) - Whether the Patient has opted out of SMS messages.
          - `last_name` (`string | null`) - The last name of the patient.
          - `mobile` (`string | null`) - The national mobile number without its country calling code.
          - `mobile_country_dial_code` (`string | null`) - The ISO 3166-1 alpha-2 country code used to derive the mobile calling code.
          - `nhs_number` (`string | null`) - The 10-digit NHS number of the patient, without formatting.
          - `object` (`any`) - Discriminator value emitted at `object`.
          - `phone` (`string | null`) - The national phone number without its country calling code.
          - `phone_country_dial_code` (`string | null`) - The ISO 3166-1 alpha-2 country code used to derive the phone calling code.
          - `phone_number` (`string | null`) - The Patient's preferred contact number, formatted for display and compatible with E.164.
          - `postcode` (`string | null`) - The postal code of the Patient.
          - `sex` (`string | null`) - enum: `female`, `male`, `other`, `null`; The Patient's recorded sex.
          - `title` (`string | null`) - The personal title of the patient, when recorded.
          - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
        - `type` (`string`) - enum: `patient`; The kind of member. Additional values may be added later.
      - `object` (`any`) - Discriminator value emitted at `object`.
      - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `developer_platform_project_id` (`string | null`) - format: `uuid`; The project ID whose credential caused the change. Null for `dashboard` events.
  - `id` (`string`) - Event identifier prefixed with `evt_`.
  - `livemode` (`boolean`) - `false` for test-event deliveries.
  - `object` (`any`)
  - `source` (`string`) - enum: `api`, `dashboard`; Origin of the change. `api` means a Developer Platform mutation; `dashboard` means a Carebit-initiated change.
  - `type` (`any`)

### Example payload

```json
{
  "id": "evt_00000000-0000-4000-8000-000000000012",
  "object": "event",
  "api_version": "v1",
  "created_at": "2026-01-01T09:00:00Z",
  "data": {
    "object": {
      "id": "00000000-0000-4000-8000-000000000010",
      "object": "list_member",
      "created_at": "2026-01-01T09:00:00Z",
      "links": {
        "list": "https://api.carebit.co/v1/lists/00000000-0000-4000-8000-000000000011",
        "patient": "https://api.carebit.co/v1/patients/00000000-0000-4000-8000-000000000004",
        "self": "https://api.carebit.co/v1/lists/00000000-0000-4000-8000-000000000011/members/00000000-0000-4000-8000-000000000010"
      },
      "list": {
        "id": "00000000-0000-4000-8000-000000000011",
        "object": "list",
        "clinician_id": "00000000-0000-4000-8000-000000000002",
        "color_hex": "#28a745",
        "created_at": "2026-01-01T09:00:00Z",
        "links": {
          "clinician": "https://api.carebit.co/v1/clinicians/00000000-0000-4000-8000-000000000002",
          "members": "https://api.carebit.co/v1/lists/00000000-0000-4000-8000-000000000011/members",
          "self": "https://api.carebit.co/v1/lists/00000000-0000-4000-8000-000000000011"
        },
        "name": "Test list",
        "notes": "Some notes",
        "updated_at": "2026-01-01T09:00:00Z"
      },
      "member": {
        "patient": {
          "id": "00000000-0000-4000-8000-000000000004",
          "object": "patient",
          "address_line_1": "1 Test Street",
          "address_line_2": null,
          "city": "Test City",
          "country_code": "GB",
          "county": "Testshire",
          "created_at": "2026-01-01T09:00:00Z",
          "creation_source": "api",
          "date_of_birth": "1970-01-01",
          "display_name": "Ms Test Patient",
          "email": "test.patient@example.invalid",
          "first_name": "Test",
          "is_opted_out_of_sms": false,
          "last_name": "Patient",
          "mobile": "7700900123",
          "mobile_country_dial_code": "GB",
          "nhs_number": "9990000000",
          "phone": "1234567890",
          "phone_country_dial_code": "GB",
          "phone_number": "+441234567890",
          "postcode": "TE1 1ST",
          "sex": "female",
          "title": "Ms",
          "updated_at": "2026-01-01T09:00:00Z"
        },
        "type": "patient"
      },
      "updated_at": "2026-01-01T09:00:00Z"
    }
  },
  "developer_platform_project_id": null,
  "livemode": false,
  "source": "dashboard",
  "type": "list.member_removed"
}
```


---

# patient_connection.created

A Patient was created for or connected to an Organization.

## Payload schema

- `object`
  - `api_version` (`any`)
  - `context` (`object`) - Present only when `source` is `api`. Identifies the acting project and API key.
    - `developer_platform_api_key_id` (`string | null`) - format: `uuid`
    - `developer_platform_project_id` (`string | null`) - format: `uuid`
  - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `data` (`object`)
    - `object` (`object`)
      - `clinician_id` (`string | null`) - format: `uuid`; The Clinician associated with this registration, when one is assigned.
      - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
      - `gp_status` (`string | null`) - enum: `none_or_omitted`, `has_gp`, `no_gp_required`, `null`; Whether this Organization has recorded a GP for the Patient. `has_gp` means a GP PatientConnection is expected. `no_gp_required` means the Patient does not need a GP. `none_or_omitted` means no GP has been recorded.
      - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
      - `is_active` (`boolean`) - Whether the Patient registration is active.
      - `links` (`object`) - URLs to related resources.
        - `patient` (`string`) - format: `uri`; The full URL of a related resource.
        - `payor` (`string | null`) - format: `uri`; The full URL of a related resource.
      - `object` (`any`) - Discriminator value emitted at `object`.
      - `organization` (`object`)
        - `address_line_1` (`string | null`) - The primary address line of the organization.
        - `address_line_2` (`string | null`) - The secondary address line of the organization.
        - `city` (`string | null`) - The city in the organization's postal address.
        - `country_code` (`string | null`) - The ISO 3166-1 alpha-2 country code for the postal address, such as `GB` for the United Kingdom.
        - `county` (`string | null`) - The county or region in the organization's postal address.
        - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
        - `currency` (`string | null`) - The ISO 4217 currency code used by the organization. Must be one of `chf`, `eur`, `gbp`, or `usd`. Null when this Organization is returned from `GET /v1/organizations` or nested on a PatientConnection.
        - `email` (`string | null`) - format: `email`; The contact email address of the organization. Null when this Organization is returned from `GET /v1/organizations` or nested on a PatientConnection.
        - `formatted_address` (`string | null`) - The single-line address of the organization, formatted for display.
        - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
        - `name` (`string`) - The display name of the organization, for example `Acme Healthcare`.
        - `object` (`any`) - Discriminator value emitted at `object`.
        - `organization_type` (`string | null`) - enum: `consultant`, `gp_practice`, `hospital`, `laboratory`, `legal`, `other`, `pharmacy`, `private_practice`, `null`; The kind of organization. Use `gp_practice` when attaching a GP.
        - `phone` (`string | null`) - The formatted contact phone number of the organization. Null when this Organization is returned from `GET /v1/organizations` or nested on a PatientConnection.
        - `postcode` (`string | null`) - The postal code in the organization's postal address.
        - `subdomain` (`string | null`) - The URL-safe subdomain that identifies the organization. Null when this Organization is returned from `GET /v1/organizations` or nested on a PatientConnection.
        - `time_zone` (`string | null`) - The IANA time zone used to interpret scheduling dates and display appointment times. Always `Europe/London` when present. Null when this Organization is returned from `GET /v1/organizations` or nested on a PatientConnection.
        - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
      - `organization_id` (`string`) - format: `uuid`; The Organization with which the Patient was registered.
      - `patient` (`object`)
        - `address_line_1` (`string | null`) - The primary address line of the Patient.
        - `address_line_2` (`string | null`) - The secondary address line of the Patient.
        - `city` (`string | null`) - The city in the Patient's postal address.
        - `country_code` (`string | null`) - The ISO 3166-1 alpha-2 country code for the postal address, such as `GB` for the United Kingdom.
        - `county` (`string | null`) - The county or region in the Patient's postal address.
        - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
        - `creation_source` (`string | null`) - How the Patient was created. `api` means the record was created through the Developer Platform. Read-only.
        - `date_of_birth` (`string | null`) - format: `date`; The date of birth of the patient, in ISO 8601 format (YYYY-MM-DD).
        - `display_name` (`string | null`) - The formatted display name of the patient, including their title when recorded.
        - `email` (`string | null`) - format: `email`; The email address of the patient, when recorded.
        - `first_name` (`string | null`) - The first name of the patient.
        - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
        - `is_opted_out_of_sms` (`boolean`) - Whether the Patient has opted out of SMS messages.
        - `last_name` (`string | null`) - The last name of the patient.
        - `mobile` (`string | null`) - The national mobile number without its country calling code.
        - `mobile_country_dial_code` (`string | null`) - The ISO 3166-1 alpha-2 country code used to derive the mobile calling code.
        - `nhs_number` (`string | null`) - The 10-digit NHS number of the patient, without formatting.
        - `object` (`any`) - Discriminator value emitted at `object`.
        - `phone` (`string | null`) - The national phone number without its country calling code.
        - `phone_country_dial_code` (`string | null`) - The ISO 3166-1 alpha-2 country code used to derive the phone calling code.
        - `phone_number` (`string | null`) - The Patient's preferred contact number, formatted for display and compatible with E.164.
        - `postcode` (`string | null`) - The postal code of the Patient.
        - `sex` (`string | null`) - enum: `female`, `male`, `other`, `null`; The Patient's recorded sex.
        - `title` (`string | null`) - The personal title of the patient, when recorded.
        - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
      - `payor_id` (`string | null`) - format: `uuid`; The Payor this Organization uses as the default billing party for the Patient.
      - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `developer_platform_project_id` (`string | null`) - format: `uuid`; The project ID whose credential caused the change. Null for `dashboard` events.
  - `id` (`string`) - Event identifier prefixed with `evt_`.
  - `livemode` (`boolean`) - `false` for test-event deliveries.
  - `object` (`any`)
  - `source` (`string`) - enum: `api`, `dashboard`; Origin of the change. `api` means a Developer Platform mutation; `dashboard` means a Carebit-initiated change.
  - `type` (`any`)

### Example payload

```json
{
  "id": "evt_00000000-0000-4000-8000-000000000012",
  "object": "event",
  "api_version": "v1",
  "created_at": "2026-01-01T09:00:00Z",
  "data": {
    "object": {
      "id": "00000000-0000-4000-8000-000000000017",
      "object": "patient_connection",
      "clinician_id": "00000000-0000-4000-8000-000000000002",
      "created_at": "2026-01-01T09:00:00Z",
      "gp_status": "has_gp",
      "is_active": true,
      "links": {
        "patient": "https://api.carebit.co/v1/patients/00000000-0000-4000-8000-000000000004",
        "payor": null
      },
      "organization": {
        "id": "00000000-0000-4000-8000-000000000018",
        "object": "organization",
        "address_line_1": "1 Test Street",
        "address_line_2": null,
        "city": "Test City",
        "country_code": "GB",
        "county": "Testshire",
        "created_at": "2026-01-01T09:00:00Z",
        "currency": null,
        "email": null,
        "formatted_address": "1 Test Street, Test City, GB, TE1 1ST",
        "name": "High Street Surgery",
        "organization_type": "gp_practice",
        "phone": null,
        "postcode": "TE1 1ST",
        "subdomain": null,
        "time_zone": null,
        "updated_at": "2026-01-01T09:00:00Z"
      },
      "organization_id": "00000000-0000-4000-8000-000000000018",
      "patient": {
        "id": "00000000-0000-4000-8000-000000000004",
        "object": "patient",
        "address_line_1": "1 Test Street",
        "address_line_2": null,
        "city": "Test City",
        "country_code": "GB",
        "county": "Testshire",
        "created_at": "2026-01-01T09:00:00Z",
        "creation_source": "api",
        "date_of_birth": "1970-01-01",
        "display_name": "Ms Test Patient",
        "email": "test.patient@example.invalid",
        "first_name": "Test",
        "is_opted_out_of_sms": false,
        "last_name": "Patient",
        "mobile": "7700900123",
        "mobile_country_dial_code": "GB",
        "nhs_number": "9990000000",
        "phone": "1234567890",
        "phone_country_dial_code": "GB",
        "phone_number": "+441234567890",
        "postcode": "TE1 1ST",
        "sex": "female",
        "title": "Ms",
        "updated_at": "2026-01-01T09:00:00Z"
      },
      "payor_id": null,
      "updated_at": "2026-01-01T09:00:00Z"
    }
  },
  "developer_platform_project_id": null,
  "livemode": false,
  "source": "dashboard",
  "type": "patient_connection.created"
}
```


---

# refund.created

A Refund was created.

## Payload schema

- `object`
  - `api_version` (`any`)
  - `context` (`object`) - Present only when `source` is `api`. Identifies the acting project and API key.
    - `developer_platform_api_key_id` (`string | null`) - format: `uuid`
    - `developer_platform_project_id` (`string | null`) - format: `uuid`
  - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `data` (`object`)
    - `object` (`object`)
      - `amount` (`integer`) - The refunded amount in minor currency units.
      - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
      - `currency` (`string | null`) - The ISO 4217 currency code.
      - `error` (`string | null`) - The failure message when the Refund did not complete.
      - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
      - `invoice_id` (`string | null`) - format: `uuid`; The Invoice associated with the refunded Payment, when one is assigned.
      - `links` (`object`) - URLs to related resources.
        - `patient` (`string | null`) - format: `uri`; The full URL of a related resource.
      - `notes` (`string | null`) - Internal notes recorded with the Refund.
      - `object` (`any`) - Discriminator value emitted at `object`.
      - `patient_id` (`string | null`) - format: `uuid`; The Patient associated with the Refund.
      - `payment_id` (`string | null`) - format: `uuid`; The Payment this Refund was issued against.
      - `reason` (`string | null`) - enum: `other`, `other_party_will_pay`, `overcharged`, `overpaid`, `service_not_delivered`, `null`; The reason the Refund was issued.
      - `refund_source` (`string | null`) - enum: `bank_account`, `deduction_from_balance`, `payment_account`, `null`; How the Refund is paid.
      - `status` (`string | null`) - enum: `canceled`, `failed`, `processing`, `requires_action`, `succeeded`, `null`; The Refund's current status.
      - `succeeded_at` (`string | null`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
      - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `developer_platform_project_id` (`string | null`) - format: `uuid`; The project ID whose credential caused the change. Null for `dashboard` events.
  - `id` (`string`) - Event identifier prefixed with `evt_`.
  - `livemode` (`boolean`) - `false` for test-event deliveries.
  - `object` (`any`)
  - `source` (`string`) - enum: `api`, `dashboard`; Origin of the change. `api` means a Developer Platform mutation; `dashboard` means a Carebit-initiated change.
  - `type` (`any`)

### Example payload

```json
{
  "id": "evt_00000000-0000-4000-8000-000000000012",
  "object": "event",
  "api_version": "v1",
  "created_at": "2026-01-01T09:00:00Z",
  "data": {
    "object": {
      "id": "00000000-0000-4000-8000-000000000025",
      "object": "refund",
      "amount": 25000,
      "created_at": "2026-01-01T09:00:00Z",
      "currency": "gbp",
      "error": null,
      "invoice_id": "00000000-0000-4000-8000-000000000027",
      "links": {
        "patient": "https://api.carebit.co/v1/patients/00000000-0000-4000-8000-000000000004"
      },
      "notes": "Refund for a canceled consultation.",
      "patient_id": "00000000-0000-4000-8000-000000000004",
      "payment_id": "00000000-0000-4000-8000-000000000026",
      "reason": "service_not_delivered",
      "refund_source": "payment_account",
      "status": "processing",
      "succeeded_at": null,
      "updated_at": "2026-01-01T09:00:00Z"
    }
  },
  "developer_platform_project_id": null,
  "livemode": false,
  "source": "dashboard",
  "type": "refund.created"
}
```


---