Sage HR
Sage HR Documents API

List document categories and upload new employee or company documents to Sage HR. Multipart form-data upload via /documents.
Sage HR Documents 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.
Tagged areas include HR, Documents, and Files. The published artifact set on APIs.io includes API documentation, an OpenAPI specification, and 1 Naftiko capability spec.
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 Documents API

Documentation

Specifications

Other Resources

OpenAPI Specification
