# Create a Service

`POST /v1/services`

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, `string`) (required) - Client-generated idempotency key. Required for every POST/PATCH write. Replay of the same key with the same body returns the stored response with an `Idempotency-Replayed: true` header. Same key + different body returns `422 idempotency_key_reused`. A duplicate that arrives while the first request is still in flight returns `409 idempotency_conflict` with `Retry-After: 1`.

## Request body (`application/json`)

- `object`
  - `appointment_setting` (`string`) - enum: `inpatient`, `outpatient`, `daycase`; Where the Service is delivered. Defaults to `outpatient` when creating a Service.
  - `description` (`string | null`) - The description of the service shown to staff members and patients.
  - `duration_minutes` (`integer`) - The scheduled duration of the service, in minutes. Also sets the slot duration when the current slot duration would be shorter.
  - `is_bookable_online` (`boolean`) - Whether patients can book this service online in the Patient Portal.
  - `name` (`string`) - The display name of the service.
  - `service_type` (`string`) - enum: `consultation`, `diagnostic`, `procedure`; The clinical category of the Service. Defaults to `consultation` when creating a Service.
  - `service_variants` (`array`) - ServiceVariants to create or update. Include `id` to update an existing variant.
    - `items` (`object`)
      - `clinician_id` (`string | null`) - format: `uuid`; The Clinician assigned to this ServiceVariant, when the variant is clinician-specific.
      - `currency` (`string | null`) - enum: `chf`, `eur`, `gbp`, `usd`, `null`; The ISO 4217 currency code used for this ServiceVariant.
      - `description` (`string | null`) - The description of this ServiceVariant.
      - `id` (`string`) - format: `uuid`; The identifier of an existing ServiceVariant to update. Omit this field to create a variant.
      - `location_id` (`string`) - format: `uuid`; The Location assigned to this ServiceVariant. Required when creating a variant.
      - `net_price` (`integer`) - The net price in minor currency units, before tax.
      - `permits_remote_bookings` (`boolean`) - Whether this ServiceVariant can be used for remote bookings.
  - `tax_rate_id` (`string | null`) - format: `uuid`; The TaxRate to apply to this Service. Null clears the TaxRate.

### Example

```json
{
  "duration_minutes": 30,
  "is_bookable_online": true,
  "name": "Initial consultation",
  "service_variants": [
    {
      "currency": "gbp",
      "location_id": "00000000-0000-4000-8000-000000000003",
      "net_price": 15000
    }
  ]
}
```

## Response `201`

The requested `Service`.

- `object`
  - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `description` (`string | null`) - The description of the service shown to staff members and patients.
  - `duration_minutes` (`integer | null`) - The scheduled duration of the service, in minutes.
  - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - `is_bookable_online` (`boolean`) - Whether patients can book this service online in the Patient Portal.
  - `name` (`string`) - The display name of the service.
  - `object` (`any`) - Discriminator value emitted at `object`.
  - `service_variants` (`array`) - The bookable variants of this service.
    - `items` (`object`)
      - `clinician_id` (`string | null`) - format: `uuid`; The identifier of the clinician assigned to this service variant, when the variant is clinician-specific.
      - `currency` (`string | null`) - The ISO 4217 currency code used for this service variant. Must be one of `chf`, `eur`, `gbp`, or `usd`.
      - `description` (`string | null`) - The description of this service variant.
      - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
      - `links` (`object`) - URLs to related resources.
        - `clinician` (`string | null`) - format: `uri`; The full URL of a related resource.
        - `location` (`string | null`) - format: `uri`; The full URL of a related resource.
      - `location_id` (`string | null`) - format: `uuid`; The identifier of the location assigned to this service variant, when the variant is location-specific.
      - `net_price` (`integer | null`) - The net price of this service variant, before tax, in the currency's minor units.
      - `permits_remote_bookings` (`boolean`) - Whether this service variant can be used for remote bookings.
  - `tax_rate` (`any`) - The tax rate applied to this service. Null when no tax rate is set.
  - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.

### Example

```json
{
  "id": "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"
}
```

## Response `400`

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

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

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

## Response `401`

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

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

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

## Response `403`

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

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

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

## Response `404`

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

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

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

## Response `409`

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

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

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

## Response `422`

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

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

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

## Response `429`

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

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

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

## Code samples

```bash
curl -X POST "https://api.carebit.co/v1/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
    }
  ]
}'
```

```javascript
const response = await fetch("https://api.carebit.co/v1/services", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
  "duration_minutes": 30,
  "is_bookable_online": true,
  "name": "Initial consultation",
  "service_variants": [
    {
      "currency": "gbp",
      "location_id": "00000000-0000-4000-8000-000000000003",
      "net_price": 15000
    }
  ]
}),
});

if (!response.ok) {
  throw new Error(`Carebit API error: ${response.status}`);
}

const data = await response.json();
```

```python
import os
import requests
import uuid

response = requests.post(
    "https://api.carebit.co/v1/services",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "duration_minutes": 30,
        "is_bookable_online": True,
        "name": "Initial consultation",
        "service_variants": [
            {
                "currency": "gbp",
                "location_id": "00000000-0000-4000-8000-000000000003",
                "net_price": 15000
            }
        ]
    }
)
response.raise_for_status()
data = response.json()
```

```ruby
require "httparty"
require "json"
require "securerandom"

response = HTTParty.post(
  "https://api.carebit.co/v1/services",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}",
    "Idempotency-Key" => SecureRandom.uuid,
    "Content-Type" => "application/json"
  },
  body: {
    "duration_minutes" => 30,
    "is_bookable_online" => true,
    "name" => "Initial consultation",
    "service_variants" => [
      {
        "currency" => "gbp",
        "location_id" => "00000000-0000-4000-8000-000000000003",
        "net_price" => 15000
      }
    ]
  }.to_json
)
raise "Carebit API error: #{response.code}" unless response.success?
data = response.parsed_response
```

```php
<?php

$client = new GuzzleHttp\Client();

$response = $client->post("https://api.carebit.co/v1/services", [
    "headers" => [
      "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
      "Idempotency-Key" => bin2hex(random_bytes(16)),
    ],
    "json" => [
      "duration_minutes" => 30,
      "is_bookable_online" => true,
      "name" => "Initial consultation",
      "service_variants" => [
        [
          "currency" => "gbp",
          "location_id" => "00000000-0000-4000-8000-000000000003",
          "net_price" => 15000
        ]
      ]
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```