Charthop timeoff API
The timeoff API from Charthop — 6 operation(s) for timeoff.
OpenAPI Specification
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'