Before you begin, make sure you are familar with the concepts in Fields and lists metadata first.

Update an employee

To update an employee field you should use the Update company employee 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 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.
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).

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.
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 Fields: See How to update custom fields.
2. For Table Columns: See How to update table columns.
3. 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.
4. This endpoint cannot update non-employee entities, like Positions.

Permissions required

The permissions required for updating employee fields should be assigned to the Service User 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 and 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 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.

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.

How to update custom fields

To update a custom field, follow these steps:

1. Read the Fields Metadata: To find the custom field’s ID. Use the Fields Metadata 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 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:

Custom fields alway appear in the "custom" section in the JSON.

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 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