openapi: 3.1.0
info:
  title: PointClickCare Long-Term Care EHR Assessments Medications API
  description: PointClickCare provides EHR and care coordination APIs for long-term and post-acute care (LTPAC) facilities. APIs enable access to resident records, medication administration records, clinical assessments, care plans, and facility data for skilled nursing facilities (SNFs) and senior living communities.
  version: 2.0.0
  contact:
    name: PointClickCare Developer Support
    url: https://developer.pointclickcare.com/spa
  license:
    name: PointClickCare Terms of Service
    url: https://pointclickcare.com/legal/terms-conditions/
servers:
- url: https://api.pointclickcare.com/v2
  description: PointClickCare API
security:
- oauth2: []
tags:
- name: Medications
  description: Medication orders and administration records (MAR)
paths:
  /patients/{patientId}/medications:
    get:
      operationId: getPatientMedications
      summary: Get patient medication orders
      description: Returns active and historical medication orders for a resident.
      tags:
      - Medications
      parameters:
      - $ref: '#/components/parameters/PatientId'
      - name: status
        in: query
        description: Filter by order status
        schema:
          type: string
          enum:
          - ACTIVE
          - DISCONTINUED
          - COMPLETED
          - ON_HOLD
      - name: startDate
        in: query
        schema:
          type: string
          format: date
      - name: endDate
        in: query
        schema:
          type: string
          format: date
      responses:
        '200':
          description: Medication orders
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/MedicationOrder'
        '404':
          $ref: '#/components/responses/NotFound'
  /patients/{patientId}/medications/mar:
    get:
      operationId: getPatientMAR
      summary: Get medication administration records
      description: Returns medication administration records (MAR) documenting when medications were given.
      tags:
      - Medications
      parameters:
      - $ref: '#/components/parameters/PatientId'
      - name: startDate
        in: query
        required: true
        schema:
          type: string
          format: date
      - name: endDate
        in: query
        required: true
        schema:
          type: string
          format: date
      responses:
        '200':
          description: MAR records
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/MARRecord'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    Error:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
        details:
          type: string
    MARRecord:
      type: object
      description: A medication administration record entry
      properties:
        marId:
          type: string
        orderId:
          type: string
        patientId:
          type: string
        scheduledDatetime:
          type: string
          format: date-time
        administeredDatetime:
          type: string
          format: date-time
          nullable: true
        status:
          type: string
          enum:
          - GIVEN
          - NOT_GIVEN
          - REFUSED
          - HELD
          - PRN_GIVEN
        doseAdministered:
          type: string
          nullable: true
        notGivenReason:
          type: string
          nullable: true
        administeredBy:
          type: string
          description: Staff member NPI or ID
        notes:
          type: string
          nullable: true
    MedicationOrder:
      type: object
      description: A medication order
      properties:
        orderId:
          type: string
        patientId:
          type: string
        medicationName:
          type: string
        genericName:
          type: string
        ndc:
          type: string
          description: National Drug Code
        dose:
          type: string
          description: Dosage amount and unit (e.g., "500 mg")
        route:
          type: string
          enum:
          - ORAL
          - IV
          - IM
          - SC
          - TOPICAL
          - SUBLINGUAL
          - INHALED
          - RECTAL
          - OTHER
        frequency:
          type: string
          description: Administration frequency (e.g., "BID", "QHS", "PRN")
        status:
          type: string
          enum:
          - ACTIVE
          - DISCONTINUED
          - COMPLETED
          - ON_HOLD
        startDate:
          type: string
          format: date
        endDate:
          type: string
          format: date
          nullable: true
        orderingPhysicianNpi:
          type: string
        orderDatetime:
          type: string
          format: date-time
        indication:
          type: string
  responses:
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    PatientId:
      name: patientId
      in: path
      required: true
      description: PointClickCare resident/patient identifier
      schema:
        type: string
  securitySchemes:
    oauth2:
      type: oauth2
      description: OAuth2 authorization code flow via PointClickCare identity server
      flows:
        authorizationCode:
          authorizationUrl: https://login.pointclickcare.com/oauth2/authorize
          tokenUrl: https://login.pointclickcare.com/oauth2/token
          scopes:
            patient.read: Read patient demographics
            clinical.read: Read clinical data (vitals, medications, assessments)
            facility.read: Read facility information