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

# Get Appointment

> Retrieve a single appointment you own by its ID

## Overview

Fetches one appointment by its id. Access is owner-only: the appointment's
`doctor_id` must match the authenticated caller, otherwise a `403 Forbidden` is
returned.

## Authentication

<ParamField header="Authorization" type="string" required>
  Bearer token for authenticated access.

  ```
  Authorization: Bearer <JWT>
  ```
</ParamField>

## Path Parameters

<ParamField path="id" type="string" required>
  Appointment ObjectId. Must be a 24-character hex ObjectId — a malformed value
  fails with a `400` cast error.
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Whether the request succeeded.
</ResponseField>

<ResponseField name="data" type="object">
  The appointment object.

  <Expandable title="Appointment Object">
    <ResponseField name="_id" type="string">
      Unique appointment identifier (ObjectId).
    </ResponseField>

    <ResponseField name="name" type="string">
      Appointment title.
    </ResponseField>

    <ResponseField name="date" type="string">
      Appointment date, serialized as a full ISO datetime
      (e.g. `2026-07-15T00:00:00.000Z`).
    </ResponseField>

    <ResponseField name="time" type="string">
      Wall-clock time, `HH:mm`.
    </ResponseField>

    <ResponseField name="recording_id" type="string">
      Associated recording id, if any.
    </ResponseField>

    <ResponseField name="recording_url" type="string">
      URL to the recording, if any.
    </ResponseField>

    <ResponseField name="recording_key" type="string">
      Recording storage key, if any.
    </ResponseField>

    <ResponseField name="status" type="string">
      Recording lifecycle status. Common values: `planned`, `recording`,
      `transcribing`, `processing`, `finished`, `error`, `error_transcription`,
      `audio_upload_failed`. Not strictly enforced — treat unknown values as
      opaque.
    </ResponseField>

    <ResponseField name="error_reason" type="string | null">
      Human-readable reason when processing failed; otherwise `null`.
    </ResponseField>

    <ResponseField name="doctor_id" type="string">
      Owning doctor's user id.
    </ResponseField>

    <ResponseField name="notes" type="string">
      Private clinical notes.
    </ResponseField>

    <ResponseField name="language" type="string">
      Language code used for note generation. Default `de`.
    </ResponseField>

    <ResponseField name="notes_type" type="string | null">
      Notes template key. Default `null` (the service selects a template).
    </ResponseField>

    <ResponseField name="appointment_type" type="string">
      Free-form appointment type. Default `in_person`.
    </ResponseField>

    <ResponseField name="room" type="string | null">
      Room / location label, or `null` when none is assigned.
    </ResponseField>

    <ResponseField name="duration_minutes" type="number | null">
      Appointment duration in minutes, or `null` when unset.
    </ResponseField>

    <ResponseField name="deletionDate" type="string">
      ISO datetime at which the appointment is scheduled for automatic deletion.
    </ResponseField>

    <ResponseField name="case_id" type="string | null">
      Case grouping id for follow-up linking, or `null`.
    </ResponseField>

    <ResponseField name="booking_status" type="string">
      Booking lifecycle state (a separate axis from `status`). Default `none`.
    </ResponseField>

    <ResponseField name="booking" type="object | null">
      Booking subdocument for appointments that carry booking metadata,
      otherwise `null`.
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      ISO creation timestamp.
    </ResponseField>

    <ResponseField name="updatedAt" type="string">
      ISO last-update timestamp.
    </ResponseField>

    <ResponseField name="__v" type="number">
      Internal document version.
    </ResponseField>
  </Expandable>
</ResponseField>

<Note>
  Additional fields may appear on the appointment object depending on how it was
  created. Treat any field not documented here as opaque.
</Note>

## Example Request

<RequestExample>
  ```bash curl theme={null}
  curl -X GET "https://app.medisync.me/api/appointments/get/65f8a1b2c3d4e5f6789012ef" \
    -H "Authorization: Bearer <JWT>"
  ```
</RequestExample>

## Example Response

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "_id": "65f8a1b2c3d4e5f6789012ef",
      "name": "Allgemeine Beratung",
      "date": "2026-07-15T00:00:00.000Z",
      "time": "14:30",
      "recording_id": "rec_123",
      "recording_url": "https://storage.example.com/recording.mp3",
      "recording_key": "recordings/rec_123.mp3",
      "status": "finished",
      "error_reason": null,
      "doctor_id": "65f0a1b2c3d4e5f678901234",
      "notes": "...",
      "language": "de",
      "notes_type": null,
      "appointment_type": "in_person",
      "room": null,
      "duration_minutes": 30,
      "deletionDate": "2026-07-29T00:00:00.000Z",
      "case_id": null,
      "booking_status": "none",
      "booking": null,
      "createdAt": "2026-07-02T09:12:00.000Z",
      "updatedAt": "2026-07-02T10:01:00.000Z",
      "__v": 0
    }
  }
  ```
</ResponseExample>

## Error Responses

<ResponseExample>
  ```json 404 Not Found theme={null}
  {
    "success": false,
    "error": "Appointment not found"
  }
  ```

  ```json 403 Forbidden theme={null}
  {
    "success": false,
    "error": "Forbidden"
  }
  ```

  ```json 400 Malformed ID theme={null}
  {
    "success": false,
    "error": "Cast to ObjectId failed for value \"abc\" (type string) at path \"_id\" for model \"Appointment\""
  }
  ```

  ```json 401 Unauthorized theme={null}
  {
    "success": false,
    "message": "Unauthorized"
  }
  ```
</ResponseExample>

<Note>
  `403 Forbidden` is returned when the appointment exists but is owned by a
  different doctor. A missing or invalid Bearer token returns `401` with a
  `message` key. A session revoked by a sign-in elsewhere returns `401` with
  `"code": "SESSION_REVOKED"`.
</Note>