AlayaCare Goals API

openapi: 3.2.0
info:
  version: 1.0.2
  title: Care Plan 2.0 Goals API
  description: "External Clinical API\n\n**Internal IDs**\nThe following terms are used to reference IDs that identify resources in AlayaCare:\n- id\n- created_by\n- client_id\n- employee_id\n- plan_id\n- diagnosis_id\n- goal_id\n- intervention_id\n\n\n**External IDs**\nThe following terms are used to reference IDs that identify resources systems external to AlayaCare:\n- external_employee_id\n- external_client_id\n- external_service_id\n\nExternal IDs are required to be unique.\nNo other assumptions are made regarding their format they are treated as strings.\n\n**Remarks**\n- All dates must be in ISO 8601 format.\n- Required fields marked with `*` cannot be null.\n  \n"
servers:
- url: https://homecare.alayacare.ca/ext/api/v2/clinical
tags:
- name: Goals
paths:
  /careplans/goal_types:
    get:
      tags:
      - Goals
      summary: Get a list of available goal types
      responses:
        '200':
          description: A list of goal types.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GoalTypeList'
        '401':
          $ref: '#/components/responses/AuthChallenge'
        '403':
          $ref: '#/components/responses/ErrorInsufficientAccess'
        '404':
          $ref: '#/components/responses/ErrorResponseGoalTypeNotFound'
  /careplans/{plan_id}/goals:
    parameters:
    - description: Send request using the Alayacare care plan ID
      name: plan_id
      in: path
      required: true
      schema:
        type: integer
    get:
      tags:
      - Goals
      summary: Get the list of goals within a care plan using the care plan ID
      description: '- Goals must be enabled in the UI at the tenant System Setting level.

        '
      responses:
        '200':
          description: A list of goals
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CarePlanGoalList'
        '401':
          $ref: '#/components/responses/AuthChallenge'
        '403':
          $ref: '#/components/responses/ErrorInsufficientAccess'
        '404':
          $ref: '#/components/responses/ErrorResponseCarePlanNotFound'
    post:
      tags:
      - Goals
      summary: Create a goal in a care plan using the care plan ID
      description: 'Create goal attached to a careplan

        - Goals must be enabled in the UI at the tenant System Setting level

        - `rank` will automatically be set to next available rank

        - Only services assigned to the client can be linked to the goal

        - `service_id` and `external_service_id` are mutually exclusive, specifying both is an invalid request.

        - Will be applied to all services defined on the client if none is selected

        - All departments will be applied if `department_id` is set to `null`

        '
      responses:
        '201':
          description: Careplan goal created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CarePlanGoal'
        '400':
          $ref: '#/components/responses/ErrorResponseInvalidRequest'
        '401':
          $ref: '#/components/responses/AuthChallenge'
        '403':
          $ref: '#/components/responses/ErrorInsufficientAccess'
        '404':
          $ref: '#/components/responses/ErrorResponseCarePlanNotFound'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCarePlanGoal'
        description: Create a goal
        required: true
  /careplans/goals/{goal_id}:
    parameters:
    - description: ID of goal
      name: goal_id
      in: path
      required: true
      schema:
        type: integer
    get:
      tags:
      - Goals
      summary: Get a specific goal by goal ID
      responses:
        '200':
          description: The goal defined by goal ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CarePlanGoal'
        '400':
          $ref: '#/components/responses/ErrorResponseInvalidRequest'
        '401':
          $ref: '#/components/responses/AuthChallenge'
        '403':
          $ref: '#/components/responses/ErrorInsufficientAccess'
        '404':
          $ref: '#/components/responses/ErrorResponseGoalNotFound'
    put:
      tags:
      - Goals
      summary: Update a specific goal using the goal ID
      description: 'Update a goal attached to a careplan

        - Only services assigned to the client can be linked to the goal.

        - `service_id` and `external_service_id` are mutually exclusive, specifying both is an invalid request.

        '
      responses:
        '204':
          description: Goal succesfully updated
        '400':
          $ref: '#/components/responses/ErrorResponseInvalidRequest'
        '401':
          $ref: '#/components/responses/AuthChallenge'
        '403':
          $ref: '#/components/responses/ErrorInsufficientAccess'
        '404':
          $ref: '#/components/responses/ErrorResponseGoalNotFound'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCarePlanGoal'
        description: update the goal (goal_id)
        required: true
    delete:
      tags:
      - Goals
      summary: Delete a specific goal using the goal ID
      description: '- Only goals in `draft` status can be deleted

        '
      responses:
        '204':
          description: Goal successfully deleted
        '400':
          $ref: '#/components/responses/ErrorResponseInvalidUpdateForRootItemType'
        '401':
          $ref: '#/components/responses/AuthChallenge'
        '403':
          $ref: '#/components/responses/ErrorInsufficientAccess'
        '404':
          $ref: '#/components/responses/ErrorResponseGoalNotFound'
  /careplans/goals/{goal_id}/status/archived:
    parameters:
    - description: ID of goal with changed status
      name: goal_id
      in: path
      required: true
      schema:
        type: integer
    put:
      tags:
      - Goals
      summary: Change the status of a specific goal to archived
      description: '- A goal can only be archived if the care plan is in active status.

        '
      responses:
        '204':
          description: Successfully changed status of goal to archived
        '400':
          $ref: '#/components/responses/ErrorResponseInvalidArchivalForRootItemType'
        '401':
          $ref: '#/components/responses/AuthChallenge'
        '403':
          $ref: '#/components/responses/ErrorInsufficientAccess'
        '404':
          $ref: '#/components/responses/ErrorResponseGoalNotFound'
  /careplans/goals/{goal_id}/status/completed:
    parameters:
    - description: ID of goal with changed status
      name: goal_id
      in: path
      required: true
      schema:
        type: integer
    put:
      tags:
      - Goals
      summary: Change the status of a specific goal to completed
      description: '- A goal can only be completed if the care plan is in active status.

        '
      responses:
        '204':
          description: Successfully changed status of goal to archived
        '400':
          $ref: '#/components/responses/ErrorResponseInvalidRequest'
        '401':
          $ref: '#/components/responses/AuthChallenge'
        '403':
          $ref: '#/components/responses/ErrorInsufficientAccess'
        '404':
          $ref: '#/components/responses/ErrorResponseGoalNotFound'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - end_date
              - completion_notes
              properties:
                end_date:
                  type: string
                  example: '2020-02-01'
                completion_note:
                  type: string
                  example: We did it! High five!
        description: object to be sent at completion
        required: true
components:
  responses:
    ErrorResponseInvalidUpdateForRootItemType:
      description: The root item type cannot be deleted once it has been completed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            status_code: 400
            message: The root item type cannot be deleted in current status
    ErrorResponseGoalNotFound:
      description: Goal not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            status_code: 404
            message: Goal not found
    AuthChallenge:
      description: Authentication required.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            status_code: 401
            message: Please verify your access level for this url.
    ErrorResponseInvalidArchivalForRootItemType:
      description: The root item type cannot be archived once it has been completed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            status_code: 400
            message: The root item type cannot be archived once it has been completed
    ErrorResponseInvalidRequest:
      description: Invalid data submitted for item creation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            status_code: 400
            message: The field 'start_date' is required.
    ErrorResponseGoalTypeNotFound:
      description: Field 'goal_type' is invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            status_code: 404
            message: Field 'goal_type' is invalid
    ErrorResponseCarePlanNotFound:
      description: Care plan not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            status_code: 404
            message: Care plan not found
    ErrorInsufficientAccess:
      description: You do not have the required permissions to perform this action
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            status_code: 403
            message: Access required
  schemas:
    ErrorResponse:
      description: Error response
      type: object
      properties:
        status_code:
          type: integer
          description: Response code
        message:
          type: string
          description: Detailed error message
      required:
      - code
      - message
    EntitySummaryList:
      type: array
      items:
        $ref: '#/components/schemas/EntitySummary'
    GoalProgress:
      description: Goal progress information
      properties:
        comment:
          type: string
        percentage:
          type: integer
        completed:
          type: boolean
      example:
        comment: That was hard
        completed: false
    EntitySummary:
      type: object
      required:
      - id
      - name
      properties:
        id:
          type: integer
          description: AlayaCare entity ID
          example: 1001
        name:
          type: string
          description: Alayacare entity name
          example: entity name
    ServiceList:
      type: array
      items:
        $ref: '#/components/schemas/ServiceDetails'
    ServiceDetails:
      description: Service details
      type:
      - object
      - 'null'
      properties:
        id:
          type: integer
          description: AlayaCare service ID
          example: 1001
        external_id:
          type:
          - string
          - 'null'
          description: External service ID
          example: sor_service_id_1
    CarePlanGoal:
      description: Care plan goal
      type: object
      properties:
        id:
          description: Care Plan Goal ID
          type: integer
          example: 100
        plan_id:
          description: Care Plan ID
          type: integer
          example: 345
        plan_name:
          description: Care plan name
          type: string
          example: 'Episode #4'
        name:
          description: A title of care plan goal
          type: string
          example: Title example
        start_date:
          description: A start date of goal
          type: string
          example: '2018-01-10'
        target_end_date:
          description: A end date of goal
          type: string
          example: '2018-01-10'
        description:
          description: A description of care plan goal
          type: string
          example: Description of goal
        is_primary:
          description: Define that this goal is primary
          type: boolean
          example: true
        rank:
          description: Used for ordering of goals in the list. The smaller, the higher ranked will the diagnosis be returned.
          type: integer
          example: 0
        department:
          $ref: '#/components/schemas/EntitySummary'
        type:
          type: string
          description: Goal Type
          example: Desires/Motivations
        progress_type:
          $ref: '#/components/schemas/GoalMethod'
        last_updated_progress:
          $ref: '#/components/schemas/GoalProgress'
        status:
          $ref: '#/components/schemas/CareplanItemStatus'
        services:
          description: The list of services that are linked to the goal
          $ref: '#/components/schemas/ServiceList'
        tags:
          description: The list of tags that are linked to the goal
          $ref: '#/components/schemas/EntitySummaryList'
        diagnoses:
          description: The list of diagnoses that are linked to the goal
          $ref: '#/components/schemas/EntitySummaryList'
        updated_at:
          description: Datetime for the last update for this goal
          type: string
          example: '2018-01-23T23:56:13+00:00'
        updated_by:
          $ref: '#/components/schemas/User'
        created_at:
          description: Datetime for the creation of this goal
          type: string
          example: '2017-12-20T23:56:13+00:00'
        created_by:
          $ref: '#/components/schemas/User'
        completed_at:
          description: Datetime when the goal was completed
          type:
          - string
          - 'null'
          example: '2017-12-20T23:56:13+00:00'
        completed_by:
          $ref: '#/components/schemas/User'
        completion_note:
          description: Completion note of the goal
          type:
          - string
          - 'null'
    User:
      description: User id, first and last names
      type: object
      properties:
        id:
          description: The id of user
          type: integer
          example: 5
        external_id:
          description: The id of user
          type: string
          example: sor_external_id_1
    GoalType:
      description: List of goal types
      type: object
      example:
      - Nursing
      - Physiotherapy
      - Occupational Therapy
      - Speech Therapy
      - Personal Care
    UpdateCarePlanGoal:
      description: JSON schema for creating care plan diagnosis
      type: object
      properties:
        name:
          description: A title of care plan goal
          type: string
          example: Example goal
        start_date:
          description: A start date of goal
          type: string
          example: '2018-01-10'
        end_date:
          description: A end date of goal
          type: string
          example: '2018-01-10'
        description:
          description: A description of care plan goal
          type: string
          example: Description of goal
        is_primary:
          description: Define that this goal is primary
          type: boolean
          example: true
        rank:
          description: Used for ordering of goals in list. The smaller, the higher. Can be the number of place in the list of goals in care plan
          type: integer
          example: 0
        type:
          $ref: '#/components/schemas/GoalType'
        progress_type:
          $ref: '#/components/schemas/GoalMethod'
        department_id:
          description: The ID of selected department
          type:
          - integer
          - 'null'
          example: 1
        service_ids:
          description: The list of service ID's that is linked to created diagnosis.Only services assigned to the client can be linked to the diagnosis.
          type: array
          items:
            type: integer
          example:
          - 1
          - 4
          - 6
        tag_ids:
          description: The list of tag ID's that is linked to created diagnosis
          type: array
          items:
            type: integer
          example:
          - 2
          - 4
          - 8
        diagnosis_ids:
          description: 'The list of diagnosis IDs that is linked to created goal. '
          type: array
          items:
            type: integer
          example:
          - 2
          - 4
          - 8
    CreateCarePlanGoal:
      description: JSON schema for creating care plan goal
      type: object
      required:
      - name
      - start_date
      - type
      - progress_type
      - department_id
      - is_primary
      properties:
        name:
          description: Title of the care plan goal
          type: string
          example: Example goal
        start_date:
          description: Start date of the goal
          type: string
          example: '2018-01-10'
        end_date:
          description: End date of the goal
          type: string
          example: '2018-01-10'
        description:
          description: Description of the care plan goal
          type: string
          example: Description of goal
        is_primary:
          description: Define that this goal is primary
          type: boolean
          example: true
        type:
          type: string
          description: Goal Type
          example: Desires/Motivations
        progress_type:
          $ref: '#/components/schemas/GoalMethod'
        department_id:
          description: The ID of selected department
          type:
          - integer
          - 'null'
          example: 1
        service_ids:
          description: The list of service ID's that is linked to created diagnosis.Only services assigned to the client can be linked to the diagnosis.
          type: array
          items:
            type: integer
          example:
          - 1
          - 4
          - 6
        external_service_ids:
          description: The list of service external ID's that is linked to a diagnosis. Only services assigned to the client can be linked to the diagnosis.
          type: array
          items:
            type: string
          example:
          - sor_service_id_1
          - sor_service_id_2
          - sor_service_id_3
        tag_ids:
          description: The list of tag ID's that is linked to created diagnosis
          type: array
          items:
            type: integer
          example:
          - 2
          - 4
          - 8
        diagnosis_ids:
          description: The list of diagnosis ID that is linked to created goal. Only giagnoses available in the careplan can be assigned to the goal.
          type: array
          items:
            type: integer
          example:
          - 2
          - 4
          - 8
    GoalMethod:
      description: Progress tracking method of goal
      type: string
      enum:
      - none
      - per_visits
      - percentage
      example: percentage
    CareplanItemStatus:
      type: string
      enum:
      - active
      - completed
      - archived
    GoalTypeList:
      description: List of goal types
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/GoalType'
    CarePlanGoalList:
      description: The list of goals
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/CarePlanGoal'
  securitySchemes:
    basic_auth:
      type: http
      scheme: basic
      description: Basic HTTP auth over https