Create an employee

Before you start, review Fields and lists metadata to understand how field IDs and list values work. .

Endpoint URL

To create an employee, use the Create company employee endpoint:

POST https://api.hibob.com/v1/people

👍

Testing tip: We recommend testing this endpoint using an external tool like Postman, rather than the “Try It!” feature. The request parameters need to be formatted exactly as shown below.

Request body

Send a JSON body that includes the fields (in a format "id": "value") you want to include when creating the employee.
You can find all available fields in the Fields Metadata.

{
  "firstName": "John",
  "surname": "Doe",
  "email": "[email protected]",
  "work": {
    "site": "New-York",
    "startDate": "2025-09-04",
    "title":"Chief Engineer",     
    "department": "Administration"
  }
}

🚧

Note: References to lists (like site, work.department, or work.title) must match existing values in the corresponding list. Otherwise, the request will return an error.

How to get the field ID

1. Use People Search to fetch an employee who already has a value in the field you want to use.
2. Look at the JSON structure in the search response to see how to reference the field.
3. For basic (root-level) fields, specify just the field name — for example, firstName.

Example:

PUT /v1/people/2813193532448179017
{
  "home": {
    "mobilePhone": "63635356"
  },
  "firstName": "Jacky"
}

Field format for table columns

Some fields, such as work.site and work.startDate are actually columns from the work table. To update them, include the full table structure in your request body instead of sending the field ID alone.

For example:

• work.title: The job title from the active row in the work table.
• work.startDate: The start date for the active job.

Because these fields come from a table structure, you can’t update them directly by field ID. Instead, include the full table structure, as shown below:

"work": {
  "site": "Germany", // must be the display value of the site
  "startDate": "2025-01-01"
}

Recommended fields for creation

• Mandatory fields: When creating a new employee, there are 5 required fields: email, first name, last name, start date (from Work table) and site (from Work table).
• Recommended fields:
  • When the system creates a new employee record in Bob, it also creates a row in the employee's Work table. If the values in this row are not provided correctly upon creation, the user needs to update these values later.
  • We recommend providing the whole Work table row, including work.title and work.department.

Response format and values

The API returns a machine-readable JSON with additional calculated and read-only properties, such as:

• fullName, displayName — derived from the provided name parts.
• work.tenureDuration, work.tenureYears, work.tenureDurationYears, work.durationOfEmployment, work.yearsOfService — calculated from start dates. If startDate is in the future, these values are zero until that date.
• work.shortStartDate — a formatted version of startDate.
• avatarUrl, coverImageUrl — managed by the server (default images if not provided).

Permissions required

The Service User calling the API must have the correct permissions to create or update employee data. The exact permissions depend on the fields and their categories.

If the service user lacks the right permissions, you may see authorization or field-specific errors.

Make sure the Service User has:

1. Features > People > Add new people to the company permission.
2. Edit permissions in People’s data and Features for the relevant categories (defined in each field’s metadata).
3. Access rights to the employee being created or updated.

To learn more about permissions and access rights, see Categories and permissions.
For details on the available fields, see the People reference guide.

🚧

Important: The system doesn’t alert you if only partial permissions are granted. When testing, verify that all expected fields were updated and review any errors that may relate to missing permissions.