Charthop Time off ledger API
The Time off ledger API from Charthop — 4 operation(s) for time off ledger.
OpenAPI Specification
swagger: '2.0'
info:
description: REST API for ChartHop
version: V1.0.0
title: ChartHop access Time off ledger 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: Time off ledger
paths:
/v1/org/{orgId}/timeoff-ledger:
post:
tags:
- Time off ledger
summary: Create a time off ledger entry
operationId: createLedgerEntry
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
required: true
schema:
$ref: '#/definitions/CreateTimeOffLedgerEntry'
responses:
'201':
description: ledger entry created
'400':
description: bad request
'401':
description: not authorized
'403':
description: forbidden
/v1/org/{orgId}/timeoff-ledger/data:
get:
tags:
- Time off ledger
summary: Query time off ledger entries in the organization, returning particular time off, job, and person data fields
operationId: queryTimeOff
consumes:
- application/json
produces:
- application/json
parameters:
- name: orgId
in: path
description: Org identifier (either id or slug)
required: true
type: string
- name: fields
in: query
description: Fields to retrieve, comma-separated
required: false
type: string
- name: fromDate
in: query
description: From date, inclusive
required: true
type: string
format: date
- name: untilDate
in: query
description: Until date, exclusive
required: true
type: string
format: date
- name: filter
in: query
description: Filter to apply on the person
required: false
type: string
- name: personId
in: query
description: If retrieving from specific people, their personIds, comma-separated
required: false
type: string
- name: policyId
in: query
description: If retrieving for specific time off policies, the policyIds, comma-separated
required: false
type: string
- name: format
in: query
description: Data format to use; default is json, can also use json-extended or json-readable
required: false
type: string
- name: splitColumns
in: query
description: Whether to split complex columns, used for tabular data formats
required: false
type: boolean
responses:
'200':
description: ledger entries found
schema:
$ref: '#/definitions/ResultsData'
'202':
description: snapshot currently building
'400':
description: bad request
'401':
description: not authorized
/v1/org/{orgId}/timeoff-ledger/export:
post:
tags:
- Time off ledger
summary: Payroll export of time off ledger
operationId: exportTimeOffLedger
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
required: true
schema:
$ref: '#/definitions/TimeOffLedgerExportOptions'
responses:
'200':
description: successful operation
schema:
$ref: '#/definitions/Process'
'400':
description: bad request
'401':
description: not authorized
'404':
description: not found
/v1/org/{orgId}/timeoff-ledger/{entryId}:
get:
tags:
- Time off ledger
summary: Get a time off ledger entry by ID
operationId: getLedgerEntry
consumes:
- application/json
produces:
- application/json
parameters:
- name: orgId
in: path
description: Org identifier (either id or slug)
required: true
type: string
- name: entryId
in: path
description: Ledger entry id
required: true
type: string
responses:
'200':
description: successful operation
schema:
$ref: '#/definitions/TimeOffLedgerEntry'
delete:
tags:
- Time off ledger
summary: Delete a time off ledger entry
operationId: deleteLedgerEntry
consumes:
- application/json
produces:
- application/json
parameters:
- name: orgId
in: path
description: Org identifier (either id or slug)
required: true
type: string
- name: entryId
in: path
description: Ledger entry id
required: true
type: string
responses:
'204':
description: ledger entry deleted
'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
TimeOffLedgerExportOptions:
type: object
properties:
fromDate:
type: string
format: date
untilDate:
type: string
format: date
columns:
type: string
filter:
type: string
format:
type: string
splitColumns:
type: boolean
personIds:
type: array
uniqueItems: true
items:
type: string
example: 588f7ee98f138b19220041a7
policyIds:
type: array
uniqueItems: true
items:
type: string
example: 588f7ee98f138b19220041a7
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
description: user id who is running the process
example: 588f7ee98f138b19220041a7
parentProcessId:
type: string
description: process id of parent process
example: 588f7ee98f138b19220041a7
createId:
type: string
description: created by user id (user who requested the process run)
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'
updateId:
type: string
description: last updated by user id
example: 588f7ee98f138b19220041a7
updateBehalfId:
type: string
description: last updated on behalf of user id
example: 588f7ee98f138b19220041a7
updateAttribution:
$ref: '#/definitions/Attribution'
updateAt:
type: string
description: last updated timestamp
example: '2017-01-24T13:57:52Z'
startAt:
type: string
description: started at timestamp
example: '2017-01-24T13:57:52Z'
endAt:
type: string
description: ended at timestamp
example: '2017-01-24T13:57:52Z'
message:
type: string
description: status or error message
progress:
type: number
format: double
description: percent progress so far
internalError:
type: string
description: internal-only error message
options:
type: object
description: options passed to the process
results:
type: object
description: results summary for the process
additionalProperties:
type: object
logDataList:
type: array
description: list of log data that occurred during running of this process
items:
$ref: '#/definitions/LogData'
state:
type: object
description: process-specific state data
summary:
type: string
description: human-readable, searchable summary of what this process did
appId:
type: string
description: app id of the process
example: 588f7ee98f138b19220041a7
uuid:
type: string
description: unique ID of the process at queue time
example: 84db3c6e-0877-4436-8af1-768c06b29586
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'
CreateTimeOffLedgerEntry:
type: object
required:
- orgId
- personId
- entryType
- date
- days
- entryAction
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
timeOffPolicyId:
type: string
description: Time off policy to which this entry pertains.
example: 588f7ee98f138b19220041a7
entryType:
type: string
description: Ledger entry type
enum:
- EXPIRATION
- BALANCE_RESET
- CARRYOVER
- UPFRONT_BALANCE
- ACCRUAL
- ADJUSTMENT
- TIME_OFF
externalId:
type: string
description: external identifier, if this entry exists in an external system
fromDate:
type: string
format: date
description: For time off, from date of time off, inclusive
fromDatePartialDay:
type: number
description: For time off, portion of the from date to take
fromDatePartialDayPeriod:
type: string
description: Portion of the from day requested (e.g. AM or PM)
enum:
- AM
- PM
untilDate:
type: string
format: date
description: For time off, until date of time off, exclusive
endDatePartialDay:
type: number
description: For time off, portion of the end date (day before the until date) to take
endDatePartialDayPeriod:
type: string
description: Portion of the end day requested (e.g. AM or PM)
enum:
- AM
- PM
date:
type: string
format: date
description: date on which this entry appears in the ledger
days:
type: number
description: Change to the balance made by this ledger entry. This value is always nonnegative; it is interpreted in the context of entryAction.
hours:
type: number
description: For time off, number of hours taken
entryAction:
type: string
description: Action this entry takes on the balance.
enum:
- SET
- MIN
- EXPIRE
- CARRYOVER
- ADD
- ADD_CLAMP
- SUBTRACT
typeDescription:
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
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
createAt:
type: string
description: created 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'
description: Time off ledger entry
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
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
ResultsData:
type: object
required:
- data
properties:
data:
type: array
items:
type: object
additionalProperties:
type: object
next:
type: string
access:
type: array
items:
$ref: '#/definitions/ResultsAccess'
totalRow:
type: object
additionalProperties:
type: object
CarryOverBalanceEntry:
type: object
required:
- balance
properties:
balance:
type: number
fromDate:
type: string
format: date
expireDate:
type: string
format: date
TimeOffLedgerEntry:
type: object
required:
- id
- orgId
- personId
- entryType
- date
- entryAction
properties:
id:
type: string
description: Globally unique id of this ledger entry
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
timeOffPolicyId:
type: string
description: Time off policy to which this entry pertains.
example: 588f7ee98f138b19220041a7
entryType:
type: string
description: Ledger entry type
enum:
- EXPIRATION
- BALANCE_RESET
- CARRYOVER
- UPFRONT_BALANCE
- ACCRUAL
- ADJUSTMENT
- TIME_OFF
externalId:
type: string
description: external identifier, if this entry exists in an external system
fromDate:
type: string
format: date
description: For time off, from date of time off, inclusive
fromDatePartialDay:
type: number
description: For time off, portion of the from date to take
fromDatePartialDayPeriod:
type: string
description: Portion of the from day requested (e.g. AM or PM)
enum:
- AM
- PM
untilDate:
type: string
format: date
description: For time off, until date of time off, exclusive
endDatePartialDay:
type: number
description: For time off, portion of the end date (day before the until date) to take
endDatePartialDayPeriod:
type: string
description: Portion of the end day requested (e.g. AM or PM)
enum:
- AM
- PM
date:
type: string
format: date
description: date on which this entry appears in the ledger
days:
type: number
description: Change to the balance made by this ledger entry. This value is always nonnegative; it is interpreted in the context of entryAction.
hours:
type: number
description: For time off, number of hours taken
entryAction:
type: string
description: Action this entry takes on the balance.
enum:
- SET
- MIN
- EXPIRE
- CARRYOVER
- ADD
- ADD_CLAMP
- SUBTRACT
typeDescription:
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
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'
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'
carryOverBalance:
type: array
description: Carry over balance after this ledger entry. Already included in balance.
items:
$ref: '#/definitions/CarryOverBalanceEntry'
balance:
type: number
description: Balance after this ledger entry.
changeFromPrevious:
type: number
description: Balance change from previous entry.
description: Time off ledger entry