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.

How to find out field IDs

You can fetch all available field IDs with Fields Metadata. This will return the fields, with their IDs and other properties:

      {
        "id": "root.email",
        "categoryId": "about",
        "categoryDisplayName": "About",
        "category": "about",
        "name": "Email",
        "description": null,
        "jsonPath": "email",
        "type": "text",
        "typeData": {},
        "historical": false
      },
		{
        "id": "home.mobilePhone",
        "categoryId": "personalContact",
        "categoryDisplayName": "Personal contact details",
        "category": "personalContact",
        "name": "Personal mobile",
        "description": null,
        "jsonPath": "home.mobilePhone",
        "type": "text",
        "typeData": {},
        "historical": false
    }

Request body example

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

🚧

Notes:

• 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.
• Reference fields: Values that are 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 build the request body

When sending the POST request, you should send a JSON request body that includes the fields (in a format "id": "value") you want to include when creating the employee:

• Root fields, like root.firstName or root.email should be mentioned with the field name only, for example, firstName.

• Other fields should appear as a structure. For example, work.department should be sent as a JSON structure:

  "work": { "department": "Administration"}

  • An easy way to find out how to consruct the field is to read it using People Search, then look at the JSON structure in the search response to see how to reference the field.

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.