Carebit API

Patients

Patients with an active connection to the Organization.

Endpoints

Scroll this page to read every Patients endpoint, or jump to one below.

get/v1/patientsList Patients connected to the Organization
post/v1/patientsCreate or find a Patient
get/v1/patients/:idGet a Patient
patch/v1/patients/:idUpdate a Patient

get/v1/patients

List Patients connected to the Organization

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.

Responses

200

Paginated list of Patient objects.

dataarrayrequired
- itemsobject
  - address_line_1string | nullrequired
    The primary address line of the Patient.
  - address_line_2string | nullrequired
    The secondary address line of the Patient.
  - citystring | nullrequired
    The city in the Patient's postal address.
  - country_codestring | nullrequired
    The ISO 3166-1 alpha-2 country code for the postal address, such as GB for the United Kingdom.
  - countystring | nullrequired
    The county or region in the Patient's postal address.
  - created_atstring · date-timerequired
    An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
  - creation_sourcestring | nullrequired
    How the Patient was created. api means the record was created through the Developer Platform. Read-only.
  - date_of_birthstring | null · daterequired
    The date of birth of the patient, in ISO 8601 format (YYYY-MM-DD).
  - display_namestring | nullrequired
    The formatted display name of the patient, including their title when recorded.
  - emailstring | null · emailrequired
    The email address of the patient, when recorded.
  - first_namestring | nullrequired
    The first name of the patient.
  - idstring · uuidrequired
    The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - is_opted_out_of_smsbooleanrequired
    Whether the Patient has opted out of SMS messages.
  - last_namestring | nullrequired
    The last name of the patient.
  - mobilestring | nullrequired
    The national mobile number without its country calling code.
  - mobile_country_dial_codestring | nullrequired
    The ISO 3166-1 alpha-2 country code used to derive the mobile calling code.
  - nhs_numberstring | nullrequired
    The 10-digit NHS number of the patient, without formatting.
  - objectanyrequired
    Discriminator value emitted at object.
  - phonestring | nullrequired
    The national phone number without its country calling code.
  - phone_country_dial_codestring | nullrequired
    The ISO 3166-1 alpha-2 country code used to derive the phone calling code.
  - phone_numberstring | nullrequired
    The Patient's preferred contact number, formatted for display and compatible with E.164.
  - postcodestring | nullrequired
    The postal code of the Patient.
  - sexstring | nullrequired
    The Patient's recorded sex.
    Allowed values: female | male | other | null
  - titlestring | nullrequired
    The personal title of the patient, when recorded.
  - updated_atstring · date-timerequired
    An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
has_morebooleanrequired
Whether another page is available after next_cursor.
next_cursorstring | nullrequired
The value to pass as cursor for the next page. Null on the last page.
objectanyrequired
Always list.
urlstringrequired
The API path that returned this list.

Example

{
  "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"
}

400

A filter or pagination parameter is invalid.

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

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

401

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

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

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

403

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

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

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

429

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

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

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

Request

curl -X GET "https://api.carebit.co/v1/patients?first_name=John&last_name=Smith" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN"

200 response

{
  "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"
}

400 response

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

401 response

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

403 response

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

429 response

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

post/v1/patients

Create or find a Patient

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 · required
string
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

address_line_1string | null
The primary address line of the Patient.
address_line_2string | null
The secondary address line of the Patient.
citystring | null
The city in the Patient's postal address.
country_codestring | null
The uppercase ISO 3166-1 alpha-2 country code for the Patient's address.
countystring | null
The county or region in the Patient's postal address.
date_of_birthstring | null · daterequired
The Patient's date of birth in ISO 8601 format.
emailstring | null · email
The Patient's email address.
first_namestring | nullrequired
The Patient's first name.
is_opted_out_of_smsboolean
Whether the Patient has opted out of SMS messages.
last_namestring | nullrequired
The Patient's last name.
mobilestring | null
The national mobile number without its country calling code.
mobile_country_dial_codestring | null
The country code used to derive the mobile calling code.
phonestring | null
The national phone number without its country calling code.
phone_country_dial_codestring | null
The country code used to derive the phone calling code.
postcodestring | nullrequired
The Patient's postal code.
sexstring | nullrequired
The Patient's recorded sex.
Allowed values: female | male | other | null
titlestring | null
The Patient's personal title.

Responses

200

An existing Patient connected to the Organization matched the supplied demographics. No Patient data was overwritten.

address_line_1string | nullrequired
The primary address line of the Patient.
address_line_2string | nullrequired
The secondary address line of the Patient.
citystring | nullrequired
The city in the Patient's postal address.
country_codestring | nullrequired
The ISO 3166-1 alpha-2 country code for the postal address, such as GB for the United Kingdom.
countystring | nullrequired
The county or region in the Patient's postal address.
created_atstring · date-timerequired
An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
creation_sourcestring | nullrequired
How the Patient was created. api means the record was created through the Developer Platform. Read-only.
date_of_birthstring | null · daterequired
The date of birth of the patient, in ISO 8601 format (YYYY-MM-DD).
display_namestring | nullrequired
The formatted display name of the patient, including their title when recorded.
emailstring | null · emailrequired
The email address of the patient, when recorded.
first_namestring | nullrequired
The first name of the patient.
idstring · uuidrequired
The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
is_opted_out_of_smsbooleanrequired
Whether the Patient has opted out of SMS messages.
last_namestring | nullrequired
The last name of the patient.
mobilestring | nullrequired
The national mobile number without its country calling code.
mobile_country_dial_codestring | nullrequired
The ISO 3166-1 alpha-2 country code used to derive the mobile calling code.
nhs_numberstring | nullrequired
The 10-digit NHS number of the patient, without formatting.
objectanyrequired
Discriminator value emitted at object.
phonestring | nullrequired
The national phone number without its country calling code.
phone_country_dial_codestring | nullrequired
The ISO 3166-1 alpha-2 country code used to derive the phone calling code.
phone_numberstring | nullrequired
The Patient's preferred contact number, formatted for display and compatible with E.164.
postcodestring | nullrequired
The postal code of the Patient.
sexstring | nullrequired
The Patient's recorded sex.
Allowed values: female | male | other | null
titlestring | nullrequired
The personal title of the patient, when recorded.
updated_atstring · date-timerequired
An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.

Example

{
  "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"
}

201

Patient created and registered with the Organization.

address_line_1string | nullrequired
The primary address line of the Patient.
address_line_2string | nullrequired
The secondary address line of the Patient.
citystring | nullrequired
The city in the Patient's postal address.
country_codestring | nullrequired
The ISO 3166-1 alpha-2 country code for the postal address, such as GB for the United Kingdom.
countystring | nullrequired
The county or region in the Patient's postal address.
created_atstring · date-timerequired
An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
creation_sourcestring | nullrequired
How the Patient was created. api means the record was created through the Developer Platform. Read-only.
date_of_birthstring | null · daterequired
The date of birth of the patient, in ISO 8601 format (YYYY-MM-DD).
display_namestring | nullrequired
The formatted display name of the patient, including their title when recorded.
emailstring | null · emailrequired
The email address of the patient, when recorded.
first_namestring | nullrequired
The first name of the patient.
idstring · uuidrequired
The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
is_opted_out_of_smsbooleanrequired
Whether the Patient has opted out of SMS messages.
last_namestring | nullrequired
The last name of the patient.
mobilestring | nullrequired
The national mobile number without its country calling code.
mobile_country_dial_codestring | nullrequired
The ISO 3166-1 alpha-2 country code used to derive the mobile calling code.
nhs_numberstring | nullrequired
The 10-digit NHS number of the patient, without formatting.
objectanyrequired
Discriminator value emitted at object.
phonestring | nullrequired
The national phone number without its country calling code.
phone_country_dial_codestring | nullrequired
The ISO 3166-1 alpha-2 country code used to derive the phone calling code.
phone_numberstring | nullrequired
The Patient's preferred contact number, formatted for display and compatible with E.164.
postcodestring | nullrequired
The postal code of the Patient.
sexstring | nullrequired
The Patient's recorded sex.
Allowed values: female | male | other | null
titlestring | nullrequired
The personal title of the patient, when recorded.
updated_atstring · date-timerequired
An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.

Example

{
  "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"
}

400

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

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

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

401

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

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

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

403

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

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

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

409

A matching Patient exists elsewhere in Carebit and requires review before connection, or another request currently holds the IdempotencyKey.

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

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

422

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

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

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

429

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

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

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

Request

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"
}'

200 response

{
  "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"
}

201 response

{
  "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"
}

400 response

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

401 response

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

403 response

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

409 response

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

422 response

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

429 response

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

get/v1/patients/:id

Get a Patient

Required API scopes: patients.read

Parameters

id
path · required
string
-

Responses

200

The requested Patient.

address_line_1string | nullrequired
The primary address line of the Patient.
address_line_2string | nullrequired
The secondary address line of the Patient.
citystring | nullrequired
The city in the Patient's postal address.
country_codestring | nullrequired
The ISO 3166-1 alpha-2 country code for the postal address, such as GB for the United Kingdom.
countystring | nullrequired
The county or region in the Patient's postal address.
created_atstring · date-timerequired
An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
creation_sourcestring | nullrequired
How the Patient was created. api means the record was created through the Developer Platform. Read-only.
date_of_birthstring | null · daterequired
The date of birth of the patient, in ISO 8601 format (YYYY-MM-DD).
display_namestring | nullrequired
The formatted display name of the patient, including their title when recorded.
emailstring | null · emailrequired
The email address of the patient, when recorded.
first_namestring | nullrequired
The first name of the patient.
idstring · uuidrequired
The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
is_opted_out_of_smsbooleanrequired
Whether the Patient has opted out of SMS messages.
last_namestring | nullrequired
The last name of the patient.
mobilestring | nullrequired
The national mobile number without its country calling code.
mobile_country_dial_codestring | nullrequired
The ISO 3166-1 alpha-2 country code used to derive the mobile calling code.
nhs_numberstring | nullrequired
The 10-digit NHS number of the patient, without formatting.
objectanyrequired
Discriminator value emitted at object.
phonestring | nullrequired
The national phone number without its country calling code.
phone_country_dial_codestring | nullrequired
The ISO 3166-1 alpha-2 country code used to derive the phone calling code.
phone_numberstring | nullrequired
The Patient's preferred contact number, formatted for display and compatible with E.164.
postcodestring | nullrequired
The postal code of the Patient.
sexstring | nullrequired
The Patient's recorded sex.
Allowed values: female | male | other | null
titlestring | nullrequired
The personal title of the patient, when recorded.
updated_atstring · date-timerequired
An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.

Example

{
  "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"
}

401

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

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

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

403

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

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

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

404

Error response.

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

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

429

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

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

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

Request

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

200 response

{
  "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"
}

401 response

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

403 response

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

404 response

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

429 response

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

patch/v1/patients/:id

Update a Patient

Required API scopes: patients.update

Parameters

id
path · required
string
-
Idempotency-Key
header · required
string
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

address_line_1string | null
The primary address line of the Patient.
address_line_2string | null
The secondary address line of the Patient.
citystring | null
The city in the Patient's postal address.
country_codestring | null
The uppercase ISO 3166-1 alpha-2 country code for the Patient's address.
countystring | null
The county or region in the Patient's postal address.
date_of_birthstring | null · date
The Patient's date of birth in ISO 8601 format.
emailstring | null · email
The Patient's email address.
first_namestring | null
The Patient's first name.
is_opted_out_of_smsboolean
Whether the Patient has opted out of SMS messages.
last_namestring | null
The Patient's last name.
mobilestring | null
The national mobile number without its country calling code.
mobile_country_dial_codestring | null
The country code used to derive the mobile calling code.
phonestring | null
The national phone number without its country calling code.
phone_country_dial_codestring | null
The country code used to derive the phone calling code.
postcodestring | null
The Patient's postal code.
sexstring | null
The Patient's recorded sex.
Allowed values: female | male | other | null
titlestring | null
The Patient's personal title.

Responses

200

The requested Patient.

address_line_1string | nullrequired
The primary address line of the Patient.
address_line_2string | nullrequired
The secondary address line of the Patient.
citystring | nullrequired
The city in the Patient's postal address.
country_codestring | nullrequired
The ISO 3166-1 alpha-2 country code for the postal address, such as GB for the United Kingdom.
countystring | nullrequired
The county or region in the Patient's postal address.
created_atstring · date-timerequired
An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
creation_sourcestring | nullrequired
How the Patient was created. api means the record was created through the Developer Platform. Read-only.
date_of_birthstring | null · daterequired
The date of birth of the patient, in ISO 8601 format (YYYY-MM-DD).
display_namestring | nullrequired
The formatted display name of the patient, including their title when recorded.
emailstring | null · emailrequired
The email address of the patient, when recorded.
first_namestring | nullrequired
The first name of the patient.
idstring · uuidrequired
The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
is_opted_out_of_smsbooleanrequired
Whether the Patient has opted out of SMS messages.
last_namestring | nullrequired
The last name of the patient.
mobilestring | nullrequired
The national mobile number without its country calling code.
mobile_country_dial_codestring | nullrequired
The ISO 3166-1 alpha-2 country code used to derive the mobile calling code.
nhs_numberstring | nullrequired
The 10-digit NHS number of the patient, without formatting.
objectanyrequired
Discriminator value emitted at object.
phonestring | nullrequired
The national phone number without its country calling code.
phone_country_dial_codestring | nullrequired
The ISO 3166-1 alpha-2 country code used to derive the phone calling code.
phone_numberstring | nullrequired
The Patient's preferred contact number, formatted for display and compatible with E.164.
postcodestring | nullrequired
The postal code of the Patient.
sexstring | nullrequired
The Patient's recorded sex.
Allowed values: female | male | other | null
titlestring | nullrequired
The personal title of the patient, when recorded.
updated_atstring · date-timerequired
An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.

Example

{
  "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"
}

400

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

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

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

401

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

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

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

403

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

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

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

404

Error response.

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

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

409

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

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

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

422

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

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

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

429

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

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

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

Request

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"
}'

200 response

{
  "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"
}

400 response

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

401 response

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

403 response

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

404 response

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

409 response

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

422 response

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

429 response

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

Prefer plain text? Append ?format=md or send Accept: text/markdown to receive this page as raw Markdown.