Update Employment

This feature is now in closed beta. Please reach out to your account manager or support.

Overview

Update Employment changes data that belongs to one employment of an employee. Get the fields the HRIS accepts, collect the required values and any changes, then submit them. To change the employee’s own details, use Update Employee.

Change	Use it for
`compensation`	Changes to what the employee is paid
`job`	Changes to the employee’s role in the company

Which fields each form has depends on the HRIS and how the company set it up.

Implementation Steps

Find the employment

Each employee lists their employments in employments on Get employees. You can also use Get employments. An employee with more than one employment needs one request per employment you want to change.employment_id accepts the Kombo ID or the HRIS ID with a remote: prefix.

Get the form

GET the form for your change:

If the HRIS can’t make this change, you get INTEGRATION.ACTION_NOT_AVAILABLE, so you can hide the option in your UI.When available, current_value contains the field’s current value in the HRIS for this employment. Use it to prefill the form. null means the field is empty. If the HRIS doesn’t let us read a field, current_value is left out.

Full form examples

compensation
job

Example Response

{
  "status": "success",
  "data": {
    "properties": {
      "effectiveDate": {
        "label": "Effective Date",
        "required": true,
        "description": "Date the new compensation starts",
        "unified_key": null,
        "type": "date",
        "current_value": null
      },
      "amount": {
        "label": "Yearly Salary",
        "required": true,
        "description": "Employee's new yearly salary",
        "unified_key": "yearly_salary",
        "type": "number",
        "min": 0,
        "max": null,
        "current_value": 70000
      },
      "reason": {
        "label": "Reason",
        "required": true,
        "description": "Reason for the change",
        "unified_key": null,
        "type": "single_select",
        "current_value": null,
        "options": {
          "type": "inline",
          "entries": [
            {
              "id": "4wPdBNLfMYBeXjNiQ5zKbStR",
              "label": "Merit Increase",
              "remote_id": "MERIT"
            },
            {
              "id": "9B3Br4Qih9EAxXxbbXr3ubJK",
              "label": "Promotion",
              "remote_id": "PROMOTION"
            }
          ]
        }
      }
    }
  },
  "warnings": []
}

Example Response

{
  "status": "success",
  "data": {
    "properties": {
      "effectiveDate": {
        "label": "Effective Date",
        "required": true,
        "description": "Date the job change starts",
        "unified_key": null,
        "type": "date",
        "current_value": null
      },
      "jobTitle": {
        "label": "Job Title",
        "required": false,
        "description": "Employee's new job title",
        "unified_key": "job_title",
        "type": "text",
        "reg_exp": null,
        "current_value": "Nurse"
      },
      "manager": {
        "label": "Manager",
        "required": false,
        "description": "Employee's new manager",
        "unified_key": null,
        "type": "single_select",
        "current_value": "26vafvWSRmbhNcxJYqjCzuJg",
        "options": {
          "type": "referenced",
          "link": "https://api.kombo.dev/v1/hris/employees?remote_model=employee"
        }
      }
    }
  },
  "warnings": []
}

Submit changes

PATCH the values in properties to the same URL:

Use the field keys returned by GET. Include required fields and any fields you want to change. Omitted fields stay unchanged; null clears a value.

compensation
job

Example Request

{
  "properties": {
    "effectiveDate": "2026-11-01",
    "amount": 75000,
    "reason": "4wPdBNLfMYBeXjNiQ5zKbStR"
  }
}

Example Request

{
  "properties": {
    "effectiveDate": "2026-11-01",
    "jobTitle": "Head Nurse"
  }
}

Rules for updates

Options listed in the form accept the option id or remote:<remote_id>. For options returned by a linked endpoint (options.type: "referenced"), use the Kombo ID.
Dates use YYYY-MM-DD. Whether a past date is allowed depends on the HRIS.

Requires the Create and manage employees permission in your scopes.

Read the response

Example Response

{
  "status": "success",
  "data": {
    "id": "8xQvTmLpRbWcNdKsYfHjGaZe",
    "remote_id": "67890"
  },
  "warnings": []
}

id: The Kombo ID of the employment.
remote_id: The ID of the employment in the HRIS.

A success response means the HRIS saved the change, and Kombo updates its copy of the employment right away.

Displaying the Form

Reuse your create employee form display code. Submit values using the keys returned by the update form. This guide explains field types and mapping.

General

Features

Guides

HRIS API Reference

Payroll API Reference

General API Reference

DATEV

Update Employment

Overview

Implementation Steps

Displaying the Form

​Overview

​Implementation Steps

Displaying the Form

Overview

Implementation Steps