Carebit API

Organization

The Organization connected to the access token.

Endpoints

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

get/v1/organizationGet the Organization for this access token
get/v1/organizationsSearch Organizations

get/v1/organization

Get the Organization for this access token

Required API scopes: organization.read

Responses

200

The requested Organization.

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.

Example

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

401

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

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

Example

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

403

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

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

Example

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

429

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

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

Example

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

Request

curl -X GET "https://api.carebit.co/v1/organization" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN"

200 response

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

401 response

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

403 response

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

429 response

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

get/v1/organizations

Search Organizations

Searches active Organizations by name or postcode so you can attach a PatientConnection, such as a GP practice. This endpoint does not create Organizations. At least one of name or postcode is required. The response uses the Organization object. Email, subdomain, phone, currency, and time_zone are null so a search cannot harvest contact details.

Required API scopes: organization.search

Parameters

name
query
string
Case-insensitive partial match on the Organization name. At least two characters. Provide name or postcode.
postcode
query
string
Case-insensitive partial match on the postal code. At least two characters. Provide name or postcode.
organization_type
query
string · enum: consultant | gp_practice | hospital | laboratory | legal | other | pharmacy | private_practice
Return only Organizations of this type. Use gp_practice when searching for a GP.
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 Organization objects.

dataarrayrequired
- itemsobject
  - 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.
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": "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"
    }
  ],
  "has_more": false,
  "next_cursor": "eyJzdGFydF90aW1lIjoiMjAyNi0wMS0wMVQwOTowMDowMFoifQ",
  "url": "/v1/organizations"
}

400

The search is missing name and postcode, a value is too short, or organization_type is not a documented value.

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

Example

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

401

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

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

Example

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

403

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

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

Example

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

429

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

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

Example

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

Request

curl -X GET "https://api.carebit.co/v1/organizations?name=High%20Street%20Surgery&postcode=SW1A&organization_type=gp_practice" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN"

200 response

{
  "object": "list",
  "data":  … ]
     … }
      "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"
    }
  ],
  "has_more": false,
  "next_cursor": "eyJzdGFydF90aW1lIjoiMjAyNi0wMS0wMVQwOTowMDowMFoifQ",
  "url": "/v1/organizations"
}

400 response

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

401 response

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

403 response

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

429 response

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

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