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

# List a patient's Passport appointments

> The patient's upcoming or past appointments. Returns the first page only: `pagination.after` is `PAGING_NOT_SUPPORTED` when the list may have more items than `limit`, and `null` when the list is complete. Sending `cursor` answers 400 until paging is supported.

**Availability:** Patient Passport answers only for organizations enabled for it. Any other organization gets 403 `ORG_NOT_ENABLED`; ask your OLH implementation contact to enable yours.

Service tokens only: a user token gets 403 `FORBIDDEN`. Every response carries `Cache-Control: no-store`.

**Permissions:** `appointments:read`



## OpenAPI

````yaml /openapi.json get /passport/appointments
openapi: 3.1.0
info:
  title: OpenLoop API
  version: 0.1.0
  description: >-
    Unified reference for the OpenLoop Patient (clinical) and Payments & Revenue
    APIs.
servers:
  - url: https://api.openloophealth.com/v0.1
    description: Production partner edge
  - url: https://api-staging.openloophealth.com/v0.1
    description: Staging partner edge (sandbox credentials)
security: []
paths:
  /passport/appointments:
    get:
      tags:
        - Patient Passport
      summary: List a patient's Passport appointments
      description: >-
        The patient's upcoming or past appointments. Returns the first page
        only: `pagination.after` is `PAGING_NOT_SUPPORTED` when the list may
        have more items than `limit`, and `null` when the list is complete.
        Sending `cursor` answers 400 until paging is supported.


        **Availability:** Patient Passport answers only for organizations
        enabled for it. Any other organization gets 403 `ORG_NOT_ENABLED`; ask
        your OLH implementation contact to enable yours.


        Service tokens only: a user token gets 403 `FORBIDDEN`. Every response
        carries `Cache-Control: no-store`.


        **Permissions:** `appointments:read`
      parameters:
        - name: patient_id
          in: query
          required: true
          schema:
            type: string
            format: uuid
          description: >-
            The patient's `id` in the Partner API, the same `id` that `GET
            /patients` returns. Anything that isn't a UUID answers 404.
        - name: scope
          in: query
          required: false
          schema:
            type: string
            enum:
              - upcoming
              - past
            default: upcoming
          description: Which appointments to return.
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 50
            default: 20
          description: Maximum number of items to return.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/PassportAppointment'
                  pagination:
                    $ref: '#/components/schemas/PassportPagination'
                  request_id:
                    type: string
                required:
                  - items
                  - pagination
                  - request_id
        '400':
          description: '`BAD_REQUEST`: a `cursor` was sent. Paging isn''t supported yet.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: >-
            Missing or invalid access token. The Partner API answers this before
            the request reaches Patient Passport.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: >-
            `error_code` says why: `FORBIDDEN` (the token lacks
            `appointments:read`, or isn't a partner service token),
            `ORG_NOT_MAPPED` (your organization has no Healthie organization
            linked) or `ORG_NOT_ENABLED` (your organization isn't enabled for
            Patient Passport).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: >-
            `PATIENT_NOT_FOUND`: no patient with that id in your organization,
            or `patient_id` isn't a UUID. The cases are deliberately
            indistinguishable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: >-
            `PATIENT_IDENTITY_UNRESOLVED`: the patient can't be matched to a
            single Patient Passport record. Quote `request_id` to support.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: >-
            `VALIDATION_ERROR`: `patient_id` is missing, `scope` isn't
            `upcoming` or `past`, or `limit` is outside 1 to 50.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: >-
            Too many requests. The route is throttled at 100 requests per
            second, with bursts of 120. Back off and retry.
        '500':
          description: >-
            `UNHANDLED_EXCEPTION`: something failed that names no cause. Quote
            `request_id` to support.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: >-
            `UPSTREAM_UNAVAILABLE`: patient data is temporarily unavailable.
            Safe to retry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '504':
          description: Patient Passport didn't answer within 29 seconds. Safe to retry.
      security:
        - serviceToken:
            - appointments:read
components:
  schemas:
    PassportAppointment:
      type: object
      properties:
        start_at:
          type: string
          format: date-time
        end_at:
          type: string
          format: date-time
        appointment_type:
          type: object
          properties:
            name:
              type: string
          required:
            - name
        contact_type:
          type:
            - string
            - 'null'
        status:
          type: string
        display_status:
          type: string
        program_upi:
          type:
            - string
            - 'null'
        program_name:
          type:
            - string
            - 'null'
        synced_at:
          type: string
          format: date-time
      required:
        - start_at
        - end_at
        - appointment_type
        - status
        - display_status
        - synced_at
    PassportPagination:
      type: object
      description: >-
        Paging state of a Patient Passport list. Paging isn't supported yet, so
        a list is always its first page.
      properties:
        after:
          type:
            - string
            - 'null'
          description: >-
            `null` when the list is complete. `PAGING_NOT_SUPPORTED` when the
            list may have more items than `limit`: it is a marker, not a cursor,
            and sending it back as `cursor` answers 400.
        before:
          type:
            - string
            - 'null'
          description: Always `null`.
        items:
          type: integer
          description: Number of items on this page.
      required:
        - after
        - before
        - items
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
            error_code:
              type: string
          required:
            - message
            - error_code
        request_id:
          type: string
      required:
        - error
        - request_id
  securitySchemes:
    serviceToken:
      type: oauth2
      description: >-
        Service (M2M) access token issued by POST /auth/token using the
        client_credentials grant. Required scopes, where known, are listed on
        each operation below.
      flows:
        clientCredentials:
          tokenUrl: https://api.openloophealth.com/v0.1/auth/token
          scopes: {}

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.