swagger: '2.0'
info:
  description: REST API for ChartHop
  version: V1.0.0
  title: ChartHop access timeoff API
  contact:
    name: ChartHop
    url: https://www.charthop.com
    email: support@charthop.com
host: localhost
schemes:
- https
- http
consumes:
- application/json
produces:
- application/json
tags:
- name: timeoff
paths:
  /v1/org/{orgId}/timeoff:
    get:
      tags:
      - timeoff
      summary: Retrieve time off requests
      operationId: findTimeOff
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        type: string
      - name: personId
        in: query
        description: Person id to filter by
        required: false
        type: string
      - name: fromDate
        in: query
        description: From date, inclusive
        required: false
        type: string
        format: date
      - name: untilDate
        in: query
        description: Until date, exclusive
        required: false
        type: string
        format: date
      - name: from
        in: query
        description: Time off id to start paginating from
        required: false
        type: string
      - name: limit
        in: query
        description: Number of results to return
        required: false
        type: integer
        format: int32
      - name: returnAccess
        in: query
        description: 'Return access information -- pass a list of actions to check, for example: create,update,delete'
        required: false
        type: string
      responses:
        '200':
          description: successful operation
          schema:
            $ref: '#/definitions/ResultsTimeOffEntity'
        '400':
          description: bad request
        '401':
          description: not authorized
        '404':
          description: not found
        '500':
          description: Not Implemented
    post:
      tags:
      - timeoff
      summary: Create a time off request
      operationId: createTimeOff
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        type: string
      - name: body
        in: body
        description: TimeOff data to create
        required: true
        schema:
          $ref: '#/definitions/CreateTimeOffEntity'
      responses:
        '201':
          description: time off created
          schema:
            $ref: '#/definitions/TimeOff'
        '400':
          description: bad request
        '401':
          description: not authorized
        '404':
          description: not found
        '500':
          description: Not Implemented
  /v1/org/{orgId}/timeoff/request:
    post:
      tags:
      - timeoff
      summary: Request time off
      operationId: requestTimeOff
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        type: string
      - name: body
        in: body
        description: Time off request
        required: true
        schema:
          $ref: '#/definitions/TimeOffRequest'
      responses:
        '201':
          description: time off created
          schema:
            $ref: '#/definitions/TimeOffEntity'
        '400':
          description: bad request
        '401':
          description: not authorized
        '404':
          description: not found
        '500':
          description: Not Implemented
  /v1/org/{orgId}/timeoff/request/validate:
    post:
      tags:
      - timeoff
      summary: Validate a time off request
      operationId: validateRequest
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        type: string
      - name: body
        in: body
        description: Time off request
        required: true
        schema:
          $ref: '#/definitions/TimeOffRequest'
      - name: ignoreRequestId
        in: query
        description: Request ID to ignore during validation (for editing)
        required: false
        type: string
      responses:
        '201':
          description: time off validated
          schema:
            $ref: '#/definitions/CalculatedTimeOffBalance'
        '400':
          description: bad request
        '401':
          description: not authorized
        '404':
          description: not found
        '500':
          description: Not Implemented
  /v1/org/{orgId}/timeoff/{timeOffId}:
    get:
      tags:
      - timeoff
      summary: Return a particular time off request by id
      operationId: getTimeOff
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        type: string
      - name: timeOffId
        in: path
        description: TimeOff id
        required: true
        type: string
      responses:
        '200':
          description: successful operation
          schema:
            $ref: '#/definitions/TimeOffEntity'
        '400':
          description: bad request
        '401':
          description: not authorized
        '404':
          description: not found
        '500':
          description: Not Implemented
    patch:
      tags:
      - timeoff
      summary: Update an existing time off request
      operationId: updateTimeOff
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        type: string
      - name: timeOffId
        in: path
        description: TimeOff id
        required: true
        type: string
      - name: body
        in: body
        description: TimeOff data to update
        required: true
        schema:
          $ref: '#/definitions/UpdateTimeOffEntity'
      responses:
        '204':
          description: time off updated
        '400':
          description: bad request
        '401':
          description: not authorized
        '404':
          description: not found
        '500':
          description: Not Implemented
    delete:
      tags:
      - timeoff
      summary: Delete a time off request
      operationId: deleteTimeOff
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        type: string
      - name: timeOffId
        in: path
        description: TimeOff id
        required: true
        type: string
      responses:
        '204':
          description: time off deleted
        '400':
          description: bad request
        '401':
          description: not authorized
        '404':
          description: not found
        '500':
          description: Not Implemented
  /v1/org/{orgId}/timeoff/{timeOffId}/approve:
    post:
      tags:
      - timeoff
      summary: Approve a pending time off request
      operationId: approveTimeOff
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        type: string
      - name: timeOffId
        in: path
        description: TimeOff id
        required: true
        type: string
      - name: targetApproverJobId
        in: query
        description: jobId of the approver the caller is acting for as their approval delegate
        required: false
        type: string
      - name: body
        in: body
        description: Approval information
        required: true
        schema:
          $ref: '#/definitions/TimeOffApproval'
      responses:
        '204':
          description: time off approved
        '400':
          description: bad request
        '401':
          description: not authorized
        '404':
          description: not found
        '500':
          description: Not Implemented
  /v1/org/{orgId}/timeoff/{timeOffId}/reject:
    post:
      tags:
      - timeoff
      summary: Reject a pending time off request
      operationId: rejectTimeOff
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        type: string
      - name: timeOffId
        in: path
        description: TimeOff id
        required: true
        type: string
      - name: targetApproverJobId
        in: query
        description: jobId of the approver the caller is acting for as their approval delegate
        required: false
        type: string
      - name: body
        in: body
        description: Rejection information
        required: true
        schema:
          $ref: '#/definitions/TimeOffApproval'
      responses:
        '204':
          description: time off rejected
        '400':
          description: bad request
        '401':
          description: not authorized
        '404':
          description: not found
        '500':
          description: Not Implemented
definitions:
  AccessAction:
    type: object
    required:
    - action
    properties:
      action:
        type: string
      fields:
        type: array
        uniqueItems: true
        items:
          type: string
      types:
        type: array
        uniqueItems: true
        items:
          type: string
  TimeOff:
    type: object
    required:
    - id
    - startDate
    - endDate
    properties:
      id:
        type: string
        description: unique id of a time off request
      startDate:
        type: string
        format: date
        description: start date of time off, inclusive
      endDate:
        type: string
        format: date
        description: end date of time off, inclusive
      days:
        type: number
        description: number of days used
      hours:
        type: number
        description: number of hours used
      type:
        type: string
        description: type of time off
      note:
        type: string
        description: notes on the time off
      approval:
        type: string
        description: approval status of the time off
        enum:
        - APPROVED
        - PENDING
        - CANCELLED
        - REJECTED
        - SUPERSEDED
  ResultsAccess:
    type: object
    required:
    - allowed
    properties:
      ids:
        type: array
        uniqueItems: true
        items:
          type: string
          example: 588f7ee98f138b19220041a7
      allowed:
        type: array
        uniqueItems: true
        items:
          $ref: '#/definitions/AccessAction'
  TimeOffRequest:
    type: object
    required:
    - startDate
    - endDate
    properties:
      startDate:
        type: string
        format: date
      startDatePartialDay:
        type: number
      startDatePartialDayPeriod:
        type: string
        enum:
        - AM
        - PM
      endDate:
        type: string
        format: date
      endDatePartialDay:
        type: number
      endDatePartialDayPeriod:
        type: string
        enum:
        - AM
        - PM
      personId:
        type: string
        example: 588f7ee98f138b19220041a7
      typeDescription:
        type: string
      timeOffPolicyId:
        type: string
        example: 588f7ee98f138b19220041a7
      note:
        type: string
  CreateTimeOffEntity:
    type: object
    required:
    - orgId
    - personId
    - startDate
    - endDate
    properties:
      orgId:
        type: string
        description: org that the time off belongs to
        example: 588f7ee98f138b19220041a7
      personId:
        type: string
        description: person taking the time off
        example: 588f7ee98f138b19220041a7
      externalId:
        type: string
        description: external identifier, if time off synced from external system
      startDate:
        type: string
        format: date
        description: start date of time off, inclusive
      startDatePartialDay:
        type: number
        description: 'portion of the start date to take '
      startDatePartialDayPeriod:
        type: string
        description: Portion of the start day requested (e.g. AM or PM)
        enum:
        - AM
        - PM
      endDate:
        type: string
        format: date
        description: end date of time off, inclusive
      endDatePartialDay:
        type: number
        description: portion of the end date to take
      endDatePartialDayPeriod:
        type: string
        description: Portion of the end day requested (e.g. AM or PM)
        enum:
        - AM
        - PM
      days:
        type: number
        description: number of days used
      hours:
        type: number
        description: number of hours used
      typeDescription:
        type: string
        description: type of time off
      timeOffPolicyId:
        type: string
        description: policy id to pull the balance from
        example: 588f7ee98f138b19220041a7
      note:
        type: string
        description: notes on the time off
      approval:
        type: string
        description: approval status of the time off
        enum:
        - APPROVED
        - PENDING
        - CANCELLED
        - REJECTED
        - SUPERSEDED
      requestAt:
        type: string
        description: requested at timestamp -- often the same as createAt
        example: '2017-01-24T13:57:52Z'
  ExcludedDay:
    type: object
    required:
    - date
    - dayLabel
    properties:
      date:
        type: string
        format: date
      dayLabel:
        type: string
  Attribution:
    type: object
    properties:
      principalUserId:
        type: string
        example: 588f7ee98f138b19220041a7
      agentUserIds:
        type: array
        items:
          type: string
          example: 588f7ee98f138b19220041a7
      eventId:
        type: string
        example: 588f7ee98f138b19220041a7
      aiChatId:
        type: string
        example: 588f7ee98f138b19220041a7
      aiToolUseId:
        type: string
      channel:
        type: string
        enum:
        - WEB
        - MOBILE
        - SLACK
        - TEAMS
        - MCP
  CalculatedTimeOffBalance:
    type: object
    required:
    - daysTaken
    - hoursTaken
    - excludedDays
    properties:
      daysTaken:
        type: number
      hoursTaken:
        type: number
      balanceBeforeRequest:
        type: number
      carryOverBeforeRequest:
        type: number
      balanceAfterRequest:
        type: number
      carryOverAfterRequest:
        type: number
      excludedDays:
        type: array
        items:
          $ref: '#/definitions/ExcludedDay'
      approverJobId:
        type: string
        example: 588f7ee98f138b19220041a7
      errorMessage:
        type: string
  TimeOffEntity:
    type: object
    required:
    - id
    - orgId
    - personId
    - startDate
    - endDate
    properties:
      id:
        type: string
        description: globally unique id of time off
        example: 588f7ee98f138b19220041a7
      orgId:
        type: string
        description: org that the time off belongs to
        example: 588f7ee98f138b19220041a7
      personId:
        type: string
        description: person taking the time off
        example: 588f7ee98f138b19220041a7
      externalId:
        type: string
        description: external identifier, if time off synced from external system
      startDate:
        type: string
        format: date
        description: start date of time off, inclusive
      startDatePartialDay:
        type: number
        description: 'portion of the start date to take '
      startDatePartialDayPeriod:
        type: string
        description: Portion of the start day requested (e.g. AM or PM)
        enum:
        - AM
        - PM
      endDate:
        type: string
        format: date
        description: end date of time off, inclusive
      endDatePartialDay:
        type: number
        description: portion of the end date to take
      endDatePartialDayPeriod:
        type: string
        description: Portion of the end day requested (e.g. AM or PM)
        enum:
        - AM
        - PM
      days:
        type: number
        description: number of days used
      hours:
        type: number
        description: number of hours used
      typeDescription:
        type: string
        description: type of time off
      timeOffPolicyId:
        type: string
        description: policy id to pull the balance from
        example: 588f7ee98f138b19220041a7
      note:
        type: string
        description: notes on the time off
      approval:
        type: string
        description: approval status of the time off
        enum:
        - APPROVED
        - PENDING
        - CANCELLED
        - REJECTED
        - SUPERSEDED
      approvalAt:
        type: string
        description: timestamp of approval
        example: '2017-01-24T13:57:52Z'
      approvalUserId:
        type: string
        description: user who either is the next one requesting approval, or the user who did the final approval or rejection
        example: 588f7ee98f138b19220041a7
      createId:
        type: string
        description: created by user id
        example: 588f7ee98f138b19220041a7
      createBehalfId:
        type: string
        description: created on behalf of user id
        example: 588f7ee98f138b19220041a7
      createAttribution:
        $ref: '#/definitions/Attribution'
      createAt:
        type: string
        description: created timestamp
        example: '2017-01-24T13:57:52Z'
      updateAt:
        type: string
        description: updated timestamp
        example: '2017-01-24T13:57:52Z'
      updateId:
        type: string
        description: updated by user id
        example: 588f7ee98f138b19220041a7
      updateBehalfId:
        type: string
        description: last updated on behalf of user id
        example: 588f7ee98f138b19220041a7
      updateAttribution:
        $ref: '#/definitions/Attribution'
      deleteId:
        type: string
        description: deleted by user id
        example: 588f7ee98f138b19220041a7
      deleteBehalfId:
        type: string
        description: deleted on behalf of user id
        example: 588f7ee98f138b19220041a7
      deleteAttribution:
        $ref: '#/definitions/Attribution'
      deleteAt:
        type: string
        description: deleted timestamp
        example: '2017-01-24T13:57:52Z'
      requestAt:
        type: string
        description: requested at timestamp -- often the same as createAt
        example: '2017-01-24T13:57:52Z'
  ResultsTimeOffEntity:
    type: object
    required:
    - data
    properties:
      data:
        type: array
        items:
          $ref: '#/definitions/TimeOffEntity'
      next:
        type: string
      access:
        type: array
        items:
          $ref: '#/definitions/ResultsAccess'
  TimeOffApproval:
    type: object
    properties:
      message:
        type: string
  UpdateTimeOffEntity:
    type: object
    properties:
      externalId:
        type: string
        description: external identifier, if time off synced from external system
      startDate:
        type: string
        format: date
        description: start date of time off, inclusive
      startDatePartialDay:
        type: number
        description: 'portion of the start date to take '
      startDatePartialDayPeriod:
        type: string
        description: Portion of the start day requested (e.g. AM or PM)
        enum:
        - AM
        - PM
      endDate:
        type: string
        format: date
        description: end date of time off, inclusive
      endDatePartialDay:
        type: number
        description: portion of the end date to take
      endDatePartialDayPeriod:
        type: string
        description: Portion of the end day requested (e.g. AM or PM)
        enum:
        - AM
        - PM
      days:
        type: number
        description: number of days used
      hours:
        type: number
        description: number of hours used
      typeDescription:
        type: string
        description: type of time off
      timeOffPolicyId:
        type: string
        description: policy id to pull the balance from
        example: 588f7ee98f138b19220041a7
      note:
        type: string
        description: notes on the time off
      approval:
        type: string
        description: approval status of the time off
        enum:
        - APPROVED
        - PENDING
        - CANCELLED
        - REJECTED
        - SUPERSEDED
      requestAt:
        type: string
        description: requested at timestamp -- often the same as createAt
        example: '2017-01-24T13:57:52Z'