# Payors The people and organizations responsible for a Patient's charges. ## List Alternative Payors `GET /v1/alternative_payors` **Required API scopes:** `payors.read` ## Parameters - `limit` (query, `integer`) - The maximum number of items to return. Defaults to `25`; the maximum is `100`. - `starting_after` (query, `string`) - Return items after this resource ID. You cannot use this with `cursor`. - `cursor` (query, `string`) - The `next_cursor` value from the previous page. You cannot use this with `starting_after`. ## Response `200` Paginated list of `AlternativePayor` objects. - `any` ### Example ```json { "object": "list", "data": [ { "id": null, "object": "alternative_payor", "created_at": "2026-01-01T09:00:00Z", "name": "Acme Health Benefits", "payor_type": "insurance_company", "updated_at": "2026-01-01T09:00:00Z" } ], "has_more": false, "next_cursor": "eyJzdGFydF90aW1lIjoiMjAyNi0wMS0wMVQwOTowMDowMFoifQ", "url": "/v1/alternative_payors" } ``` ## Response `401` The access token is missing, invalid, expired, or revoked. - `object` - `error` (`object`) - The structured details that describe why the request failed. - `code` (`string`) - The machine-readable error code. - `errors` (`array | null`) - Additional errors from a failed validation. - `items` (`object`) - `code` (`string`) - The machine-readable code for this validation error. - `message` (`string`) - A message that explains this validation error. - `param` (`string | null`) - The name of the parameter that caused this validation error, when known. - `message` (`string`) - A message that explains the error and how to resolve it. - `param` (`string | null`) - The name of the parameter that caused the error, when known. - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error. ### Example ```json { "error": { "code": "resource_missing", "errors": [ { "code": "resource_missing", "message": "The requested resource was not found.", "param": "patient_id" } ], "message": "The requested resource was not found.", "param": "patient_id", "type": "authentication_error" } } ``` ## Response `403` The access token lacks the required scope, or the project is disabled. - `object` - `error` (`object`) - The structured details that describe why the request failed. - `code` (`string`) - The machine-readable error code. - `errors` (`array | null`) - Additional errors from a failed validation. - `items` (`object`) - `code` (`string`) - The machine-readable code for this validation error. - `message` (`string`) - A message that explains this validation error. - `param` (`string | null`) - The name of the parameter that caused this validation error, when known. - `message` (`string`) - A message that explains the error and how to resolve it. - `param` (`string | null`) - The name of the parameter that caused the error, when known. - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error. ### Example ```json { "error": { "code": "resource_missing", "errors": [ { "code": "resource_missing", "message": "The requested resource was not found.", "param": "patient_id" } ], "message": "The requested resource was not found.", "param": "patient_id", "type": "authentication_error" } } ``` ## Response `429` Too many requests. Retry after the delay indicated by `Retry-After`. - `object` - `error` (`object`) - The structured details that describe why the request failed. - `code` (`string`) - The machine-readable error code. - `errors` (`array | null`) - Additional errors from a failed validation. - `items` (`object`) - `code` (`string`) - The machine-readable code for this validation error. - `message` (`string`) - A message that explains this validation error. - `param` (`string | null`) - The name of the parameter that caused this validation error, when known. - `message` (`string`) - A message that explains the error and how to resolve it. - `param` (`string | null`) - The name of the parameter that caused the error, when known. - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error. ### Example ```json { "error": { "code": "resource_missing", "errors": [ { "code": "resource_missing", "message": "The requested resource was not found.", "param": "patient_id" } ], "message": "The requested resource was not found.", "param": "patient_id", "type": "authentication_error" } } ``` ## Code samples ```bash curl -X GET "https://api.carebit.co/v1/alternative_payors" \ -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN" ``` ```javascript const response = await fetch("https://api.carebit.co/v1/alternative_payors", { method: "GET", headers: { Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`, }, }); if (!response.ok) { throw new Error(`Carebit API error: ${response.status}`); } const data = await response.json(); ``` ```python import os import requests response = requests.get( "https://api.carebit.co/v1/alternative_payors", headers={ "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}", } ) response.raise_for_status() data = response.json() ``` ```ruby require "httparty" response = HTTParty.get( "https://api.carebit.co/v1/alternative_payors", headers: { "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}" } ) raise "Carebit API error: #{response.code}" unless response.success? data = response.parsed_response ``` ```php get("https://api.carebit.co/v1/alternative_payors", [ "headers" => [ "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"), ] ]); $data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR); ``` ## Get an Alternative Payor `GET /v1/alternative_payors/:id` **Required API scopes:** `payors.read` ## Parameters - `id` (path, `string`) (required) ## Response `200` The requested `AlternativePayor`. - `object` - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`. - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID. - `name` (`string`) - The name of the alternative payor. - `object` (`any`) - Discriminator value emitted at `object`. - `payor_type` (`string`) - enum: `legal`, `medical_facility`, `other`; The category of the alternative payor. - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`. ### Example ```json { "id": null, "object": "alternative_payor", "created_at": "2026-01-01T09:00:00Z", "name": "Acme Health Benefits", "payor_type": "insurance_company", "updated_at": "2026-01-01T09:00:00Z" } ``` ## Response `401` The access token is missing, invalid, expired, or revoked. - `object` - `error` (`object`) - The structured details that describe why the request failed. - `code` (`string`) - The machine-readable error code. - `errors` (`array | null`) - Additional errors from a failed validation. - `items` (`object`) - `code` (`string`) - The machine-readable code for this validation error. - `message` (`string`) - A message that explains this validation error. - `param` (`string | null`) - The name of the parameter that caused this validation error, when known. - `message` (`string`) - A message that explains the error and how to resolve it. - `param` (`string | null`) - The name of the parameter that caused the error, when known. - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error. ### Example ```json { "error": { "code": "resource_missing", "errors": [ { "code": "resource_missing", "message": "The requested resource was not found.", "param": "patient_id" } ], "message": "The requested resource was not found.", "param": "patient_id", "type": "authentication_error" } } ``` ## Response `403` The access token lacks the required scope, or the project is disabled. - `object` - `error` (`object`) - The structured details that describe why the request failed. - `code` (`string`) - The machine-readable error code. - `errors` (`array | null`) - Additional errors from a failed validation. - `items` (`object`) - `code` (`string`) - The machine-readable code for this validation error. - `message` (`string`) - A message that explains this validation error. - `param` (`string | null`) - The name of the parameter that caused this validation error, when known. - `message` (`string`) - A message that explains the error and how to resolve it. - `param` (`string | null`) - The name of the parameter that caused the error, when known. - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error. ### Example ```json { "error": { "code": "resource_missing", "errors": [ { "code": "resource_missing", "message": "The requested resource was not found.", "param": "patient_id" } ], "message": "The requested resource was not found.", "param": "patient_id", "type": "authentication_error" } } ``` ## Response `404` Error response. - `object` - `error` (`object`) - The structured details that describe why the request failed. - `code` (`string`) - The machine-readable error code. - `errors` (`array | null`) - Additional errors from a failed validation. - `items` (`object`) - `code` (`string`) - The machine-readable code for this validation error. - `message` (`string`) - A message that explains this validation error. - `param` (`string | null`) - The name of the parameter that caused this validation error, when known. - `message` (`string`) - A message that explains the error and how to resolve it. - `param` (`string | null`) - The name of the parameter that caused the error, when known. - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error. ### Example ```json { "error": { "code": "resource_missing", "errors": [ { "code": "resource_missing", "message": "The requested resource was not found.", "param": "patient_id" } ], "message": "The requested resource was not found.", "param": "patient_id", "type": "authentication_error" } } ``` ## Response `429` Too many requests. Retry after the delay indicated by `Retry-After`. - `object` - `error` (`object`) - The structured details that describe why the request failed. - `code` (`string`) - The machine-readable error code. - `errors` (`array | null`) - Additional errors from a failed validation. - `items` (`object`) - `code` (`string`) - The machine-readable code for this validation error. - `message` (`string`) - A message that explains this validation error. - `param` (`string | null`) - The name of the parameter that caused this validation error, when known. - `message` (`string`) - A message that explains the error and how to resolve it. - `param` (`string | null`) - The name of the parameter that caused the error, when known. - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error. ### Example ```json { "error": { "code": "resource_missing", "errors": [ { "code": "resource_missing", "message": "The requested resource was not found.", "param": "patient_id" } ], "message": "The requested resource was not found.", "param": "patient_id", "type": "authentication_error" } } ``` ## Code samples ```bash curl -X GET "https://api.carebit.co/v1/alternative_payors/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c" \ -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN" ``` ```javascript const response = await fetch("https://api.carebit.co/v1/alternative_payors/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c", { method: "GET", headers: { Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`, }, }); if (!response.ok) { throw new Error(`Carebit API error: ${response.status}`); } const data = await response.json(); ``` ```python import os import requests response = requests.get( "https://api.carebit.co/v1/alternative_payors/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c", headers={ "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}", } ) response.raise_for_status() data = response.json() ``` ```ruby require "httparty" response = HTTParty.get( "https://api.carebit.co/v1/alternative_payors/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c", headers: { "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}" } ) raise "Carebit API error: #{response.code}" unless response.success? data = response.parsed_response ``` ```php get("https://api.carebit.co/v1/alternative_payors/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c", [ "headers" => [ "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"), ] ]); $data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR); ``` ## List Insurance Companies `GET /v1/insurance_companies` Returns active insurance companies. Embassies and overseas government health offices are excluded. **Required API scopes:** `payors.read` ## Parameters - `limit` (query, `integer`) - The maximum number of items to return. Defaults to `25`; the maximum is `100`. - `starting_after` (query, `string`) - Return items after this resource ID. You cannot use this with `cursor`. - `cursor` (query, `string`) - The `next_cursor` value from the previous page. You cannot use this with `starting_after`. ## Response `200` Paginated list of `InsuranceCompany` objects. - `any` ### Example ```json { "object": "list", "data": [ { "id": "855e25b0-b138-48da-86ea-15162ce81f14", "object": "insurance_company", "created_at": "2026-01-01T09:00:00Z", "name": "Bupa", "updated_at": "2026-01-01T09:00:00Z" } ], "has_more": false, "next_cursor": "eyJzdGFydF90aW1lIjoiMjAyNi0wMS0wMVQwOTowMDowMFoifQ", "url": "/v1/insurance_companies" } ``` ## Response `401` The access token is missing, invalid, expired, or revoked. - `object` - `error` (`object`) - The structured details that describe why the request failed. - `code` (`string`) - The machine-readable error code. - `errors` (`array | null`) - Additional errors from a failed validation. - `items` (`object`) - `code` (`string`) - The machine-readable code for this validation error. - `message` (`string`) - A message that explains this validation error. - `param` (`string | null`) - The name of the parameter that caused this validation error, when known. - `message` (`string`) - A message that explains the error and how to resolve it. - `param` (`string | null`) - The name of the parameter that caused the error, when known. - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error. ### Example ```json { "error": { "code": "resource_missing", "errors": [ { "code": "resource_missing", "message": "The requested resource was not found.", "param": "patient_id" } ], "message": "The requested resource was not found.", "param": "patient_id", "type": "authentication_error" } } ``` ## Response `403` The access token lacks the required scope, or the project is disabled. - `object` - `error` (`object`) - The structured details that describe why the request failed. - `code` (`string`) - The machine-readable error code. - `errors` (`array | null`) - Additional errors from a failed validation. - `items` (`object`) - `code` (`string`) - The machine-readable code for this validation error. - `message` (`string`) - A message that explains this validation error. - `param` (`string | null`) - The name of the parameter that caused this validation error, when known. - `message` (`string`) - A message that explains the error and how to resolve it. - `param` (`string | null`) - The name of the parameter that caused the error, when known. - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error. ### Example ```json { "error": { "code": "resource_missing", "errors": [ { "code": "resource_missing", "message": "The requested resource was not found.", "param": "patient_id" } ], "message": "The requested resource was not found.", "param": "patient_id", "type": "authentication_error" } } ``` ## Response `429` Too many requests. Retry after the delay indicated by `Retry-After`. - `object` - `error` (`object`) - The structured details that describe why the request failed. - `code` (`string`) - The machine-readable error code. - `errors` (`array | null`) - Additional errors from a failed validation. - `items` (`object`) - `code` (`string`) - The machine-readable code for this validation error. - `message` (`string`) - A message that explains this validation error. - `param` (`string | null`) - The name of the parameter that caused this validation error, when known. - `message` (`string`) - A message that explains the error and how to resolve it. - `param` (`string | null`) - The name of the parameter that caused the error, when known. - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error. ### Example ```json { "error": { "code": "resource_missing", "errors": [ { "code": "resource_missing", "message": "The requested resource was not found.", "param": "patient_id" } ], "message": "The requested resource was not found.", "param": "patient_id", "type": "authentication_error" } } ``` ## Code samples ```bash curl -X GET "https://api.carebit.co/v1/insurance_companies" \ -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN" ``` ```javascript const response = await fetch("https://api.carebit.co/v1/insurance_companies", { method: "GET", headers: { Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`, }, }); if (!response.ok) { throw new Error(`Carebit API error: ${response.status}`); } const data = await response.json(); ``` ```python import os import requests response = requests.get( "https://api.carebit.co/v1/insurance_companies", headers={ "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}", } ) response.raise_for_status() data = response.json() ``` ```ruby require "httparty" response = HTTParty.get( "https://api.carebit.co/v1/insurance_companies", headers: { "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}" } ) raise "Carebit API error: #{response.code}" unless response.success? data = response.parsed_response ``` ```php get("https://api.carebit.co/v1/insurance_companies", [ "headers" => [ "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"), ] ]); $data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR); ``` ## Get an Insurance Company `GET /v1/insurance_companies/:id` Returns an active insurance company. Embassy and overseas government health office identifiers return `404`. **Required API scopes:** `payors.read` ## Parameters - `id` (path, `string`) (required) ## Response `200` The requested `InsuranceCompany`. - `object` - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`. - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID. - `name` (`string`) - The name of the insurance company. - `object` (`any`) - Discriminator value emitted at `object`. - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`. ### Example ```json { "id": "855e25b0-b138-48da-86ea-15162ce81f14", "object": "insurance_company", "created_at": "2026-01-01T09:00:00Z", "name": "Bupa", "updated_at": "2026-01-01T09:00:00Z" } ``` ## Response `401` The access token is missing, invalid, expired, or revoked. - `object` - `error` (`object`) - The structured details that describe why the request failed. - `code` (`string`) - The machine-readable error code. - `errors` (`array | null`) - Additional errors from a failed validation. - `items` (`object`) - `code` (`string`) - The machine-readable code for this validation error. - `message` (`string`) - A message that explains this validation error. - `param` (`string | null`) - The name of the parameter that caused this validation error, when known. - `message` (`string`) - A message that explains the error and how to resolve it. - `param` (`string | null`) - The name of the parameter that caused the error, when known. - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error. ### Example ```json { "error": { "code": "resource_missing", "errors": [ { "code": "resource_missing", "message": "The requested resource was not found.", "param": "patient_id" } ], "message": "The requested resource was not found.", "param": "patient_id", "type": "authentication_error" } } ``` ## Response `403` The access token lacks the required scope, or the project is disabled. - `object` - `error` (`object`) - The structured details that describe why the request failed. - `code` (`string`) - The machine-readable error code. - `errors` (`array | null`) - Additional errors from a failed validation. - `items` (`object`) - `code` (`string`) - The machine-readable code for this validation error. - `message` (`string`) - A message that explains this validation error. - `param` (`string | null`) - The name of the parameter that caused this validation error, when known. - `message` (`string`) - A message that explains the error and how to resolve it. - `param` (`string | null`) - The name of the parameter that caused the error, when known. - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error. ### Example ```json { "error": { "code": "resource_missing", "errors": [ { "code": "resource_missing", "message": "The requested resource was not found.", "param": "patient_id" } ], "message": "The requested resource was not found.", "param": "patient_id", "type": "authentication_error" } } ``` ## Response `404` Error response. - `object` - `error` (`object`) - The structured details that describe why the request failed. - `code` (`string`) - The machine-readable error code. - `errors` (`array | null`) - Additional errors from a failed validation. - `items` (`object`) - `code` (`string`) - The machine-readable code for this validation error. - `message` (`string`) - A message that explains this validation error. - `param` (`string | null`) - The name of the parameter that caused this validation error, when known. - `message` (`string`) - A message that explains the error and how to resolve it. - `param` (`string | null`) - The name of the parameter that caused the error, when known. - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error. ### Example ```json { "error": { "code": "resource_missing", "errors": [ { "code": "resource_missing", "message": "The requested resource was not found.", "param": "patient_id" } ], "message": "The requested resource was not found.", "param": "patient_id", "type": "authentication_error" } } ``` ## Response `429` Too many requests. Retry after the delay indicated by `Retry-After`. - `object` - `error` (`object`) - The structured details that describe why the request failed. - `code` (`string`) - The machine-readable error code. - `errors` (`array | null`) - Additional errors from a failed validation. - `items` (`object`) - `code` (`string`) - The machine-readable code for this validation error. - `message` (`string`) - A message that explains this validation error. - `param` (`string | null`) - The name of the parameter that caused this validation error, when known. - `message` (`string`) - A message that explains the error and how to resolve it. - `param` (`string | null`) - The name of the parameter that caused the error, when known. - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error. ### Example ```json { "error": { "code": "resource_missing", "errors": [ { "code": "resource_missing", "message": "The requested resource was not found.", "param": "patient_id" } ], "message": "The requested resource was not found.", "param": "patient_id", "type": "authentication_error" } } ``` ## Code samples ```bash curl -X GET "https://api.carebit.co/v1/insurance_companies/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c" \ -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN" ``` ```javascript const response = await fetch("https://api.carebit.co/v1/insurance_companies/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c", { method: "GET", headers: { Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`, }, }); if (!response.ok) { throw new Error(`Carebit API error: ${response.status}`); } const data = await response.json(); ``` ```python import os import requests response = requests.get( "https://api.carebit.co/v1/insurance_companies/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c", headers={ "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}", } ) response.raise_for_status() data = response.json() ``` ```ruby require "httparty" response = HTTParty.get( "https://api.carebit.co/v1/insurance_companies/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c", headers: { "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}" } ) raise "Carebit API error: #{response.code}" unless response.success? data = response.parsed_response ``` ```php get("https://api.carebit.co/v1/insurance_companies/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c", [ "headers" => [ "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"), ] ]); $data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR); ``` ## List a Patient's Payors `GET /v1/patients/:patient_id/payors` **Required API scopes:** `payors.read` ## Parameters - `patient_id` (path, `string`) (required) - `limit` (query, `integer`) - The maximum number of items to return. Defaults to `25`; the maximum is `100`. - `starting_after` (query, `string`) - Return items after this resource ID. You cannot use this with `cursor`. - `cursor` (query, `string`) - The `next_cursor` value from the previous page. You cannot use this with `starting_after`. ## Response `200` Paginated list of `Payor` objects. - `any` ### Example ```json { "object": "list", "data": [ { "id": "708192a3-b4c5-4def-8012-3456789abcde", "object": "payor", "address_line_1": "10 Harley Street", "address_line_2": "Marylebone", "alternative_payor_id": null, "city": "London", "country_code": "GB", "county": "Greater London", "created_at": "2026-01-01T09:00:00Z", "first_name": "Alex", "formatted_name": "Dr Alex Morgan", "formatted_payor_name": "Bupa", "insurance_authorization_code": "AUTH123", "insurance_company_id": "855e25b0-b138-48da-86ea-15162ce81f14", "insurance_policy_end_date": "2026-12-31", "insurance_policy_number": "POLICY123", "insurance_policy_start_date": "2026-01-01", "last_name": "Morgan", "notes": "Please confirm the appointment by email.", "payor_type": "insurance_company", "postcode": "W1G 9PF", "title": "Dr", "updated_at": "2026-01-01T09:00:00Z" } ], "has_more": false, "next_cursor": "eyJzdGFydF90aW1lIjoiMjAyNi0wMS0wMVQwOTowMDowMFoifQ", "url": "/v1/payors" } ``` ## Response `401` The access token is missing, invalid, expired, or revoked. - `object` - `error` (`object`) - The structured details that describe why the request failed. - `code` (`string`) - The machine-readable error code. - `errors` (`array | null`) - Additional errors from a failed validation. - `items` (`object`) - `code` (`string`) - The machine-readable code for this validation error. - `message` (`string`) - A message that explains this validation error. - `param` (`string | null`) - The name of the parameter that caused this validation error, when known. - `message` (`string`) - A message that explains the error and how to resolve it. - `param` (`string | null`) - The name of the parameter that caused the error, when known. - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error. ### Example ```json { "error": { "code": "resource_missing", "errors": [ { "code": "resource_missing", "message": "The requested resource was not found.", "param": "patient_id" } ], "message": "The requested resource was not found.", "param": "patient_id", "type": "authentication_error" } } ``` ## Response `403` The access token lacks the required scope, or the project is disabled. - `object` - `error` (`object`) - The structured details that describe why the request failed. - `code` (`string`) - The machine-readable error code. - `errors` (`array | null`) - Additional errors from a failed validation. - `items` (`object`) - `code` (`string`) - The machine-readable code for this validation error. - `message` (`string`) - A message that explains this validation error. - `param` (`string | null`) - The name of the parameter that caused this validation error, when known. - `message` (`string`) - A message that explains the error and how to resolve it. - `param` (`string | null`) - The name of the parameter that caused the error, when known. - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error. ### Example ```json { "error": { "code": "resource_missing", "errors": [ { "code": "resource_missing", "message": "The requested resource was not found.", "param": "patient_id" } ], "message": "The requested resource was not found.", "param": "patient_id", "type": "authentication_error" } } ``` ## Response `404` Error response. - `object` - `error` (`object`) - The structured details that describe why the request failed. - `code` (`string`) - The machine-readable error code. - `errors` (`array | null`) - Additional errors from a failed validation. - `items` (`object`) - `code` (`string`) - The machine-readable code for this validation error. - `message` (`string`) - A message that explains this validation error. - `param` (`string | null`) - The name of the parameter that caused this validation error, when known. - `message` (`string`) - A message that explains the error and how to resolve it. - `param` (`string | null`) - The name of the parameter that caused the error, when known. - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error. ### Example ```json { "error": { "code": "resource_missing", "errors": [ { "code": "resource_missing", "message": "The requested resource was not found.", "param": "patient_id" } ], "message": "The requested resource was not found.", "param": "patient_id", "type": "authentication_error" } } ``` ## Response `429` Too many requests. Retry after the delay indicated by `Retry-After`. - `object` - `error` (`object`) - The structured details that describe why the request failed. - `code` (`string`) - The machine-readable error code. - `errors` (`array | null`) - Additional errors from a failed validation. - `items` (`object`) - `code` (`string`) - The machine-readable code for this validation error. - `message` (`string`) - A message that explains this validation error. - `param` (`string | null`) - The name of the parameter that caused this validation error, when known. - `message` (`string`) - A message that explains the error and how to resolve it. - `param` (`string | null`) - The name of the parameter that caused the error, when known. - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error. ### Example ```json { "error": { "code": "resource_missing", "errors": [ { "code": "resource_missing", "message": "The requested resource was not found.", "param": "patient_id" } ], "message": "The requested resource was not found.", "param": "patient_id", "type": "authentication_error" } } ``` ## Code samples ```bash curl -X GET "https://api.carebit.co/v1/patients/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c/payors" \ -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN" ``` ```javascript const response = await fetch("https://api.carebit.co/v1/patients/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c/payors", { method: "GET", headers: { Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`, }, }); if (!response.ok) { throw new Error(`Carebit API error: ${response.status}`); } const data = await response.json(); ``` ```python import os import requests response = requests.get( "https://api.carebit.co/v1/patients/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c/payors", headers={ "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}", } ) response.raise_for_status() data = response.json() ``` ```ruby require "httparty" response = HTTParty.get( "https://api.carebit.co/v1/patients/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c/payors", headers: { "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}" } ) raise "Carebit API error: #{response.code}" unless response.success? data = response.parsed_response ``` ```php get("https://api.carebit.co/v1/patients/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c/payors", [ "headers" => [ "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"), ] ]); $data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR); ``` ## Create a Patient Payor `POST /v1/patients/:patient_id/payors` Creates an insurance or alternative Payor. Provide exactly one of `insurance_company_id` or `alternative_payor_id`. Set `set_as_default_payor` to `true` to also select this Payor on this Organization's PatientConnection. Carebit creates a self-pay Payor automatically when it creates the Patient. **Required API scopes:** `payors.create` ## Parameters - `patient_id` (path, `string`) (required) - `Idempotency-Key` (header, `string`) (required) - Client-generated idempotency key. Required for every POST/PATCH write. Replay of the same key with the same body returns the stored response with an `Idempotency-Replayed: true` header. Same key + different body returns `422 idempotency_key_reused`. A duplicate that arrives while the first request is still in flight returns `409 idempotency_conflict` with `Retry-After: 1`. ## Request body (`application/json`) - `object` - `address_line_1` (`string | null`) - The primary policyholder address line. - `address_line_2` (`string | null`) - The secondary policyholder address line. - `alternative_payor_id` (`string`) - format: `uuid`; The Organization-owned AlternativePayor responsible for payment. - `city` (`string | null`) - The city in the policyholder address. - `country_code` (`string | null`) - The uppercase ISO 3166-1 alpha-2 country code for the policyholder address. - `county` (`string | null`) - The county or region in the policyholder address. - `first_name` (`string | null`) - The policyholder's first name override. - `insurance_authorization_code` (`string | null`) - The insurer authorization code. - `insurance_company_id` (`string`) - format: `uuid`; The active InsuranceCompany responsible for payment. - `insurance_policy_end_date` (`string | null`) - format: `date`; The insurance policy end date. - `insurance_policy_number` (`string | null`) - The insurance policy or membership number. - `insurance_policy_start_date` (`string | null`) - format: `date`; The insurance policy start date. - `last_name` (`string | null`) - The policyholder's last name override. - `notes` (`string | null`) - Additional billing or insurance information. - `postcode` (`string | null`) - The postal code in the policyholder address. - `set_as_default_payor` (`boolean`) - When `true` on create, Carebit also sets this Payor as the default billing party on this Organization's PatientConnection. Nested GP connections are not changed. Omit or pass `false` to leave the selected Payor unchanged. - `title` (`string | null`) - The policyholder's personal title override. ### Example ```json { "insurance_company_id": "00000000-0000-4000-8000-00000000000e", "insurance_policy_number": "POLICY123", "set_as_default_payor": true } ``` ## Response `201` The requested `Payor`. - `object` - `address_line_1` (`string | null`) - The primary address line of the payor. - `address_line_2` (`string | null`) - The secondary address line of the payor. - `alternative_payor_id` (`string | null`) - format: `uuid`; The identifier of the alternative payor responsible for payment, when `payor_type` is `alternative_payor`. - `city` (`string | null`) - The city in the payor's postal address. - `country_code` (`string | null`) - The ISO 3166-1 alpha-2 country code for the postal address, such as `GB` for the United Kingdom. - `county` (`string | null`) - The county or region in the payor's postal address. - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`. - `first_name` (`string | null`) - The first name of the person responsible for payment, when applicable. - `formatted_name` (`string | null`) - The formatted name of the person responsible for payment. - `formatted_payor_name` (`string | null`) - The display name of the patient, insurer, or alternative payor responsible for payment. - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID. - `insurance_authorization_code` (`string | null`) - The insurer's authorization code. - `insurance_company_id` (`string | null`) - format: `uuid`; The identifier of the insurance company responsible for payment, when `payor_type` is `insurance_company`. - `insurance_policy_end_date` (`string | null`) - format: `date`; The end date of the insurance policy, when recorded. - `insurance_policy_number` (`string | null`) - The policy or membership number supplied by the insurer. - `insurance_policy_start_date` (`string | null`) - format: `date`; The start date of the insurance policy, when recorded. - `last_name` (`string | null`) - The last name of the person responsible for payment, when applicable. - `notes` (`string | null`) - The additional payment or insurance information recorded for this payor. - `object` (`any`) - Discriminator value emitted at `object`. - `payor_type` (`string`) - enum: `patient`, `insurance_company`, `alternative_payor`; The type of party responsible for payment. - `postcode` (`string | null`) - The postal code of the payor. - `title` (`string | null`) - The personal title of the person responsible for payment, when applicable. - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`. ### Example ```json { "id": "708192a3-b4c5-4def-8012-3456789abcde", "object": "payor", "address_line_1": "10 Harley Street", "address_line_2": "Marylebone", "alternative_payor_id": null, "city": "London", "country_code": "GB", "county": "Greater London", "created_at": "2026-01-01T09:00:00Z", "first_name": "Alex", "formatted_name": "Dr Alex Morgan", "formatted_payor_name": "Bupa", "insurance_authorization_code": "AUTH123", "insurance_company_id": "855e25b0-b138-48da-86ea-15162ce81f14", "insurance_policy_end_date": "2026-12-31", "insurance_policy_number": "POLICY123", "insurance_policy_start_date": "2026-01-01", "last_name": "Morgan", "notes": "Please confirm the appointment by email.", "payor_type": "insurance_company", "postcode": "W1G 9PF", "title": "Dr", "updated_at": "2026-01-01T09:00:00Z" } ``` ## Response `400` The `Idempotency-Key` header is missing (`idempotency_key_required`) or exceeds 255 characters (`idempotency_key_too_long`). - `object` - `error` (`object`) - The structured details that describe why the request failed. - `code` (`string`) - The machine-readable error code. - `errors` (`array | null`) - Additional errors from a failed validation. - `items` (`object`) - `code` (`string`) - The machine-readable code for this validation error. - `message` (`string`) - A message that explains this validation error. - `param` (`string | null`) - The name of the parameter that caused this validation error, when known. - `message` (`string`) - A message that explains the error and how to resolve it. - `param` (`string | null`) - The name of the parameter that caused the error, when known. - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error. ### Example ```json { "error": { "code": "resource_missing", "errors": [ { "code": "resource_missing", "message": "The requested resource was not found.", "param": "patient_id" } ], "message": "The requested resource was not found.", "param": "patient_id", "type": "authentication_error" } } ``` ## Response `401` The access token is missing, invalid, expired, or revoked. - `object` - `error` (`object`) - The structured details that describe why the request failed. - `code` (`string`) - The machine-readable error code. - `errors` (`array | null`) - Additional errors from a failed validation. - `items` (`object`) - `code` (`string`) - The machine-readable code for this validation error. - `message` (`string`) - A message that explains this validation error. - `param` (`string | null`) - The name of the parameter that caused this validation error, when known. - `message` (`string`) - A message that explains the error and how to resolve it. - `param` (`string | null`) - The name of the parameter that caused the error, when known. - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error. ### Example ```json { "error": { "code": "resource_missing", "errors": [ { "code": "resource_missing", "message": "The requested resource was not found.", "param": "patient_id" } ], "message": "The requested resource was not found.", "param": "patient_id", "type": "authentication_error" } } ``` ## Response `403` The access token lacks the required scope, or the project is disabled. - `object` - `error` (`object`) - The structured details that describe why the request failed. - `code` (`string`) - The machine-readable error code. - `errors` (`array | null`) - Additional errors from a failed validation. - `items` (`object`) - `code` (`string`) - The machine-readable code for this validation error. - `message` (`string`) - A message that explains this validation error. - `param` (`string | null`) - The name of the parameter that caused this validation error, when known. - `message` (`string`) - A message that explains the error and how to resolve it. - `param` (`string | null`) - The name of the parameter that caused the error, when known. - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error. ### Example ```json { "error": { "code": "resource_missing", "errors": [ { "code": "resource_missing", "message": "The requested resource was not found.", "param": "patient_id" } ], "message": "The requested resource was not found.", "param": "patient_id", "type": "authentication_error" } } ``` ## Response `404` Error response. - `object` - `error` (`object`) - The structured details that describe why the request failed. - `code` (`string`) - The machine-readable error code. - `errors` (`array | null`) - Additional errors from a failed validation. - `items` (`object`) - `code` (`string`) - The machine-readable code for this validation error. - `message` (`string`) - A message that explains this validation error. - `param` (`string | null`) - The name of the parameter that caused this validation error, when known. - `message` (`string`) - A message that explains the error and how to resolve it. - `param` (`string | null`) - The name of the parameter that caused the error, when known. - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error. ### Example ```json { "error": { "code": "resource_missing", "errors": [ { "code": "resource_missing", "message": "The requested resource was not found.", "param": "patient_id" } ], "message": "The requested resource was not found.", "param": "patient_id", "type": "authentication_error" } } ``` ## Response `409` A concurrent request holds the idempotency lease (`idempotency_conflict`). Retry after the delay indicated by `Retry-After`. - `object` - `error` (`object`) - The structured details that describe why the request failed. - `code` (`string`) - The machine-readable error code. - `errors` (`array | null`) - Additional errors from a failed validation. - `items` (`object`) - `code` (`string`) - The machine-readable code for this validation error. - `message` (`string`) - A message that explains this validation error. - `param` (`string | null`) - The name of the parameter that caused this validation error, when known. - `message` (`string`) - A message that explains the error and how to resolve it. - `param` (`string | null`) - The name of the parameter that caused the error, when known. - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error. ### Example ```json { "error": { "code": "resource_missing", "errors": [ { "code": "resource_missing", "message": "The requested resource was not found.", "param": "patient_id" } ], "message": "The requested resource was not found.", "param": "patient_id", "type": "authentication_error" } } ``` ## Response `422` The `Idempotency-Key` was previously used with a different request body (`idempotency_key_reused`), or the request body failed validation. - `object` - `error` (`object`) - The structured details that describe why the request failed. - `code` (`string`) - The machine-readable error code. - `errors` (`array | null`) - Additional errors from a failed validation. - `items` (`object`) - `code` (`string`) - The machine-readable code for this validation error. - `message` (`string`) - A message that explains this validation error. - `param` (`string | null`) - The name of the parameter that caused this validation error, when known. - `message` (`string`) - A message that explains the error and how to resolve it. - `param` (`string | null`) - The name of the parameter that caused the error, when known. - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error. ### Example ```json { "error": { "code": "resource_missing", "errors": [ { "code": "resource_missing", "message": "The requested resource was not found.", "param": "patient_id" } ], "message": "The requested resource was not found.", "param": "patient_id", "type": "authentication_error" } } ``` ## Response `429` Too many requests. Retry after the delay indicated by `Retry-After`. - `object` - `error` (`object`) - The structured details that describe why the request failed. - `code` (`string`) - The machine-readable error code. - `errors` (`array | null`) - Additional errors from a failed validation. - `items` (`object`) - `code` (`string`) - The machine-readable code for this validation error. - `message` (`string`) - A message that explains this validation error. - `param` (`string | null`) - The name of the parameter that caused this validation error, when known. - `message` (`string`) - A message that explains the error and how to resolve it. - `param` (`string | null`) - The name of the parameter that caused the error, when known. - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error. ### Example ```json { "error": { "code": "resource_missing", "errors": [ { "code": "resource_missing", "message": "The requested resource was not found.", "param": "patient_id" } ], "message": "The requested resource was not found.", "param": "patient_id", "type": "authentication_error" } } ``` ## Code samples ```bash curl -X POST "https://api.carebit.co/v1/patients/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c/payors" \ -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "insurance_company_id": "00000000-0000-4000-8000-00000000000e", "insurance_policy_number": "POLICY123", "set_as_default_payor": true }' ``` ```javascript const response = await fetch("https://api.carebit.co/v1/patients/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c/payors", { method: "POST", headers: { Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`, "Content-Type": "application/json", "Idempotency-Key": crypto.randomUUID(), }, body: JSON.stringify({ "insurance_company_id": "00000000-0000-4000-8000-00000000000e", "insurance_policy_number": "POLICY123", "set_as_default_payor": true }), }); if (!response.ok) { throw new Error(`Carebit API error: ${response.status}`); } const data = await response.json(); ``` ```python import os import requests import uuid response = requests.post( "https://api.carebit.co/v1/patients/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c/payors", headers={ "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}", "Idempotency-Key": str(uuid.uuid4()), }, json={ "insurance_company_id": "00000000-0000-4000-8000-00000000000e", "insurance_policy_number": "POLICY123", "set_as_default_payor": True } ) response.raise_for_status() data = response.json() ``` ```ruby require "httparty" require "json" require "securerandom" response = HTTParty.post( "https://api.carebit.co/v1/patients/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c/payors", headers: { "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}", "Idempotency-Key" => SecureRandom.uuid, "Content-Type" => "application/json" }, body: { "insurance_company_id" => "00000000-0000-4000-8000-00000000000e", "insurance_policy_number" => "POLICY123", "set_as_default_payor" => true }.to_json ) raise "Carebit API error: #{response.code}" unless response.success? data = response.parsed_response ``` ```php post("https://api.carebit.co/v1/patients/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c/payors", [ "headers" => [ "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"), "Idempotency-Key" => bin2hex(random_bytes(16)), ], "json" => [ "insurance_company_id" => "00000000-0000-4000-8000-00000000000e", "insurance_policy_number" => "POLICY123", "set_as_default_payor" => true ] ]); $data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR); ``` ## Get a Patient Payor `GET /v1/patients/:patient_id/payors/:id` **Required API scopes:** `payors.read` ## Parameters - `patient_id` (path, `string`) (required) - `id` (path, `string`) (required) ## Response `200` The requested `Payor`. - `object` - `address_line_1` (`string | null`) - The primary address line of the payor. - `address_line_2` (`string | null`) - The secondary address line of the payor. - `alternative_payor_id` (`string | null`) - format: `uuid`; The identifier of the alternative payor responsible for payment, when `payor_type` is `alternative_payor`. - `city` (`string | null`) - The city in the payor's postal address. - `country_code` (`string | null`) - The ISO 3166-1 alpha-2 country code for the postal address, such as `GB` for the United Kingdom. - `county` (`string | null`) - The county or region in the payor's postal address. - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`. - `first_name` (`string | null`) - The first name of the person responsible for payment, when applicable. - `formatted_name` (`string | null`) - The formatted name of the person responsible for payment. - `formatted_payor_name` (`string | null`) - The display name of the patient, insurer, or alternative payor responsible for payment. - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID. - `insurance_authorization_code` (`string | null`) - The insurer's authorization code. - `insurance_company_id` (`string | null`) - format: `uuid`; The identifier of the insurance company responsible for payment, when `payor_type` is `insurance_company`. - `insurance_policy_end_date` (`string | null`) - format: `date`; The end date of the insurance policy, when recorded. - `insurance_policy_number` (`string | null`) - The policy or membership number supplied by the insurer. - `insurance_policy_start_date` (`string | null`) - format: `date`; The start date of the insurance policy, when recorded. - `last_name` (`string | null`) - The last name of the person responsible for payment, when applicable. - `notes` (`string | null`) - The additional payment or insurance information recorded for this payor. - `object` (`any`) - Discriminator value emitted at `object`. - `payor_type` (`string`) - enum: `patient`, `insurance_company`, `alternative_payor`; The type of party responsible for payment. - `postcode` (`string | null`) - The postal code of the payor. - `title` (`string | null`) - The personal title of the person responsible for payment, when applicable. - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`. ### Example ```json { "id": "708192a3-b4c5-4def-8012-3456789abcde", "object": "payor", "address_line_1": "10 Harley Street", "address_line_2": "Marylebone", "alternative_payor_id": null, "city": "London", "country_code": "GB", "county": "Greater London", "created_at": "2026-01-01T09:00:00Z", "first_name": "Alex", "formatted_name": "Dr Alex Morgan", "formatted_payor_name": "Bupa", "insurance_authorization_code": "AUTH123", "insurance_company_id": "855e25b0-b138-48da-86ea-15162ce81f14", "insurance_policy_end_date": "2026-12-31", "insurance_policy_number": "POLICY123", "insurance_policy_start_date": "2026-01-01", "last_name": "Morgan", "notes": "Please confirm the appointment by email.", "payor_type": "insurance_company", "postcode": "W1G 9PF", "title": "Dr", "updated_at": "2026-01-01T09:00:00Z" } ``` ## Response `401` The access token is missing, invalid, expired, or revoked. - `object` - `error` (`object`) - The structured details that describe why the request failed. - `code` (`string`) - The machine-readable error code. - `errors` (`array | null`) - Additional errors from a failed validation. - `items` (`object`) - `code` (`string`) - The machine-readable code for this validation error. - `message` (`string`) - A message that explains this validation error. - `param` (`string | null`) - The name of the parameter that caused this validation error, when known. - `message` (`string`) - A message that explains the error and how to resolve it. - `param` (`string | null`) - The name of the parameter that caused the error, when known. - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error. ### Example ```json { "error": { "code": "resource_missing", "errors": [ { "code": "resource_missing", "message": "The requested resource was not found.", "param": "patient_id" } ], "message": "The requested resource was not found.", "param": "patient_id", "type": "authentication_error" } } ``` ## Response `403` The access token lacks the required scope, or the project is disabled. - `object` - `error` (`object`) - The structured details that describe why the request failed. - `code` (`string`) - The machine-readable error code. - `errors` (`array | null`) - Additional errors from a failed validation. - `items` (`object`) - `code` (`string`) - The machine-readable code for this validation error. - `message` (`string`) - A message that explains this validation error. - `param` (`string | null`) - The name of the parameter that caused this validation error, when known. - `message` (`string`) - A message that explains the error and how to resolve it. - `param` (`string | null`) - The name of the parameter that caused the error, when known. - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error. ### Example ```json { "error": { "code": "resource_missing", "errors": [ { "code": "resource_missing", "message": "The requested resource was not found.", "param": "patient_id" } ], "message": "The requested resource was not found.", "param": "patient_id", "type": "authentication_error" } } ``` ## Response `404` Error response. - `object` - `error` (`object`) - The structured details that describe why the request failed. - `code` (`string`) - The machine-readable error code. - `errors` (`array | null`) - Additional errors from a failed validation. - `items` (`object`) - `code` (`string`) - The machine-readable code for this validation error. - `message` (`string`) - A message that explains this validation error. - `param` (`string | null`) - The name of the parameter that caused this validation error, when known. - `message` (`string`) - A message that explains the error and how to resolve it. - `param` (`string | null`) - The name of the parameter that caused the error, when known. - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error. ### Example ```json { "error": { "code": "resource_missing", "errors": [ { "code": "resource_missing", "message": "The requested resource was not found.", "param": "patient_id" } ], "message": "The requested resource was not found.", "param": "patient_id", "type": "authentication_error" } } ``` ## Response `429` Too many requests. Retry after the delay indicated by `Retry-After`. - `object` - `error` (`object`) - The structured details that describe why the request failed. - `code` (`string`) - The machine-readable error code. - `errors` (`array | null`) - Additional errors from a failed validation. - `items` (`object`) - `code` (`string`) - The machine-readable code for this validation error. - `message` (`string`) - A message that explains this validation error. - `param` (`string | null`) - The name of the parameter that caused this validation error, when known. - `message` (`string`) - A message that explains the error and how to resolve it. - `param` (`string | null`) - The name of the parameter that caused the error, when known. - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error. ### Example ```json { "error": { "code": "resource_missing", "errors": [ { "code": "resource_missing", "message": "The requested resource was not found.", "param": "patient_id" } ], "message": "The requested resource was not found.", "param": "patient_id", "type": "authentication_error" } } ``` ## Code samples ```bash curl -X GET "https://api.carebit.co/v1/patients/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c/payors/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c" \ -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN" ``` ```javascript const response = await fetch("https://api.carebit.co/v1/patients/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c/payors/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c", { method: "GET", headers: { Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`, }, }); if (!response.ok) { throw new Error(`Carebit API error: ${response.status}`); } const data = await response.json(); ``` ```python import os import requests response = requests.get( "https://api.carebit.co/v1/patients/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c/payors/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c", headers={ "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}", } ) response.raise_for_status() data = response.json() ``` ```ruby require "httparty" response = HTTParty.get( "https://api.carebit.co/v1/patients/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c/payors/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c", headers: { "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}" } ) raise "Carebit API error: #{response.code}" unless response.success? data = response.parsed_response ``` ```php get("https://api.carebit.co/v1/patients/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c/payors/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c", [ "headers" => [ "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"), ] ]); $data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR); ``` ## Update a Patient Payor `PATCH /v1/patients/:patient_id/payors/:id` Updates a Payor. To change its type, provide one non-null `insurance_company_id` or `alternative_payor_id`. Once set, the Payor type cannot be cleared. **Required API scopes:** `payors.update` ## Parameters - `patient_id` (path, `string`) (required) - `id` (path, `string`) (required) - `Idempotency-Key` (header, `string`) (required) - Client-generated idempotency key. Required for every POST/PATCH write. Replay of the same key with the same body returns the stored response with an `Idempotency-Replayed: true` header. Same key + different body returns `422 idempotency_key_reused`. A duplicate that arrives while the first request is still in flight returns `409 idempotency_conflict` with `Retry-After: 1`. ## Request body (`application/json`) - `object` - `address_line_1` (`string | null`) - The primary policyholder address line. - `address_line_2` (`string | null`) - The secondary policyholder address line. - `alternative_payor_id` (`string`) - format: `uuid`; The Organization-owned AlternativePayor responsible for payment. - `city` (`string | null`) - The city in the policyholder address. - `country_code` (`string | null`) - The uppercase ISO 3166-1 alpha-2 country code for the policyholder address. - `county` (`string | null`) - The county or region in the policyholder address. - `first_name` (`string | null`) - The policyholder's first name override. - `insurance_authorization_code` (`string | null`) - The insurer authorization code. - `insurance_company_id` (`string`) - format: `uuid`; The active InsuranceCompany responsible for payment. - `insurance_policy_end_date` (`string | null`) - format: `date`; The insurance policy end date. - `insurance_policy_number` (`string | null`) - The insurance policy or membership number. - `insurance_policy_start_date` (`string | null`) - format: `date`; The insurance policy start date. - `last_name` (`string | null`) - The policyholder's last name override. - `notes` (`string | null`) - Additional billing or insurance information. - `postcode` (`string | null`) - The postal code in the policyholder address. - `title` (`string | null`) - The policyholder's personal title override. ### Example ```json { "insurance_authorization_code": "AUTH123" } ``` ## Response `200` The requested `Payor`. - `object` - `address_line_1` (`string | null`) - The primary address line of the payor. - `address_line_2` (`string | null`) - The secondary address line of the payor. - `alternative_payor_id` (`string | null`) - format: `uuid`; The identifier of the alternative payor responsible for payment, when `payor_type` is `alternative_payor`. - `city` (`string | null`) - The city in the payor's postal address. - `country_code` (`string | null`) - The ISO 3166-1 alpha-2 country code for the postal address, such as `GB` for the United Kingdom. - `county` (`string | null`) - The county or region in the payor's postal address. - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`. - `first_name` (`string | null`) - The first name of the person responsible for payment, when applicable. - `formatted_name` (`string | null`) - The formatted name of the person responsible for payment. - `formatted_payor_name` (`string | null`) - The display name of the patient, insurer, or alternative payor responsible for payment. - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID. - `insurance_authorization_code` (`string | null`) - The insurer's authorization code. - `insurance_company_id` (`string | null`) - format: `uuid`; The identifier of the insurance company responsible for payment, when `payor_type` is `insurance_company`. - `insurance_policy_end_date` (`string | null`) - format: `date`; The end date of the insurance policy, when recorded. - `insurance_policy_number` (`string | null`) - The policy or membership number supplied by the insurer. - `insurance_policy_start_date` (`string | null`) - format: `date`; The start date of the insurance policy, when recorded. - `last_name` (`string | null`) - The last name of the person responsible for payment, when applicable. - `notes` (`string | null`) - The additional payment or insurance information recorded for this payor. - `object` (`any`) - Discriminator value emitted at `object`. - `payor_type` (`string`) - enum: `patient`, `insurance_company`, `alternative_payor`; The type of party responsible for payment. - `postcode` (`string | null`) - The postal code of the payor. - `title` (`string | null`) - The personal title of the person responsible for payment, when applicable. - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`. ### Example ```json { "id": "708192a3-b4c5-4def-8012-3456789abcde", "object": "payor", "address_line_1": "10 Harley Street", "address_line_2": "Marylebone", "alternative_payor_id": null, "city": "London", "country_code": "GB", "county": "Greater London", "created_at": "2026-01-01T09:00:00Z", "first_name": "Alex", "formatted_name": "Dr Alex Morgan", "formatted_payor_name": "Bupa", "insurance_authorization_code": "AUTH123", "insurance_company_id": "855e25b0-b138-48da-86ea-15162ce81f14", "insurance_policy_end_date": "2026-12-31", "insurance_policy_number": "POLICY123", "insurance_policy_start_date": "2026-01-01", "last_name": "Morgan", "notes": "Please confirm the appointment by email.", "payor_type": "insurance_company", "postcode": "W1G 9PF", "title": "Dr", "updated_at": "2026-01-01T09:00:00Z" } ``` ## Response `400` The `Idempotency-Key` header is missing (`idempotency_key_required`) or exceeds 255 characters (`idempotency_key_too_long`). - `object` - `error` (`object`) - The structured details that describe why the request failed. - `code` (`string`) - The machine-readable error code. - `errors` (`array | null`) - Additional errors from a failed validation. - `items` (`object`) - `code` (`string`) - The machine-readable code for this validation error. - `message` (`string`) - A message that explains this validation error. - `param` (`string | null`) - The name of the parameter that caused this validation error, when known. - `message` (`string`) - A message that explains the error and how to resolve it. - `param` (`string | null`) - The name of the parameter that caused the error, when known. - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error. ### Example ```json { "error": { "code": "resource_missing", "errors": [ { "code": "resource_missing", "message": "The requested resource was not found.", "param": "patient_id" } ], "message": "The requested resource was not found.", "param": "patient_id", "type": "authentication_error" } } ``` ## Response `401` The access token is missing, invalid, expired, or revoked. - `object` - `error` (`object`) - The structured details that describe why the request failed. - `code` (`string`) - The machine-readable error code. - `errors` (`array | null`) - Additional errors from a failed validation. - `items` (`object`) - `code` (`string`) - The machine-readable code for this validation error. - `message` (`string`) - A message that explains this validation error. - `param` (`string | null`) - The name of the parameter that caused this validation error, when known. - `message` (`string`) - A message that explains the error and how to resolve it. - `param` (`string | null`) - The name of the parameter that caused the error, when known. - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error. ### Example ```json { "error": { "code": "resource_missing", "errors": [ { "code": "resource_missing", "message": "The requested resource was not found.", "param": "patient_id" } ], "message": "The requested resource was not found.", "param": "patient_id", "type": "authentication_error" } } ``` ## Response `403` The access token lacks the required scope, or the project is disabled. - `object` - `error` (`object`) - The structured details that describe why the request failed. - `code` (`string`) - The machine-readable error code. - `errors` (`array | null`) - Additional errors from a failed validation. - `items` (`object`) - `code` (`string`) - The machine-readable code for this validation error. - `message` (`string`) - A message that explains this validation error. - `param` (`string | null`) - The name of the parameter that caused this validation error, when known. - `message` (`string`) - A message that explains the error and how to resolve it. - `param` (`string | null`) - The name of the parameter that caused the error, when known. - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error. ### Example ```json { "error": { "code": "resource_missing", "errors": [ { "code": "resource_missing", "message": "The requested resource was not found.", "param": "patient_id" } ], "message": "The requested resource was not found.", "param": "patient_id", "type": "authentication_error" } } ``` ## Response `404` Error response. - `object` - `error` (`object`) - The structured details that describe why the request failed. - `code` (`string`) - The machine-readable error code. - `errors` (`array | null`) - Additional errors from a failed validation. - `items` (`object`) - `code` (`string`) - The machine-readable code for this validation error. - `message` (`string`) - A message that explains this validation error. - `param` (`string | null`) - The name of the parameter that caused this validation error, when known. - `message` (`string`) - A message that explains the error and how to resolve it. - `param` (`string | null`) - The name of the parameter that caused the error, when known. - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error. ### Example ```json { "error": { "code": "resource_missing", "errors": [ { "code": "resource_missing", "message": "The requested resource was not found.", "param": "patient_id" } ], "message": "The requested resource was not found.", "param": "patient_id", "type": "authentication_error" } } ``` ## Response `409` A concurrent request holds the idempotency lease (`idempotency_conflict`). Retry after the delay indicated by `Retry-After`. - `object` - `error` (`object`) - The structured details that describe why the request failed. - `code` (`string`) - The machine-readable error code. - `errors` (`array | null`) - Additional errors from a failed validation. - `items` (`object`) - `code` (`string`) - The machine-readable code for this validation error. - `message` (`string`) - A message that explains this validation error. - `param` (`string | null`) - The name of the parameter that caused this validation error, when known. - `message` (`string`) - A message that explains the error and how to resolve it. - `param` (`string | null`) - The name of the parameter that caused the error, when known. - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error. ### Example ```json { "error": { "code": "resource_missing", "errors": [ { "code": "resource_missing", "message": "The requested resource was not found.", "param": "patient_id" } ], "message": "The requested resource was not found.", "param": "patient_id", "type": "authentication_error" } } ``` ## Response `422` The `Idempotency-Key` was previously used with a different request body (`idempotency_key_reused`), or the request body failed validation. - `object` - `error` (`object`) - The structured details that describe why the request failed. - `code` (`string`) - The machine-readable error code. - `errors` (`array | null`) - Additional errors from a failed validation. - `items` (`object`) - `code` (`string`) - The machine-readable code for this validation error. - `message` (`string`) - A message that explains this validation error. - `param` (`string | null`) - The name of the parameter that caused this validation error, when known. - `message` (`string`) - A message that explains the error and how to resolve it. - `param` (`string | null`) - The name of the parameter that caused the error, when known. - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error. ### Example ```json { "error": { "code": "resource_missing", "errors": [ { "code": "resource_missing", "message": "The requested resource was not found.", "param": "patient_id" } ], "message": "The requested resource was not found.", "param": "patient_id", "type": "authentication_error" } } ``` ## Response `429` Too many requests. Retry after the delay indicated by `Retry-After`. - `object` - `error` (`object`) - The structured details that describe why the request failed. - `code` (`string`) - The machine-readable error code. - `errors` (`array | null`) - Additional errors from a failed validation. - `items` (`object`) - `code` (`string`) - The machine-readable code for this validation error. - `message` (`string`) - A message that explains this validation error. - `param` (`string | null`) - The name of the parameter that caused this validation error, when known. - `message` (`string`) - A message that explains the error and how to resolve it. - `param` (`string | null`) - The name of the parameter that caused the error, when known. - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error. ### Example ```json { "error": { "code": "resource_missing", "errors": [ { "code": "resource_missing", "message": "The requested resource was not found.", "param": "patient_id" } ], "message": "The requested resource was not found.", "param": "patient_id", "type": "authentication_error" } } ``` ## Code samples ```bash curl -X PATCH "https://api.carebit.co/v1/patients/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c/payors/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c" \ -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "insurance_authorization_code": "AUTH123" }' ``` ```javascript const response = await fetch("https://api.carebit.co/v1/patients/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c/payors/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c", { method: "PATCH", headers: { Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`, "Content-Type": "application/json", "Idempotency-Key": crypto.randomUUID(), }, body: JSON.stringify({ "insurance_authorization_code": "AUTH123" }), }); if (!response.ok) { throw new Error(`Carebit API error: ${response.status}`); } const data = await response.json(); ``` ```python import os import requests import uuid response = requests.patch( "https://api.carebit.co/v1/patients/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c/payors/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c", headers={ "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}", "Idempotency-Key": str(uuid.uuid4()), }, json={ "insurance_authorization_code": "AUTH123" } ) response.raise_for_status() data = response.json() ``` ```ruby require "httparty" require "json" require "securerandom" response = HTTParty.patch( "https://api.carebit.co/v1/patients/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c/payors/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c", headers: { "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}", "Idempotency-Key" => SecureRandom.uuid, "Content-Type" => "application/json" }, body: { "insurance_authorization_code" => "AUTH123" }.to_json ) raise "Carebit API error: #{response.code}" unless response.success? data = response.parsed_response ``` ```php patch("https://api.carebit.co/v1/patients/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c/payors/8f14e45f-ea7d-4b6f-9c2a-1d3e5f7a9b0c", [ "headers" => [ "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"), "Idempotency-Key" => bin2hex(random_bytes(16)), ], "json" => [ "insurance_authorization_code" => "AUTH123" ] ]); $data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR); ```