Carebit API

Patients

Patients with an active connection to the Organization.

Required API scopes: patients.createpatients.readpatients.update

Endpoints

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

get/v1/patientsList Patients connected to the Organizationpatients.read
post/v1/patientsCreate or find a Patientpatients.create
get/v1/patients/:idGet a Patientpatients.read
patch/v1/patients/:idUpdate a Patientpatients.update

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 API. 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.
  - internal_patient_idstring | nullrequired
    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_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.
  - patient_numberstring | nullrequired
    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_urlstring · urirequired
    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.
  - 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": "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"
}

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

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. 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. This endpoint allows 10 requests per access token per minute.

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.
internal_patient_idstring | 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_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.
nhs_numberstring | null
The 10-digit NHS number of the Patient, without spaces or other formatting. Set it to null to clear it.
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 was already connected to the Organization and was returned without changing their record.

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 API. 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.
internal_patient_idstring | nullrequired
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_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.
patient_numberstring | nullrequired
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_urlstring · urirequired
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.
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": "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"
}

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 API. 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.
internal_patient_idstring | nullrequired
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_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.
patient_numberstring | nullrequired
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_urlstring · urirequired
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.
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": "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"
}

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.

available_actionsarrayrequired
The actions the caller can take while this request is pending. The array is empty after resolution or expiry.
- itemsstring
  Allowed values: connect_existing_patient | create_new_patient | deny
candidateobject | nullrequired
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_fieldsarrayrequired
  Reserved for compatibility. Carebit returns an empty array so the response cannot disclose whether a candidate has a particular contact or NHS number value.
  - itemsstring
- matched_fieldsarrayrequired
  The submitted demographic fields that match the recommended candidate. Contact and NHS number matches are not disclosed.
  - itemsstring
- not_recorded_fieldsarrayrequired
  Reserved for compatibility. Carebit returns an empty array so the response cannot disclose whether a candidate has a particular contact or NHS number value.
  - itemsstring
created_atstring · date-timerequired
An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
expires_atstring · date-timerequired
The time after which a pending PatientConnectionRequest expires if the Organization has not resolved it.
idstring · uuidrequired
The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
linksobjectrequired
URLs to related resources.
- dashboardstring · urirequired
  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.
- patientstring | null · urirequired
  The Patient retrieve URL after an approved action. Null while the request is pending, denied, or expired.
objectanyrequired
Discriminator value emitted at object.
patient_idstring | null · uuidrequired
The resulting Patient identifier after the Organization connects an existing Patient or creates a separate Patient. Null while pending, denied, or expired.
resolved_outcomestring | nullrequired
How the Organization resolved this request. Null while it is pending.
Allowed values: connected_existing | created_new | denied | expired | null
statusstringrequired
The lifecycle status of the PatientConnectionRequest. granted means a resulting PatientConnection exists.
Allowed values: pending | granted | denied | expired
submittedobjectrequired
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_atstring · date-timerequired
An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.

Example

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

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

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

201 response

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

202 response

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

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 API. 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.
internal_patient_idstring | nullrequired
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_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.
patient_numberstring | nullrequired
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_urlstring · urirequired
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.
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": "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"
}

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/00000000-0000-4000-8000-000000000004" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN"

200 response

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

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.
internal_patient_idstring | 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_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.
nhs_numberstring | null
The 10-digit NHS number of the Patient, without spaces or other formatting. Set it to null to clear it.
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 API. 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.
internal_patient_idstring | nullrequired
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_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.
patient_numberstring | nullrequired
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_urlstring · urirequired
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.
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": "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"
}

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

200 response

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

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.