> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kombo.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Update Employment

> Update an employment’s compensation or job in the connected HRIS.

<Note>
  This feature is now in closed beta. Please reach out to your account manager
  or [support](mailto:support@kombo.dev).
</Note>

## 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](/hris/features/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

<Steps>
  <Step title="Find the employment">
    Each employee lists their employments in `employments` on [Get employees](/hris/v1/get-employees). You can also use [Get employments](/hris/v1/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.
  </Step>

  <Step title="Get the form">
    `GET` the form for your change:

    * [/hris/employments/\{employment\_id}/form/compensation](/hris/v1/get-employments-employment-id-form-compensation)
    * [/hris/employments/\{employment\_id}/form/job](/hris/v1/get-employments-employment-id-form-job)

    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.

    <Accordion title="Full form examples">
      <Tabs>
        <Tab title="compensation">
          ```json Example Response theme={null}
          {
            "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": []
          }
          ```
        </Tab>

        <Tab title="job">
          ```json Example Response theme={null}
          {
            "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": []
          }
          ```
        </Tab>
      </Tabs>
    </Accordion>
  </Step>

  <Step title="Submit changes">
    `PATCH` the values in `properties` to the same URL:

    * [/hris/employments/\{employment\_id}/form/compensation](/hris/v1/patch-employments-employment-id-form-compensation)
    * [/hris/employments/\{employment\_id}/form/job](/hris/v1/patch-employments-employment-id-form-job)

    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.

    <Tabs>
      <Tab title="compensation">
        ```json Example Request theme={null}
        {
          "properties": {
            "effectiveDate": "2026-11-01",
            "amount": 75000,
            "reason": "4wPdBNLfMYBeXjNiQ5zKbStR"
          }
        }
        ```
      </Tab>

      <Tab title="job">
        ```json Example Request theme={null}
        {
          "properties": {
            "effectiveDate": "2026-11-01",
            "jobTitle": "Head Nurse"
          }
        }
        ```
      </Tab>
    </Tabs>

    <Accordion title="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.
    </Accordion>

    Requires the **Create and manage employees** permission in your [scopes](/hris/features/scopes).
  </Step>

  <Step title="Read the response">
    ```json Example Response theme={null}
    {
      "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.
  </Step>
</Steps>

<Card title="Displaying the Form" icon="book-open" href="/hris/implementation-guide/create-employee" arrow={true}>
  Reuse your create employee form display code. Submit values using the keys
  returned by the update form. This guide explains field types and mapping.
</Card>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.