Carebit API

Services

The Services offered by the Organization and the ServiceVariants that can be booked.

Required API scopes: services.createservices.readservices.update

Endpoints

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

post/v1/service_variantsCreate a ServiceVariantservices.create
patch/v1/service_variants/:idUpdate a ServiceVariantservices.update
get/v1/servicesList the Organization's Servicesservices.read
post/v1/servicesCreate a Serviceservices.create
get/v1/services/:idGet a Serviceservices.read
patch/v1/services/:idUpdate a Serviceservices.update

post/v1/service_variants

Create a ServiceVariant

Creates a ServiceVariant on an existing Service. net_price uses minor currency units. The response is the parent Service. Requires services.create.

Required API scopes: services.create

Parameters

Idempotency-Key
header · required
string
Client-generated idempotency key. Required for every POST/PATCH write. Replay of the same key with the same body returns the stored response with an Idempotency-Replayed: true header. Same key + different body returns 422 idempotency_key_reused. A duplicate that arrives while the first request is still in flight returns 409 idempotency_conflict with Retry-After: 1.

Request body

application/json

clinician_idstring | null · uuid
The Clinician assigned to this ServiceVariant, when the variant is clinician-specific.
currencystring | null
The ISO 4217 currency code used for this ServiceVariant.
Allowed values: chf | eur | gbp | usd | null
descriptionstring | null
The description of this ServiceVariant.
location_idstring · uuidrequired
The Location assigned to this ServiceVariant. Required when creating a variant.
net_priceintegerrequired
The net price in minor currency units, before tax.
permits_remote_bookingsboolean
Whether this ServiceVariant can be used for remote bookings.
service_idstring · uuidrequired
The Service this variant belongs to. Required when creating a variant.

Responses

201

The requested Service.

created_atstring · date-timerequired
An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
descriptionstring | nullrequired
The description of the service shown to staff members and patients.
duration_minutesinteger | nullrequired
The scheduled duration of the service, in minutes.
idstring · uuidrequired
The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
is_bookable_onlinebooleanrequired
Whether patients can book this service online in the Patient Portal.
namestringrequired
The display name of the service.
objectanyrequired
Discriminator value emitted at object.
service_variantsarrayrequired
The bookable variants of this service.
- itemsobject
  - clinician_idstring | null · uuidrequired
    The identifier of the clinician assigned to this service variant, when the variant is clinician-specific.
  - currencystring | nullrequired
    The ISO 4217 currency code used for this service variant. Must be one of chf, eur, gbp, or usd.
  - descriptionstring | nullrequired
    The description of this service variant.
  - idstring · uuidrequired
    The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - linksobjectrequired
    URLs to related resources.
    - clinicianstring | null · urirequired
      The full URL of a related resource.
    - locationstring | null · urirequired
      The full URL of a related resource.
  - location_idstring | null · uuidrequired
    The identifier of the location assigned to this service variant, when the variant is location-specific.
  - net_priceinteger | nullrequired
    The net price of this service variant, before tax, in the currency's minor units.
  - permits_remote_bookingsbooleanrequired
    Whether this service variant can be used for remote bookings.
tax_rateobject | nullrequired
The tax rate applied to this service. Null when no tax rate is set.
- descriptionstring | nullrequired
  The description of when the tax rate applies.
- idstring · uuidrequired
  The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
- percentagenumberrequired
  The tax rate as a percentage from 0 to 100.
- titlestringrequired
  The display name of the tax rate, for example 20% VAT.
updated_atstring · date-timerequired
An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.

Example

{
  "id": "00000000-0000-4000-8000-000000000005",
  "object": "service",
  "created_at": "2026-01-01T09:00:00Z",
  "description": "An initial consultation at the Harley Street Clinic.",
  "duration_minutes": 30,
  "is_bookable_online": true,
  "name": "Initial consultation",
  "service_variants":  … ]
     … }
      "id": "00000000-0000-4000-8000-000000000006",
      "clinician_id": "00000000-0000-4000-8000-000000000002",
      "currency": "GBP",
      "description": "An initial consultation at the Harley Street Clinic.",
      "links":  … }
        "clinician": "https://api.carebit.co/v1/clinicians/00000000-0000-4000-8000-000000000002",
        "location": "https://api.carebit.co/v1/locations/00000000-0000-4000-8000-000000000003"
      },
      "location_id": "00000000-0000-4000-8000-000000000003",
      "net_price": 1,
      "permits_remote_bookings": true
    }
  ],
  "tax_rate":  … }
    "id": "00000000-0000-4000-8000-000000000029",
    "description": "An initial consultation at the Harley Street Clinic.",
    "percentage": 20,
    "title": "VAT"
  },
  "updated_at": "2026-01-01T09:00:00Z"
}

400

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

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

Example

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

401

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

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

Example

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

403

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

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

Example

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

404

The Service, Location, or Clinician was not found in the Organization.

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

Example

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

409

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

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

Example

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

422

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

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

Example

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

429

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

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

Example

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

Request

curl -X POST "https://api.carebit.co/v1/service_variants" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "currency": "gbp",
  "location_id": "00000000-0000-4000-8000-000000000003",
  "net_price": 15000,
  "service_id": "00000000-0000-4000-8000-000000000005"
}'

201 response

{
  "id": "00000000-0000-4000-8000-000000000005",
  "object": "service",
  "created_at": "2026-01-01T09:00:00Z",
  "description": "An initial consultation at the Harley Street Clinic.",
  "duration_minutes": 30,
  "is_bookable_online": true,
  "name": "Initial consultation",
  "service_variants":  … ]
     … }
      "id": "00000000-0000-4000-8000-000000000006",
      "clinician_id": "00000000-0000-4000-8000-000000000002",
      "currency": "GBP",
      "description": "An initial consultation at the Harley Street Clinic.",
      "links":  … }
        "clinician": "https://api.carebit.co/v1/clinicians/00000000-0000-4000-8000-000000000002",
        "location": "https://api.carebit.co/v1/locations/00000000-0000-4000-8000-000000000003"
      },
      "location_id": "00000000-0000-4000-8000-000000000003",
      "net_price": 1,
      "permits_remote_bookings": true
    }
  ],
  "tax_rate":  … }
    "id": "00000000-0000-4000-8000-000000000029",
    "description": "An initial consultation at the Harley Street Clinic.",
    "percentage": 20,
    "title": "VAT"
  },
  "updated_at": "2026-01-01T09:00:00Z"
}

400 response

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

401 response

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

403 response

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

404 response

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

409 response

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

422 response

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

429 response

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

patch/v1/service_variants/:id

Update a ServiceVariant

Updates a ServiceVariant, including its net price. Use this for bulk price increases. The response is the parent Service. Requires services.update.

Required API scopes: services.update

Parameters

id
path · required
string
-
Idempotency-Key
header · required
string
Client-generated idempotency key. Required for every POST/PATCH write. Replay of the same key with the same body returns the stored response with an Idempotency-Replayed: true header. Same key + different body returns 422 idempotency_key_reused. A duplicate that arrives while the first request is still in flight returns 409 idempotency_conflict with Retry-After: 1.

Request body

application/json

clinician_idstring | null · uuid
The Clinician assigned to this ServiceVariant, when the variant is clinician-specific.
currencystring | null
The ISO 4217 currency code used for this ServiceVariant.
Allowed values: chf | eur | gbp | usd | null
descriptionstring | null
The description of this ServiceVariant.
location_idstring · uuid
The Location assigned to this ServiceVariant. Required when creating a variant.
net_priceinteger
The net price in minor currency units, before tax.
permits_remote_bookingsboolean
Whether this ServiceVariant can be used for remote bookings.
service_idstring · uuid
The Service this variant belongs to. Required when creating a variant.

Responses

200

The requested Service.

created_atstring · date-timerequired
An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
descriptionstring | nullrequired
The description of the service shown to staff members and patients.
duration_minutesinteger | nullrequired
The scheduled duration of the service, in minutes.
idstring · uuidrequired
The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
is_bookable_onlinebooleanrequired
Whether patients can book this service online in the Patient Portal.
namestringrequired
The display name of the service.
objectanyrequired
Discriminator value emitted at object.
service_variantsarrayrequired
The bookable variants of this service.
- itemsobject
  - clinician_idstring | null · uuidrequired
    The identifier of the clinician assigned to this service variant, when the variant is clinician-specific.
  - currencystring | nullrequired
    The ISO 4217 currency code used for this service variant. Must be one of chf, eur, gbp, or usd.
  - descriptionstring | nullrequired
    The description of this service variant.
  - idstring · uuidrequired
    The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - linksobjectrequired
    URLs to related resources.
    - clinicianstring | null · urirequired
      The full URL of a related resource.
    - locationstring | null · urirequired
      The full URL of a related resource.
  - location_idstring | null · uuidrequired
    The identifier of the location assigned to this service variant, when the variant is location-specific.
  - net_priceinteger | nullrequired
    The net price of this service variant, before tax, in the currency's minor units.
  - permits_remote_bookingsbooleanrequired
    Whether this service variant can be used for remote bookings.
tax_rateobject | nullrequired
The tax rate applied to this service. Null when no tax rate is set.
- descriptionstring | nullrequired
  The description of when the tax rate applies.
- idstring · uuidrequired
  The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
- percentagenumberrequired
  The tax rate as a percentage from 0 to 100.
- titlestringrequired
  The display name of the tax rate, for example 20% VAT.
updated_atstring · date-timerequired
An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.

Example

{
  "id": "00000000-0000-4000-8000-000000000005",
  "object": "service",
  "created_at": "2026-01-01T09:00:00Z",
  "description": "An initial consultation at the Harley Street Clinic.",
  "duration_minutes": 30,
  "is_bookable_online": true,
  "name": "Initial consultation",
  "service_variants":  … ]
     … }
      "id": "00000000-0000-4000-8000-000000000006",
      "clinician_id": "00000000-0000-4000-8000-000000000002",
      "currency": "GBP",
      "description": "An initial consultation at the Harley Street Clinic.",
      "links":  … }
        "clinician": "https://api.carebit.co/v1/clinicians/00000000-0000-4000-8000-000000000002",
        "location": "https://api.carebit.co/v1/locations/00000000-0000-4000-8000-000000000003"
      },
      "location_id": "00000000-0000-4000-8000-000000000003",
      "net_price": 1,
      "permits_remote_bookings": true
    }
  ],
  "tax_rate":  … }
    "id": "00000000-0000-4000-8000-000000000029",
    "description": "An initial consultation at the Harley Street Clinic.",
    "percentage": 20,
    "title": "VAT"
  },
  "updated_at": "2026-01-01T09:00:00Z"
}

400

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

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

Example

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

401

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

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

Example

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

403

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

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

Example

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

404

Error response.

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

Example

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

409

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

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

Example

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

422

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

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

Example

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

429

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

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

Example

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

Request

curl -X PATCH "https://api.carebit.co/v1/service_variants/00000000-0000-4000-8000-000000000005" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "net_price": 17500
}'

200 response

{
  "id": "00000000-0000-4000-8000-000000000005",
  "object": "service",
  "created_at": "2026-01-01T09:00:00Z",
  "description": "An initial consultation at the Harley Street Clinic.",
  "duration_minutes": 30,
  "is_bookable_online": true,
  "name": "Initial consultation",
  "service_variants":  … ]
     … }
      "id": "00000000-0000-4000-8000-000000000006",
      "clinician_id": "00000000-0000-4000-8000-000000000002",
      "currency": "GBP",
      "description": "An initial consultation at the Harley Street Clinic.",
      "links":  … }
        "clinician": "https://api.carebit.co/v1/clinicians/00000000-0000-4000-8000-000000000002",
        "location": "https://api.carebit.co/v1/locations/00000000-0000-4000-8000-000000000003"
      },
      "location_id": "00000000-0000-4000-8000-000000000003",
      "net_price": 1,
      "permits_remote_bookings": true
    }
  ],
  "tax_rate":  … }
    "id": "00000000-0000-4000-8000-000000000029",
    "description": "An initial consultation at the Harley Street Clinic.",
    "percentage": 20,
    "title": "VAT"
  },
  "updated_at": "2026-01-01T09:00:00Z"
}

400 response

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

401 response

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

403 response

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

404 response

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

409 response

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

422 response

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

429 response

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

get/v1/services

List the Organization's Services

Required API scopes: services.read

Parameters

is_bookable_online
query
boolean
Only return Services that patients can book online.
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 Service objects.

dataarrayrequired
- itemsobject
  - created_atstring · date-timerequired
    An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
  - descriptionstring | nullrequired
    The description of the service shown to staff members and patients.
  - duration_minutesinteger | nullrequired
    The scheduled duration of the service, in minutes.
  - idstring · uuidrequired
    The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - is_bookable_onlinebooleanrequired
    Whether patients can book this service online in the Patient Portal.
  - namestringrequired
    The display name of the service.
  - objectanyrequired
    Discriminator value emitted at object.
  - service_variantsarrayrequired
    The bookable variants of this service.
    - itemsobject
      - clinician_idstring | null · uuidrequired
        The identifier of the clinician assigned to this service variant, when the variant is clinician-specific.
      - currencystring | nullrequired
        The ISO 4217 currency code used for this service variant. Must be one of chf, eur, gbp, or usd.
      - descriptionstring | nullrequired
        The description of this service variant.
      - idstring · uuidrequired
        The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
      - linksobjectrequired
        URLs to related resources.
        clinicianstring | null · urirequired
        The full URL of a related resource.
        locationstring | null · urirequired
        The full URL of a related resource.
      - location_idstring | null · uuidrequired
        The identifier of the location assigned to this service variant, when the variant is location-specific.
      - net_priceinteger | nullrequired
        The net price of this service variant, before tax, in the currency's minor units.
      - permits_remote_bookingsbooleanrequired
        Whether this service variant can be used for remote bookings.
  - tax_rateobject | nullrequired
    The tax rate applied to this service. Null when no tax rate is set.
    - descriptionstring | nullrequired
      The description of when the tax rate applies.
    - idstring · uuidrequired
      The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
    - percentagenumberrequired
      The tax rate as a percentage from 0 to 100.
    - titlestringrequired
      The display name of the tax rate, for example 20% VAT.
  - updated_atstring · date-timerequired
    An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
has_morebooleanrequired
Whether another page is available after next_cursor.
next_cursorstring | nullrequired
The value to pass as cursor for the next page. Null on the last page.
objectanyrequired
Always list.
urlstringrequired
The API path that returned this list.

Example

{
  "object": "list",
  "data":  … ]
     … }
      "id": "00000000-0000-4000-8000-000000000005",
      "object": "service",
      "created_at": "2026-01-01T09:00:00Z",
      "description": "An initial consultation at the Harley Street Clinic.",
      "duration_minutes": 30,
      "is_bookable_online": true,
      "name": "Initial consultation",
      "service_variants":  … ]
         … }
          "id": "00000000-0000-4000-8000-000000000006",
          "clinician_id": "00000000-0000-4000-8000-000000000002",
          "currency": "GBP",
          "description": "An initial consultation at the Harley Street Clinic.",
          "links":  … }
            "clinician": "https://api.carebit.co/v1/clinicians/00000000-0000-4000-8000-000000000002",
            "location": "https://api.carebit.co/v1/locations/00000000-0000-4000-8000-000000000003"
          },
          "location_id": "00000000-0000-4000-8000-000000000003",
          "net_price": 1,
          "permits_remote_bookings": true
        }
      ],
      "tax_rate":  … }
        "id": "00000000-0000-4000-8000-000000000029",
        "description": "An initial consultation at the Harley Street Clinic.",
        "percentage": 20,
        "title": "VAT"
      },
      "updated_at": "2026-01-01T09:00:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": "eyJzdGFydF90aW1lIjoiMjAyNi0wMS0wMVQwOTowMDowMFoifQ",
  "url": "/v1/services"
}

400

A filter or pagination parameter is invalid.

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

Example

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

401

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

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

Example

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

403

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

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

Example

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

429

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

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

Example

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

Request

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

200 response

{
  "object": "list",
  "data":  … ]
     … }
      "id": "00000000-0000-4000-8000-000000000005",
      "object": "service",
      "created_at": "2026-01-01T09:00:00Z",
      "description": "An initial consultation at the Harley Street Clinic.",
      "duration_minutes": 30,
      "is_bookable_online": true,
      "name": "Initial consultation",
      "service_variants":  … ]
         … }
          "id": "00000000-0000-4000-8000-000000000006",
          "clinician_id": "00000000-0000-4000-8000-000000000002",
          "currency": "GBP",
          "description": "An initial consultation at the Harley Street Clinic.",
          "links":  … }
            "clinician": "https://api.carebit.co/v1/clinicians/00000000-0000-4000-8000-000000000002",
            "location": "https://api.carebit.co/v1/locations/00000000-0000-4000-8000-000000000003"
          },
          "location_id": "00000000-0000-4000-8000-000000000003",
          "net_price": 1,
          "permits_remote_bookings": true
        }
      ],
      "tax_rate":  … }
        "id": "00000000-0000-4000-8000-000000000029",
        "description": "An initial consultation at the Harley Street Clinic.",
        "percentage": 20,
        "title": "VAT"
      },
      "updated_at": "2026-01-01T09:00:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": "eyJzdGFydF90aW1lIjoiMjAyNi0wMS0wMVQwOTowMDowMFoifQ",
  "url": "/v1/services"
}

400 response

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

401 response

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

403 response

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

429 response

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

post/v1/services

Create a Service

Creates a Service. Optionally include service_variants to create bookable variants in the same request. Amounts use minor currency units. Requires services.create.

Required API scopes: services.create

Parameters

Idempotency-Key
header · required
string
Client-generated idempotency key. Required for every POST/PATCH write. Replay of the same key with the same body returns the stored response with an Idempotency-Replayed: true header. Same key + different body returns 422 idempotency_key_reused. A duplicate that arrives while the first request is still in flight returns 409 idempotency_conflict with Retry-After: 1.

Request body

application/json

appointment_settingstring
Where the Service is delivered. Defaults to outpatient when creating a Service.
Allowed values: inpatient | outpatient | daycase
descriptionstring | null
The description of the service shown to staff members and patients.
duration_minutesintegerrequired
The scheduled duration of the service, in minutes. Also sets the slot duration when the current slot duration would be shorter.
is_bookable_onlineboolean
Whether patients can book this service online in the Patient Portal.
namestringrequired
The display name of the service.
service_typestring
The clinical category of the Service. Defaults to consultation when creating a Service.
Allowed values: consultation | diagnostic | procedure
service_variantsarray
ServiceVariants to create or update. Include id to update an existing variant.
- itemsobject
  - clinician_idstring | null · uuid
    The Clinician assigned to this ServiceVariant, when the variant is clinician-specific.
  - currencystring | null
    The ISO 4217 currency code used for this ServiceVariant.
    Allowed values: chf | eur | gbp | usd | null
  - descriptionstring | null
    The description of this ServiceVariant.
  - idstring · uuid
    The identifier of an existing ServiceVariant to update. Omit this field to create a variant.
  - location_idstring · uuid
    The Location assigned to this ServiceVariant. Required when creating a variant.
  - net_priceinteger
    The net price in minor currency units, before tax.
  - permits_remote_bookingsboolean
    Whether this ServiceVariant can be used for remote bookings.
tax_rate_idstring | null · uuid
The TaxRate to apply to this Service. Null clears the TaxRate.

Responses

201

The requested Service.

created_atstring · date-timerequired
An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
descriptionstring | nullrequired
The description of the service shown to staff members and patients.
duration_minutesinteger | nullrequired
The scheduled duration of the service, in minutes.
idstring · uuidrequired
The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
is_bookable_onlinebooleanrequired
Whether patients can book this service online in the Patient Portal.
namestringrequired
The display name of the service.
objectanyrequired
Discriminator value emitted at object.
service_variantsarrayrequired
The bookable variants of this service.
- itemsobject
  - clinician_idstring | null · uuidrequired
    The identifier of the clinician assigned to this service variant, when the variant is clinician-specific.
  - currencystring | nullrequired
    The ISO 4217 currency code used for this service variant. Must be one of chf, eur, gbp, or usd.
  - descriptionstring | nullrequired
    The description of this service variant.
  - idstring · uuidrequired
    The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - linksobjectrequired
    URLs to related resources.
    - clinicianstring | null · urirequired
      The full URL of a related resource.
    - locationstring | null · urirequired
      The full URL of a related resource.
  - location_idstring | null · uuidrequired
    The identifier of the location assigned to this service variant, when the variant is location-specific.
  - net_priceinteger | nullrequired
    The net price of this service variant, before tax, in the currency's minor units.
  - permits_remote_bookingsbooleanrequired
    Whether this service variant can be used for remote bookings.
tax_rateobject | nullrequired
The tax rate applied to this service. Null when no tax rate is set.
- descriptionstring | nullrequired
  The description of when the tax rate applies.
- idstring · uuidrequired
  The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
- percentagenumberrequired
  The tax rate as a percentage from 0 to 100.
- titlestringrequired
  The display name of the tax rate, for example 20% VAT.
updated_atstring · date-timerequired
An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.

Example

{
  "id": "00000000-0000-4000-8000-000000000005",
  "object": "service",
  "created_at": "2026-01-01T09:00:00Z",
  "description": "An initial consultation at the Harley Street Clinic.",
  "duration_minutes": 30,
  "is_bookable_online": true,
  "name": "Initial consultation",
  "service_variants":  … ]
     … }
      "id": "00000000-0000-4000-8000-000000000006",
      "clinician_id": "00000000-0000-4000-8000-000000000002",
      "currency": "GBP",
      "description": "An initial consultation at the Harley Street Clinic.",
      "links":  … }
        "clinician": "https://api.carebit.co/v1/clinicians/00000000-0000-4000-8000-000000000002",
        "location": "https://api.carebit.co/v1/locations/00000000-0000-4000-8000-000000000003"
      },
      "location_id": "00000000-0000-4000-8000-000000000003",
      "net_price": 1,
      "permits_remote_bookings": true
    }
  ],
  "tax_rate":  … }
    "id": "00000000-0000-4000-8000-000000000029",
    "description": "An initial consultation at the Harley Street Clinic.",
    "percentage": 20,
    "title": "VAT"
  },
  "updated_at": "2026-01-01T09:00:00Z"
}

400

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

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

Example

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

401

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

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

Example

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

403

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

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

Example

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

404

A referenced TaxRate, Location, or Clinician was not found in the Organization.

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

Example

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

409

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

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

Example

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

422

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

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

Example

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

429

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

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

Example

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

Request

curl -X POST "https://api.carebit.co/v1/services" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "duration_minutes": 30,
  "is_bookable_online": true,
  "name": "Initial consultation",
  "service_variants": [
    {
      "currency": "gbp",
      "location_id": "00000000-0000-4000-8000-000000000003",
      "net_price": 15000
    }
  ]
}'

201 response

{
  "id": "00000000-0000-4000-8000-000000000005",
  "object": "service",
  "created_at": "2026-01-01T09:00:00Z",
  "description": "An initial consultation at the Harley Street Clinic.",
  "duration_minutes": 30,
  "is_bookable_online": true,
  "name": "Initial consultation",
  "service_variants":  … ]
     … }
      "id": "00000000-0000-4000-8000-000000000006",
      "clinician_id": "00000000-0000-4000-8000-000000000002",
      "currency": "GBP",
      "description": "An initial consultation at the Harley Street Clinic.",
      "links":  … }
        "clinician": "https://api.carebit.co/v1/clinicians/00000000-0000-4000-8000-000000000002",
        "location": "https://api.carebit.co/v1/locations/00000000-0000-4000-8000-000000000003"
      },
      "location_id": "00000000-0000-4000-8000-000000000003",
      "net_price": 1,
      "permits_remote_bookings": true
    }
  ],
  "tax_rate":  … }
    "id": "00000000-0000-4000-8000-000000000029",
    "description": "An initial consultation at the Harley Street Clinic.",
    "percentage": 20,
    "title": "VAT"
  },
  "updated_at": "2026-01-01T09:00:00Z"
}

400 response

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

401 response

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

403 response

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

404 response

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

409 response

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

422 response

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

429 response

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

get/v1/services/:id

Get a Service

Required API scopes: services.read

Parameters

id
path · required
string
-

Responses

200

The requested Service.

created_atstring · date-timerequired
An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
descriptionstring | nullrequired
The description of the service shown to staff members and patients.
duration_minutesinteger | nullrequired
The scheduled duration of the service, in minutes.
idstring · uuidrequired
The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
is_bookable_onlinebooleanrequired
Whether patients can book this service online in the Patient Portal.
namestringrequired
The display name of the service.
objectanyrequired
Discriminator value emitted at object.
service_variantsarrayrequired
The bookable variants of this service.
- itemsobject
  - clinician_idstring | null · uuidrequired
    The identifier of the clinician assigned to this service variant, when the variant is clinician-specific.
  - currencystring | nullrequired
    The ISO 4217 currency code used for this service variant. Must be one of chf, eur, gbp, or usd.
  - descriptionstring | nullrequired
    The description of this service variant.
  - idstring · uuidrequired
    The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - linksobjectrequired
    URLs to related resources.
    - clinicianstring | null · urirequired
      The full URL of a related resource.
    - locationstring | null · urirequired
      The full URL of a related resource.
  - location_idstring | null · uuidrequired
    The identifier of the location assigned to this service variant, when the variant is location-specific.
  - net_priceinteger | nullrequired
    The net price of this service variant, before tax, in the currency's minor units.
  - permits_remote_bookingsbooleanrequired
    Whether this service variant can be used for remote bookings.
tax_rateobject | nullrequired
The tax rate applied to this service. Null when no tax rate is set.
- descriptionstring | nullrequired
  The description of when the tax rate applies.
- idstring · uuidrequired
  The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
- percentagenumberrequired
  The tax rate as a percentage from 0 to 100.
- titlestringrequired
  The display name of the tax rate, for example 20% VAT.
updated_atstring · date-timerequired
An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.

Example

{
  "id": "00000000-0000-4000-8000-000000000005",
  "object": "service",
  "created_at": "2026-01-01T09:00:00Z",
  "description": "An initial consultation at the Harley Street Clinic.",
  "duration_minutes": 30,
  "is_bookable_online": true,
  "name": "Initial consultation",
  "service_variants":  … ]
     … }
      "id": "00000000-0000-4000-8000-000000000006",
      "clinician_id": "00000000-0000-4000-8000-000000000002",
      "currency": "GBP",
      "description": "An initial consultation at the Harley Street Clinic.",
      "links":  … }
        "clinician": "https://api.carebit.co/v1/clinicians/00000000-0000-4000-8000-000000000002",
        "location": "https://api.carebit.co/v1/locations/00000000-0000-4000-8000-000000000003"
      },
      "location_id": "00000000-0000-4000-8000-000000000003",
      "net_price": 1,
      "permits_remote_bookings": true
    }
  ],
  "tax_rate":  … }
    "id": "00000000-0000-4000-8000-000000000029",
    "description": "An initial consultation at the Harley Street Clinic.",
    "percentage": 20,
    "title": "VAT"
  },
  "updated_at": "2026-01-01T09:00:00Z"
}

401

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

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

Example

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

403

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

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

Example

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

404

Error response.

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

Example

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

429

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

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

Example

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

Request

curl -X GET "https://api.carebit.co/v1/services/00000000-0000-4000-8000-000000000005" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN"

200 response

{
  "id": "00000000-0000-4000-8000-000000000005",
  "object": "service",
  "created_at": "2026-01-01T09:00:00Z",
  "description": "An initial consultation at the Harley Street Clinic.",
  "duration_minutes": 30,
  "is_bookable_online": true,
  "name": "Initial consultation",
  "service_variants":  … ]
     … }
      "id": "00000000-0000-4000-8000-000000000006",
      "clinician_id": "00000000-0000-4000-8000-000000000002",
      "currency": "GBP",
      "description": "An initial consultation at the Harley Street Clinic.",
      "links":  … }
        "clinician": "https://api.carebit.co/v1/clinicians/00000000-0000-4000-8000-000000000002",
        "location": "https://api.carebit.co/v1/locations/00000000-0000-4000-8000-000000000003"
      },
      "location_id": "00000000-0000-4000-8000-000000000003",
      "net_price": 1,
      "permits_remote_bookings": true
    }
  ],
  "tax_rate":  … }
    "id": "00000000-0000-4000-8000-000000000029",
    "description": "An initial consultation at the Harley Street Clinic.",
    "percentage": 20,
    "title": "VAT"
  },
  "updated_at": "2026-01-01T09:00:00Z"
}

401 response

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

403 response

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

404 response

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

429 response

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

patch/v1/services/:id

Update a Service

Updates a Service. Send service_variants with an id to update an existing variant, or omit id to create a variant. Use this to apply a bulk price change across a Service's variants. Requires services.update.

Required API scopes: services.update

Parameters

id
path · required
string
-
Idempotency-Key
header · required
string
Client-generated idempotency key. Required for every POST/PATCH write. Replay of the same key with the same body returns the stored response with an Idempotency-Replayed: true header. Same key + different body returns 422 idempotency_key_reused. A duplicate that arrives while the first request is still in flight returns 409 idempotency_conflict with Retry-After: 1.

Request body

application/json

appointment_settingstring
Where the Service is delivered. Defaults to outpatient when creating a Service.
Allowed values: inpatient | outpatient | daycase
descriptionstring | null
The description of the service shown to staff members and patients.
duration_minutesinteger
The scheduled duration of the service, in minutes. Also sets the slot duration when the current slot duration would be shorter.
is_bookable_onlineboolean
Whether patients can book this service online in the Patient Portal.
namestring
The display name of the service.
service_typestring
The clinical category of the Service. Defaults to consultation when creating a Service.
Allowed values: consultation | diagnostic | procedure
service_variantsarray
ServiceVariants to create or update. Include id to update an existing variant.
- itemsobject
  - clinician_idstring | null · uuid
    The Clinician assigned to this ServiceVariant, when the variant is clinician-specific.
  - currencystring | null
    The ISO 4217 currency code used for this ServiceVariant.
    Allowed values: chf | eur | gbp | usd | null
  - descriptionstring | null
    The description of this ServiceVariant.
  - idstring · uuid
    The identifier of an existing ServiceVariant to update. Omit this field to create a variant.
  - location_idstring · uuid
    The Location assigned to this ServiceVariant. Required when creating a variant.
  - net_priceinteger
    The net price in minor currency units, before tax.
  - permits_remote_bookingsboolean
    Whether this ServiceVariant can be used for remote bookings.
tax_rate_idstring | null · uuid
The TaxRate to apply to this Service. Null clears the TaxRate.

Responses

200

The requested Service.

created_atstring · date-timerequired
An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
descriptionstring | nullrequired
The description of the service shown to staff members and patients.
duration_minutesinteger | nullrequired
The scheduled duration of the service, in minutes.
idstring · uuidrequired
The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
is_bookable_onlinebooleanrequired
Whether patients can book this service online in the Patient Portal.
namestringrequired
The display name of the service.
objectanyrequired
Discriminator value emitted at object.
service_variantsarrayrequired
The bookable variants of this service.
- itemsobject
  - clinician_idstring | null · uuidrequired
    The identifier of the clinician assigned to this service variant, when the variant is clinician-specific.
  - currencystring | nullrequired
    The ISO 4217 currency code used for this service variant. Must be one of chf, eur, gbp, or usd.
  - descriptionstring | nullrequired
    The description of this service variant.
  - idstring · uuidrequired
    The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - linksobjectrequired
    URLs to related resources.
    - clinicianstring | null · urirequired
      The full URL of a related resource.
    - locationstring | null · urirequired
      The full URL of a related resource.
  - location_idstring | null · uuidrequired
    The identifier of the location assigned to this service variant, when the variant is location-specific.
  - net_priceinteger | nullrequired
    The net price of this service variant, before tax, in the currency's minor units.
  - permits_remote_bookingsbooleanrequired
    Whether this service variant can be used for remote bookings.
tax_rateobject | nullrequired
The tax rate applied to this service. Null when no tax rate is set.
- descriptionstring | nullrequired
  The description of when the tax rate applies.
- idstring · uuidrequired
  The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
- percentagenumberrequired
  The tax rate as a percentage from 0 to 100.
- titlestringrequired
  The display name of the tax rate, for example 20% VAT.
updated_atstring · date-timerequired
An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.

Example

{
  "id": "00000000-0000-4000-8000-000000000005",
  "object": "service",
  "created_at": "2026-01-01T09:00:00Z",
  "description": "An initial consultation at the Harley Street Clinic.",
  "duration_minutes": 30,
  "is_bookable_online": true,
  "name": "Initial consultation",
  "service_variants":  … ]
     … }
      "id": "00000000-0000-4000-8000-000000000006",
      "clinician_id": "00000000-0000-4000-8000-000000000002",
      "currency": "GBP",
      "description": "An initial consultation at the Harley Street Clinic.",
      "links":  … }
        "clinician": "https://api.carebit.co/v1/clinicians/00000000-0000-4000-8000-000000000002",
        "location": "https://api.carebit.co/v1/locations/00000000-0000-4000-8000-000000000003"
      },
      "location_id": "00000000-0000-4000-8000-000000000003",
      "net_price": 1,
      "permits_remote_bookings": true
    }
  ],
  "tax_rate":  … }
    "id": "00000000-0000-4000-8000-000000000029",
    "description": "An initial consultation at the Harley Street Clinic.",
    "percentage": 20,
    "title": "VAT"
  },
  "updated_at": "2026-01-01T09:00:00Z"
}

400

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

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

Example

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

401

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

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

Example

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

403

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

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

Example

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

404

Error response.

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

Example

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

409

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

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

Example

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

422

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

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

Example

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

429

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

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

Example

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

Request

curl -X PATCH "https://api.carebit.co/v1/services/00000000-0000-4000-8000-000000000005" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "service_variants": [
    {
      "id": "00000000-0000-4000-8000-000000000006",
      "net_price": 17500
    }
  ]
}'

200 response

{
  "id": "00000000-0000-4000-8000-000000000005",
  "object": "service",
  "created_at": "2026-01-01T09:00:00Z",
  "description": "An initial consultation at the Harley Street Clinic.",
  "duration_minutes": 30,
  "is_bookable_online": true,
  "name": "Initial consultation",
  "service_variants":  … ]
     … }
      "id": "00000000-0000-4000-8000-000000000006",
      "clinician_id": "00000000-0000-4000-8000-000000000002",
      "currency": "GBP",
      "description": "An initial consultation at the Harley Street Clinic.",
      "links":  … }
        "clinician": "https://api.carebit.co/v1/clinicians/00000000-0000-4000-8000-000000000002",
        "location": "https://api.carebit.co/v1/locations/00000000-0000-4000-8000-000000000003"
      },
      "location_id": "00000000-0000-4000-8000-000000000003",
      "net_price": 1,
      "permits_remote_bookings": true
    }
  ],
  "tax_rate":  … }
    "id": "00000000-0000-4000-8000-000000000029",
    "description": "An initial consultation at the Harley Street Clinic.",
    "percentage": 20,
    "title": "VAT"
  },
  "updated_at": "2026-01-01T09:00:00Z"
}

400 response

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

401 response

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

403 response

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

404 response

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

409 response

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

422 response

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

429 response

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

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