Charthop timeOffPolicy API

openapi: 3.2.0
info:
  description: REST API for ChartHop
  version: V1.0.0
  title: ChartHop access Time Off Policy API
  contact:
    name: ChartHop
    url: https://www.charthop.com
    email: support@charthop.com
servers:
- url: https://localhost
- url: http://localhost
tags:
- name: timeOffPolicy
paths:
  /v1/org/{orgId}/timeoff/policy:
    post:
      tags:
      - timeOffPolicy
      summary: Create a time off policy
      operationId: createTimeOffPolicy
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      responses:
        '201':
          description: created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimeOffPolicy'
        '400':
          description: bad request
        '401':
          description: not authorized
        '404':
          description: not found
        '500':
          description: Not Implemented
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTimeOffPolicy'
        description: TimeOff policy data to create
        required: true
    get:
      tags:
      - timeOffPolicy
      summary: Return all policies in the organization
      operationId: findTimeOffPolicies
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: limit
        in: query
        description: Number of results to return
        required: false
        schema:
          type: integer
          format: int32
      - name: from
        in: query
        description: From result id
        required: false
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultsTimeOffPolicy'
        '400':
          description: bad request
        '401':
          description: not authorized
        '404':
          description: not found
  /v1/org/{orgId}/timeoff/policy/balances:
    get:
      tags:
      - timeOffPolicy
      summary: Return time off balances for a given policy and date
      operationId: findTimeOffPolicyBalances
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: policies
        in: query
        description: Policy Ids to retrieve, comma-separated
        required: false
        schema:
          type: string
      - name: date
        in: query
        description: Date
        required: false
        schema:
          type: string
          format: date
      - name: format
        in: query
        description: Data format to use; default is json, can also use json-extended or json-readable
        required: false
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: object
        '400':
          description: bad request
        '401':
          description: not authorized
        '404':
          description: not found
  /v1/org/{orgId}/timeoff/policy/balances/{personId}:
    get:
      tags:
      - timeOffPolicy
      summary: Return time off balances per policy for a given person
      operationId: findTimeOffPolicyBalancesForPerson
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: personId
        in: path
        description: Person ID
        required: true
        schema:
          type: string
      - name: date
        in: query
        description: Date
        required: false
        schema:
          type: string
          format: date
      - name: format
        in: query
        description: Data format to use; default is json, can also use json-extended or json-readable
        required: false
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: object
        '400':
          description: bad request
        '401':
          description: not authorized
        '404':
          description: not found
  /v1/org/{orgId}/timeoff/policy/balances/{policyId}:
    post:
      tags:
      - timeOffPolicy
      summary: Adjust time off balances for a group of people on a given policy and effective date
      operationId: updateTimeOffPolicyBalances
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: policyId
        in: path
        description: Policy id associated with balances
        required: true
        schema:
          type: string
      - name: date
        in: query
        description: Effective Date
        required: false
        schema:
          type: string
          format: date
      - name: enterMatching
        in: query
        description: Add adjustment even if it matches current balance
        required: false
        schema:
          type: boolean
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Process'
        '400':
          description: bad request
        '401':
          description: not authorized
        '404':
          description: not found
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TimeOffBalanceAdjustmentBody'
        description: Balances to adjust
        required: true
  /v1/org/{orgId}/timeoff/policy/{policyId}:
    get:
      tags:
      - timeOffPolicy
      summary: Return a particular time off policy by id
      operationId: getTimeOffPolicy
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: policyId
        in: path
        description: TimeOff policy id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimeOffPolicy'
        '400':
          description: bad request
        '401':
          description: not authorized
        '404':
          description: not found
    patch:
      tags:
      - timeOffPolicy
      summary: Update an existing time off policy
      operationId: updateTimeOffPolicy
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: policyId
        in: path
        description: TimeOff id
        required: true
        schema:
          type: string
      responses:
        '204':
          description: no content
        '400':
          description: bad request
        '401':
          description: not authorized
        '404':
          description: not found
        '500':
          description: Not Implemented
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateTimeOffPolicy'
        description: TimeOff data to update
        required: true
    delete:
      tags:
      - timeOffPolicy
      summary: Delete a time off request
      operationId: deleteTimeOffPolicy
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: policyId
        in: path
        description: TimeOff policy id
        required: true
        schema:
          type: string
      responses:
        '204':
          description: time off policy deleted
        '400':
          description: bad request
        '401':
          description: not authorized
        '404':
          description: not found
        '500':
          description: Not Implemented
  /v1/org/{orgId}/timeoff/policy/{policyId}/duplicate:
    post:
      tags:
      - timeOffPolicy
      summary: Duplicate a time off policy
      operationId: duplicateTimeOffPolicy
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: policyId
        in: path
        description: TimeOff policy id
        required: true
        schema:
          type: string
      responses:
        '201':
          description: created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimeOffPolicy'
        '400':
          description: invalid data
        '403':
          description: permission denied
        '404':
          description: not found
  /v1/org/{orgId}/timeoff/policy/{policyId}/estimateAccruals:
    post:
      tags:
      - timeOffPolicy
      summary: Estimate accrual value for policy
      operationId: estimateAccrualForPolicy
      parameters:
      - name: orgId
        in: path
        description: Org identifier (either id or slug)
        required: true
        schema:
          type: string
      - name: policyId
        in: path
        description: TimeOff policy id
        required: true
        schema:
          type: string
      responses:
        '202':
          description: accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EstimatedAccrual'
        '400':
          description: bad request
        '401':
          description: not authorized
        '404':
          description: not found
        '500':
          description: Not Implemented
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateTimeOffPolicy'
        description: TimeOff policy data to estimate from
        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
    LogData:
      type: object
      required:
      - level
      - at
      - data
      properties:
        level:
          type: string
          enum:
          - INFO
          - WARN
          - ERROR
        at:
          type: string
          description: created timestamp
          example: '2017-01-24T13:57:52Z'
        message:
          type: string
        data:
          type: object
          additionalProperties:
            type: object
    EstimatedAccrual:
      type: object
      required:
      - daysPerPeriod
      properties:
        daysPerPeriod:
          type: number
    PolicyEvent:
      type: object
      required:
      - dateExpr
      - action
      properties:
        dateExpr:
          type: string
        action:
          $ref: '#/components/schemas/PolicyAction'
        noteExpr:
          type: string
        groupId:
          type: string
          example: 588f7ee98f138b19220041a7
        title:
          type: string
          description: Display name for the milestone group this event belongs to
          example: Tenure milestones
          minItems: 1
          maxItems: 80
    RequestedBalanceAdjustment:
      type: object
      required:
      - personId
      properties:
        personId:
          type: string
          description: person id
          example: 588f7ee98f138b19220041a7
        days:
          type: number
          description: adjusted balance in days
    UpdateTimeOffPolicy:
      type: object
      properties:
        name:
          type: string
          description: Internal policy name
          example: US Part-Time/Intern
          minItems: 1
          maxItems: 80
        displayName:
          type: string
          description: External policy name displayed to users
          example: PTO
          minItems: 1
          maxItems: 80
        description:
          type: string
          description: Policy description
          example: Annual sick days allotted to employees
          minItems: 0
          maxItems: 2000
        guidelines:
          type: string
          description: Policy guidelines
          minItems: 0
          maxItems: 2000
        type:
          type: string
          description: Type of policy to be created
          enum:
          - PTO
          - TOIL
          - VACATION
          - SICK
          - MEDICAL
          - JURY
          - OFFSITE
          - PARENTAL
          - UNPAID
          - DISABILITY_SHORT
          - DISABILITY_LONG
          - BEREAVEMENT
          - MILITARY
          - RELIGIOUS
          - VOTING
          - VOLUNTEER
          - UNKNOWN
        status:
          type: string
          description: Status of the policy
          enum:
          - ACTIVE
          - INACTIVE
        allocationType:
          type: string
          description: Whether the time off is accrued, received upfront, or is an unlimited policy
          enum:
          - UPFRONT
          - UNLIMITED
          - ACCRUAL
        annualAllocation:
          type: number
          description: Number of days allocated annually
        accrualConfig:
          description: Configuration for how time off is accrued.
          $ref: '#/components/schemas/AccrualConfig'
        maxConsecutiveDaysPerRequest:
          type: number
          description: An optional max number of days allowed per request
        minBalance:
          type: number
          description: An optional minimum balance
        enableCarryOverBalance:
          type: boolean
          description: Enable carry over balance.
        maxCarryOverBalance:
          type: number
          description: An optional maximum carry over balance
        carryOverExpirationDate:
          type: string
          description: Month and day of carry over expiration.
        carryOverExpirationMonths:
          type: integer
          format: int32
          description: Months after carry over date that carry over expires.
        enablePartialDayRequests:
          type: boolean
          description: Allow half day requests
        partialDayGranularity:
          type: number
          description: Partial day requests can only be made down to this level of granularity (i.e. request % granularity == 0)
        enablePartialDayPeriod:
          type: boolean
          description: Allow specifying periods of time (e.g. AM, PM) for partial days
        disableRequests:
          type: boolean
          description: Whether to disable time off requests for this policy
        noteRequired:
          type: boolean
          description: Whether a note is required for time off requests
        filter:
          type: string
          description: CQL used to determine which jobs the policy applies to
        holidayCalendarId:
          type: string
          description: an associated holiday calendar, days on this calendar are not deducted from the time off balance
          example: 588f7ee98f138b19220041a7
        disableProratedAllocation:
          type: boolean
          description: whether limited allocation policies are prorated based on person start date
        prorationRounding:
          type: string
          description: rounding method for prorating calculations
          enum:
          - UP
          - NEAREST
          - HALF
        yearStartDate:
          type: string
          description: Month and day of policy year rollover. Defaults to January 1.
        policyFromDate:
          type: string
          format: date
          description: The date on which this policy's balance/accrual settings come into effect. The policy may have entries before this date, but it will not generate e.g. accrual entries.
        policyUntilDate:
          type: string
          format: date
          description: The first date after this policy's balance/accrual settings end (i.e. the exclusive end date). The policy may have entries after this date, but it will not generate e.g. accrual entries.
        workDays:
          type: array
          description: Days of the week that count against the time off balance. Defaults to Monday through Friday if not set.
          uniqueItems: true
          items:
            type: string
            enum:
            - MONDAY
            - TUESDAY
            - WEDNESDAY
            - THURSDAY
            - FRIDAY
            - SATURDAY
            - SUNDAY
        policyEvents:
          type: array
          items:
            $ref: '#/components/schemas/PolicyEvent'
    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'
    PolicyAction:
      type: object
      required:
      - type
      properties:
        type:
          type: string
          enum:
          - OPEN
          - CLOSE
          - MOD_ALLOCATION
          - ADJUST
          - TRANSFER
          - PRORATED_MOD
          - FULL_MOD
        exprString:
          type: string
    TimeOffPolicy:
      type: object
      required:
      - id
      - orgId
      - name
      - status
      - filter
      properties:
        id:
          type: string
          description: Globally unique id of time off policy
          example: 588f7ee98f138b19220041a7
        orgId:
          type: string
          description: Org that the time off belongs to
          example: 588f7ee98f138b19220041a7
        name:
          type: string
          description: Internal policy name
          example: US Part-Time/Intern
          minItems: 1
          maxItems: 80
        displayName:
          type: string
          description: External policy name displayed to users
          example: PTO
          minItems: 1
          maxItems: 80
        description:
          type: string
          description: Policy description
          example: Annual sick days allotted to employees
          minItems: 0
          maxItems: 2000
        guidelines:
          type: string
          description: Policy guidelines
          minItems: 0
          maxItems: 2000
        type:
          type: string
          description: Type of policy to be created
          enum:
          - PTO
          - TOIL
          - VACATION
          - SICK
          - MEDICAL
          - JURY
          - OFFSITE
          - PARENTAL
          - UNPAID
          - DISABILITY_SHORT
          - DISABILITY_LONG
          - BEREAVEMENT
          - MILITARY
          - RELIGIOUS
          - VOTING
          - VOLUNTEER
          - UNKNOWN
        status:
          type: string
          description: Status of the policy
          enum:
          - ACTIVE
          - INACTIVE
        allocationType:
          type: string
          description: Whether the time off is accrued, received upfront, or is an unlimited policy
          enum:
          - UPFRONT
          - UNLIMITED
          - ACCRUAL
        annualAllocation:
          type: number
          description: Number of days allocated annually
        accrualConfig:
          description: Configuration for how time off is accrued.
          $ref: '#/components/schemas/AccrualConfig'
        maxConsecutiveDaysPerRequest:
          type: number
          description: An optional max number of days allowed per request
        minBalance:
          type: number
          description: An optional minimum balance
        enableCarryOverBalance:
          type: boolean
          description: Enable carry over balance.
        maxCarryOverBalance:
          type: number
          description: An optional maximum carry over balance
        carryOverExpirationDate:
          type: string
          description: Month and day of carry over expiration.
        carryOverExpirationMonths:
          type: integer
          format: int32
          description: Months after carry over date that carry over expires.
        enablePartialDayRequests:
          type: boolean
          description: Allow half day requests
        partialDayGranularity:
          type: number
          description: Partial day requests can only be made down to this level of granularity (i.e. request % granularity == 0)
        enablePartialDayPeriod:
          type: boolean
          description: Allow specifying periods of time (e.g. AM, PM) for partial days
        disableRequests:
          type: boolean
          description: Whether to disable time off requests for this policy
        noteRequired:
          type: boolean
          description: Whether a note is required for time off requests
        filter:
          type: string
          description: CQL used to determine which jobs the policy applies to
        holidayCalendarId:
          type: string
          description: an associated holiday calendar, days on this calendar are not deducted from the time off balance
          example: 588f7ee98f138b19220041a7
        disableProratedAllocation:
          type: boolean
          description: whether limited allocation policies are prorated based on person start date
        prorationRounding:
          type: string
          description: rounding method for prorating calculations
          enum:
          - UP
          - NEAREST
          - HALF
        yearStartDate:
          type: string
          description: Month and day of policy year rollover. Defaults to January 1.
        policyFromDate:
          type: string
          format: date
          description: The date on which this policy's balance/accrual settings come into effect. The policy may have entries before this date, but it will not generate e.g. accrual entries.
        policyUntilDate:
          type: string
          format: date
          description: The first date after this policy's balance/accrual settings end (i.e. the exclusive end date). The policy may have entries after this date, but it will not generate e.g. accrual entries.
        workDays:
          type: array
          description: Days of the week that count against the time off balance. Defaults to Monday through Friday if not set.
          uniqueItems: true
          items:
            type: string
            enum:
            - MONDAY
            - TUESDAY
            - WEDNESDAY
            - THURSDAY
            - FRIDAY
            - SATURDAY
            - SUNDAY
        policyEvents:
          type: array
          items:
            $ref: '#/components/schemas/PolicyEvent'
        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'
    CreateTimeOffPolicy:
      type: object
      required:
      - name
      - type
      - status
      - allocationType
      - filter
      properties:
        name:
          type: string
          description: Internal policy name
          example: US Part-Time/Intern
          minItems: 1
          maxItems: 80
        displayName:
          type: string
          description: External policy name displayed to users
          example: PTO
          minItems: 1
          maxItems: 80
        description:
          type: string
          description: Policy description
          example: Annual sick days allotted to employees
          minItems: 0
          maxItems: 2000
        guidelines:
          type: string
          description: Policy guidelines
          minItems: 0
          maxItems: 2000
        type:
          type: string
          description: Type of policy to be created
          enum:
          - PTO
          - TOIL
          - VACATION
          - SICK
          - MEDICAL
          - JURY
          - OFFSITE
          - PARENTAL
          - UNPAID
          - DISABILITY_SHORT
          - DISABILITY_LONG
          - BEREAVEMENT
          - MILITARY
          - RELIGIOUS
          - VOTING
          - VOLUNTEER
          - UNKNOWN
        status:
          type: string
          description: Status of the policy
          enum:
          - ACTIVE
          - INACTIVE
        allocationType:
          type: string
          description: Whether the time off is accrued, received upfront, or is an unlimited policy
          enum:
          - UPFRONT
          - UNLIMITED
          - ACCRUAL
        annualAllocation:
          type: number
          description: Number of days allocated annually
        accrualConfig:
          description: Configuration for how time off is accrued.
          $ref: '#/components/schemas/AccrualConfig'
        maxConsecutiveDaysPerRequest:
          type: number
          description: An optional max number of days allowed per request
        minBalance:
          type: number
          description: An optional minimum balance
        enableCarryOverBalance:
          type: boolean
          description: Enable carry over balance.
        maxCarryOverBalance:
          type: number
          description: An optional maximum carry over balance
        carryOverExpirationDate:
          type: string
          description: Month and day of carry over expiration.
        carryOverExpirationMonths:
          type: integer
          format: int32
          description: Months after carry over date that carry over expires.
        enablePartialDayRequests:
          type: boolean
          description: Allow half day requests
        partialDayGranularity:
          type: number
          description: Partial day requests can only be made down to this level of granularity (i.e. request % granularity == 0)
        enablePartialDayPeriod:
          type: boolean
          description: Allow specifying periods of time (e.g. AM, PM) for partial days
        disableRequests:
          type: boolean
          description: Whether to disable time off requests for this policy
        noteRequired:
          type: boolean
          description: Whether a note is required for time off requests
        filter:
          type: string
          description: CQL used to determine which jobs the policy applies to
        holidayCalendarId:
          type: string
          description: an associated holiday calendar, days on this calendar are not deducted from the time off balance
          example: 588f7ee98f138b19220041a7
        disableProratedAllocation:
          type: boolean
          description: whether limited allocation policies are prorated based on person start date
        prorationRounding:
          type: string
          description: rounding method for prorating calculations
          enum:
          - UP
          - NEAREST
          - HALF
        yearStartDate:
          type: string
          description: Month and day of policy year rollover. Defaults to January 1.
        policyFromDate:
          type: string
          format: date
          description: The date on which this policy's balance/accrual settings come into effect. The policy may have entries before this date, but it will not generate e.g. accrual entries.
        policyUntilDate:
          type: string
          format: date
          description: The first date after this policy's balance/accrual settings end (i.e. the exclusive end date). The policy may have entries after this date, but it will not generate e.g. accrual entries.
        workDays:
          type: array
          description: Days of the week that count against the time off balance. Defaults to Monday through Friday if not set.
          uniqueItems: true
          items:
            type: string
            enum:
            - MONDAY
            - TUESDAY
            - WEDNESDAY
            - THURSDAY
            - FRIDAY
            - SATURDAY
            - SUNDAY
        policyEvents:
          type: array
          items:
            $ref: '#/components/schemas/PolicyEvent'
    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
    TimeOffBalanceAdjustmentBody:
      type: object
      required:
      - balances
      properties:
        balances:
          type: array
          items:
            $ref: '#/components/schemas/RequestedBalanceAdjustment'
    AccrualConfig:
      type: object
      required:
      - frequency
      - accrualOffsetFromStartDate
      properties:
        frequency:
          type: string
          enum:
          - SEMI_MONTHLY
          - MONTHLY
          - WEEKLY
        monthlyDaysOfMonth:
          type: array
          items:
            type: integer
            format: int32
        weeklyStartDate:
          type: string
          format: date
        weeklyIncrement:
          type: integer
          format: int32
        balanceCapInWholeDays:
          type: integer
          format: int32
        accrualOffsetFromStartDate:
          type: integer
          format: int32
    Process:
      type: object
      required:
      - id
      - orgId
      - label
      - type
      - status
      - runUserId
      - createId
      - createAt
      - options
      properties:
        id:
          type: string
          description: globally unique id
          example: 588f7ee98f138b19220041a7
        orgId:
          type: string
          description: parent org id
          example: 588f7ee98f138b19220041a7
        label:
          type: string
          description: human-readable label that identifies this process
        type:
          type: string
          description: process type
        status:
          type: string
          description: current status of process
          enum:
          - PENDING
          - RUNNING
          - DONE
          - ERROR
        filePath:
          type: string
          description: data file path
        logPath:
          type: string
          description: data log path
        runUserId:
          type: string


# --- truncated at 32 KB (34 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/charthop/refs/heads/main/openapi/charthop-timeoffpolicy-api-openapi.yml