Sage HR
Sage HR Employee API

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.
Sage HR Employee API is one of 9 APIs that Sage HR publishes on the APIs.io network, described by a machine-readable OpenAPI specification.
This API exposes 1 machine-runnable capability that can be deployed as REST, MCP, or Agent Skill surfaces via Naftiko and 1 JSON Schema definition.
Tagged areas include HR, HRIS, Employees, and People. The published artifact set on APIs.io includes API documentation, an OpenAPI specification, a JSON-LD context, 1 Naftiko capability spec, and 1 JSON Schema.
Documentation GitHub OpenAPI
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 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: [email protected]
                      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: [email protected]
                      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: [email protected]
                      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: [email protected]
                      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
Sage HR Employee API

Documentation

Specifications

Schemas & Data

Other Resources

OpenAPI Specification
