A field's metadata represents its properties, allowing you to understand its type and how to process the data it contains. Accessing the metadata does not require special permissions. However, reading the actual data within these fields requires appropriate permissions.

Field metadata

The field metadata includes the ID, the category, and data type.

• Field ID: The field ID is the string you must specify in the query you send to the search API. Fetching field metadata will return all the fields, including custom fields defined by the user. This will allow you to specify any field you need in the query.
• Field Category: The category of the field is how you grant access to the service user. The search API will not return this field in the response without granting permissions to the field's category.
• Field Data Type: You need to know the data type to process the field values correctly in the response payload. To learn more, see Field Types.

Field Types

The field type determines how you should approach the data. For example, a "short date" will not contain the year (e.g., "08-10") as opposed to a "date" (e.g., "1986-08-10"). Another example is a "list," which will contain the list item's string ID rather than its value, and you will need to extract the values using the list's metadata.

Field types can be any of the data types supported by Bob:

To learn more about field types in Bob, see Set up people's data fields ↗.

Field ID notation

You can find out the field’s id using the field’s metadata:
For example: "id": "work.department"

A field ID can be represented in 2 ways:

• work.department
• /work/department

Both ways are valid:

fields": [
    "/root/id",									
    "/work/department"
  ],

fields": [
    "root.id",									
    "work.department"
  ],

Note: Field ids in a response with data will always contain the “/” notation:

employee:{      
	"/root/id": {				
    			"value": "3332883884017713938"
 		},
	"/work/department": {	
       "value": "Account Receivables"
}

Custom fields

Employee data may include custom fields defined by the user. When reading the default employee data it does not include the custom fields. You should read these fields explicitly by mentioning their ID in the fields parameter when calling the search endpoint.

Example:

{
        "id": "work.custom.field_1711886937296", // the custom field ID
        "category": "work",
        "name": "Has Dog",
        "description": null,
        "jsonPath": "work.custom.field_1711886937296",
        "type": "number",
        "typeData": {},
        "historical": false
    }

Lists

Fields can be linked to a list. Lists hold string item values that can be selected for the field.

Lists can be out-of-the-box or custom (defined by the user) and can be one of the following types:

• list - a collection of list items.
• multi-list - a collection of lists.
• hierarchy-list - a collection of lists with levels.

All lists and their values can be retrieved using the lists metadata API.

List items backend-IDs

Each list item has a backend ID, which represents the id of the item in the list as stored in the database. The id can be a text (for out-of-the-box lists) or a number (for custom lists). In order to view the string value of the list item, you should convert it to human-readable format.

Converting list items to human-readable format

When reading fields of type: 'list', 'multi-list' and 'hierarchy-list', the API returns by default the list-item's ID rather than the value as displayed in the UI.

For example:

{
  "work": {
    "department": "209192163"		// the numeric ID of the item in the Departments list
  }
}
{
  "work": {
    "department": "Animals"		// the string ID of the item in the Departments list
  }
}

The ID may be a string (if this is an out-of-the-box list item), or a numerical ID (for custom list items that were added by the use). In both cases you need to convert this ID to a "human readable" format, in order to see the item's display value.

To convert the ID to the display value you can:

1. Use metadata: Read the list's metadata and find the relevant item. To learn more, see 'Get all company lists' metadata
2. Use a flag: Use the 'employee search' endpoint which allows you to use a flag that will return the display value automatically. To learn more, see Converting list items using a flag

Note: You should always retrieve the display value which represents how the list item appears in the UI, because even when the ID is a string that seems like the display value, it may have been renamed, and will have a different display value. For example, the "Animals" list item was rename to "Pets":

JSON

{
	"id": "Animals",			// original out-of-the-box ID
	"value": "Pets",			// renamed display value
	"name": "Pets",
	"archived": false,
	"children": []
},

Converting list items using a flag

Some endpoints support a shortcut of fetching the human-readable value of a list item using the humanReadable flag. This is support when calling the Search for employees endpoint and other People data endpoints. Using this flag, you can retrieve the human-readable values of the list while querying the data, rather than calling the metadata endpoint and retrieving the list values.

Possible values for the humanReadable flag:

• None: If you don’t pass the flag, all field values will be returned in machine format.
• "APPEND": Include supported "humanReadable" fields in the response as an additional part of the response JSON. Fields that do not support "human readable" values in this call will return in the machine-format only.
• "REPLACE": Return only human-readable values. This will return only fields that support the human readable flag as described in the endpoint’s response. Fields that are not supported will not be returned at all.

Example response with humanReadable = "APPEND":

{
    "/root/creationDate": {										// all fields are in machine format
        "value": "2019-09-08"
    },
    "fullName": "Alan Tullins",
    "creationDate": "2019-09-08",
    "work": {
        "department": "209192163"
    },
    "/root/fullName": {
        "value": "Alan Tullins"
    },
    "/work/department": {
        "value": "209192163" 										
    },
    "humanReadable": {													// human readable section
        "fullName": "Alan Tullins",
        "creationDate": "08/09/2019",
        "work": {
            "department": "Account Receivables" 
        }
    },
    "id": "2128438031986721630"
}

Metadata endpoints

'Get all company fields' metadata endpoint

To find out the properties of fields, you should call the Get all company fields metadata endpoint:

GET https://api.hibob.com/v1/company/people/fields

Response:

{
       "id": "work.department",	// Field ID
       "category": "work",	// Field Category
       "name": "Department",
       "description": null,
       "jsonPath": "work.department",
       "type": "list",	// Field Type
       "typeData": {
           "listId": "department" // use this to read the list metadata
},
"historical": true
}

📘

Category name

The category returned in the field properties contains the category ID. It may look something like 'workContact' or 'work' if this is an out-of-the-box category or something like 'category_1720508362305' for custom categories. To obtain the category name as it appears in Bob's UI, you can view the category in the UI and see the category ID as part of the URL: https://app.hibob.com/employee-profile/3332883884017717778#category_1720508362305

'Get all company lists' metadata

This endpoint returns lists and their values. So, when you read a field containing a list item backend ID, you should use this endpoint to fetch the item's display value.

1. Follow the steps in Get all company fields to get the field's metadata.
2. Locate the field ID and check the metadata.
3. If the field's type is list, multi list or hierarchical list, use Get all company lists endpoint to get the list values, and pass the field name in the listName parameter.

Example:

   {
        "id": "work.department",
        "category": "work",
        "name": "Department",
        "description": null,
        "jsonPath": "work.department",
        "type": "list",
        "typeData": {
            "listId": "department"
        },
        "historical": true
    },

• Field ID: "work.department"
• List ID: typeData > "list" > listId > "department"
• Get the list's values:

GET https://api.hibob.com/v1/company/named-lists/department 

4. Locate the items' backend ID in the response and fetch the the display value from the value property:

    "department": {
        "name": "department",
        "values": [
            {
                "id": "209192143",							// list item ID
                "value": "Account Management",	// Human readable (display) value
                "name": "Account Management",
                "archived": false,
                "children": []
            }
        ],