openapi: 3.0.0
info:
  version: 1.0.19-oas3
  title: AlayaCare Accounting Accounts Employee Unavailabilities API
  description: '**AlayaCare IDs:**

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

    - id

    - visit_id

    - premium_id

    - visit_premium_id

    - employee_id

    - cost_centre_id

    - client_id


    **External IDs**

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

    - employee_external_id

    - client_external_id


    External IDs are required to be unique.

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

    '
servers:
- url: https://example.alayacare.com/ext/api/v2/accounting
security:
- basic_auth: []
tags:
- name: Employee Unavailabilities
paths:
  /employee/{employee_id}/unavailabilities:
    parameters:
    - name: employee_id
      description: AlayaCare ID of the employee
      in: path
      type: string
      required: true
    get:
      tags:
      - Employee Unavailabilities
      parameters:
      - $ref: '#/parameters/page'
      - $ref: '#/parameters/count'
      - name: start_date_from
        in: query
        required: false
        type: string
        format: date
        description: 'Filter by unavailability start date greater or equal than specified value.

          Expected format is ISO 8601 converted to UTC timezone.

          Ex: `2020-02-03`

          '
      - name: start_date_to
        in: query
        required: false
        type: string
        format: date
        description: 'Filter by unavailability start date less than or equal than specified value.

          Expected format is ISO 8601 converted to UTC timezone.

          Ex: `2020-02-18`

          '
      - name: end_date_from
        in: query
        required: false
        type: string
        format: date
        description: 'Filter by unavailability end date greater or equal than specified value.

          Expected format is ISO 8601 converted to UTC timezone.

          Ex: `2020-02-03`

          '
      - name: end_date_to
        in: query
        required: false
        type: string
        format: date
        description: 'Filter by unavailability end date less than or equal than specified value.

          Expected format is ISO 8601 converted to UTC timezone.

          Ex: `2020-02-18`

          '
      - name: time_off_type_id
        description: Filter by AlayaCare time off type ID.
        in: query
        type: string
      - name: filter
        description: Substring search on unavailability `description` and `rrule`.
        in: query
        type: string
        required: false
      - name: order
        description: 'Order `items` in **ascending** or **descending** order. By default, `items` are ordered by `id` of the unavailability in ascending order.

          For example:

          -`order=asc` will order `items` in ascending order

          -`order=desc` will order `items` in descending order

          '
        in: query
        type: string
        required: false
      - name: order_by
        description: 'Order `items` by unavailability **start date** or **end date**. By default, `items` are ordered by `id` of the unavailability in ascending order.

          For example:

          -`order_by=start_at` will order `items` by start date in ascending order

          -`order_by=end_at&order=desc` will order `items` by end date in descending order

          '
        in: query
        type: string
        required: false
      summary: 'Get a list of an employee unavailabilities using its AlayaCare ID

        '
      responses:
        200:
          description: A list of an employee unavailabilities
          schema:
            $ref: '#/definitions/UnavailabilitiesList'
        401:
          $ref: '#/responses/ErrorResponseAuthentication'
        404:
          $ref: '#/responses/ErrorResponseEmployeeNotFound'
    post:
      tags:
      - Employee Unavailabilities
      summary: 'Create an employee unavailability using its AlayaCare ID

        '
      description: '* `duration_paid_per_day` can only be set when the Time Off Type `pay_schedule_time` is set to `No` and the unavailability `all_day` is set to `true`

        * `duration_paid_per_day` is optional, if omitted the unavailability will be created with the Time Off Type `all_day_duration`

        * `time_off_type_id` is optional, if omitted the unavailability will be created with a Time Off Type set as `Unavailable`

        * `duration` can only be set when when `all_day` is set to `false`

        '
      parameters:
      - name: body
        description: Unavailability data in JSON format
        in: body
        required: true
        schema:
          $ref: '#/definitions/UnavailabilityCreate'
      responses:
        201:
          description: Unavailability created successfully
          schema:
            $ref: '#/definitions/UnavailabilityCreated'
        401:
          $ref: '#/responses/ErrorResponseAuthentication'
        400:
          description: Invalid request
          schema:
            $ref: '#/definitions/ErrorResponse'
          examples:
            application/json:
              code: 400
              message: Field 'time_off_type_id' is invalid
        404:
          $ref: '#/responses/ErrorResponseEmployeeNotFound'
        409:
          description: Conflict
          examples:
            application/json:
              code: 409
              message: 'Role conflict: Time Off Type cannot be assigned to the employee'
  /employee/by_id/{external_employee_id}/unavailabilities:
    parameters:
    - name: external_employee_id
      description: External ID of the employee
      in: path
      type: string
      required: true
    get:
      tags:
      - Employee Unavailabilities
      parameters:
      - $ref: '#/parameters/page'
      - $ref: '#/parameters/count'
      - name: start_date_from
        in: query
        required: false
        type: string
        format: date
        description: 'Filter by unavailability start date greater or equal than specified value.

          Expected format is ISO 8601 converted to UTC timezone.

          Ex: `2020-02-03`

          '
      - name: start_date_to
        in: query
        required: false
        type: string
        format: date
        description: 'Filter by unavailability start date less than or equal than specified value.

          Expected format is ISO 8601 converted to UTC timezone.

          Ex: `2020-02-18`

          '
      - name: end_date_from
        in: query
        required: false
        type: string
        format: date
        description: 'Filter by unavailability end date greater or equal than specified value.

          Expected format is ISO 8601 converted to UTC timezone.

          Ex: `2020-02-03`

          '
      - name: end_date_to
        in: query
        required: false
        type: string
        format: date
        description: 'Filter by unavailability end date less than or equal than specified value.

          Expected format is ISO 8601 converted to UTC timezone.

          Ex: `2020-02-18`

          '
      - name: time_off_type_id
        description: Filter by AlayaCare time off type ID.
        in: query
        type: string
      - name: filter
        description: Substring search on unavailability `description` and `rrule`.
        in: query
        type: string
        required: false
      - name: order
        description: 'Order `items` in **ascending** or **descending** order. By default, `items` are ordered by `id` of the unavailability in ascending order.

          For example:

          -`order=asc` will order `items` in ascending order

          -`order=desc` will order `items` in descending order

          '
        in: query
        type: string
        required: false
      - name: order_by
        description: 'Order `items` by unavailability **start date** or **end date**. By default, `items` are ordered by `id` of the unavailability in ascending order.

          For example:

          -`order_by=start_at` will order `items` by start date in ascending order

          -`order_by=end_at&order=desc` will order `items` by end date in descending order

          '
        in: query
        type: string
        required: false
      summary: 'Get a list of an employee unavailabilities using its External Employee ID

        '
      responses:
        200:
          description: A list of an employee unavailabilities
          schema:
            $ref: '#/definitions/UnavailabilitiesList'
        401:
          $ref: '#/responses/ErrorResponseAuthentication'
        404:
          $ref: '#/responses/ErrorResponseEmployeeNotFound'
    post:
      tags:
      - Employee Unavailabilities
      summary: 'Create an employee unavailability using its External Employee ID

        '
      description: '* `duration_paid_per_day` can only be set when the Time Off Type `pay_schedule_time` is set to `No` and the unavailability `all_day` is set to `true`

        * `duration_paid_per_day` is optional, if omitted the unavailability will be created with the Time Off Type `all_day_duration`

        * `time_off_type_id` is optional, if omitted the unavailability will be created with a Time Off Type set as `Unavailable`

        * `duration` can only be set when when `all_day` is set to `false`

        '
      parameters:
      - name: body
        description: Unavailability data in JSON format
        in: body
        required: true
        schema:
          $ref: '#/definitions/UnavailabilityCreate'
      responses:
        201:
          description: Unavailability created successfully
          schema:
            $ref: '#/definitions/UnavailabilityCreated'
        401:
          $ref: '#/responses/ErrorResponseAuthentication'
        400:
          description: Invalid request
          schema:
            $ref: '#/definitions/ErrorResponse'
          examples:
            application/json:
              code: 400
              message: Field 'time_off_type_id' is invalid
        404:
          $ref: '#/responses/ErrorResponseEmployeeNotFound'
        409:
          description: Conflict
          examples:
            application/json:
              code: 409
              message: 'Role conflict: Time Off Type cannot be assigned to the employee'
components:
  securitySchemes:
    basic_auth:
      type: http
      description: Basic HTTP auth over https
      scheme: basic
definitions:
  UnavailabilityCreated:
    description: Unavailability created details
    type: object
    required:
    - id
    properties:
      id:
        type: integer
        description: ID of the unavailability
        example: 1
  Unavailability:
    description: Unavailability details
    type: object
    properties:
      id:
        type: integer
        description: ID of the unavailability
        example: 1
      employee:
        $ref: '#/definitions/EmployeeDetails'
      time_off_type:
        $ref: '#/definitions/TimeOffTypeDetails'
      description:
        type: string
        description: Free text comment on the employee unavailability
        example: Daily unavailability used for paid sick leaves.
      duration:
        type: integer
        description: Unavailability duration in minutes. The duration will be set to 0 for an all day unavailability
        example: 60
      all_day:
        type: boolean
        description: Specifies if the unavailability is applicable for the entire day
        example: false
      rrule:
        type: string
        description: "Recurrence rule applied to the employee unavailability, configured based on the below parameters:\n  - `FREQ` is mandatory and can only be set to `DAILY`,`WEEKLY`or`MONTHLY`.\n  - `DTSTART` is mandatory \n    - The format will be ISO 8601 converted to employee timezone\n  - `UNTIL` is not mandatory\n    - The format will be ISO 8601 converted to employee timezone\n  - `INTERVAL` is mandatory. \n    - When `FREQ` is set to `DAILY`, `INTERVAL` can be set to a value between `1` to `365`\n    - When `FREQ` is set to `WEEKLY`, `INTERVAL` can be set to a value between `1` to `52`\n    - When `FREQ` is set to `MONTHLY`, `INTERVAL` can be set to a value between `1` to `12`\n  - `BYDAY` is mandatory and can only be set when `FREQ` is set to `WEEKLY`. `BYDAY` can be set to either `MO`,`TU`,`WE`,`TH`,`FR`,`SA`and/or`SU`. If multiple values are selected, separate them with a comma (i.e.: `BYDAY=TU,TH,SA`)\n  - `BYMONTHDAY` is mandatory and can only be set when `FREQ` is set to `MONTHLY`. `BYMONTHDAY` can be set to a value between `1` to `28`.\n  - `TIMEZONE` is the timezone of the employee.\n\nRefer to https://tools.ietf.org/html/rfc5545 for more information.\n"
        example: FREQ=DAILY;DTSTART=20200130T050000Z;UNTIL=20200130T050000Z;INTERVAL=1;TIMEZONE=America/Toronto
      duration_paid_per_day:
        type: integer
        description: "Payable portion of the day for an all day unavailability. For example, an 8 hours work day will be represented as 480 minutes of `duration_paid_per_day`. \nOverwrites the `all_day_duration` setting of the Time Off Type. Only available when `pay_schedule_time` of the Time Off Type is set to 'No' and the unavailability `all_day` is set to `true`.\n"
        example: null
      branch:
        $ref: '#/definitions/BranchSummary'
  TimeOffTypeDetails:
    description: Time Off Type details
    type: object
    properties:
      id:
        type: integer
        description: ID of the time off type
        example: 1
      name:
        type: string
        description: Name of the time off type
        example: SICKPAID
      pay_schedule_time:
        type: string
        description: Time off type usable payable scheduled hours for payroll configuration
        example: Visit_Pay_Code
        enum:
        - false
        - Time_Off_Pay_Code
        - Visit_Pay_Code
  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
  EmployeeDetails:
    description: Employee details
    type: object
    properties:
      id:
        type: integer
        description: AlayaCare ID of the employee
        example: 1
      external_id:
        type: string
        description: External ID of the employee
        example: external_id_1
  UnavailabilityCreate:
    description: Unavailability creation details
    type: object
    required:
    - all_day
    - rrule
    properties:
      time_off_type_id:
        type: integer
        description: 'ID of the Time Off Type associated with this unavailability

          Optional, if omitted the unavailability will be created with a Time Off Type set as `Unavailable`

          '
        example: 1
      description:
        type: string
        description: Free text comment on the employee unavailability
        example: Weekly unavailability used for paid sick leaves.
      duration:
        type: integer
        description: Unavailability duration in minutes. The duration can only be updated when `all_day` is set to `false`
        example: 60
      all_day:
        type: boolean
        description: Specifies if the unavailability is applicable for the entire day
        example: false
      rrule:
        type: string
        description: "Recurrence rule applied to the employee unavailability, configured based on the below parameters:\n  - `FREQ` is mandatory and can only be set to `DAILY`,`WEEKLY`or`MONTHLY`.\n  - `DTSTART` is mandatory \n    - The format must be ISO 8601 and must be sent in the specific employee timezone\n    - The time specified in `DTSTART` represents the start time of the unavailability. The end time of the unavailability will be calculated using the `duration`\n  - `UNTIL` is not mandatory\n    - The format must be ISO 8601 and must be sent in the specific employee timezone\n  - `INTERVAL` is mandatory. \n    - When `FREQ` is set to `DAILY`, `INTERVAL` can be set to a value between `1` to `365`\n    - When `FREQ` is set to `WEEKLY`, `INTERVAL` can be set to a value between `1` to `52`\n    - When `FREQ` is set to `MONTHLY`, `INTERVAL` can be set to a value between `1` to `12`\n  - `BYDAY` is mandatory and can only be set when `FREQ` is set to `WEEKLY`. `BYDAY` can be set to either `MO`,`TU`,`WE`,`TH`,`FR`,`SA`and/or`SU`. If multiple values are selected, separate them with a comma (i.e.: `BYDAY=TU,TH,SA`)\n  - `BYMONTHDAY` is mandatory and can only be set when `FREQ` is set to `MONTHLY`. `BYMONTHDAY` can be set to a value between `1` to `28`.\n\nRefer to https://tools.ietf.org/html/rfc5545 for more information.\n"
        example: FREQ=WEEKLY;DTSTART=20200211T180000Z;UNTIL=20200303T180000Z;INTERVAL=1;BYDAY=TU,TH,SA
      duration_paid_per_day:
        type: integer
        description: "Payable portion of the day for an all day unavailability. For example, an 8 hours work day will be represented as 480 minutes of `duration_paid_per_day`. \nOverwrites the `all_day_duration` setting of the Time Off Type. Only available when `pay_schedule_time` of the Time Off Type is set to 'No' and the unavailability `all_day` is set to `true`.\n"
        example: null
  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
  ErrorResponse:
    description: Error response
    type: object
    properties:
      code:
        type: integer
        description: Response code
      message:
        type: string
        description: Detailed error message
    required:
    - code
    - message
  UnavailabilitiesList:
    allOf:
    - $ref: '#/definitions/PaginatedList'
    description: List of an employee unavailabilities
    type: object
    properties:
      items:
        type: array
        items:
          allOf:
          - $ref: '#/definitions/Unavailability'
parameters:
  count:
    description: Number of items per page.
    name: count
    default: 100
    in: query
    required: false
    type: integer
  page:
    description: Filter by page number.
    name: page
    default: 1
    in: query
    required: false
    type: integer
responses:
  ErrorResponseAuthentication:
    description: Authorization required
    schema:
      $ref: '#/definitions/ErrorResponse'
    examples:
      application/json:
        code: 401
        message: Authorization required
  ErrorResponseEmployeeNotFound:
    description: Employee not found
    schema:
      $ref: '#/definitions/ErrorResponse'
    examples:
      application/json:
        code: 404
        message: Employee not found