# Patients

Patients with an active connection to the Organization.

**Required API scopes:** `patients.create`, `patients.read`, `patients.update`

## 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": "00000000-0000-4000-8000-000000000004",
      "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",
      "internal_patient_id": "EXT-9001",
      "is_opted_out_of_sms": false,
      "last_name": "Morgan",
      "mobile": "7700900123",
      "mobile_country_dial_code": "GB",
      "nhs_number": "485 777 3456",
      "patient_number": "PAT-1001",
      "patient_portal_add_payment_method_url": "https://files.example.invalid/document.pdf?signature=test",
      "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. Matching requires the same first name, last name, date of birth, sex, and postcode. Contact details and NHS number rank matching candidates. If a match is already connected to the Organization, Carebit returns that Patient without changing their record. An unconnected match returns a pending PatientConnectionRequest with evidence for only the strongest recommendation. Carebit does not connect it automatically. If you are ready to connect the recommendation immediately, POST `connect_existing_patient`. Staff can also grant or deny the request in Carebit. See [PatientConnectionRequest](/guides/creating-patients#patientconnectionrequest). This endpoint allows 10 requests per access token per minute.

**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.
  - `internal_patient_id` (`string | null`) - The identifier for this Patient in your own systems. Carebit stores it on the Organization's PatientConnection, not on the shared Patient record. Set it to null to clear it.
  - `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.
  - `nhs_number` (`string | null`) - The 10-digit NHS number of the Patient, without spaces or other formatting. Set it to null to clear it.
  - `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 was already connected to the Organization and was returned without changing their record.

- `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 API. 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.
  - `internal_patient_id` (`string | null`) - The identifier for this Patient in the requesting Organization's other third party systems. Note that this is not the same as the patient_number and is not generated automaticallyby Carebit. Null when none has been recorded.
  - `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`.
  - `patient_number` (`string | null`) - The Organization-specific identifier/number for this Patient, as generated automatically by Carebit. Null when numbering is disabled or no number has been assigned. Read-only.
  - `patient_portal_add_payment_method_url` (`string`) - format: `uri`; The Patient Portal URL where this Patient can add a stored card PaymentMethod for the Organization. Send this URL to the Patient before creating a card Payment if they do not already have a card on file. Read-only.
  - `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": "00000000-0000-4000-8000-000000000004",
  "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",
  "internal_patient_id": "EXT-9001",
  "is_opted_out_of_sms": false,
  "last_name": "Morgan",
  "mobile": "7700900123",
  "mobile_country_dial_code": "GB",
  "nhs_number": "485 777 3456",
  "patient_number": "PAT-1001",
  "patient_portal_add_payment_method_url": "https://files.example.invalid/document.pdf?signature=test",
  "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 API. 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.
  - `internal_patient_id` (`string | null`) - The identifier for this Patient in the requesting Organization's other third party systems. Note that this is not the same as the patient_number and is not generated automaticallyby Carebit. Null when none has been recorded.
  - `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`.
  - `patient_number` (`string | null`) - The Organization-specific identifier/number for this Patient, as generated automatically by Carebit. Null when numbering is disabled or no number has been assigned. Read-only.
  - `patient_portal_add_payment_method_url` (`string`) - format: `uri`; The Patient Portal URL where this Patient can add a stored card PaymentMethod for the Organization. Send this URL to the Patient before creating a card Payment if they do not already have a card on file. Read-only.
  - `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": "00000000-0000-4000-8000-000000000004",
  "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",
  "internal_patient_id": "EXT-9001",
  "is_opted_out_of_sms": false,
  "last_name": "Morgan",
  "mobile": "7700900123",
  "mobile_country_dial_code": "GB",
  "nhs_number": "485 777 3456",
  "patient_number": "PAT-1001",
  "patient_portal_add_payment_method_url": "https://files.example.invalid/document.pdf?signature=test",
  "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 `202`

At least one unconnected Patient matched. Carebit created a pending PatientConnectionRequest and returned evidence for only the strongest recommendation. If you are ready to connect it immediately, POST `connect_existing_patient`. Staff can also review it in Carebit. See [PatientConnectionRequest](/guides/creating-patients#patientconnectionrequest).

- `object`
  - `available_actions` (`array`) - The actions the caller can take while this request is pending. The array is empty after resolution or expiry.
    - `items` (`string`) - enum: `connect_existing_patient`, `create_new_patient`, `deny`
  - `candidate` (`object | null`) - The strongest current match, or null when no match remains. Demographic, contact, and NHS number evidence determine the ranking; PatientConnection and Document counts break ties. Only matching demographic field names are disclosed. Existing values, contact and NHS number classifications, activity counts, alternative candidates, and Patient identifiers are not disclosed. POST `connect_existing_patient` to connect this recommendation.
    - `conflicting_fields` (`array`) - Reserved for compatibility. Carebit returns an empty array so the response cannot disclose whether a candidate has a particular contact or NHS number value.
      - `items` (`string`)
    - `matched_fields` (`array`) - The submitted demographic fields that match the recommended candidate. Contact and NHS number matches are not disclosed.
      - `items` (`string`)
    - `not_recorded_fields` (`array`) - Reserved for compatibility. Carebit returns an empty array so the response cannot disclose whether a candidate has a particular contact or NHS number value.
      - `items` (`string`)
  - `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 a pending PatientConnectionRequest expires if the Organization has not resolved it.
  - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - `links` (`object`) - URLs to related resources.
    - `dashboard` (`string`) - format: `uri`; The Carebit Admin URL listing Patient connection requests for the Organization. This is a Carebit UI URL, not a Developer Platform API URL. Carebit does not email staff when a request is created. Send this URL if you want someone to review pending requests.
    - `patient` (`string | null`) - format: `uri`; The Patient retrieve URL after an approved action. Null while the request is pending, denied, or expired.
  - `object` (`any`) - Discriminator value emitted at `object`.
  - `patient_id` (`string | null`) - format: `uuid`; The resulting Patient identifier after the Organization connects an existing Patient or creates a separate Patient. Null while pending, denied, or expired.
  - `resolved_outcome` (`string | null`) - enum: `connected_existing`, `created_new`, `denied`, `expired`, `null`; How the Organization resolved this request. Null while it is pending.
  - `status` (`string`) - enum: `pending`, `granted`, `denied`, `expired`; The lifecycle status of the PatientConnectionRequest. `granted` means a resulting PatientConnection exists.
  - `submitted` (`object`) - The Patient create payload that produced this request. Carebit echoes the fields you sent. It does not include existing-Patient fields you did not submit.
  - `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": "f50a3a17-e1a9-4eaf-813b-a062b56e6683",
  "object": "patient_connection_request",
  "available_actions": [
    "connect_existing_patient"
  ],
  "candidate": {
    "conflicting_fields": [],
    "matched_fields": [
      "first_name",
      "last_name",
      "date_of_birth",
      "sex",
      "postcode"
    ],
    "not_recorded_fields": []
  },
  "created_at": "2026-01-01T09:00:00Z",
  "expires_at": "2026-01-01T09:00:00Z",
  "links": {
    "dashboard": "https://example.carebit.co/admin/patients/connection-requests",
    "patient": "https://api.carebit.co/v1/patients/00000000-0000-4000-8000-000000000004"
  },
  "patient_id": "00000000-0000-4000-8000-000000000004",
  "resolved_outcome": "connected_existing",
  "status": "pending",
  "submitted": {},
  "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`

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 API. 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.
  - `internal_patient_id` (`string | null`) - The identifier for this Patient in the requesting Organization's other third party systems. Note that this is not the same as the patient_number and is not generated automaticallyby Carebit. Null when none has been recorded.
  - `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`.
  - `patient_number` (`string | null`) - The Organization-specific identifier/number for this Patient, as generated automatically by Carebit. Null when numbering is disabled or no number has been assigned. Read-only.
  - `patient_portal_add_payment_method_url` (`string`) - format: `uri`; The Patient Portal URL where this Patient can add a stored card PaymentMethod for the Organization. Send this URL to the Patient before creating a card Payment if they do not already have a card on file. Read-only.
  - `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": "00000000-0000-4000-8000-000000000004",
  "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",
  "internal_patient_id": "EXT-9001",
  "is_opted_out_of_sms": false,
  "last_name": "Morgan",
  "mobile": "7700900123",
  "mobile_country_dial_code": "GB",
  "nhs_number": "485 777 3456",
  "patient_number": "PAT-1001",
  "patient_portal_add_payment_method_url": "https://files.example.invalid/document.pdf?signature=test",
  "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/00000000-0000-4000-8000-000000000004" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN"
```

```javascript
const response = await fetch("https://api.carebit.co/v1/patients/00000000-0000-4000-8000-000000000004", {
  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/00000000-0000-4000-8000-000000000004",
    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/00000000-0000-4000-8000-000000000004",
  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/00000000-0000-4000-8000-000000000004", [
    "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.
  - `internal_patient_id` (`string | null`) - The identifier for this Patient in your own systems. Carebit stores it on the Organization's PatientConnection, not on the shared Patient record. Set it to null to clear it.
  - `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.
  - `nhs_number` (`string | null`) - The 10-digit NHS number of the Patient, without spaces or other formatting. Set it to null to clear it.
  - `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 API. 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.
  - `internal_patient_id` (`string | null`) - The identifier for this Patient in the requesting Organization's other third party systems. Note that this is not the same as the patient_number and is not generated automaticallyby Carebit. Null when none has been recorded.
  - `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`.
  - `patient_number` (`string | null`) - The Organization-specific identifier/number for this Patient, as generated automatically by Carebit. Null when numbering is disabled or no number has been assigned. Read-only.
  - `patient_portal_add_payment_method_url` (`string`) - format: `uri`; The Patient Portal URL where this Patient can add a stored card PaymentMethod for the Organization. Send this URL to the Patient before creating a card Payment if they do not already have a card on file. Read-only.
  - `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": "00000000-0000-4000-8000-000000000004",
  "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",
  "internal_patient_id": "EXT-9001",
  "is_opted_out_of_sms": false,
  "last_name": "Morgan",
  "mobile": "7700900123",
  "mobile_country_dial_code": "GB",
  "nhs_number": "485 777 3456",
  "patient_number": "PAT-1001",
  "patient_portal_add_payment_method_url": "https://files.example.invalid/document.pdf?signature=test",
  "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/00000000-0000-4000-8000-000000000004" \
  -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/00000000-0000-4000-8000-000000000004", {
  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/00000000-0000-4000-8000-000000000004",
    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/00000000-0000-4000-8000-000000000004",
  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/00000000-0000-4000-8000-000000000004", [
    "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);
```