Charthop timeoff API

openapi: 3.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
servers:
- url: https://localhost
- url: http://localhost
tags:
- name: timeoff
paths:
  /v1/org/{orgId}/timeoff:
    get:
      tags:
      - timeoff
      summary: Retrieve time off requests
      operationId: findTimeOff
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: personId
        in: query
        description: Person id to filter by
        required: false
        schema:
          type: string
      - name: fromDate
        in: query
        description: From date, inclusive
        required: false
        schema:
          type: string
          format: date
      - name: untilDate
        in: query
        description: Until date, exclusive
        required: false
        schema:
          type: string
          format: date
      - name: from
        in: query
        description: Time off id to start paginating from
        required: false
        schema:
          type: string
      - name: limit
        in: query
        description: Number of results to return
        required: false
        schema:
          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
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/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
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      responses:
        '201':
          description: time off created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimeOff'
        '400':
          description: bad request
        '401':
          description: not authorized
        '404':
          description: not found
        '500':
          description: Not Implemented
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTimeOffEntity'
        description: TimeOff data to create
        required: true
  /v1/org/{orgId}/timeoff/request:
    post:
      tags:
      - timeoff
      summary: Request time off
      operationId: requestTimeOff
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      responses:
        '201':
          description: time off created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimeOffEntity'
        '400':
          description: bad request
        '401':
          description: not authorized
        '404':
          description: not found
        '500':
          description: Not Implemented
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TimeOffRequest'
        description: Time off request
        required: true
  /v1/org/{orgId}/timeoff/request/validate:
    post:
      tags:
      - timeoff
      summary: Validate a time off request
      operationId: validateRequest
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: ignoreRequestId
        in: query
        description: Request ID to ignore during validation (for editing)
        required: false
        schema:
          type: string
      responses:
        '201':
          description: time off validated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CalculatedTimeOffBalance'
        '400':
          description: bad request
        '401':
          description: not authorized
        '404':
          description: not found
        '500':
          description: Not Implemented
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TimeOffRequest'
        description: Time off request
        required: true
  /v1/org/{orgId}/timeoff/{timeOffId}:
    get:
      tags:
      - timeoff
      summary: Return a particular time off request by id
      operationId: getTimeOff
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: timeOffId
        in: path
        description: TimeOff id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/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
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: timeOffId
        in: path
        description: TimeOff id
        required: true
        schema:
          type: string
      responses:
        '204':
          description: time off updated
        '400':
          description: bad request
        '401':
          description: not authorized
        '404':
          description: not found
        '500':
          description: Not Implemented
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateTimeOffEntity'
        description: TimeOff data to update
        required: true
    delete:
      tags:
      - timeoff
      summary: Delete a time off request
      operationId: deleteTimeOff
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: timeOffId
        in: path
        description: TimeOff id
        required: true
        schema:
          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
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: timeOffId
        in: path
        description: TimeOff id
        required: true
        schema:
          type: string
      - name: targetApproverJobId
        in: query
        description: jobId of the approver the caller is acting for as their approval delegate
        required: false
        schema:
          type: string
      responses:
        '204':
          description: time off approved
        '400':
          description: bad request
        '401':
          description: not authorized
        '404':
          description: not found
        '500':
          description: Not Implemented
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TimeOffApproval'
        description: Approval information
        required: true
  /v1/org/{orgId}/timeoff/{timeOffId}/reject:
    post:
      tags:
      - timeoff
      summary: Reject a pending time off request
      operationId: rejectTimeOff
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: timeOffId
        in: path
        description: TimeOff id
        required: true
        schema:
          type: string
      - name: targetApproverJobId
        in: query
        description: jobId of the approver the caller is acting for as their approval delegate
        required: false
        schema:
          type: string
      responses:
        '204':
          description: time off rejected
        '400':
          description: bad request
        '401':
          description: not authorized
        '404':
          description: not found
        '500':
          description: Not Implemented
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TimeOffApproval'
        description: Rejection information
        required: true
components:
  schemas:
    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
    ExcludedDay:
      type: object
      required:
      - date
      - dayLabel
      properties:
        date:
          type: string
          format: date
        dayLabel:
          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
    TimeOffApproval:
      type: object
      properties:
        message:
          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'
    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: '#/components/schemas/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: '#/components/schemas/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: '#/components/schemas/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'
    ResultsAccess:
      type: object
      required:
      - allowed
      properties:
        ids:
          type: array
          uniqueItems: true
          items:
            type: string
            example: 588f7ee98f138b19220041a7
        allowed:
          type: array
          uniqueItems: true
          items:
            $ref: '#/components/schemas/AccessAction'
    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'
    ResultsTimeOffEntity:
      type: object
      required:
      - data
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/TimeOffEntity'
        next:
          type: string
        access:
          type: array
          items:
            $ref: '#/components/schemas/ResultsAccess'
    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: '#/components/schemas/ExcludedDay'
        approverJobId:
          type: string
          example: 588f7ee98f138b19220041a7
        errorMessage:
          type: string
    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
    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