> ## 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 employee personal data

> Update an employee's personal data using values from the personal data form.

> [!WARNING]
>
> **Closed Beta Feature:** This endpoint is now in closed beta. Please reach out to your account manager or [support](mailto:support@kombo.dev).

First, [get the update form](https://docs.kombo.dev/hris/v1/get-employees-employee-id-form-personal-data.md). Use the returned field keys. Include required fields and any fields you want to change. Omitted fields stay unchanged; `null` clears a value.

Error messages are written so you can show them to your users. When the HRIS refuses a value and names the field, the error message starts with the field key, so you can show it on that field. Some HRIS save a form in several steps. If a later step fails, the earlier ones stay saved, and the error says which part was saved and which part to send again.

If a request times out, or fails with an error that does not say what was saved, the HRIS may still have saved the change. Check the employee in the HRIS before you send the form again.

> [!NOTE]
>
> This endpoint requires the permission **Update personal data** to be enabled in [your scope config](https://docs.kombo.dev/scopes.md).

### Example Request Body

```json theme={null}
{
  "properties": {
    "homeCity": "Berlin",
    "homeAddressLine2": null
  }
}
```


## OpenAPI

````yaml POST /hris/employees/{employee_id}/form/personal-data
openapi: 3.1.0
info:
  title: Kombo API
  version: 1.0.0
servers:
  - url: https://api.kombo.dev/v1
    description: Kombo EU API
  - url: https://api.us.kombo.dev/v1
    description: Kombo US API
  - url: https://api.ca.kombo.dev/v1
    description: Kombo CA API
security:
  - ApiKey: []
tags:
  - name: General
  - name: Kombo Connect
    description: >-
      Endpoints for Kombo Connect, our end-user-facing flow for setting up new
      integrations.
  - name: Unified HRIS API
    description: Unified endpoints to access all the HR concepts you might need.
  - name: Unified ATS API
    description: Unified endpoints to access all the ATS concepts you might need.
  - name: Unified ATS (Assessment & Background Check) API
    description: >-
      Unified endpoints to operate Assessments and Background Checks for many
      applicant tracking systems.
  - name: Unified LMS API
    description: Unified endpoints to access all the LMS concepts you might need.
  - name: AI Apply
    description: Endpoints for AI-powered job application features.
  - name: Custom Endpoints
    description: Custom integration-specific endpoints.
paths:
  /hris/employees/{employee_id}/form/personal-data:
    post:
      tags:
        - Unified HRIS API
      summary: Update employee personal data
      description: >-
        Update an employee's personal data using values from the personal data
        form.




        <Warning>**Closed Beta Feature:** This endpoint is now in closed beta.
        Please reach out to your account manager or
        [support](mailto:support@kombo.dev).</Warning>




        First, [get the update
        form](/hris/v1/get-employees-employee-id-form-personal-data). Use the
        returned field keys. Include required fields and any fields you want to
        change. Omitted fields stay unchanged; `null` clears a value.


        Error messages are written so you can show them to your users. When the
        HRIS refuses a value and names the field, the error message starts with
        the field key, so you can show it on that field. Some HRIS save a form
        in several steps. If a later step fails, the earlier ones stay saved,
        and the error says which part was saved and which part to send again.


        If a request times out, or fails with an error that does not say what
        was saved, the HRIS may still have saved the change. Check the employee
        in the HRIS before you send the form again.


        <Note>
          This endpoint requires the permission **Update personal data** to be enabled in [your scope config](/scopes).
        </Note>


        ### Example Request Body


        ```json

        {
          "properties": {
            "homeCity": "Berlin",
            "homeAddressLine2": null
          }
        }

        ```
      operationId: PostHrisEmployeesEmployeeIdFormPersonalData
      parameters:
        - in: header
          name: X-Integration-Id
          schema:
            type: string
          description: ID of the integration you want to interact with.
          example: bamboohr:HWUTwvyx2wLoSUHphiWVrp28
          required: true
        - name: employee_id
          in: path
          required: true
          description: >-
            The Kombo ID of the employee, or its HRIS ID with a `remote:`
            prefix.
          schema:
            $ref: >-
              #/components/schemas/PostHrisEmployeesEmployeeIdFormPersonalDataParameterEmployeeId
          examples:
            example1:
              value: remote:12345
      requestBody:
        description: POST /hris/employees/:employee_id/form/personal-data Request body
        content:
          application/json:
            schema:
              $ref: >-
                #/components/schemas/PostHrisEmployeesEmployeeIdFormPersonalDataRequestBody
            examples:
              example1:
                value:
                  properties:
                    homeCity: Berlin
                    homeAddressLine2: null
      responses:
        '200':
          description: >-
            POST /hris/employees/:employee_id/form/personal-data Positive
            response
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/PostHrisEmployeesEmployeeIdFormPersonalDataPositiveResponse
              examples:
                example1:
                  value:
                    status: success
                    data:
                      status: COMPLETED
                      remote_url: https://my.hris.com/employees/12345
        default:
          $ref: '#/components/responses/ErrorResponseHRIS'
components:
  schemas:
    PostHrisEmployeesEmployeeIdFormPersonalDataParameterEmployeeId:
      type: string
      description: The Kombo ID of the employee, or its HRIS ID with a `remote:` prefix.
      examples:
        - remote:12345
    PostHrisEmployeesEmployeeIdFormPersonalDataRequestBody:
      type: object
      properties:
        properties:
          type: object
          additionalProperties:
            oneOf:
              - $ref: '#/components/schemas/Schema4'
              - type: 'null'
          description: >-
            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.
      required:
        - properties
    PostHrisEmployeesEmployeeIdFormPersonalDataPositiveResponse:
      type: object
      properties:
        status:
          type: string
          const: success
        data:
          type: object
          properties:
            status:
              type: string
              enum:
                - COMPLETED
                - PENDING_APPROVAL
              description: >-
                `COMPLETED`: the HRIS saved the change. `PENDING_APPROVAL`: the
                HRIS saved it and it waits for someone to approve it there. Some
                HRIS don't tell us about an approval step, so you get
                `COMPLETED`.
            remote_url:
              type:
                - string
                - 'null'
              description: >-
                Link to the employee in the HRIS, where your user can check the
                change or handle an approval. `null` when the HRIS has no link
                we can build.
          required:
            - status
            - remote_url
          examples:
            - status: COMPLETED
              remote_url: https://my.hris.com/employees/12345
      required:
        - status
        - data
    Schema4:
      oneOf:
        - type: string
        - type: number
          format: double
        - type: boolean
        - $ref: '#/components/schemas/Schema13'
        - $ref: '#/components/schemas/Schema14'
    Schema13:
      type: object
      additionalProperties:
        $ref: '#/components/schemas/Schema4'
    Schema14:
      type: array
      items:
        $ref: '#/components/schemas/Schema4'
  responses:
    ErrorResponseHRIS:
      description: The standard error response with the error codes for the HRIS use case.
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: string
                enum:
                  - error
              error:
                type: object
                properties:
                  code:
                    type:
                      - string
                      - 'null'
                    enum:
                      - PLATFORM.RATE_LIMIT_EXCEEDED
                      - PLATFORM.CONCURRENCY_LIMIT_EXCEEDED
                      - PLATFORM.INTEGRATION_NOT_FOUND
                      - PLATFORM.INPUT_INVALID
                      - PLATFORM.UNKNOWN_ERROR
                      - PLATFORM.IP_NOT_WHITELISTED
                      - PLATFORM.AUTHENTICATION_INVALID
                      - PLATFORM.TASK_TIMED_OUT
                      - INTEGRATION.PERMISSION_MISSING
                      - INTEGRATION.AUTHENTICATION_INVALID
                      - INTEGRATION.QA_FAILED
                      - INTEGRATION.SETUP_SYNC_PENDING
                      - INTEGRATION.SETUP_INCOMPLETE
                      - INTEGRATION.INACTIVE
                      - INTEGRATION.MODEL_NOT_AVAILABLE
                      - INTEGRATION.MODEL_DISABLED
                      - INTEGRATION.ACTION_NOT_AVAILABLE
                      - INTEGRATION.ACTION_DISABLED
                      - REMOTE.SERVICE_UNAVAILABLE
                      - REMOTE.RATE_LIMIT_EXCEEDED
                      - REMOTE.INPUT_INVALID
                      - REMOTE.UNKNOWN_HTTP_ERROR
                      - HRIS.STAFFING_ENTITY_CLOSED
                      - HRIS.EMPLOYEE_ALREADY_EXISTS
                    example: HRIS.EMPLOYEE_ALREADY_EXISTS
                    description: >-
                      Some errors include an error code that can be used to
                      identify their cause. See the [Error Handling
                      Docs](https://docs.kombo.dev/guides/errors) for more
                      information. For your error handling logic please use the
                      error `code` instead of other properties (e.g. message,
                      http status code, ...).
                  title:
                    type:
                      - string
                      - 'null'
                    description: A static, human-readable label.
                  message:
                    type: string
                    description: >-
                      A dynamic, detailed description of what went wrong in this
                      specific instance.
                  log_url:
                    type:
                      - string
                      - 'null'
                    format: uri
                    description: >-
                      The log page in the Kombo UI lists every interaction with
                      full details. If you need assistance, share that link with
                      our support team.
                required:
                  - code
                  - title
                  - message
                  - log_url
                description: Error details with structured code for programmatic handling.
            required:
              - status
              - error
          examples:
            Error Response:
              description: >-
                When building error handling logic, always use the `code` field
                to identify specific error types programmatically. See the
                complete list of error codes in the
                [docs](https://docs.kombo.dev/guides/errors).
              value:
                status: error
                error:
                  code: INTEGRATION.MODEL_NOT_AVAILABLE
                  title: >-
                    This data model isn't supported for the selected
                    integration.
                  message: >-
                    The "employees" model is not yet available for Greenhouse.
                    Please reach out to Kombo if you need this functionality.
                  log_url: https://app.kombo.dev/my-prod/logs?interactionId=123456
            Minimal Error Response:
              description: >-
                The "message" is always required while other fields can also be
                `null`. See the [docs](https://docs.kombo.dev/guides/errors) for
                more information.
              value:
                status: error
                error:
                  code: null
                  title: null
                  message: The message is always in the response.
                  log_url: null
  securitySchemes:
    ApiKey:
      type: http
      scheme: bearer
      description: >-
        Create an API key on the [Secrets](https://app.kombo.dev/secrets) page
        in the Kombo dashboard.

````

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