Manage the employee directory in Sage HR — list active and terminated employees, fetch an employee by ID, create new employees, update employee records and custom fields, retrieve compensation history, and process terminations. Backed by the /employees and /terminated-employees resource trees.
openapi: 3.0.0
info:
description: "All requests are required to be sent to your subdomain. To learn how\
\ to enable API in your Sage HR account, please visit https://support.sage.hr/en/articles/3246469-how-does-cakehr-api-work"
title: Sage HR API
version: "1.0"
x-konfig-ignore:
potential-incorrect-type: true
x-konfig-uses-multipart-form-data: true
servers:
- url: https://subdomain.sage.hr/api
tags:
- name: Integrations
- name: Employee
- name: Leave management
- name: Recruitment
- name: Performance
- name: KIT days
- name: Policies
- name: Documents
- name: Onboarding
- name: Offboarding
- name: Positions
- name: Teams
- name: Timesheets
- name: Terminations reasons
paths:
/employees:
get:
operationId: Employee_listActiveEmployees
parameters:
- example: 2
explode: true
in: query
name: page
required: false
schema:
type: integer
style: form
x-konfig-original-example: 2
- example: true
explode: true
in: query
name: team_history
required: false
schema:
type: boolean
style: form
x-konfig-original-example: true
- example: true
explode: true
in: query
name: employment_status_history
required: false
schema:
type: boolean
style: form
x-konfig-original-example: true
- example: true
explode: true
in: query
name: position_history
required: false
schema:
type: boolean
style: form
x-konfig-original-example: true
responses:
"200":
content:
application/json:
examples:
response:
value:
data:
- id: 19
email: john@example.com
first_name: John
last_name: Doe
picture_url: https://example.com/john.png
employment_start_date: 2014-08-25
date_of_birth: 1991-02-13
team: Sage HR
team_id: 1
position: Api developer
position_id: 123
reports_to_employee_id: 5
work_phone: 555-0505
home_phone: 555-0506
mobile_phone: 555-0507
gender: Male
street_first: 84 Glenwood Street
street_second: Peoria
city: London
post_code: 99999
country: GB
employee_number: A01
employment_status: Full-time
team_history:
- team_id: 1
start_date: 2018-01-01
end_date: 201-01-01
team_name: Some Team
employment_status_history:
- employment_status_id: 1
start_date: 2018-01-01
end_date: 201-01-01
employment_statu_name: Full time
position_history:
- position_id: 1
start_date: 2018-01-01
end_date: 201-01-01
position_name: Developer
position_code: "1234"
meta:
current_page: 1
next_page: 2
previous_page: null
total_pages: 2
per_page: 50
total_entries: 75
schema:
$ref: '#/components/schemas/EmployeeListActiveEmployeesResponse'
description: "Successful Response, team_history/employment_status_history/position_history\
\ collections are returned only if regarding optional paramters are provided\
\ in query"
security:
- api_key: []
summary: List active employees in company
tags:
- Employee
x-konfig-operation-can-have-single-parameter: true
x-konfig-single-parameter-schema: konfig-generated-schema-single-parameter-schema-get--employees
x-accepts: application/json
post:
operationId: Employee_createNewEmployee
requestBody:
content:
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/EmployeeCreateNewEmployeeRequest'
required: true
responses:
"201":
content:
application/json:
examples:
response:
value:
data:
id: 1
schema:
$ref: '#/components/schemas/EmployeeCreateNewEmployeeResponse'
description: Successful Response
summary: Create new employee
tags:
- Employee
x-konfig-operation-can-have-single-parameter: true
x-konfig-single-parameter-schema: konfig-generated-schema-single-parameter-schema-post--employees
x-content-type: application/x-www-form-urlencoded
x-accepts: application/json
summary: Employees
/employees/{id}:
get:
operationId: Employee_getById
parameters:
- description: Numeric ID of the user to get.
explode: false
in: path
name: id
required: true
schema:
type: integer
style: simple
- example: true
explode: true
in: query
name: team_history
required: false
schema:
type: boolean
style: form
x-konfig-original-example: true
- example: true
explode: true
in: query
name: employment_status_history
required: false
schema:
type: boolean
style: form
x-konfig-original-example: true
- example: true
explode: true
in: query
name: position_history
required: false
schema:
type: boolean
style: form
x-konfig-original-example: true
responses:
"200":
content:
application/json:
examples:
response:
value:
data:
id: 19
email: john@example.com
first_name: John
last_name: Doe
picture_url: https://example.com/john.png
employment_start_date: 2014-08-25
date_of_birth: 1991-02-13
team: Sage HR
team_id: 6742
position: Api developer
position_id: 123
reports_to_employee_id: 5
work_phone: 555-0505
home_phone: 555-0506
mobile_phone: 555-0507
gender: Male
street_first: 84 Glenwood Street
street_second: Peoria
city: London
post_code: 99999
country: GB
employee_number: A1
employment_status: Full-time
team_history:
- team_id: 1
start_date: 2018-01-01
end_date: 201-01-01
team_name: Some Team
employment_status_history:
- employment_status_id: 1
start_date: 2018-01-01
end_date: 201-01-01
employment_statu_name: Full time
position_history:
- position_id: 1
start_date: 2018-01-01
end_date: 201-01-01
position_name: Developer
position_code: "1234"
schema:
$ref: '#/components/schemas/EmployeeGetByIdResponse'
description: "Successful Response, team_history/employment_status_history/position_history\
\ collections are returned only if regarding optional paramters are provided\
\ in query"
security:
- api_key: []
summary: Single active employee in company
tags:
- Employee
x-konfig-operation-can-have-single-parameter: true
x-konfig-single-parameter-schema: konfig-generated-schema-single-parameter-schema-get--employees-id
x-accepts: application/json
put:
operationId: Employee_updateById
parameters:
- description: Numeric ID of the user to update.
explode: false
in: path
name: id
required: true
schema:
type: integer
style: simple
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/EmployeeUpdateByIdRequest'
responses:
"202":
content:
application/json:
examples:
response:
value:
data:
id: 1711
schema:
$ref: '#/components/schemas/EmployeeUpdateByIdResponse'
description: Accepted
"404":
content:
application/json:
examples:
response:
value:
error_code: not_found
errors: []
schema:
$ref: '#/components/schemas/EmployeeUpdateById404Response'
description: Not Found
x-do-not-generate: true
summary: Update Employee
tags:
- Employee
x-konfig-operation-can-have-single-parameter: true
x-konfig-single-parameter-schema: konfig-generated-schema-single-parameter-schema-put--employees-id
x-content-type: application/json
x-accepts: application/json
summary: Employee
/employees/{id}/custom-fields:
get:
operationId: Employee_getCustomFields
parameters:
- description: Numeric ID of the user to get.
explode: false
in: path
name: id
required: true
schema:
type: integer
style: simple
responses:
"200":
content:
application/json:
examples:
response:
value:
data:
- id: 1
label: Hobby
type: CustomDropdownField
value: Hockey
options:
- Hockey
- Football
- Voleyball
- id: 2
label: Languages
type: CustomTags
options: null
value:
- English
- Latvian
- Estonian
schema:
$ref: '#/components/schemas/EmployeeGetCustomFieldsResponse'
description: Successful Response
security:
- api_key: []
summary: Employee custom fields
tags:
- Employee
x-konfig-operation-can-have-single-parameter: true
x-konfig-single-parameter-schema: konfig-generated-schema-single-parameter-schema-get--employees-id-custom-fields
x-accepts: application/json
summary: Custom fields
/employees/{id}/custom-fields/{custom_field_id}:
put:
description: Update employee custom field
operationId: Employee_updateCustomField
parameters:
- description: Employee identifier
explode: false
in: path
name: id
required: true
schema:
type: integer
style: simple
- description: Custom field identifier
explode: false
in: path
name: custom_field_id
required: true
schema:
type: integer
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/EmployeeUpdateCustomFieldRequest'
required: true
responses:
"200":
content:
application/json:
examples:
response:
value:
data: null
schema:
$ref: '#/components/schemas/EmployeeUpdateCustomFieldResponse'
description: Successful Response
"422":
content:
application/json:
examples:
response:
value:
error_code: validation_failed
errors:
- Custom field text too long (max 250 characters)
schema:
$ref: '#/components/schemas/EmployeeUpdateCustomField422Response'
description: Unprocessable entity
x-do-not-generate: true
summary: Update custom field
tags:
- Employee
x-konfig-operation-can-have-single-parameter: true
x-konfig-single-parameter-schema: konfig-generated-schema-single-parameter-schema-put--employees-id-custom-fields-custom_field_id
x-content-type: application/x-www-form-urlencoded
x-accepts: application/json
summary: Custom field
/employees/{id}/terminations:
post:
operationId: Employee_terminateEmployee
parameters:
- description: Numeric ID of the user
explode: false
in: path
name: id
required: true
schema:
type: integer
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/EmployeeTerminateEmployeeRequest'
required: true
responses:
"201":
content:
application/json:
examples:
response:
value:
data: {}
schema:
$ref: '#/components/schemas/EmployeeTerminateEmployeeResponse'
description: Successful Response
security:
- api_key: []
summary: Terminate employee
tags:
- Employee
x-konfig-operation-can-have-single-parameter: true
x-konfig-single-parameter-schema: konfig-generated-schema-single-parameter-schema-post--employees-id-terminations
x-content-type: application/x-www-form-urlencoded
x-accepts: application/json
summary: Terminate employee
/terminated-employees:
get:
operationId: Employee_listTerminatedEmployees
parameters:
- example: 2
explode: true
in: query
name: page
required: false
schema:
type: integer
style: form
x-konfig-original-example: 2
responses:
"200":
content:
application/json:
examples:
response:
value:
data:
- id: 19
termination_date: 2015-05-28
employee_number: "123"
email: john@example.com
first_name: John
last_name: Doe
picture_url: https://example.com/john.png
employment_start_date: 2014-08-25
date_of_birth: 1991-02-13
position: Api developer
meta:
current_page: 1
next_page: 2
previous_page: null
total_pages: 2
per_page: 50
total_entries: 75
schema:
$ref: '#/components/schemas/EmployeeListTerminatedEmployeesResponse'
description: Successful Response
security:
- api_key: []
summary: List terminated employees in company
tags:
- Employee
x-konfig-operation-can-have-single-parameter: true
x-konfig-single-parameter-schema: konfig-generated-schema-single-parameter-schema-get--terminated-employees
x-accepts: application/json
summary: Terminated employees
/terminated-employees/{id}:
get:
operationId: Employee_getTerminatedEmployee
parameters:
- description: Numeric ID of the user to get.
explode: false
in: path
name: id
required: true
schema:
type: integer
style: simple
responses:
"200":
content:
application/json:
examples:
response:
value:
data:
id: 19
termination_date: 2015-05-28
email: john@example.com
first_name: John
last_name: Doe
picture_url: https://example.com/john.png
employment_start_date: 2014-08-25
date_of_birth: 1991-02-13
position: Api developer
termination:
reason: Moving location
comments: Moving to
schema:
$ref: '#/components/schemas/EmployeeGetTerminatedEmployeeResponse'
description: Successful Response
security:
- api_key: []
summary: Single terminated employee in company
tags:
- Employee
x-konfig-operation-can-have-single-parameter: true
x-konfig-single-parameter-schema: konfig-generated-schema-single-parameter-schema-get--terminated-employees-id
x-accepts: application/json
summary: Terminated employee
/leave-management/policies:
get:
operationId: LeaveManagement_listTimeOffPolicies
parameters: []
responses:
"200":
content:
application/json:
examples:
response:
value:
data:
- id: 1
name: Vacation
color: '#49B284'
do_not_accrue: false
unit: days
default_allowance: "26"
max_carryover: "100.0"
accrue_type: yearly
- id: 2
name: Sickday
color: '#DB263F'
do_not_accrue: true
unit: days
default_allowance: "0.0"
max_carryover: "0.0"
accrue_type: no_tracking
schema:
$ref: '#/components/schemas/LeaveManagementListTimeOffPoliciesResponse'
description: Successful Response
security:
- api_key: []
summary: List time off policies
tags:
- Leave management
x-konfig-operation-can-have-single-parameter: true
x-konfig-single-parameter-schema: konfig-generated-schema-single-parameter-schema-get--leave-management-policies
x-accepts: application/json
summary: Time off policies
/leave-management/policies/{id}:
get:
operationId: LeaveManagement_getTimeOffPolicyById
parameters:
- description: Numeric ID of the policy to get.
explode: false
in: path
name: id
required: true
schema:
type: integer
style: simple
responses:
"200":
content:
application/json:
examples:
response:
value:
data:
- id: 1
name: Vacation
color: '#3a7dd8'
do_not_accrue: false
unit: days
default_allowance: "25.0"
max_carryover: "100.0"
accrue_type: yearly
enable_employee_access: true
only_full_days: false
enable_probation_period: false
dont_allow_negative_amount: false
requests_in_advance_required: false
enable_minimum_days: false
enable_limited_days: false
enable_dependent_policy": false
blocks_enabled: false
no_reset: false
termination_recalculation: true
enable_service_accruals: false
child_allowance_enabled: false
enable_negative_carryover: false
max_accrual: false
accrue_at_start: true
enable_monthly_expiration: false
starter_monthly_accrual_limitation: false
starter_yearly_accrual_limitation: false
auto_approves: false
enable_specific_approvers: false
override_approvers_enabled: false
enable_duplicate_time_offs: false
enable_replacement: false
replacement_required: false
enable_scopped_replacement: false
enable_replacement_away: false
enable_details: true
require_details: false
additional_field: true
enable_attachment: false
schema:
$ref: '#/components/schemas/LeaveManagementGetTimeOffPolicyByIdResponse'
description: Successful Response
security:
- api_key: []
summary: Details about a time off policy
tags:
- Leave management
x-konfig-operation-can-have-single-parameter: true
x-konfig-single-parameter-schema: konfig-generated-schema-single-parameter-schema-get--leave-management-policies-id
x-accepts: application/json
patch:
operationId: LeaveManagement_updateKitDaysConfiguration
parameters:
- description: Numeric ID of the policy to get.
explode: false
in: path
name: id
required: true
schema:
type: integer
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/LeaveManagementUpdateKitDaysConfigurationRequest'
required: true
responses:
"200":
description: Successful Response
"422":
content:
application/json:
examples:
response:
value:
error_code: invalid_policy_type
errors:
- The policy specified is not an event-based policy
schema:
$ref: '#/components/schemas/LeaveManagementUpdateKitDaysConfigurationResponse'
description: Unprocessable entity
x-do-not-generate: true
security:
- api_key: []
summary: Update KIT days configuration of a time off policy
tags:
- Leave management
- KIT days
x-konfig-operation-can-have-single-parameter: true
x-konfig-single-parameter-schema: konfig-generated-schema-single-parameter-schema-patch--leave-management-policies-id
x-content-type: application/x-www-form-urlencoded
x-accepts: application/json
summary: Time off policy
/leave-management/kit-days:
get:
operationId: LeaveManagement_getKitDays
parameters:
- description: Time-off policy identifier
example: 1
explode: true
in: query
name: policy_id
required: true
schema:
type: integer
style: form
x-konfig-original-example: 1
- description: Employee identifier
example: 2
explode: true
in: query
name: employee_id
required: true
schema:
type: integer
style: form
x-konfig-original-example: 2
responses:
"200":
content:
application/json:
examples:
response:
value:
data:
- id: 1
status: declined
start_date: 2021-03-09
end_date: 2021-03-10
- id: 2
status: approved
start_date: 2021-03-09
end_date: 2021-03-10
schema:
$ref: '#/components/schemas/LeaveManagementGetKitDaysResponse'
description: Successful Response
security:
- api_key: []
summary: View all the KIT days of an employee in a policy
tags:
- Leave management
- KIT days
- Policies
x-konfig-operation-can-have-single-parameter: true
x-konfig-single-parameter-schema: konfig-generated-schema-single-parameter-schema-get--leave-management-kit-days
x-accepts: application/json
post:
operationId: LeaveManagement_createKitDay
parameters: []
requestBody:
content:
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/LeaveManagementCreateKitDayRequest'
required: true
responses:
"200":
content:
application/json:
examples:
response:
value:
data:
- id: 1
schema:
$ref: '#/components/schemas/LeaveManagementCreateKitDayResponse'
description: Successful Response
"422":
content:
application/json:
examples:
response:
value:
error_code: validation_failed
errors:
- First error
- Second error
schema:
$ref: '#/components/schemas/LeaveManagementCreateKitDay422Response'
description: Unprocessable entity
x-do-not-generate: true
security:
- api_key: []
summary: Create a KIT day in a leave
tags:
- Leave management
- KIT days
- Policies
x-konfig-operation-can-have-single-parameter: true
x-konfig-single-parameter-schema: konfig-generated-schema-single-parameter-schema-post--leave-management-kit-days
x-content-type: application/x-www-form-urlencoded
x-accepts: application/json
summary: KIT days
/leave-management/kit-days/{id}:
patch:
operationId: LeaveManagement_processKitDay
parameters:
- description: KIT day identifier
explode: false
in: path
name: id
required: true
schema:
type: integer
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/LeaveManagementProcessKitDayRequest'
required: true
responses:
"200":
description: Successful Response
security:
- api_key: []
summary: "Approve, decline or cancel a KIT day"
tags:
- Leave management
- KIT days
- Policies
x-konfig-operation-can-have-single-parameter: true
x-konfig-single-parameter-schema: konfig-generated-schema-single-parameter-schema-patch--leave-management-kit-days-id
x-content-type: application/x-www-form-urlencoded
x-accepts: application/json
summary: KIT days
/leave-management/reports/individual-allowances:
get:
operationId: LeaveManagement_getIndividualAllowances
parameters:
- example: 2
explode: true
in: query
name: page
required: false
schema:
type: integer
style: form
x-konfig-original-example: 2
- example: 25
explode: true
in: query
name: per_page
required: false
schema:
type: integer
style: form
x-konfig-original-example: 25
- description: Limit the reports to employees in specified location ids
example:
- 14
- 13
explode: false
in: query
name: location_ids
required: false
schema:
items:
type: integer
type: array
style: form
x-konfig-original-example:
- 14
- 13
- description: Limit the reports to selected employee ids
example:
- 1
- 2
- 3
explode: false
in: query
name: employee_ids
required: false
schema:
items:
type: integer
type: array
style: form
x-konfig-original-example:
- 1
- 2
- 3
- description: Limit the reports to employees in specified team ids
example:
- 1
explode: false
in: query
name: team_ids
required: false
schema:
items:
type: integer
type: array
style: form
x-konfig-original-example:
- 1
responses:
"200":
content:
application/json:
examples:
response:
value:
data:
- full_name: Joe Doe
id: 11
eligibilities:
- policy:
name: Sickday
id: 2
quantity: "0.0"
unit: days
carryover: "0.0"
- policy:
name: Vacation
id: 1
quantity: "25.0"
unit: days
carryover: "100.0"
- full_name: Jane Doe
id: 13
eligibilities:
- policy:
name: Custom Policy
id: 4
quantity: "0.0"
unit: days
carryover: "0.0"
- policy:
name: Vacation
id: 1
quantity: "25.0"
unit: days
carryover: "100.0"
meta:
current_page: 1
next_page: null
previous_page: null
total_pages: 1
per_page: 25
total_entries: 1
schema:
$ref: '#/components/schemas/LeaveManagementGetIndividualAllowancesResponse'
description: Successful Response
security:
- api_key: []
summary: Report with individual allowances
tags:
- Leave management
x-konfig-operation-can-have-single-parameter: true
x-konfig-single-parameter-schema: konfig-generated-schema-single-parameter-schema-get--leave-management-reports-individual-allowances
x-accepts: application/json
summary: Individual Allowances
/employees/{id}/leave-management/balances:
get:
operationId: LeaveManagement_getTimeOffBalances
parameters:
- description: Numeric ID of the user to get.
explode: false
in: path
name: id
required: true
schema:
type: integer
style: simple
responses:
"200":
content:
application/json:
examples:
response:
value:
data:
- policy_id: 1
used: 5.6
available: 2
- policy_id: 2
used: 75
available: null
schema:
$ref: '#/components/schemas/LeaveManagementGetTimeOffBalancesResponse'
description: Successful Response
security:
- api_
# --- truncated at 32 KB (535 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/sage-hr/refs/heads/main/openapi/sage-hr-openapi.yml