# Patients

Patients with an active connection to the Organization.

## 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);
```