Carebit API

Patient Connections

Unlocked registrations between a Patient and an Organization, including GP practices.

Endpoints

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

get/v1/patients/:patient_id/connectionsList a Patient's unlocked PatientConnections
post/v1/patients/:patient_id/connectionsCreate a PatientConnection
get/v1/patients/:patient_id/connections/:idGet an unlocked PatientConnection
patch/v1/patients/:patient_id/connections/:idUpdate this Organization's PatientConnection

get/v1/patients/:patient_id/connections

List a Patient's unlocked PatientConnections

Returns PatientConnections this Organization already has ResourcePermissions for. Locked connections, including a GP that has not been unlocked in Carebit, are omitted.

Required API scopes: patient_connections.read

Parameters

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

Responses

200

Paginated list of PatientConnection objects.

dataarrayrequired
- itemsobject
  - clinician_idstring | null · uuidrequired
    The Clinician associated with this registration, when one is assigned.
  - created_atstring · date-timerequired
    An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
  - gp_statusstring | nullrequired
    Whether this Organization has recorded a GP for the Patient. has_gp means a GP PatientConnection is expected. no_gp_required means the Patient does not need a GP. none_or_omitted means no GP has been recorded.
    Allowed values: none_or_omitted | has_gp | no_gp_required | null
  - idstring · uuidrequired
    The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - is_activebooleanrequired
    Whether the Patient registration is active.
  - linksobjectrequired
    URLs to related resources.
    - patientstring · urirequired
      The full URL of a related resource.
    - payorstring | null · urirequired
      The full URL of a related resource.
  - objectanyrequired
    Discriminator value emitted at object.
  - organizationobjectrequired
    - address_line_1string | nullrequired
      The primary address line of the organization.
    - address_line_2string | nullrequired
      The secondary address line of the organization.
    - citystring | nullrequired
      The city in the organization'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 organization's postal address.
    - created_atstring · date-timerequired
      An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
    - currencystring | nullrequired
      The ISO 4217 currency code used by the organization. Must be one of chf, eur, gbp, or usd. Null when this Organization is returned from GET /v1/organizations or nested on a PatientConnection.
    - emailstring | null · emailrequired
      The contact email address of the organization. Null when this Organization is returned from GET /v1/organizations or nested on a PatientConnection.
    - formatted_addressstring | nullrequired
      The single-line address of the organization, formatted for display.
    - idstring · uuidrequired
      The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
    - namestringrequired
      The display name of the organization, for example Acme Healthcare.
    - objectanyrequired
      Discriminator value emitted at object.
    - organization_typestring | nullrequired
      The kind of organization. Use gp_practice when attaching a GP.
      Allowed values: consultant | gp_practice | hospital | laboratory | legal | other | pharmacy | private_practice | null
    - phonestring | nullrequired
      The formatted contact phone number of the organization. Null when this Organization is returned from GET /v1/organizations or nested on a PatientConnection.
    - postcodestring | nullrequired
      The postal code in the organization's postal address.
    - subdomainstring | nullrequired
      The URL-safe subdomain that identifies the organization. Null when this Organization is returned from GET /v1/organizations or nested on a PatientConnection.
    - time_zonestring | nullrequired
      The IANA time zone used to interpret scheduling dates and display appointment times. Always Europe/London when present. Null when this Organization is returned from GET /v1/organizations or nested on a PatientConnection.
    - updated_atstring · date-timerequired
      An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
  - organization_idstring · uuidrequired
    The Organization with which the Patient was registered.
  - patientobjectrequired
    - 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.
  - payor_idstring | null · uuidrequired
    The Payor this Organization uses as the default billing party for the Patient.
  - 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": "fcdd446b-eef0-4bf2-83d1-35764265817d",
      "object": "patient_connection",
      "clinician_id": "2b3c4d5e-6f70-489a-9bcd-ef0123456789",
      "created_at": "2026-01-01T09:00:00Z",
      "gp_status": "none_or_omitted",
      "is_active": true,
      "links":  … }
        "patient": "https://api.carebit.co/v1/patients/1a2b3c4d-5e6f-4789-8abc-def012345678",
        "payor": "https://api.carebit.co/v1/payors/708192a3-b4c5-4def-8012-3456789abcde"
      },
      "organization":  … }
        "id": "8192a3b4-c5d6-4ef0-9123-456789abcdef",
        "object": "organization",
        "address_line_1": "10 Harley Street",
        "address_line_2": "Marylebone",
        "city": "London",
        "country_code": "GB",
        "county": "Greater London",
        "created_at": "2026-01-01T09:00:00Z",
        "currency": "GBP",
        "email": "alex.morgan@example.com",
        "formatted_address": "10 Harley Street, Marylebone, London, W1G 9PF",
        "name": "Harley Street Clinic",
        "organization_type": "consultant",
        "phone": "2071234567",
        "postcode": "W1G 9PF",
        "subdomain": "harley-street-clinic",
        "time_zone": "Example time zone",
        "updated_at": "2026-01-01T09:00:00Z"
      },
      "organization_id": "8192a3b4-c5d6-4ef0-9123-456789abcdef",
      "patient":  … }
        "id": "1a2b3c4d-5e6f-4789-8abc-def012345678",
        "object": "patient",
        "address_line_1": "10 Harley Street",
        "address_line_2": "Marylebone",
        "city": "London",
        "country_code": "GB",
        "county": "Greater London",
        "created_at": "2026-01-01T09:00:00Z",
        "creation_source": "api",
        "date_of_birth": "1990-01-01",
        "display_name": "Dr Alex Morgan",
        "email": "alex.morgan@example.com",
        "first_name": "Alex",
        "is_opted_out_of_sms": false,
        "last_name": "Morgan",
        "mobile": "7700900123",
        "mobile_country_dial_code": "GB",
        "nhs_number": "485 777 3456",
        "phone": "2071234567",
        "phone_country_dial_code": "GB",
        "phone_number": "+44 7700 900123",
        "postcode": "W1G 9PF",
        "sex": "female",
        "title": "Dr",
        "updated_at": "2026-01-01T09:00:00Z"
      },
      "payor_id": "708192a3-b4c5-4def-8012-3456789abcde",
      "updated_at": "2026-01-01T09:00:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": "eyJzdGFydF90aW1lIjoiMjAyNi0wMS0wMVQwOTowMDowMFoifQ",
  "url": "/v1/patient_connections"
}

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/connections" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN"

200 response

{
  "object": "list",
  "data":  … ]
     … }
      "id": "fcdd446b-eef0-4bf2-83d1-35764265817d",
      "object": "patient_connection",
      "clinician_id": "2b3c4d5e-6f70-489a-9bcd-ef0123456789",
      "created_at": "2026-01-01T09:00:00Z",
      "gp_status": "none_or_omitted",
      "is_active": true,
      "links":  … }
        "patient": "https://api.carebit.co/v1/patients/1a2b3c4d-5e6f-4789-8abc-def012345678",
        "payor": "https://api.carebit.co/v1/payors/708192a3-b4c5-4def-8012-3456789abcde"
      },
      "organization":  … }
        "id": "8192a3b4-c5d6-4ef0-9123-456789abcdef",
        "object": "organization",
        "address_line_1": "10 Harley Street",
        "address_line_2": "Marylebone",
        "city": "London",
        "country_code": "GB",
        "county": "Greater London",
        "created_at": "2026-01-01T09:00:00Z",
        "currency": "GBP",
        "email": "alex.morgan@example.com",
        "formatted_address": "10 Harley Street, Marylebone, London, W1G 9PF",
        "name": "Harley Street Clinic",
        "organization_type": "consultant",
        "phone": "2071234567",
        "postcode": "W1G 9PF",
        "subdomain": "harley-street-clinic",
        "time_zone": "Example time zone",
        "updated_at": "2026-01-01T09:00:00Z"
      },
      "organization_id": "8192a3b4-c5d6-4ef0-9123-456789abcdef",
      "patient":  … }
        "id": "1a2b3c4d-5e6f-4789-8abc-def012345678",
        "object": "patient",
        "address_line_1": "10 Harley Street",
        "address_line_2": "Marylebone",
        "city": "London",
        "country_code": "GB",
        "county": "Greater London",
        "created_at": "2026-01-01T09:00:00Z",
        "creation_source": "api",
        "date_of_birth": "1990-01-01",
        "display_name": "Dr Alex Morgan",
        "email": "alex.morgan@example.com",
        "first_name": "Alex",
        "is_opted_out_of_sms": false,
        "last_name": "Morgan",
        "mobile": "7700900123",
        "mobile_country_dial_code": "GB",
        "nhs_number": "485 777 3456",
        "phone": "2071234567",
        "phone_country_dial_code": "GB",
        "phone_number": "+44 7700 900123",
        "postcode": "W1G 9PF",
        "sex": "female",
        "title": "Dr",
        "updated_at": "2026-01-01T09:00:00Z"
      },
      "payor_id": "708192a3-b4c5-4def-8012-3456789abcde",
      "updated_at": "2026-01-01T09:00:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": "eyJzdGFydF90aW1lIjoiMjAyNi0wMS0wMVQwOTowMDowMFoifQ",
  "url": "/v1/patient_connections"
}

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

post/v1/patients/:patient_id/connections

Create a PatientConnection

Connects the Patient to an existing Organization, such as a GP practice. If the Patient is already connected, Carebit returns that PatientConnection and grants this Organization access. This endpoint does not create Organizations. Search with GET /v1/organizations first.

Required API scopes: patient_connections.create

Parameters

patient_id
path · 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

clinician_idstring | null · uuid
The Clinician at the target Organization. The Clinician must already belong to that Organization. Pass null on update to remove the Clinician.
gp_statusstring | null
Whether this Organization has recorded a GP for the Patient.
Allowed values: none_or_omitted | has_gp | no_gp_required | null
is_activeboolean
Whether the PatientConnection is active. Defaults to true on create.
organization_idstring · uuidrequired
The existing Organization to connect the Patient to. Required on create. This endpoint does not create Organizations.
payor_idstring · uuid
The Patient's Payor this Organization should use as the default billing party. The Payor must belong to the Patient.

Responses

200

The Patient was already connected to the Organization. Carebit returned the existing PatientConnection.

clinician_idstring | null · uuidrequired
The Clinician associated with this registration, when one is assigned.
created_atstring · date-timerequired
An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
gp_statusstring | nullrequired
Whether this Organization has recorded a GP for the Patient. has_gp means a GP PatientConnection is expected. no_gp_required means the Patient does not need a GP. none_or_omitted means no GP has been recorded.
Allowed values: none_or_omitted | has_gp | no_gp_required | null
idstring · uuidrequired
The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
is_activebooleanrequired
Whether the Patient registration is active.
linksobjectrequired
URLs to related resources.
- patientstring · urirequired
  The full URL of a related resource.
- payorstring | null · urirequired
  The full URL of a related resource.
objectanyrequired
Discriminator value emitted at object.
organizationobjectrequired
- address_line_1string | nullrequired
  The primary address line of the organization.
- address_line_2string | nullrequired
  The secondary address line of the organization.
- citystring | nullrequired
  The city in the organization'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 organization's postal address.
- created_atstring · date-timerequired
  An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
- currencystring | nullrequired
  The ISO 4217 currency code used by the organization. Must be one of chf, eur, gbp, or usd. Null when this Organization is returned from GET /v1/organizations or nested on a PatientConnection.
- emailstring | null · emailrequired
  The contact email address of the organization. Null when this Organization is returned from GET /v1/organizations or nested on a PatientConnection.
- formatted_addressstring | nullrequired
  The single-line address of the organization, formatted for display.
- idstring · uuidrequired
  The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
- namestringrequired
  The display name of the organization, for example Acme Healthcare.
- objectanyrequired
  Discriminator value emitted at object.
- organization_typestring | nullrequired
  The kind of organization. Use gp_practice when attaching a GP.
  Allowed values: consultant | gp_practice | hospital | laboratory | legal | other | pharmacy | private_practice | null
- phonestring | nullrequired
  The formatted contact phone number of the organization. Null when this Organization is returned from GET /v1/organizations or nested on a PatientConnection.
- postcodestring | nullrequired
  The postal code in the organization's postal address.
- subdomainstring | nullrequired
  The URL-safe subdomain that identifies the organization. Null when this Organization is returned from GET /v1/organizations or nested on a PatientConnection.
- time_zonestring | nullrequired
  The IANA time zone used to interpret scheduling dates and display appointment times. Always Europe/London when present. Null when this Organization is returned from GET /v1/organizations or nested on a PatientConnection.
- updated_atstring · date-timerequired
  An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
organization_idstring · uuidrequired
The Organization with which the Patient was registered.
patientobjectrequired
- 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.
payor_idstring | null · uuidrequired
The Payor this Organization uses as the default billing party for the Patient.
updated_atstring · date-timerequired
An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.

Example

{
  "id": "fcdd446b-eef0-4bf2-83d1-35764265817d",
  "object": "patient_connection",
  "clinician_id": "2b3c4d5e-6f70-489a-9bcd-ef0123456789",
  "created_at": "2026-01-01T09:00:00Z",
  "gp_status": "none_or_omitted",
  "is_active": true,
  "links":  … }
    "patient": "https://api.carebit.co/v1/patients/1a2b3c4d-5e6f-4789-8abc-def012345678",
    "payor": "https://api.carebit.co/v1/payors/708192a3-b4c5-4def-8012-3456789abcde"
  },
  "organization":  … }
    "id": "8192a3b4-c5d6-4ef0-9123-456789abcdef",
    "object": "organization",
    "address_line_1": "10 Harley Street",
    "address_line_2": "Marylebone",
    "city": "London",
    "country_code": "GB",
    "county": "Greater London",
    "created_at": "2026-01-01T09:00:00Z",
    "currency": "GBP",
    "email": "alex.morgan@example.com",
    "formatted_address": "10 Harley Street, Marylebone, London, W1G 9PF",
    "name": "Harley Street Clinic",
    "organization_type": "consultant",
    "phone": "2071234567",
    "postcode": "W1G 9PF",
    "subdomain": "harley-street-clinic",
    "time_zone": "Example time zone",
    "updated_at": "2026-01-01T09:00:00Z"
  },
  "organization_id": "8192a3b4-c5d6-4ef0-9123-456789abcdef",
  "patient":  … }
    "id": "1a2b3c4d-5e6f-4789-8abc-def012345678",
    "object": "patient",
    "address_line_1": "10 Harley Street",
    "address_line_2": "Marylebone",
    "city": "London",
    "country_code": "GB",
    "county": "Greater London",
    "created_at": "2026-01-01T09:00:00Z",
    "creation_source": "api",
    "date_of_birth": "1990-01-01",
    "display_name": "Dr Alex Morgan",
    "email": "alex.morgan@example.com",
    "first_name": "Alex",
    "is_opted_out_of_sms": false,
    "last_name": "Morgan",
    "mobile": "7700900123",
    "mobile_country_dial_code": "GB",
    "nhs_number": "485 777 3456",
    "phone": "2071234567",
    "phone_country_dial_code": "GB",
    "phone_number": "+44 7700 900123",
    "postcode": "W1G 9PF",
    "sex": "female",
    "title": "Dr",
    "updated_at": "2026-01-01T09:00:00Z"
  },
  "payor_id": "708192a3-b4c5-4def-8012-3456789abcde",
  "updated_at": "2026-01-01T09:00:00Z"
}

201

PatientConnection created.

clinician_idstring | null · uuidrequired
The Clinician associated with this registration, when one is assigned.
created_atstring · date-timerequired
An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
gp_statusstring | nullrequired
Whether this Organization has recorded a GP for the Patient. has_gp means a GP PatientConnection is expected. no_gp_required means the Patient does not need a GP. none_or_omitted means no GP has been recorded.
Allowed values: none_or_omitted | has_gp | no_gp_required | null
idstring · uuidrequired
The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
is_activebooleanrequired
Whether the Patient registration is active.
linksobjectrequired
URLs to related resources.
- patientstring · urirequired
  The full URL of a related resource.
- payorstring | null · urirequired
  The full URL of a related resource.
objectanyrequired
Discriminator value emitted at object.
organizationobjectrequired
- address_line_1string | nullrequired
  The primary address line of the organization.
- address_line_2string | nullrequired
  The secondary address line of the organization.
- citystring | nullrequired
  The city in the organization'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 organization's postal address.
- created_atstring · date-timerequired
  An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
- currencystring | nullrequired
  The ISO 4217 currency code used by the organization. Must be one of chf, eur, gbp, or usd. Null when this Organization is returned from GET /v1/organizations or nested on a PatientConnection.
- emailstring | null · emailrequired
  The contact email address of the organization. Null when this Organization is returned from GET /v1/organizations or nested on a PatientConnection.
- formatted_addressstring | nullrequired
  The single-line address of the organization, formatted for display.
- idstring · uuidrequired
  The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
- namestringrequired
  The display name of the organization, for example Acme Healthcare.
- objectanyrequired
  Discriminator value emitted at object.
- organization_typestring | nullrequired
  The kind of organization. Use gp_practice when attaching a GP.
  Allowed values: consultant | gp_practice | hospital | laboratory | legal | other | pharmacy | private_practice | null
- phonestring | nullrequired
  The formatted contact phone number of the organization. Null when this Organization is returned from GET /v1/organizations or nested on a PatientConnection.
- postcodestring | nullrequired
  The postal code in the organization's postal address.
- subdomainstring | nullrequired
  The URL-safe subdomain that identifies the organization. Null when this Organization is returned from GET /v1/organizations or nested on a PatientConnection.
- time_zonestring | nullrequired
  The IANA time zone used to interpret scheduling dates and display appointment times. Always Europe/London when present. Null when this Organization is returned from GET /v1/organizations or nested on a PatientConnection.
- updated_atstring · date-timerequired
  An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
organization_idstring · uuidrequired
The Organization with which the Patient was registered.
patientobjectrequired
- 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.
payor_idstring | null · uuidrequired
The Payor this Organization uses as the default billing party for the Patient.
updated_atstring · date-timerequired
An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.

Example

{
  "id": "fcdd446b-eef0-4bf2-83d1-35764265817d",
  "object": "patient_connection",
  "clinician_id": "2b3c4d5e-6f70-489a-9bcd-ef0123456789",
  "created_at": "2026-01-01T09:00:00Z",
  "gp_status": "none_or_omitted",
  "is_active": true,
  "links":  … }
    "patient": "https://api.carebit.co/v1/patients/1a2b3c4d-5e6f-4789-8abc-def012345678",
    "payor": "https://api.carebit.co/v1/payors/708192a3-b4c5-4def-8012-3456789abcde"
  },
  "organization":  … }
    "id": "8192a3b4-c5d6-4ef0-9123-456789abcdef",
    "object": "organization",
    "address_line_1": "10 Harley Street",
    "address_line_2": "Marylebone",
    "city": "London",
    "country_code": "GB",
    "county": "Greater London",
    "created_at": "2026-01-01T09:00:00Z",
    "currency": "GBP",
    "email": "alex.morgan@example.com",
    "formatted_address": "10 Harley Street, Marylebone, London, W1G 9PF",
    "name": "Harley Street Clinic",
    "organization_type": "consultant",
    "phone": "2071234567",
    "postcode": "W1G 9PF",
    "subdomain": "harley-street-clinic",
    "time_zone": "Example time zone",
    "updated_at": "2026-01-01T09:00:00Z"
  },
  "organization_id": "8192a3b4-c5d6-4ef0-9123-456789abcdef",
  "patient":  … }
    "id": "1a2b3c4d-5e6f-4789-8abc-def012345678",
    "object": "patient",
    "address_line_1": "10 Harley Street",
    "address_line_2": "Marylebone",
    "city": "London",
    "country_code": "GB",
    "county": "Greater London",
    "created_at": "2026-01-01T09:00:00Z",
    "creation_source": "api",
    "date_of_birth": "1990-01-01",
    "display_name": "Dr Alex Morgan",
    "email": "alex.morgan@example.com",
    "first_name": "Alex",
    "is_opted_out_of_sms": false,
    "last_name": "Morgan",
    "mobile": "7700900123",
    "mobile_country_dial_code": "GB",
    "nhs_number": "485 777 3456",
    "phone": "2071234567",
    "phone_country_dial_code": "GB",
    "phone_number": "+44 7700 900123",
    "postcode": "W1G 9PF",
    "sex": "female",
    "title": "Dr",
    "updated_at": "2026-01-01T09:00:00Z"
  },
  "payor_id": "708192a3-b4c5-4def-8012-3456789abcde",
  "updated_at": "2026-01-01T09:00:00Z"
}

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

The Patient, Organization, Clinician, or Payor was not found.

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 POST "https://api.carebit.co/v1/patients/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c/connections" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "organization_id": "00000000-0000-4000-8000-000000000018"
}'

200 response

{
  "id": "fcdd446b-eef0-4bf2-83d1-35764265817d",
  "object": "patient_connection",
  "clinician_id": "2b3c4d5e-6f70-489a-9bcd-ef0123456789",
  "created_at": "2026-01-01T09:00:00Z",
  "gp_status": "none_or_omitted",
  "is_active": true,
  "links":  … }
    "patient": "https://api.carebit.co/v1/patients/1a2b3c4d-5e6f-4789-8abc-def012345678",
    "payor": "https://api.carebit.co/v1/payors/708192a3-b4c5-4def-8012-3456789abcde"
  },
  "organization":  … }
    "id": "8192a3b4-c5d6-4ef0-9123-456789abcdef",
    "object": "organization",
    "address_line_1": "10 Harley Street",
    "address_line_2": "Marylebone",
    "city": "London",
    "country_code": "GB",
    "county": "Greater London",
    "created_at": "2026-01-01T09:00:00Z",
    "currency": "GBP",
    "email": "alex.morgan@example.com",
    "formatted_address": "10 Harley Street, Marylebone, London, W1G 9PF",
    "name": "Harley Street Clinic",
    "organization_type": "consultant",
    "phone": "2071234567",
    "postcode": "W1G 9PF",
    "subdomain": "harley-street-clinic",
    "time_zone": "Example time zone",
    "updated_at": "2026-01-01T09:00:00Z"
  },
  "organization_id": "8192a3b4-c5d6-4ef0-9123-456789abcdef",
  "patient":  … }
    "id": "1a2b3c4d-5e6f-4789-8abc-def012345678",
    "object": "patient",
    "address_line_1": "10 Harley Street",
    "address_line_2": "Marylebone",
    "city": "London",
    "country_code": "GB",
    "county": "Greater London",
    "created_at": "2026-01-01T09:00:00Z",
    "creation_source": "api",
    "date_of_birth": "1990-01-01",
    "display_name": "Dr Alex Morgan",
    "email": "alex.morgan@example.com",
    "first_name": "Alex",
    "is_opted_out_of_sms": false,
    "last_name": "Morgan",
    "mobile": "7700900123",
    "mobile_country_dial_code": "GB",
    "nhs_number": "485 777 3456",
    "phone": "2071234567",
    "phone_country_dial_code": "GB",
    "phone_number": "+44 7700 900123",
    "postcode": "W1G 9PF",
    "sex": "female",
    "title": "Dr",
    "updated_at": "2026-01-01T09:00:00Z"
  },
  "payor_id": "708192a3-b4c5-4def-8012-3456789abcde",
  "updated_at": "2026-01-01T09:00:00Z"
}

201 response

{
  "id": "fcdd446b-eef0-4bf2-83d1-35764265817d",
  "object": "patient_connection",
  "clinician_id": "2b3c4d5e-6f70-489a-9bcd-ef0123456789",
  "created_at": "2026-01-01T09:00:00Z",
  "gp_status": "none_or_omitted",
  "is_active": true,
  "links":  … }
    "patient": "https://api.carebit.co/v1/patients/1a2b3c4d-5e6f-4789-8abc-def012345678",
    "payor": "https://api.carebit.co/v1/payors/708192a3-b4c5-4def-8012-3456789abcde"
  },
  "organization":  … }
    "id": "8192a3b4-c5d6-4ef0-9123-456789abcdef",
    "object": "organization",
    "address_line_1": "10 Harley Street",
    "address_line_2": "Marylebone",
    "city": "London",
    "country_code": "GB",
    "county": "Greater London",
    "created_at": "2026-01-01T09:00:00Z",
    "currency": "GBP",
    "email": "alex.morgan@example.com",
    "formatted_address": "10 Harley Street, Marylebone, London, W1G 9PF",
    "name": "Harley Street Clinic",
    "organization_type": "consultant",
    "phone": "2071234567",
    "postcode": "W1G 9PF",
    "subdomain": "harley-street-clinic",
    "time_zone": "Example time zone",
    "updated_at": "2026-01-01T09:00:00Z"
  },
  "organization_id": "8192a3b4-c5d6-4ef0-9123-456789abcdef",
  "patient":  … }
    "id": "1a2b3c4d-5e6f-4789-8abc-def012345678",
    "object": "patient",
    "address_line_1": "10 Harley Street",
    "address_line_2": "Marylebone",
    "city": "London",
    "country_code": "GB",
    "county": "Greater London",
    "created_at": "2026-01-01T09:00:00Z",
    "creation_source": "api",
    "date_of_birth": "1990-01-01",
    "display_name": "Dr Alex Morgan",
    "email": "alex.morgan@example.com",
    "first_name": "Alex",
    "is_opted_out_of_sms": false,
    "last_name": "Morgan",
    "mobile": "7700900123",
    "mobile_country_dial_code": "GB",
    "nhs_number": "485 777 3456",
    "phone": "2071234567",
    "phone_country_dial_code": "GB",
    "phone_number": "+44 7700 900123",
    "postcode": "W1G 9PF",
    "sex": "female",
    "title": "Dr",
    "updated_at": "2026-01-01T09:00:00Z"
  },
  "payor_id": "708192a3-b4c5-4def-8012-3456789abcde",
  "updated_at": "2026-01-01T09:00:00Z"
}

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

get/v1/patients/:patient_id/connections/:id

Get an unlocked PatientConnection

Required API scopes: patient_connections.read

Parameters

patient_id
path · required
string
-
id
path · required
string
-

Responses

200

The requested PatientConnection.

clinician_idstring | null · uuidrequired
The Clinician associated with this registration, when one is assigned.
created_atstring · date-timerequired
An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
gp_statusstring | nullrequired
Whether this Organization has recorded a GP for the Patient. has_gp means a GP PatientConnection is expected. no_gp_required means the Patient does not need a GP. none_or_omitted means no GP has been recorded.
Allowed values: none_or_omitted | has_gp | no_gp_required | null
idstring · uuidrequired
The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
is_activebooleanrequired
Whether the Patient registration is active.
linksobjectrequired
URLs to related resources.
- patientstring · urirequired
  The full URL of a related resource.
- payorstring | null · urirequired
  The full URL of a related resource.
objectanyrequired
Discriminator value emitted at object.
organizationobjectrequired
- address_line_1string | nullrequired
  The primary address line of the organization.
- address_line_2string | nullrequired
  The secondary address line of the organization.
- citystring | nullrequired
  The city in the organization'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 organization's postal address.
- created_atstring · date-timerequired
  An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
- currencystring | nullrequired
  The ISO 4217 currency code used by the organization. Must be one of chf, eur, gbp, or usd. Null when this Organization is returned from GET /v1/organizations or nested on a PatientConnection.
- emailstring | null · emailrequired
  The contact email address of the organization. Null when this Organization is returned from GET /v1/organizations or nested on a PatientConnection.
- formatted_addressstring | nullrequired
  The single-line address of the organization, formatted for display.
- idstring · uuidrequired
  The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
- namestringrequired
  The display name of the organization, for example Acme Healthcare.
- objectanyrequired
  Discriminator value emitted at object.
- organization_typestring | nullrequired
  The kind of organization. Use gp_practice when attaching a GP.
  Allowed values: consultant | gp_practice | hospital | laboratory | legal | other | pharmacy | private_practice | null
- phonestring | nullrequired
  The formatted contact phone number of the organization. Null when this Organization is returned from GET /v1/organizations or nested on a PatientConnection.
- postcodestring | nullrequired
  The postal code in the organization's postal address.
- subdomainstring | nullrequired
  The URL-safe subdomain that identifies the organization. Null when this Organization is returned from GET /v1/organizations or nested on a PatientConnection.
- time_zonestring | nullrequired
  The IANA time zone used to interpret scheduling dates and display appointment times. Always Europe/London when present. Null when this Organization is returned from GET /v1/organizations or nested on a PatientConnection.
- updated_atstring · date-timerequired
  An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
organization_idstring · uuidrequired
The Organization with which the Patient was registered.
patientobjectrequired
- 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.
payor_idstring | null · uuidrequired
The Payor this Organization uses as the default billing party for the Patient.
updated_atstring · date-timerequired
An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.

Example

{
  "id": "fcdd446b-eef0-4bf2-83d1-35764265817d",
  "object": "patient_connection",
  "clinician_id": "2b3c4d5e-6f70-489a-9bcd-ef0123456789",
  "created_at": "2026-01-01T09:00:00Z",
  "gp_status": "none_or_omitted",
  "is_active": true,
  "links":  … }
    "patient": "https://api.carebit.co/v1/patients/1a2b3c4d-5e6f-4789-8abc-def012345678",
    "payor": "https://api.carebit.co/v1/payors/708192a3-b4c5-4def-8012-3456789abcde"
  },
  "organization":  … }
    "id": "8192a3b4-c5d6-4ef0-9123-456789abcdef",
    "object": "organization",
    "address_line_1": "10 Harley Street",
    "address_line_2": "Marylebone",
    "city": "London",
    "country_code": "GB",
    "county": "Greater London",
    "created_at": "2026-01-01T09:00:00Z",
    "currency": "GBP",
    "email": "alex.morgan@example.com",
    "formatted_address": "10 Harley Street, Marylebone, London, W1G 9PF",
    "name": "Harley Street Clinic",
    "organization_type": "consultant",
    "phone": "2071234567",
    "postcode": "W1G 9PF",
    "subdomain": "harley-street-clinic",
    "time_zone": "Example time zone",
    "updated_at": "2026-01-01T09:00:00Z"
  },
  "organization_id": "8192a3b4-c5d6-4ef0-9123-456789abcdef",
  "patient":  … }
    "id": "1a2b3c4d-5e6f-4789-8abc-def012345678",
    "object": "patient",
    "address_line_1": "10 Harley Street",
    "address_line_2": "Marylebone",
    "city": "London",
    "country_code": "GB",
    "county": "Greater London",
    "created_at": "2026-01-01T09:00:00Z",
    "creation_source": "api",
    "date_of_birth": "1990-01-01",
    "display_name": "Dr Alex Morgan",
    "email": "alex.morgan@example.com",
    "first_name": "Alex",
    "is_opted_out_of_sms": false,
    "last_name": "Morgan",
    "mobile": "7700900123",
    "mobile_country_dial_code": "GB",
    "nhs_number": "485 777 3456",
    "phone": "2071234567",
    "phone_country_dial_code": "GB",
    "phone_number": "+44 7700 900123",
    "postcode": "W1G 9PF",
    "sex": "female",
    "title": "Dr",
    "updated_at": "2026-01-01T09:00:00Z"
  },
  "payor_id": "708192a3-b4c5-4def-8012-3456789abcde",
  "updated_at": "2026-01-01T09:00:00Z"
}

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/connections/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN"

200 response

{
  "id": "fcdd446b-eef0-4bf2-83d1-35764265817d",
  "object": "patient_connection",
  "clinician_id": "2b3c4d5e-6f70-489a-9bcd-ef0123456789",
  "created_at": "2026-01-01T09:00:00Z",
  "gp_status": "none_or_omitted",
  "is_active": true,
  "links":  … }
    "patient": "https://api.carebit.co/v1/patients/1a2b3c4d-5e6f-4789-8abc-def012345678",
    "payor": "https://api.carebit.co/v1/payors/708192a3-b4c5-4def-8012-3456789abcde"
  },
  "organization":  … }
    "id": "8192a3b4-c5d6-4ef0-9123-456789abcdef",
    "object": "organization",
    "address_line_1": "10 Harley Street",
    "address_line_2": "Marylebone",
    "city": "London",
    "country_code": "GB",
    "county": "Greater London",
    "created_at": "2026-01-01T09:00:00Z",
    "currency": "GBP",
    "email": "alex.morgan@example.com",
    "formatted_address": "10 Harley Street, Marylebone, London, W1G 9PF",
    "name": "Harley Street Clinic",
    "organization_type": "consultant",
    "phone": "2071234567",
    "postcode": "W1G 9PF",
    "subdomain": "harley-street-clinic",
    "time_zone": "Example time zone",
    "updated_at": "2026-01-01T09:00:00Z"
  },
  "organization_id": "8192a3b4-c5d6-4ef0-9123-456789abcdef",
  "patient":  … }
    "id": "1a2b3c4d-5e6f-4789-8abc-def012345678",
    "object": "patient",
    "address_line_1": "10 Harley Street",
    "address_line_2": "Marylebone",
    "city": "London",
    "country_code": "GB",
    "county": "Greater London",
    "created_at": "2026-01-01T09:00:00Z",
    "creation_source": "api",
    "date_of_birth": "1990-01-01",
    "display_name": "Dr Alex Morgan",
    "email": "alex.morgan@example.com",
    "first_name": "Alex",
    "is_opted_out_of_sms": false,
    "last_name": "Morgan",
    "mobile": "7700900123",
    "mobile_country_dial_code": "GB",
    "nhs_number": "485 777 3456",
    "phone": "2071234567",
    "phone_country_dial_code": "GB",
    "phone_number": "+44 7700 900123",
    "postcode": "W1G 9PF",
    "sex": "female",
    "title": "Dr",
    "updated_at": "2026-01-01T09:00:00Z"
  },
  "payor_id": "708192a3-b4c5-4def-8012-3456789abcde",
  "updated_at": "2026-01-01T09:00:00Z"
}

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/:patient_id/connections/:id

Update this Organization's PatientConnection

Updates this Organization's PatientConnection for the Patient. Unlocked connections to other Organizations, such as a GP, can be listed and retrieved but not updated. Use payor_id to select the default billing party this Organization uses for the Patient. You cannot change organization_id; connect the Patient to a different Organization with POST instead.

Required API scopes: patient_connections.update

Parameters

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

clinician_idstring | null · uuid
The Clinician at the target Organization. The Clinician must already belong to that Organization. Pass null to remove the Clinician.
gp_statusstring | null
Whether this Organization has recorded a GP for the Patient.
Allowed values: none_or_omitted | has_gp | no_gp_required | null
is_activeboolean
Whether the PatientConnection is active.
payor_idstring · uuid
The Patient's Payor this Organization should use as the default billing party. The Payor must belong to the Patient.

Responses

200

The requested PatientConnection.

clinician_idstring | null · uuidrequired
The Clinician associated with this registration, when one is assigned.
created_atstring · date-timerequired
An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
gp_statusstring | nullrequired
Whether this Organization has recorded a GP for the Patient. has_gp means a GP PatientConnection is expected. no_gp_required means the Patient does not need a GP. none_or_omitted means no GP has been recorded.
Allowed values: none_or_omitted | has_gp | no_gp_required | null
idstring · uuidrequired
The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
is_activebooleanrequired
Whether the Patient registration is active.
linksobjectrequired
URLs to related resources.
- patientstring · urirequired
  The full URL of a related resource.
- payorstring | null · urirequired
  The full URL of a related resource.
objectanyrequired
Discriminator value emitted at object.
organizationobjectrequired
- address_line_1string | nullrequired
  The primary address line of the organization.
- address_line_2string | nullrequired
  The secondary address line of the organization.
- citystring | nullrequired
  The city in the organization'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 organization's postal address.
- created_atstring · date-timerequired
  An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
- currencystring | nullrequired
  The ISO 4217 currency code used by the organization. Must be one of chf, eur, gbp, or usd. Null when this Organization is returned from GET /v1/organizations or nested on a PatientConnection.
- emailstring | null · emailrequired
  The contact email address of the organization. Null when this Organization is returned from GET /v1/organizations or nested on a PatientConnection.
- formatted_addressstring | nullrequired
  The single-line address of the organization, formatted for display.
- idstring · uuidrequired
  The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
- namestringrequired
  The display name of the organization, for example Acme Healthcare.
- objectanyrequired
  Discriminator value emitted at object.
- organization_typestring | nullrequired
  The kind of organization. Use gp_practice when attaching a GP.
  Allowed values: consultant | gp_practice | hospital | laboratory | legal | other | pharmacy | private_practice | null
- phonestring | nullrequired
  The formatted contact phone number of the organization. Null when this Organization is returned from GET /v1/organizations or nested on a PatientConnection.
- postcodestring | nullrequired
  The postal code in the organization's postal address.
- subdomainstring | nullrequired
  The URL-safe subdomain that identifies the organization. Null when this Organization is returned from GET /v1/organizations or nested on a PatientConnection.
- time_zonestring | nullrequired
  The IANA time zone used to interpret scheduling dates and display appointment times. Always Europe/London when present. Null when this Organization is returned from GET /v1/organizations or nested on a PatientConnection.
- updated_atstring · date-timerequired
  An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
organization_idstring · uuidrequired
The Organization with which the Patient was registered.
patientobjectrequired
- 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.
payor_idstring | null · uuidrequired
The Payor this Organization uses as the default billing party for the Patient.
updated_atstring · date-timerequired
An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.

Example

{
  "id": "fcdd446b-eef0-4bf2-83d1-35764265817d",
  "object": "patient_connection",
  "clinician_id": "2b3c4d5e-6f70-489a-9bcd-ef0123456789",
  "created_at": "2026-01-01T09:00:00Z",
  "gp_status": "none_or_omitted",
  "is_active": true,
  "links":  … }
    "patient": "https://api.carebit.co/v1/patients/1a2b3c4d-5e6f-4789-8abc-def012345678",
    "payor": "https://api.carebit.co/v1/payors/708192a3-b4c5-4def-8012-3456789abcde"
  },
  "organization":  … }
    "id": "8192a3b4-c5d6-4ef0-9123-456789abcdef",
    "object": "organization",
    "address_line_1": "10 Harley Street",
    "address_line_2": "Marylebone",
    "city": "London",
    "country_code": "GB",
    "county": "Greater London",
    "created_at": "2026-01-01T09:00:00Z",
    "currency": "GBP",
    "email": "alex.morgan@example.com",
    "formatted_address": "10 Harley Street, Marylebone, London, W1G 9PF",
    "name": "Harley Street Clinic",
    "organization_type": "consultant",
    "phone": "2071234567",
    "postcode": "W1G 9PF",
    "subdomain": "harley-street-clinic",
    "time_zone": "Example time zone",
    "updated_at": "2026-01-01T09:00:00Z"
  },
  "organization_id": "8192a3b4-c5d6-4ef0-9123-456789abcdef",
  "patient":  … }
    "id": "1a2b3c4d-5e6f-4789-8abc-def012345678",
    "object": "patient",
    "address_line_1": "10 Harley Street",
    "address_line_2": "Marylebone",
    "city": "London",
    "country_code": "GB",
    "county": "Greater London",
    "created_at": "2026-01-01T09:00:00Z",
    "creation_source": "api",
    "date_of_birth": "1990-01-01",
    "display_name": "Dr Alex Morgan",
    "email": "alex.morgan@example.com",
    "first_name": "Alex",
    "is_opted_out_of_sms": false,
    "last_name": "Morgan",
    "mobile": "7700900123",
    "mobile_country_dial_code": "GB",
    "nhs_number": "485 777 3456",
    "phone": "2071234567",
    "phone_country_dial_code": "GB",
    "phone_number": "+44 7700 900123",
    "postcode": "W1G 9PF",
    "sex": "female",
    "title": "Dr",
    "updated_at": "2026-01-01T09:00:00Z"
  },
  "payor_id": "708192a3-b4c5-4def-8012-3456789abcde",
  "updated_at": "2026-01-01T09:00:00Z"
}

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/connections/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "payor_id": "00000000-0000-4000-8000-00000000000e"
}'

200 response

{
  "id": "fcdd446b-eef0-4bf2-83d1-35764265817d",
  "object": "patient_connection",
  "clinician_id": "2b3c4d5e-6f70-489a-9bcd-ef0123456789",
  "created_at": "2026-01-01T09:00:00Z",
  "gp_status": "none_or_omitted",
  "is_active": true,
  "links":  … }
    "patient": "https://api.carebit.co/v1/patients/1a2b3c4d-5e6f-4789-8abc-def012345678",
    "payor": "https://api.carebit.co/v1/payors/708192a3-b4c5-4def-8012-3456789abcde"
  },
  "organization":  … }
    "id": "8192a3b4-c5d6-4ef0-9123-456789abcdef",
    "object": "organization",
    "address_line_1": "10 Harley Street",
    "address_line_2": "Marylebone",
    "city": "London",
    "country_code": "GB",
    "county": "Greater London",
    "created_at": "2026-01-01T09:00:00Z",
    "currency": "GBP",
    "email": "alex.morgan@example.com",
    "formatted_address": "10 Harley Street, Marylebone, London, W1G 9PF",
    "name": "Harley Street Clinic",
    "organization_type": "consultant",
    "phone": "2071234567",
    "postcode": "W1G 9PF",
    "subdomain": "harley-street-clinic",
    "time_zone": "Example time zone",
    "updated_at": "2026-01-01T09:00:00Z"
  },
  "organization_id": "8192a3b4-c5d6-4ef0-9123-456789abcdef",
  "patient":  … }
    "id": "1a2b3c4d-5e6f-4789-8abc-def012345678",
    "object": "patient",
    "address_line_1": "10 Harley Street",
    "address_line_2": "Marylebone",
    "city": "London",
    "country_code": "GB",
    "county": "Greater London",
    "created_at": "2026-01-01T09:00:00Z",
    "creation_source": "api",
    "date_of_birth": "1990-01-01",
    "display_name": "Dr Alex Morgan",
    "email": "alex.morgan@example.com",
    "first_name": "Alex",
    "is_opted_out_of_sms": false,
    "last_name": "Morgan",
    "mobile": "7700900123",
    "mobile_country_dial_code": "GB",
    "nhs_number": "485 777 3456",
    "phone": "2071234567",
    "phone_country_dial_code": "GB",
    "phone_number": "+44 7700 900123",
    "postcode": "W1G 9PF",
    "sex": "female",
    "title": "Dr",
    "updated_at": "2026-01-01T09:00:00Z"
  },
  "payor_id": "708192a3-b4c5-4def-8012-3456789abcde",
  "updated_at": "2026-01-01T09:00:00Z"
}

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.