AlayaCare Visit interventions API

openapi: 3.2.0
info:
  version: 1.0.17
  title: AlayaCare Scheduler Visit interventions API
  description: '**External IDs:**

    The following terms are used to reference ids that identify resources in systems external to AlayaCare:

    - client_id

    - employee_id

    - service_id

    - funder_id

    - visit_id

    - facility_id


    External IDs are required to be unique.'
  contact:
    name: AlayaCare
servers:
- url: https://homecare.alayacare.ca/ext/api/v2/scheduler
tags:
- name: Visit interventions
paths:
  /visits/{alayacare_visit_id}/interventions:
    get:
      tags:
      - Visit interventions
      summary: Get a list of interventions for a visit using it's Alayacare ID
      parameters:
      - name: alayacare_visit_id
        description: The ID of the visit
        in: path
        required: true
        schema:
          type: integer
      - name: is_required
        description: Filter for interventions that are required to finish a visit
        in: query
        required: false
        schema:
          type: boolean
      - name: has_comment
        description: Filter for interventions that have a comment or not_completed_reason_name
        in: query
        required: false
        schema:
          type: boolean
      - name: is_completed
        description: Filter for interventions that have been completed
        in: query
        required: false
        schema:
          type: boolean
      responses:
        '200':
          description: Visit details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VisitInterventionsList'
        '401':
          $ref: '#/components/responses/ErrorResponseAuthentication'
        '403':
          $ref: '#/components/responses/ErrorResponseCareplanFeatureFlagState'
        '404':
          $ref: '#/components/responses/ErrorResponseVisitNotFound'
      operationId: getVisitsByAlayacareVisitIdInterventions
      x-operation-id-source: derived
    put:
      tags:
      - Visit interventions
      summary: Link Interventions to a visit
      description: '- The full list of Interventions must be provided in the request body, it will override the previously available list.

        - Only active `interventions` on the patient active Careplan can be added

        - Only the admin user can update the visit interventions when the work session is not open.'
      parameters:
      - name: alayacare_visit_id
        description: The ID of the visit
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: A list of interventions for a visit
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VisitInterventionsList'
        '401':
          $ref: '#/components/responses/ErrorResponseAuthentication'
        '403':
          $ref: '#/components/responses/ErrorResponseCareplanFeatureFlagState'
        '404':
          $ref: '#/components/responses/ErrorResponseVisitNotFound'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VisitInterventionsUpdate'
        description: List of interventions to apply to a visit
        required: true
      operationId: putVisitsByAlayacareVisitIdInterventions
      x-operation-id-source: derived
  /visits/{alayacare_visit_id}/interventions/ivr:
    put:
      tags:
      - Visit interventions
      summary: Update interventions in a visit using it's Alayacare ID
      description: '- The full list of Interventions must be provided in the request body, it will override the previously available list.

        - User credentials MUST have an admin role.

        - (Employee internal id) MUST be informed on the url path as a param, like this: ''?completions_by={employee_internal_id}''.

        - Position should be always 0. It does not cover the interventions tries.

        - The Employee ''?completions_by={employee_internal_id} must be clocked-in to the visit.'
      parameters:
      - name: alayacare_visit_id
        description: The ID of the visit
        in: path
        required: true
        schema:
          type: integer
      - name: completions_by
        description: Employee internal id
        in: query
        required: true
        schema:
          type: integer
      responses:
        '204':
          description: Success with no content. Interventions were updated.
        '400':
          description: 'Make sure that:

            - completions_by is informed.

            - the Visit is assigned for the same (employee internal id) informed at completions_by query param.

            - the Visit is clocked-in.

            - the Employee is clocked-in to the visit.

            - position is 0.

            - intervention already exists.

            '
        '403':
          description: Make sure that your api credentials have an admin role.
        '404':
          description: Make sure that visit_id is valid.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IvrVisitInterventions'
        description: List of interventions to apply to a visit
        required: true
      operationId: putVisitsByAlayacareVisitIdInterventionsIvr
      x-operation-id-source: derived
  /visits/by_id/{visit_id}/interventions:
    get:
      tags:
      - Visit interventions
      summary: Get a list of interventions for a visit using it's Alayacare external ID
      parameters:
      - name: visit_id
        description: The ID of the visit
        in: path
        required: true
        schema:
          type: integer
      - name: is_required
        description: Filter for interventions that are required to finish a visit
        in: query
        required: false
        schema:
          type: boolean
      - name: has_comment
        description: Filter for interventions that have a comment
        in: query
        required: false
        schema:
          type: boolean
      - name: is_completed
        description: Filter for interventions that have been completed
        in: query
        required: false
        schema:
          type: boolean
      responses:
        '200':
          description: A list of interventions for a visit
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VisitInterventionsList'
        '401':
          $ref: '#/components/responses/ErrorResponseAuthentication'
        '403':
          $ref: '#/components/responses/ErrorResponseCareplanFeatureFlagState'
        '404':
          $ref: '#/components/responses/ErrorResponseVisitNotFound'
      operationId: getVisitsByIdByVisitIdInterventions
      x-operation-id-source: derived
    put:
      tags:
      - Visit interventions
      summary: Update interventions in a visit using it's Alayacare external ID
      description: '- The full list of Interventions must be provided in the request body, it will override the previously available list.

        - Only active `interventions` on the patient active careplan can be added

        - Only the admin user can update the visit interventions when the work session is not open..'
      parameters:
      - name: visit_id
        description: The ID of the visit
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: A list of interventions for a visit
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VisitInterventionsList'
        '401':
          $ref: '#/components/responses/ErrorResponseAuthentication'
        '403':
          $ref: '#/components/responses/ErrorResponseCareplanFeatureFlagState'
        '404':
          $ref: '#/components/responses/ErrorResponseVisitNotFound'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VisitInterventionsUpdate'
        description: List of interventions to apply to a visit
        required: true
      operationId: putVisitsByIdByVisitIdInterventions
      x-operation-id-source: derived
components:
  schemas:
    VisitInterventionsUpdate:
      description: Interventions
      type: object
      properties:
        interventions:
          type: string
          description: list of visit intervention ids
          example: '[1, 2, 3, 4]'
    ErrorResponse:
      description: Error response
      type: object
      properties:
        code:
          type: integer
          example: 400
          description: Response code
        message:
          type: string
          example: Invalid request
          description: Detailed error message
      required:
      - code
      - message
    Intervention:
      type: object
      properties:
        careplan_id:
          type: integer
          description: ID of the client's careplan
          example: 709
        client_id:
          type: string
          description: Alayacare client external ID
          example: external_id_client_123
        alayacare_client_id:
          type: integer
          description: Alayacare client ID
          example: 1001
        name:
          type: string
          description: Name of the intervention
          example: Blood pressure measurement
        completions:
          type: array
          description: Date-time of completion of the intervention (ISO 8601)
          items:
            type: object
        is_required:
          type: boolean
          description: Intervention is required or not to clock out of the visit
        module:
          type: string
          description: Alayacare Module to which the intervention is attached
          example: Vitals
        status:
          type: string
          description: Status of the intervention in the Careplan
          example: active
          enum:
          - draft
          - active
          - completed
          - archived
        type:
          type: string
          description: One of the types defined in the setting "Care Documentation > Care Plan Intervention Types"
          example: Nursing
    IvrVisitInterventions:
      description: A list of visit interventions
      type: object
      required:
      - intervention_id
      - completed
      - position
      properties:
        intervention_id:
          description: ID of the intervention configured in the client's careplan
          type: integer
          example: 101
        completed:
          description: Completion of the instance of the intervention in the visit
          type: boolean
          example: true
        comment:
          description: Comment entered in the visit intervention
          type:
          - string
          - 'null'
          example: Vitals recorded. Blood pressure normal.
        position:
          type: integer
          example: 1
        duration:
          description: Duration of the intervention in minutes
          type:
          - integer
          - 'null'
          example: 10
        work_session_uuid:
          description: UUID of the work session
          type:
          - string
          - 'null'
          example: uuid
    VisitInterventionsList:
      allOf:
      - $ref: '#/components/schemas/PaginatedList'
      description: Paginated list of visits
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/VisitInterventions'
    VisitInterventions:
      description: A list of visit interventions
      type: object
      properties:
        intervention_id:
          type: integer
          description: ID of the intervention configured in the client's careplan
          example: 101
        completed:
          type: boolean
          example: true
          description: Completion of the instance of the intervention in the visit
        comment:
          type: string
          description: Comment entered in the visit intervention. Will return the `not_completed_reason_name` if it is set but there is no comment
          example: Vitals recorded. Blood pressure normal.
        not_completed_reason_name:
          type: string
          description: Reason code for not completed the visit intervention
          example: client_declined
        status:
          type: string
          enum:
          - not_documented
          - not_done
          - done
          description: The status of the visit intervention
        intervention:
          $ref: '#/components/schemas/Intervention'
        position:
          type: integer
          example: 1
        created_at:
          type: string
          format: date-time
          description: Visit start time (ISO 8601)
          example: '2017-07-08T13:30:00+00:00'
        created_by:
          type: object
          description: User who created the intervention in the visit
          properties:
            id:
              type: integer
              example: 1001
            first_name:
              type: string
              example: John
            last_name:
              type: string
              example: Smith
        updated_at:
          type: string
          format: date-time
          description: Visit updated time (ISO 8601)
          example: '2018-07-08T13:30:00+00:00'
        updated_by:
          type: object
          description: User who last updated the intervention in the visit
          properties:
            id:
              type: integer
              example: 1001
            first_name:
              type: string
              example: John
            last_name:
              type: string
              example: Smith
        visit_id:
          description: External ID of the visit
          type: string
          example: external_id_123
        alayacare_visit_id:
          description: Alayacare ID of the visit
          type: integer
          example: 2384
    PaginatedList:
      description: Base model of all paginated lists
      type: object
      properties:
        count:
          type: integer
          description: Number of items in the response
          example: 1
        page:
          type: integer
          description: Current page number
          example: 1
        total_pages:
          type: integer
          description: Total number of pages available
          example: 1
        items:
          type: array
          items:
            type: object
      required:
      - count
      - page
      - total_pages
      - items
  responses:
    ErrorResponseVisitNotFound:
      description: Visit not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            code: 404
            message: Visit not found
    ErrorResponseAuthentication:
      description: Authorization required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            code: 401
            message: Authorization required.
    ErrorResponseCareplanFeatureFlagState:
      description: Authorization required due to feature flag state.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            code: 403
            message: You do not have the required permissions to perform this action.
  securitySchemes:
    basic_auth:
      type: http
      scheme: basic
      description: Basic HTTP auth over https