> ## Documentation Index
> Fetch the complete documentation index at: https://docs.carewithemma.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Managing Appointments

> Search, book, reschedule, and cancel appointments

## GET /Appointment

Returns the patient's **next upcoming** appointment. Past and cancelled appointments aren't returned.

Query parameter `patient` (required): `Patient/{id}`. Missing returns 400.

### Response

200 OK, a FHIR Bundle with `total` of `0` (empty `entry`) or `1`:

```json theme={null}
{
  "resourceType": "Bundle",
  "type": "searchset",
  "total": 1,
  "entry": [
    {
      "resource": {
        "resourceType": "Appointment",
        "id": "appt-001",
        "status": "booked",
        "start": "2026-09-15T14:30:00.000Z",
        "end": "2026-09-15T15:00:00.000Z",
        "serviceType": [{ "text": "Follow-up consultation" }],
        "participant": [
          { "actor": { "reference": "Patient/pat-1001" }, "status": "accepted" },
          { "actor": { "reference": "Practitioner/Dr. Patel" }, "status": "accepted" }
        ]
      }
    }
  ]
}
```

`status` is one of `booked`, `cancelled`, or `fulfilled`.

## POST /Appointment/\$book

Books an open slot.

### Request body

A FHIR Parameters resource wrapping an Appointment:

```json theme={null}
{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "appointment",
      "resource": {
        "resourceType": "Appointment",
        "status": "proposed",
        "serviceType": [{ "text": "Follow-up consultation" }],
        "start": "2026-09-15T14:30:00.000Z",
        "participant": [
          { "actor": { "reference": "Patient/pat-1001" } },
          { "actor": { "reference": "Practitioner/Dr. Patel" } }
        ]
      }
    }
  ]
}
```

`serviceType[0].text` defaults to `Follow-up consultation` if omitted. `start`, and both a `Patient/` and `Practitioner/` participant reference, are required. Missing any of them returns 400.

### Response

200 OK, the booked Appointment resource (same shape as above).

<Warning>
  On a double-booking conflict, this returns HTTP 409 with a genuine FHIR OperationOutcome, not a generic error body, matching real Epic's own error style:

  ```json theme={null}
  {
    "resourceType": "OperationOutcome",
    "issue": [{ "severity": "error", "code": "conflict", "diagnostics": "slot_taken" }]
  }
  ```
</Warning>

## POST /Appointment/\{id}/\$reschedule

Moves an existing appointment to a new time.

<Note>
  Epic itself frequently models a reschedule as cancel-then-rebook rather than a dedicated operation. This sandbox exposes reschedule as one convenience call instead.
</Note>

### Request body

```json theme={null}
{ "start": "2026-09-16T15:00:00.000Z" }
```

`start` is required. Missing or invalid returns 400.

### Response

200 OK, the updated Appointment, `status: "booked"`.

404 Not Found for an unknown or cross-clinic appointment id:

```json theme={null}
{ "statusCode": 404, "message": "Appointment {id} not found", "error": "Not Found" }
```

## POST /Appointment/\{id}/\$cancel

Cancels an existing appointment. No request body.

### Response

200 OK, the Appointment, `status: "cancelled"`. Same 404 behavior as `$reschedule` for an unknown or cross-clinic id.

### Example request

```bash theme={null}
curl -X POST 'https://your-emma-domain/api/Appointment/appt-001/$cancel' \
  -H "Authorization: Bearer <jwt>"
```