---
updatedAt: 2026-06-16T13:12:44.000Z
---
Fetch the complete documentation index at: https://apidocs.hibob.com/llms.txt. Use this file to discover all available pages before exploring further.
# Update employee data
Learn how to update employee data fields using Bob’s API
> Before you begin, make sure you are familar with the concepts in [Fields and lists metadata](https://apidocs.hibob.com/docs/fields-metadata) first.
# Update an employee
To update an employee field you should use the [Update company employee](https://apidocs.hibob.com/reference/put_people-identifier) endpoint.
`PUT https://api.hibob.com/v1/people/{identifier}`
The `{identifier}` represents the employee ID, which is the unique identifier for an employee in the backend database.
To replace `{identifier}` with the employee's ID:
1. You should use the [People endpoints](https://apidocs.hibob.com/reference/people) to programmatically retrieve employee data, including the employee IDs, which are found in the `root.id` or `/root/id` in the response JSON. To learn more, see [Read employee data](https://apidocs.hibob.com/docs/how-to-read-employee-data).
2. For **testing purposes** only, you can retrieve the ID from the employee’s URL in Bob. For example:\
`PUT https://api.hibob.com/v1/people/2813193532448179017`.
> 📘 Note:
>
> Although this is a PUT method, you can send to this endpoint only the fields you want to update and other fields will remain untouched (**behaves like PATCH**).
## Read-after-update consistency
> 📘 **Note:** Recently updated employee data may take a few seconds to become available when fetching data. If you update employee data and then immediately retrieve the same data, the response may still show the previous value or `null`. To ensure the latest data is returned, add a short delay (up to **20 seconds**) before making a subsequent read request.
>
> See also [People read API contract — Read-after-update consistency](/docs/people-read-api-contract#read-after-update-consistency).
# Request Body
Include the fields you want to update in the request body. You can find available fields using the [Fields Metadata]().
> 🚧 **Note**:
>
> We recommend testing this endpoint using an external tool, such as Postman, rather than the 'Try It!' feature in the documentation. This is because the parameters need to be constructed in a specific format. The easiest way to do this is by copying the parameter structure from the 'Search' endpoint's response, as explained below.
**Steps to get the Field ID:**
1. Fetch the field for an employee who has a value in this field using the [People Search](https://apidocs.hibob.com/reference/post_people-search).
2. Use the **JSON structure** from the search response to specify the field.
3. For basic fields with "root" in their path, only specify the field name (e.g., firstName).
**Example**:
```
PUT /v1/people/2813193532448179017
{
"home": {
"mobilePhone": "63635356"
},
"firstName": "Jacky"
}
```
> 📘 Notes:
>
> 1. For **custom employee fields:** See [How to update custom fields](#how-to-update-custom-fields).
> 2. For **custom columns on employee tables:** See [How to update custom columns](#how-to-update-custom-columns).
> 3. For **custom table rows:** See [How to update custom table entries](#how-to-update-custom-table-entries).
> 4. If you receive a ‘**304 Not Modified**’ error, ensure you are setting a **new** value to the field and that you are using the correct Field ID format.
> 5. This endpoint cannot update non-employee entities, like **[Positions](https://apidocs.hibob.com/reference/workforce-planning)**.
# Permissions required
The permissions required for updating employee fields should be assigned to the [Service User ](https://apidocs.hibob.com/docs/api-service-users) used when calling the API. The specific permissions depend on the data fields you want to update and the categories these fields belong to. Attempting to update fields without the necessary permissions will result in authorization errors or fields not being updated.
Ensure the Service User has the correct permissions:
1. Grant 'Edit' permissions in the [People’s data](https://apidocs.hibob.com/docs/api-service-users#32-peoples-data) and [Features](https://apidocs.hibob.com/docs/api-service-users#31-features) for the relevant categories. Note that the category is specified in the field's metadata.
2. The Service User has the [correct access rights](https://apidocs.hibob.com/docs/api-service-users#33-access-rights) to the employee that is about to be updated.
To learn more about setting access rights and permissions to the service user based on the categories, see [Categories and permissions](https://apidocs.hibob.com/docs/categories-and-permissions).
**Partial updating of fields**\
If you receive a '200 OK' response but notice that only some of the requested fields have been updated, this could indicate that the Service User's permissions do not cover all the requested data. The server will simply exclude any fields that the Service User cannot modify.
**Important**: You will not be explicitly notified that only partial permissions are available. Therefore, when testing, please ensure all expected fields being updated and that any permission-related issues are accounted for.
# How to update table columns
Bob's Out-of-the-box table columns **cannot be updated using the fields update endpoint.**
Although some column fields (like the examples below) are returned by the 'Fields Metadata' and 'Search' endpoints, these fields cannot be updated via the employee update endpoint because they represent data from the "current" row of a table (indicated by a green dot in the UI), not standalone fields that can be directly modified:
For example,
* `work.activeEffectiveDate`: The effective date of the “active” row in the work table.
* `work.title`: The Job title of a the "active" row in the work table.
* `payroll.employment.activeEffectiveDate`: The effective date of the “active” row in the employment table under the payroll category.
Because such fields are derived from the table’s structure, they cannot be updated through the employee update endpoint and must be modified using the table-specific update methods. For more details on how to update the table data (columns), see [Employee Tables](https://apidocs.hibob.com/reference/employee-tables).
# How to update custom columns
Custom **columns** on out-of-the-box employee tables (Work, Training, Salary, and others) are not updated through [Update company employee](https://apidocs.hibob.com/reference/put_people-identifier). Use the matching [Employee table](https://apidocs.hibob.com/reference/employee-tables) endpoint for that table.
1. **Resolve the column ID** from [Get all employee fields](https://apidocs.hibob.com/reference/get_company-people-fields) (IDs look like `work.customColumns.column_1732443454173`).
2. **Read an existing row** (optional) to see the payload shape, including `customColumns` in the response.
3. **Create or update a row** with POST/PUT on the table endpoint. Include custom column values under `customColumns` using the `column_{id}` keys returned when you read the row.
Example shape when updating a Work row:
```json
{
"customColumns": {
"column_1732443454173": "updated value"
}
}
```
Historical tables (Work, Employment, Lifecycle) also require a valid `effectiveDate` on create/update. See [Employee tables and custom tables](https://apidocs.hibob.com/docs/additional-employee-data#custom-columns-in-out-of-the-box-tables) and [Custom fields and custom columns in API responses](https://apidocs.hibob.com/docs/fields-metadata#custom-fields-and-custom-columns-in-api-responses).
# How to update custom fields
Before updating, confirm whether you are working with a **custom field** (on a category) or a **custom column** (on a table). They use different JSON shapes and endpoints when reading and writing. See [Custom fields and custom columns in API responses](https://apidocs.hibob.com/docs/fields-metadata#custom-fields-and-custom-columns-in-api-responses).
To update a custom field, follow these steps:
1. **Read the Fields Metadata**: To find the custom field’s ID. Use the [Fields Metadata](https://apidocs.hibob.com/reference/get_company-people-fields) and locate the custom field you want to update.
2. **Read the Employee’s custom field**: To get the field's JSON structure. Use [People Search](https://apidocs.hibob.com/reference/post_people-search) to fetch the custom field for an employee who has a value in this field (only when there is a value you will receive the custom field in the response).
3. **Update the custom field**: Specify the field ID using the structure received in the JSON response.
Custom field JSON structure example:
```
{
"userData": {
"custom": {
"field_17257492283795": "custom user data"
}
}
}
```
> 📘 Note:
>
> Category custom fields appear under a `custom` object in the update request body (for example `work.custom.field_*`). Custom **columns** on out-of-the-box tables are read and updated via [Employee table](https://apidocs.hibob.com/reference/employee-tables) endpoints and appear under `customColumns` in table row responses—not under `custom`.
## Example: How to update a custom field
This example demonstrates how to fetch a custom field while working with **Postman**.
1. **Find an Employee who has a value in the custom field**. Copy the employee’s ID from the URL.
2. **Retrieve the Field ID**. Use the [Fields Metadata]() endpoint to find the JSON structure of the custom fields.
3. **Retrieve the rmployee's custom field**: Call the [People Search](), and specify the custom **field ID** and **employee ID** in the '**fields**' and '**filters**' parameters.
4. **Update the custom field**. Call the [Update Employee](https://apidocs.hibob.com/reference/put_people-identifier) endpoint, using the custom field's JSON structure from the response. Remember to replace the employee ID in the path parameter, and to update the custom field's value.
5. **You should get a 200 OK response** if the update is successful. Check the employee data in Bob to confirm the update. If you verify via [People Search](https://apidocs.hibob.com/reference/post_people-search) or [Read by employee ID](https://apidocs.hibob.com/reference/post_people-identifier), wait up to **20 seconds** before reading — see [Read-after-update consistency](#read-after-update-consistency).
# How to update custom table entries
[Custom tables](https://apidocs.hibob.com/reference/custom-tables) store rows per employee. Column IDs come from [custom table metadata](https://apidocs.hibob.com/reference/get_people-custom-tables-metadata); values use top-level `column_{id}` keys on each row (not `customColumns`). See [Custom fields and custom columns in API responses](https://apidocs.hibob.com/docs/fields-metadata#custom-fields-and-custom-columns-in-api-responses).
1. Discover tables and columns via metadata endpoints.
2. **Create** a row: [Create new custom table entry](https://apidocs.hibob.com/reference/post_people-custom-tables-employee-id-custom-table-id).
3. **Update** a row: [Update custom table entry](https://apidocs.hibob.com/reference/put_people-custom-tables-employee-id-custom-table-id-entry-id).
4. **Delete** a row: [Delete custom table entry](https://apidocs.hibob.com/reference/delete_people-custom-tables-employee-id-custom-table-id-entry-id).
For a full walkthrough, see [Employee tables and custom tables](https://apidocs.hibob.com/docs/additional-employee-data#custom-tables).