Sage HR Employee API
The Employee API from Sage HR — 9 operation(s) for employee.
OpenAPI Specification
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 Documents Employee 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: Employee
paths:
/employees:
summary: 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
/employees/{id}:
summary: Employee
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
/employees/{id}/custom-fields:
summary: 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
/employees/{id}/custom-fields/{custom_field_id}:
summary: Custom field
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
/employees/{id}/terminations:
summary: Terminate employee
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
/terminated-employees:
summary: 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
/terminated-employees/{id}:
summary: Terminated employee
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
/employees/{id}/leave-management/balances:
summary: Employee time off 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_key: []
summary: Employee time off balances
tags:
- Employee
x-konfig-operation-can-have-single-parameter: true
x-konfig-single-parameter-schema: konfig-generated-schema-single-parameter-schema-get--employees-id-leave-management-balances
x-accepts: application/json
/employees/{id}/compensations:
summary: Compensation
get:
operationId: Employee_getCompensations
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:
- start_date: 2017-01-01
end_date: 2019-01-01
currency: EUR
amount: 1234
period: monthly
comment: Starting salary
category: Salary
meta:
current_page: 1
next_page: 2
previous_page: null
total_pages: 2
per_page: 50
total_entries: 75
schema:
$ref: '#/components/schemas/EmployeeGetCompensationsResponse'
description: Successful Response
security:
- api_key: []
summary: Employee compensations
tags:
- Employee
x-konfig-operation-can-have-single-parameter: true
x-konfig-single-parameter-schema: konfig-generated-schema-single-parameter-schema-get--employees-id-compensations
x-accepts: application/json
components:
schemas:
EmployeeGetByIdResponse_data:
properties:
id:
example: 19
type: number
x-konfig-original-example: 19
x-konfig-generated-schema: konfig-generated-schema-components-schemas-EmployeeGetByIdResponse-properties-data-properties-id
email:
example: john@example.com
type: string
x-konfig-original-example: john@example.com
x-konfig-generated-schema: konfig-generated-schema-components-schemas-EmployeeGetByIdResponse-properties-data-properties-email
first_name:
example: John
type: string
x-konfig-original-example: John
x-konfig-generated-schema: konfig-generated-schema-components-schemas-EmployeeGetByIdResponse-properties-data-properties-first_name
last_name:
example: Doe
type: string
x-konfig-original-example: Doe
x-konfig-generated-schema: konfig-generated-schema-components-schemas-EmployeeGetByIdResponse-properties-data-properties-last_name
picture_url:
example: https://example.com/john.png
type: string
x-konfig-original-example: https://example.com/john.png
x-konfig-generated-schema: konfig-generated-schema-components-schemas-EmployeeGetByIdResponse-properties-data-properties-picture_url
employment_start_date:
example: 2014-08-25
type: string
x-konfig-original-example: 2014-08-25
x-konfig-generated-schema: konfig-generated-schema-components-schemas-EmployeeGetByIdResponse-properties-data-properties-employment_start_date
date_of_birth:
example: 1991-02-13
type: string
x-konfig-original-example: 1991-02-13
x-konfig-generated-schema: konfig-generated-schema-components-schemas-EmployeeGetByIdResponse-properties-data-properties-date_of_birth
team:
example: Sage HR
type: string
x-konfig-original-example: Sage HR
x-konfig-generated-schema: konfig-generated-schema-components-schemas-EmployeeGetByIdResponse-properties-data-properties-team
team_id:
example: 6742
type: number
x-konfig-original-example: 6742
x-konfig-generated-schema: konfig-generated-schema-components-schemas-EmployeeGetByIdResponse-properties-data-properties-team_id
position:
example: Api developer
type: string
x-konfig-original-example: Api developer
x-konfig-generated-schema: konfig-generated-schema-components-schemas-EmployeeGetByIdResponse-properties-data-properties-position
position_id:
example: 123
type: number
x-konfig-original-example: 123
x-konfig-generated-schema: konfig-generated-schema-components-schemas-EmployeeGetByIdResponse-properties-data-properties-position_id
reports_to_employee_id:
example: 5
type: number
x-konfig-original-example: 5
x-konfig-generated-schema: konfig-generated-schema-components-schemas-EmployeeGetByIdResponse-properties-data-properties-reports_to_employee_id
work_phone:
example: 555-0505
type: string
x-konfig-original-example: 555-0505
x-konfig-generated-schema: konfig-generated-schema-components-schemas-EmployeeGetByIdResponse-properties-data-properties-work_phone
home_phone:
example: 555-0506
type: string
x-konfig-original-example: 555-0506
x-konfig-generated-schema: konfig-generated-schema-components-schemas-EmployeeGetByIdResponse-properties-data-properties-home_phone
mobile_phone:
example: 555-0507
type: string
x-konfig-original-example: 555-0507
x-konfig-generated-schema: konfig-generated-schema-components-schemas-EmployeeGetByIdResponse-properties-data-properties-mobile_phone
gender:
example: Male
type: string
x-konfig-original-example: Male
x-konfig-generated-schema: konfig-generated-schema-components-schemas-EmployeeGetByIdResponse-properties-data-properties-gender
street_first:
example: 84 Glenwood Street
type: string
x-konfig-original-example: 84 Glenwood Street
x-konfig-generated-schema: konfig-generated-schema-components-schemas-EmployeeGetByIdResponse-properties-data-properties-street_first
street_second:
example: Peoria
type: string
x-konfig-original-example: Peoria
x-konfig-generated-schema: konfig-generated-schema-components-schemas-EmployeeGetByIdResponse-properties-data-properties-street_second
city:
example: London
type: string
x-konfig-original-example: London
x-konfig-generated-schema: konfig-generated-schema-components-schemas-EmployeeGetByIdResponse-properties-data-properties-city
post_code:
example: 99999
type: number
x-konfig-original-example: 99999
x-konfig-generated-schema: konfig-generated-schema-components-schemas-EmployeeGetByIdResponse-properties-data-properties-post_code
country:
example: GB
type: string
x-konfig-original-example: GB
x-konfig-generated-schema: konfig-generated-schema-components-schemas-EmployeeGetByIdResponse-properties-data-properties-country
employee_number:
example: A1
type: string
x-konfig-original-example: A1
x-konfig-generated-schema: konfig-generated-schema-components-schemas-EmployeeGetByIdResponse-properties-data-properties-employee_number
employment_status:
example: Full-time
type: string
x-konfig-original-example: Full-time
x-konfig-generated-schema: konfig-generated-schema-components-schemas-EmployeeGetByIdResponse-properties-data-properties-employment_status
team_history:
items:
$ref: '#/components/schemas/EmployeeGetByIdResponse_data_team_history_inner'
type: array
employment_status_history:
items:
$ref: '#/components/schemas/EmployeeGetByIdResponse_data_employment_status_history_inner'
type: array
position_history:
items:
$ref: '#/components/schemas/EmployeeGetByIdResponse_data_position_history_inner'
type: array
type: object
EmployeeGetTerminatedEmployeeResponse_data_termination:
properties:
reason:
example: Moving location
type: string
x-konfig-original-example: Moving location
x-konfig-generated-schema: konfig-generated-schema-components-schemas-EmployeeGetTerminatedEmployeeResponse-properties-data-properties-termination-properties-reason
comments:
example: Moving to
type: string
x-konfig-original-example: Moving to
x-konfig-generated-schema: konfig-generated-schema-components-schemas-EmployeeGetTerminatedEmployeeResponse-properties-data-properties-termination-properties-comments
type: object
EmployeeListActiveEmployeesResponse_data_inner_position_history_inner:
properties:
position_id:
example: 1
type: number
x-konfig-original-example: 1
x-konfig-generated-schema: konfig-generated-schema-components-schemas-EmployeeListActiveEmployeesResponse-properties-data-items-properties-position_history-items-properties-position_id
start_date:
example: 2018-01-01
type: string
x-konfig-original-example: 2018-01-01
x-konfig-generated-schema: konfig-generated-schema-components-schemas-EmployeeListActiveEmployeesResponse-properties-data-items-properties-position_history-items-properties-start_date
end_date:
example: 201-01-01
type: string
x-konfig-original-example: 201-01-01
x-konfig-generated-schema: konfig-generated-schema-components-schemas-EmployeeListActiveEmployeesResponse-properties-data-items-properties-position_history-items-properties-end_date
position_name:
example: Developer
type: string
x-konfig-original-example: Developer
x-konfig-generated-schema: konfig-generated-schema-components-schemas-EmployeeListActiveEmployeesResponse-properties-data-items-properties-position_history-items-properties-position_name
position_code:
example: '1234'
type: string
x-konfig-original-example: '1234'
x-konfig-generated-schema: konfig-generated-schema-components-schemas-EmployeeListActiveEmployeesResponse-properties-data-items-properties-position_history-items-properties-position_code
type: object
EmployeeTerminateEmployeeResponse:
example:
data: {}
properties:
data:
properties: {}
type: object
type: object
x-konfig-original-example:
data: {}
x-konfig-generated-schema: konfig-generated-schema-components-schemas-EmployeeTerminateEmployeeResponse
x-konfig-is-used-in-successful-response: true
EmployeeUpdateByIdRequest:
example:
last_name: Doe
employee_number: '0123456'
approver_ids:
- 1
- 1
leader_id: 3
selected_leave_types:
- 2
- 2
team_id: 2
first_name: Jane
work_start_date: 2020-01-28
location_id: 1
position_id: 101
properties:
first_name:
example: Jane
type: string
x-konfig-original-example: Jane
x-konfig-generated-schema: konfig-generated-schema-components-schemas-EmployeeUpdateByIdRequest-properties-first_name
last_name:
example: Doe
type: string
x-konfig-original-example: Doe
x-konfig-generated-schema: konfig-generated-schema-components-schemas-EmployeeUpdateByIdRequest-properties-last_name
work_start_date:
example: 2020-01-28
type: string
x-konfig-original-example: 2020-01-28
x-konfig-generated-schema: konfig-generated-schema-components-schemas-EmployeeUpdateByIdRequest-properties-work_start_date
location_id:
example: 1
type: integer
x-konfig-original-example: 1
x-konfig-generated-schema: konfig-generated-schema-components-schemas-EmployeeUpdateByIdRequest-properties-location_id
team_id:
example: 2
type: integer
x-konfig-original-example: 2
x-konfig-generated-schema: konfig-generated-schema-components-schemas-EmployeeUpdateByIdRequest-properties-team_id
leader_id:
example: 3
type: integer
x-konfig-original-example: 3
x-konfig-generated-schema: konfig-generated-schema-components-schemas-EmployeeUpdateByIdRequest-properties-leader_id
position_id:
example: 101
type: integer
x-konfig-original-example: 101
x-konfig-generated-schema: konfig-generated-schema-components-schemas-EmployeeUpdateByIdRequest-properties-position_id
employee_number:
example: '0123456'
type: string
x-konfig-original-example: '0123456'
x-konfig-generated-schema: konfig-generated-schema-components-schemas-EmployeeUpdateByIdRequest-properties-employee_number
approver_ids:
items:
example: 1
type: integer
x-konfig-original-example: 1
x-konfig-generated-schema: konfig-generated-schema-components-schemas-EmployeeUpdateByIdRequest-properties-approver_ids-items
type: array
selected_leave_types:
items:
example: 2
type: integer
x-konfig-original-example: 2
x-konfig-generated-schema: konfig-generated-schema-components-schemas-EmployeeUpdateByIdRequest-properties-selected_leave_types-items
type: array
type: object
EmployeeUpdateById404Respons
# --- truncated at 32 KB (77 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/sage-hr/refs/heads/main/openapi/sage-hr-employee-api-openapi.yml