AlayaCare Employee Skills API

openapi: 3.2.0
info:
  title: AlayaCare Skills Employee Skills API
  version: 1.0.0
  description: '**AlayaCare IDs:**

    The following terms are used to reference IDs that identify resources in AlayaCare:

    - employee_id

    - skill_id


    **External IDs**

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

    - external_employee_id


    External IDs are required to be unique.

    No other assumptions are made regarding their format they are treated as strings.


    **Remarks**

    - All dates must be in ISO 8601 format with timezone data


    **Skills Considerations**

    - The skill master list and employee skills management are supported by this API

    - Client specific skills are not supported by this API

    '
servers:
- url: https://homecare.alayacare.ca/ext/api/v2/employees
tags:
- name: Employee Skills
paths:
  /employees/{employee_id}/skills:
    parameters:
    - name: employee_id
      description: The AlayaCare ID of a employee
      in: path
      required: true
      schema:
        type: integer
    get:
      tags:
      - Employee Skills
      summary: Get a list of an employee's skills by the employee AlayaCare ID
      parameters:
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/count'
      - $ref: '#/components/parameters/filter'
      - $ref: '#/components/parameters/category_id'
      responses:
        200:
          description: A list of an employee skills
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmployeeSkillList'
        401:
          $ref: '#/components/responses/ErrorResponseAuthentication'
        404:
          $ref: '#/components/responses/ErrorResponseEmployeeNotFound'
    post:
      tags:
      - Employee Skills
      summary: Create an employee specific skill by the employee AlayaCare ID
      description: "- Skill fields (`acquired_date`, `expired_date`,  `label_1` and `label_2`) should only be included if they are configured on the skill master list.\n- `comment` can only be set if one or more skill field is configured on the skill master list. \n- Employee must have a status of active, pending, on hold, suspended, or applicant to have skills assigned.\n"
      responses:
        201:
          description: An employee specific skill
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmployeeSkillDetails'
        401:
          $ref: '#/components/responses/ErrorResponseAuthentication'
        400:
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: 400
                message: Field skill_id is required
        404:
          $ref: '#/components/responses/ErrorResponseEmployeeNotFound'
        409:
          description: Conflict
          content:
            application/json:
              example:
                code: 409
                message: 'Branch conflict: Skill cannot be assigned to the employee'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmployeeSkillCreate'
        required: true
  /employees/{employee_id}/skills/{skill_id}:
    parameters:
    - name: employee_id
      description: The AlayaCare ID of an employee
      in: path
      required: true
      schema:
        type: integer
    - name: skill_id
      description: The AlayaCare ID of a skill
      in: path
      required: true
      schema:
        type: integer
    get:
      tags:
      - Employee Skills
      summary: Get an employee's skills details by the employee AlayaCare ID
      responses:
        '200':
          description: Skill details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmployeeSkillDetails'
        '401':
          $ref: '#/components/responses/ErrorResponseAuthentication'
        '404':
          $ref: '#/components/responses/ErrorResponseEmployeeSkillNotFound'
    put:
      tags:
      - Employee Skills
      summary: Update an employee's skill by the employee AlayaCare ID
      description: "- Skill fields sent in the payload will overwrite existing fields on the employee skill.\n- Skill fields (`acquired_date`, `expired_date`,  `label_1` and `label_2`) should only be included if they are configured on the skill master list.\n- `comment` can only be set if one or more skill field is configured on the skill master list. \n- Employee must have a status of active, pending, on hold, suspended, or applicant to have skills assigned.\n"
      responses:
        200:
          description: Employee skill updated successfuly
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmployeeSkillDetails'
        400:
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: 400
                message: Custom field name invalid.
        401:
          $ref: '#/components/responses/ErrorResponseAuthentication'
        404:
          $ref: '#/components/responses/ErrorResponseEmployeeSkillNotFound'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmployeeSkillUpdate'
        description: Employe skill data to update
        required: true
    delete:
      tags:
      - Employee Skills
      summary: Remove a employee's skill by the employee AlayaCare ID
      description: '- Employee must have a status of active, pending, on hold, suspended, or applicant to have skills unassigned.

        '
      responses:
        204:
          description: Skill successfully deleted
        401:
          $ref: '#/components/responses/ErrorResponseAuthentication'
        404:
          $ref: '#/components/responses/ErrorResponseEmployeeSkillNotFound'
  /employees/by_id/{external_employee_id}/skills:
    parameters:
    - name: external_employee_id
      description: The external ID of an employee
      in: path
      required: true
      schema:
        type: string
    get:
      tags:
      - Employee Skills
      summary: Get a list of an employee's skills by the employee external ID
      parameters:
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/count'
      - $ref: '#/components/parameters/filter'
      - $ref: '#/components/parameters/category_id'
      responses:
        200:
          description: A list of an employee skills
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmployeeSkillList'
        401:
          $ref: '#/components/responses/ErrorResponseAuthentication'
        404:
          $ref: '#/components/responses/ErrorResponseEmployeeNotFound'
    post:
      tags:
      - Employee Skills
      summary: Create an employee specific skill by the employee external ID
      description: "- Skill fields (`acquired_date`, `expired_date`,  `label_1` and `label_2`) should only be included if they are configured on the skill master list.\n- `comment` can only be set if one or more skill field is configured on the skill master list. \n- Employee must have a status of active, pending, on hold, suspended, or applicant to have skills assigned.\n"
      responses:
        201:
          description: An employee specific skill
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmployeeSkillDetails'
        401:
          $ref: '#/components/responses/ErrorResponseAuthentication'
        400:
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: 400
                message: Field skill_id is required
        404:
          $ref: '#/components/responses/ErrorResponseEmployeeNotFound'
        409:
          description: Conflict
          content:
            application/json:
              example:
                code: 409
                message: 'Branch conflict: Skill cannot be assigned to the employee'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmployeeSkillCreate'
        required: true
  /employees/by_id/{external_employee_id}/skills/{skill_id}:
    parameters:
    - name: external_employee_id
      description: External ID of an employee
      in: path
      required: true
      schema:
        type: integer
    - name: skill_id
      description: ID of the employee's skill
      in: path
      required: true
      schema:
        type: string
    get:
      tags:
      - Employee Skills
      summary: Get an employee's skills details by the employee external ID
      responses:
        '200':
          description: Skill details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmployeeSkillDetails'
        '401':
          $ref: '#/components/responses/ErrorResponseAuthentication'
        '404':
          $ref: '#/components/responses/ErrorResponseEmployeeSkillNotFound'
    put:
      tags:
      - Employee Skills
      summary: Update an employee's skill by the employee external ID
      description: '- Skill fields sent in the payload will overwrite existing fields on the employee skill.

        - Skill fields (`acquired_date`, `expired_date`,  `label_1` and `label_2`) should only be included if they are configured on the skill master list.

        - `comment` can only be set if one or more skill field is configured on the skill master list.

        - Employee must have a status of active, pending, on hold, suspended, or applicant to have skills assigned.

        '
      responses:
        200:
          description: Employee skill updated successfuly
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmployeeSkillDetails'
        400:
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: 400
                message: Custom field name invalid.
        401:
          $ref: '#/components/responses/ErrorResponseAuthentication'
        404:
          $ref: '#/components/responses/ErrorResponseEmployeeSkillNotFound'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmployeeSkillUpdate'
        description: Employe skill data to update
        required: true
    delete:
      tags:
      - Employee Skills
      summary: Remove a employee's skill by the employee external ID
      description: '- Employee must have a status of active, pending, on hold, suspended, or applicant to have skills unassigned.

        '
      responses:
        204:
          description: Skill successfully deleted
        401:
          $ref: '#/components/responses/ErrorResponseAuthentication'
        404:
          $ref: '#/components/responses/ErrorResponseEmployeeSkillNotFound'
components:
  schemas:
    EmployeeSkillField:
      description: Field(s) configured in the skill
      type: object
      required:
      - acquired_date
      - expired_date
      - label_1
      - label_2
      properties:
        acquired_date:
          type: string
          format: date
          description: The skill field `acquired_date` value. For `type = Date` format must be ISO 8601
          example: '2018-07-08T00:00:00+00:00'
        expired_date:
          type: string
          format: date
          description: The skill field `expired_date` value. For `type = Date` format must be ISO 8601
          example: '2020-07-08T00:00:00+00:00'
        label_1:
          type: string
          description: The skill field `label_1` value.
          example: X3S J1M
        label_2:
          type: string
          description: The skill field `label_2` value.
          example: Volkswagen
    ErrorResponse:
      description: Error response
      type: object
      properties:
        code:
          type: integer
          description: Response code
        message:
          type: string
          description: Detailed error message
      required:
      - code
      - message
    SkillCategory:
      description: Skill Category
      type: object
      required:
      - id
      - name
      properties:
        id:
          type: integer
          description: ID of the skill category
          example: 1
        name:
          type: string
          description: Name of the skill category
          example: Languages
    EmployeeSkillList:
      allOf:
      - $ref: '#/components/schemas/PaginatedList'
      description: 'List of skills

        '
      type: object
      properties:
        items:
          type: array
          items:
            allOf:
            - $ref: '#/components/schemas/EmployeeSkillDetails'
    EmployeeSkillCreate:
      type: object
      required:
      - skill_id
      properties:
        skill_id:
          type: integer
          description: Id of the skill to assign to the employee
          example: 123
        comment:
          type: string
          description: Free text comment on the employee specific skill
          example: This employee has reached a proficiency level in this skill
        fields:
          $ref: '#/components/schemas/EmployeeSkillField'
    EmployeeSkillUpdate:
      type: object
      properties:
        comment:
          type: string
          description: Free text comment on the employee specific skill
          example: This employee has reached a proficiency level in this skill
        fields:
          $ref: '#/components/schemas/EmployeeSkillField'
    BranchSummary:
      description: Branch summary
      type: object
      properties:
        id:
          type: integer
          description: ID of the branch
          example: 1
        name:
          type: string
          description: Name of the branch
          example: Headquarters
    EmployeeSkillDetails:
      description: AlayaCare employee skill attributes
      type: object
      required:
      - skill_id
      - name
      - category
      - branch
      - created_details
      properties:
        skill_id:
          type: integer
          description: Id of the skill to assign to the employee
          example: 123
        comment:
          type: string
          description: Free text comment on the employee specific skill
          example: This employee has reached a proficiency level in this skill
        name:
          type: string
          description: Skill Name
          example: Hoyer lift
        category:
          $ref: '#/components/schemas/SkillCategory'
        branch:
          $ref: '#/components/schemas/BranchSummary'
        fields:
          $ref: '#/components/schemas/EmployeeSkillField'
        created_details:
          $ref: '#/components/schemas/CreatedDetails'
    CreatedDetails:
      description: Created by and Created at information
      type: object
      properties:
        created_by:
          type: object
          description: User who created the employee skill entry
          properties:
            id:
              type: integer
              description: Id of the employee who assigned the skill
              example: 284
            external_id:
              type: string
              description: External ID of the employee who assigned the skill
              example: 450
            name:
              type: string
              description: Name of the employee who assigned the skill
              example: John Smith
        created_at:
          type: string
          format: date-time
          description: Date employee specific skill was assigned to the employee (ISO 8601) - Time saved at `T00:00:00+00:00`
          example: '2017-07-08T00:00:00+00:00'
    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 availbale
          example: 1
      required:
      - count
      - page
      - total_pages
      - items
  parameters:
    filter:
      description: Substring search on skill category and name
      name: filter
      in: query
      required: false
      schema:
        type: string
    page:
      description: Filter by page number.
      name: page
      in: query
      required: false
      schema:
        type: integer
        default: 1
    category_id:
      description: Filter skills by category ID, one or more using **OR**
      name: category_id
      in: query
      required: false
      schema:
        type: integer
    count:
      description: Number of items per page.
      name: count
      in: query
      required: false
      schema:
        type: integer
        default: 100
  responses:
    ErrorResponseEmployeeSkillNotFound:
      description: Employee skill relationship not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            code: 404
            message: Employee skill relationship not found
    ErrorResponseEmployeeNotFound:
      description: Employee not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            code: 404
            message: Employee not found.
    ErrorResponseAuthentication:
      description: Authorization required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            code: 401
            message: Authorization required.
  securitySchemes:
    basic_auth:
      type: http
      scheme: basic
      description: Basic HTTP auth over https