# Create a new slot

Operation ID: `appointments.createSlot`

Create a provider-owned slot that can later be discovered with `appointments.listSlots` and booked via `appointments.book` (pass the returned `slot_id`, which is the real FHIR resource id). Times use ISO 8601 date-time values and `end` must be strictly after `start`. Restricted to a PROVIDER (their own provider_id only) or TENANTADMIN caller. Rejects a slot whose [start, end) range overlaps an existing slot on the *same schedule* (409) — back-to-back slots (one ending exactly when the next starts) are not an overlap, so a schedule holding many contiguous, non-overlapping slots is normal and expected; a slot being updated is excluded from its own overlap check. The overlap scope is per schedule (in practice per provider) — an identical time range on a different provider's schedule is never a conflict.

## Public method

`createSlot`

Signature: `appointments.createSlot(request)`

Return type: `Promise<CreateSlotResponse>`

## Authentication

Classification: **AUTHENTICATED**

Schemes: `bearerAuth`

## Prerequisites

None documented.

## HTTP

`POST /slots`

## Path parameters

None.

## Query parameters

None.

## Body parameters

| Name | Type | Required | Format | Allowed values | Default | Nullable | Description |
|---|---|---:|---|---|---|---:|---|
| `body` | [`CreateSlotRequest`](../models/CreateSlotRequest.md) | No |  |  |  | Yes |  |

Request model: [`CreateSlotRequest`](../models/CreateSlotRequest.md)

## Request example

```json
{
  "comment": "Follow-up slot",
  "end": "2026-08-15T09:30:00Z",
  "location": "Room 3A",
  "provider_id": "pract-123",
  "provider_name": "Dr. Smith",
  "schedule_id": "sch-789",
  "service_type_code": "408467006",
  "specialty_code": "394617004",
  "start": "2026-08-15T09:00:00Z",
  "status": "free"
}
```

## Success responses

| Status | Shape | Content type | Description |
|---|---|---|---|
| `201` | [`Slot`](../models/Slot.md) | application/json | Slot created successfully |

## Success response examples

### 201

```json
{
  "athena_appointment_id": "string",
  "end": "2026-01-01T09:00:00Z",
  "location": "string",
  "openloop_appointment_id": "string",
  "provider_id": "string",
  "provider_name": "string",
  "slot_id": "string",
  "specialty_code": "string",
  "start": "2026-01-01T09:00:00Z",
  "status": "free",
  "steadymd_clinician_guid": "string"
}
```

## Common errors

| Status | Shape | Content type | Description |
|---|---|---|---|
| `400` | [`appointments.ErrorResponse`](../models/appointments.ErrorResponse.md) | application/json | Required fields are missing, date-time values are invalid, end is not after start, or FHIR rejected the slot |
| `401` | [`appointments.ErrorResponse`](../models/appointments.ErrorResponse.md) | application/json | Authorization required — missing or invalid Bearer JWT |
| `403` | [`appointments.ErrorResponse`](../models/appointments.ErrorResponse.md) | application/json | Caller is not a provider or tenant administrator, or a provider tried to create a slot for a different provider_id |
| `409` | [`appointments.ErrorResponse`](../models/appointments.ErrorResponse.md) | application/json | The requested time range overlaps an existing slot on the same schedule |
| `500` | [`appointments.ErrorResponse`](../models/appointments.ErrorResponse.md) | application/json | Internal server error |

## Error examples

### 400 — FHIR rejected the slot

```json
{
  "error": "Invalid slot",
  "outcome": {
    "issue": [
      {
        "diagnostics": "Invalid slot",
        "severity": "error"
      }
    ],
    "resourceType": "OperationOutcome"
  }
}
```

### 400 — end is not after start

```json
{
  "error": "end must be after start"
}
```

### 400 — Date-time values are invalid

```json
{
  "error": "start and end must be valid ISO 8601 datetime strings"
}
```

### 400 — Required fields are missing

```json
{
  "error": "schedule_id, provider_id, start, and end are required"
}
```

### 401 — Missing or invalid access token

```json
{
  "error": "Authorization required"
}
```

### 403 — Caller pool type is not provider/tenant administrator

```json
{
  "error": "Provider or tenant administrator authorization required"
}
```

### 403 — Provider caller does not own this provider_id

```json
{
  "error": "Providers may only create their own slots"
}
```

### 409 — Conflicts with an existing slot

```json
{
  "error": "Slot slot-existing on schedule schedule-pract-123 already occupies 2026-09-01T09:00:00Z–2026-09-01T09:30:00Z, which overlaps the requested 2026-09-01T09:15:00Z–2026-09-01T09:45:00Z"
}
```

### 500 — Unexpected service failure (sanitized example)

```json
{
  "error": "Internal server error"
}
```

## NodeJS / TypeScript implementation

```ts
import { HCSDK } from "@healthcloudai/hc-sdk";
import type { CreateSlotRequest } from "@healthcloudai/hc-sdk";
```

```ts
const request = {
  "comment": "Follow-up slot",
  "end": "2026-08-15T09:30:00Z",
  "location": "Room 3A",
  "provider_id": "pract-123",
  "provider_name": "Dr. Smith",
  "schedule_id": "sch-789",
  "service_type_code": "408467006",
  "specialty_code": "394617004",
  "start": "2026-08-15T09:00:00Z",
  "status": "free"
};

const result = await appointments.createSlot(request);
```

## cURL

```bash
curl -X POST \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{"comment":"Follow-up slot","end":"2026-08-15T09:30:00Z","location":"Room 3A","provider_id":"pract-123","provider_name":"Dr. Smith","schedule_id":"sch-789","service_type_code":"408467006","specialty_code":"394617004","start":"2026-08-15T09:00:00Z","status":"free"}' \
  'https://dev-api-appointments.health.cloud/slots'
```

## Notes

None.

## Prepared Test Console scenario

No canonical scenario is currently associated.

## Real response

No approved real integration response is currently published. Unapproved candidates are never rendered as examples.