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

# Retrieve an appointment



## OpenAPI

````yaml GET /appointments/{appointment}
openapi: 3.1.0
info:
  title: Caspen
  version: 0.0.1
servers:
  - url: https://api.caspen.com/v1
    description: Production
security: []
paths:
  /appointments/{appointment}:
    get:
      tags:
        - Appointment
      operationId: appointment.show
      parameters:
        - name: appointment
          in: path
          required: true
          description: The appointment ID
          schema:
            type: string
      responses:
        '200':
          description: '`AppointmentResource`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppointmentResource'
        '401':
          $ref: '#/components/responses/AuthenticationException'
        '403':
          $ref: '#/components/responses/AuthorizationException'
        '404':
          $ref: '#/components/responses/ModelNotFoundException'
        '422':
          $ref: '#/components/responses/ValidationException'
components:
  schemas:
    AppointmentResource:
      type: object
      properties:
        id:
          type: string
          description: The appointment's unique identifier.
          examples:
            - app_01HQFQ9QWTNNPY58FZ8CB3FWWK
        location_id:
          type: string
          description: The location identifier where the appointment takes place.
          examples:
            - loc_01HQFQ9QWTNNPY58FZ8CB3FWWK
        practitioner_id:
          type: string
          description: The practitioner identifier who provides the service.
          examples:
            - pra_01HQFQ9QWTNNPY58FZ8CB3FWWK
        service_id:
          type: string
          description: The service identifier being provided.
          examples:
            - ser_01HQFQ9QWTNNPY58FZ8CB3FWWK
        service_price:
          type: integer
          description: The snapshotted base price from the service at time of booking.
          examples:
            - 12000
        price:
          type: integer
          description: >-
            The calculated total price (service_price × client count if
            price_per_client).
          examples:
            - 24000
        price_unit:
          $ref: '#/components/schemas/ServicePriceUnit'
          description: The snapshotted price unit from the service at time of booking.
          examples:
            - hourly
        price_per_client:
          type: boolean
          description: Whether the price is per client (true) or per appointment (false).
          examples:
            - false
        travel:
          type: boolean
          description: Whether billable travel time applies to this appointment.
          examples:
            - true
        travel_name:
          type:
            - string
            - 'null'
          description: The snapshotted travel line item name.
          examples:
            - Travel
        travel_price:
          type:
            - integer
            - 'null'
          description: The snapshotted flat travel price in cents.
          examples:
            - 5000
        travel_before_duration:
          type:
            - integer
            - 'null'
          description: The billable travel time before the appointment in minutes.
          examples:
            - 15
        travel_after_duration:
          type:
            - integer
            - 'null'
          description: The billable travel time after the appointment in minutes.
          examples:
            - 15
        travel_address:
          type:
            - string
            - 'null'
          description: The travel destination address (single-line, free text).
          examples:
            - 123 Sample Street, Sydney NSW 2000, Australia
        travel_expenses:
          type: array
          description: The travel expense line items (when loaded).
          items:
            $ref: '#/components/schemas/AppointmentTravelExpenseResource'
        transports:
          type: array
          description: The transport line items (when loaded).
          items:
            $ref: '#/components/schemas/AppointmentTransportResource'
        appointment_clients:
          type: array
          description: The appointment clients (when loaded).
          items:
            $ref: '#/components/schemas/AppointmentClientResource'
        starts_at:
          type: string
          description: The appointment start time (ISO 8601).
          examples:
            - '2024-01-01T10:00:00Z'
        ends_at:
          type: string
          description: The appointment end time (ISO 8601).
          examples:
            - '2024-01-01T11:00:00Z'
        duration:
          type: integer
          description: The appointment duration in minutes.
          examples:
            - 60
        status:
          $ref: '#/components/schemas/AppointmentStatus'
          description: The appointment status.
          examples:
            - pending
        room_id:
          type:
            - string
            - 'null'
          description: The room identifier where the appointment takes place.
          examples:
            - rom_01HQFQ9QWTNNPY58FZ8CB3FWWK
        vehicle_id:
          type:
            - string
            - 'null'
          description: The vehicle identifier if transportation is involved.
          examples:
            - veh_01HQFQ9QWTNNPY58FZ8CB3FWWK
        resource_ids:
          type: array
          description: The IDs of resources required for this appointment.
          examples:
            - - res_01HYHYQHA682J0K1RW7B2HVA9F
              - res_01HYHYW37MTYJPMT5JV4RN99GK
          items:
            type: string
        note:
          type:
            - string
            - 'null'
          description: The appointment note.
          examples:
            - Client requested morning appointment.
        cancellation_reason_id:
          type:
            - string
            - 'null'
          description: The cancellation reason identifier if cancelled.
          examples:
            - cnr_01HQFQ9QWTNNPY58FZ8CB3FWWK
        cancellation_note:
          type:
            - string
            - 'null'
          description: The cancellation note if cancelled.
          examples:
            - Client had to travel unexpectedly.
        cancelled_at:
          type:
            - string
            - 'null'
          description: When the appointment was cancelled (ISO 8601).
          examples:
            - '2024-01-01T08:00:00Z'
        archived_at:
          type:
            - string
            - 'null'
          description: When the appointment was archived (ISO 8601).
          examples:
            - '2024-01-01T08:00:00Z'
        created_at:
          type: string
          description: The timestamp when the appointment was created (ISO 8601).
          examples:
            - '2024-01-01T12:00:00Z'
      title: AppointmentResource
    ServicePriceUnit:
      type: string
      enum:
        - hourly
        - fixed
      title: ServicePriceUnit
    AppointmentTravelExpenseResource:
      type: object
      properties:
        id:
          type: string
          description: The travel expense's unique identifier.
          examples:
            - ate_01HQFQ9QWTNNPY58FZ8CB3FWWK
        name:
          type:
            - string
            - 'null'
          description: The line item name.
          examples:
            - Mileage
        price:
          type:
            - integer
            - 'null'
          description: The price per unit in cents.
          examples:
            - 85
        price_unit:
          anyOf:
            - $ref: '#/components/schemas/ServiceExpensePriceUnit'
              description: The unit the price is charged per.
              examples:
                - km
            - type: 'null'
        quantity:
          type:
            - string
            - 'null'
          description: The quantity of units.
          examples:
            - '42.50'
      title: AppointmentTravelExpenseResource
    AppointmentTransportResource:
      type: object
      properties:
        id:
          type: string
          description: The transport's unique identifier.
          examples:
            - atr_01HQFQ9QWTNNPY58FZ8CB3FWWK
        name:
          type:
            - string
            - 'null'
          description: The line item name.
          examples:
            - Client transport
        price:
          type:
            - integer
            - 'null'
          description: The price per unit in cents.
          examples:
            - 85
        price_unit:
          anyOf:
            - $ref: '#/components/schemas/ServiceExpensePriceUnit'
              description: The unit the price is charged per.
              examples:
                - km
            - type: 'null'
        quantity:
          type:
            - string
            - 'null'
          description: The quantity of units.
          examples:
            - '12.00'
      title: AppointmentTransportResource
    AppointmentClientResource:
      type: object
      properties:
        id:
          type: string
          description: The appointment client's unique identifier.
          examples:
            - apc_01HQFQ9QWTNNPY58FZ8CB3FWWK
        appointment_id:
          type: string
          description: The appointment identifier.
          examples:
            - apt_01HQFQ9QWTNNPY58FZ8CB3FWWK
        client_id:
          type: string
          description: The client identifier.
          examples:
            - cli_01HQFQ9QWTNNPY58FZ8CB3FWWK
        case_id:
          type:
            - string
            - 'null'
          description: The case identifier for this client's booking.
          examples:
            - cas_01HQFQ9QWTNNPY58FZ8CB3FWWK
        client_package_id:
          type:
            - string
            - 'null'
          description: The client package identifier if this booking uses a package.
          examples:
            - cpk_01HQFQ9QWTNNPY58FZ8CB3FWWK
        status:
          anyOf:
            - $ref: '#/components/schemas/AppointmentClientStatus'
              description: The attendance status of the client.
              examples:
                - arrived
            - type: 'null'
        do_not_invoice:
          type: boolean
          description: Whether this client should not be invoiced for this appointment.
          examples:
            - false
        note:
          type:
            - string
            - 'null'
          description: Notes specific to this client's appointment.
          examples:
            - Client requested extra time
        confirmed:
          type: boolean
          description: Whether the client has confirmed their attendance.
          examples:
            - true
        confirmed_at:
          type:
            - string
            - 'null'
          description: When the client confirmed their attendance (ISO 8601).
          examples:
            - '2024-01-01T12:00:00Z'
        cancellation_reason_id:
          type:
            - string
            - 'null'
          description: The cancellation reason identifier if cancelled.
          examples:
            - cnr_01HQFQ9QWTNNPY58FZ8CB3FWWK
        cancellation_note:
          type:
            - string
            - 'null'
          description: Additional notes about the cancellation.
          examples:
            - Client called to cancel
        cancelled_at:
          type:
            - string
            - 'null'
          description: When this client's appointment was cancelled (ISO 8601).
          examples:
            - '2024-01-01T12:00:00Z'
        starts_at:
          type: string
          description: The appointment start time (ISO 8601).
          examples:
            - '2024-01-01T09:00:00Z'
        ends_at:
          type: string
          description: The appointment end time (ISO 8601).
          examples:
            - '2024-01-01T10:00:00Z'
        created_at:
          type: string
          description: The timestamp when this record was created (ISO 8601).
          examples:
            - '2024-01-01T12:00:00Z'
        updated_at:
          type: string
          description: The timestamp when this record was last updated (ISO 8601).
          examples:
            - '2024-01-01T12:00:00Z'
      title: AppointmentClientResource
    AppointmentStatus:
      type: string
      enum:
        - pending
        - arrived
        - missed
        - cancelled
      title: AppointmentStatus
    ServiceExpensePriceUnit:
      type: string
      enum:
        - km
        - mile
        - each
      title: ServiceExpensePriceUnit
    AppointmentClientStatus:
      type: string
      enum:
        - pending
        - arrived
        - missed
        - cancelled
      title: AppointmentClientStatus
  responses:
    AuthenticationException:
      description: Unauthenticated
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                description: Error overview.
            required:
              - message
    AuthorizationException:
      description: Authorization error
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                description: Error overview.
            required:
              - message
    ModelNotFoundException:
      description: Not found
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                description: Error overview.
            required:
              - message
    ValidationException:
      description: Validation error
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                description: Errors overview.
              errors:
                type: object
                description: A detailed description of each field that failed validation.
                additionalProperties:
                  type: array
                  items:
                    type: string
            required:
              - message
              - errors

````