How to work with lists Public API

People API and returned data

When working with the people AP, by default, Bob returns the data in a “machine-readable” manner. This means fields from type list will be returned with their ID, dates in ISO format, etc.

E.g.

{

  "fullName": "Alan Tullin",

  "creationDate": "2018-05-13",

  "work": {

    "department": "209192163"

  }

}

To get the lists data in a “Human readable” format, the humanReadable parameter shall be sent in the request body as follows:

humanReadable (string) *this is an optional field.

Possible values:

APPEND - include the additional "humanReadable" JSON node in the response.

REPLACE - supply humanReadable values in JSON instead of machine-readable format.

For example, when using APPEND (humanReadable=APPEND) you will get an additional JSON that contains the values in a "human-readable" manner.

In the example below the dates will be rendered in the format of the calling user (according to the user settings in Bob), and display names of list items will be rendered instead of their internal IDs:

{
    "/root/creationDate": {
        "value": "2019-09-08"
    },
    "fullName": "Alan Tullins",
    "creationDate": "2019-09-08",
    "work": {
        "department": "209192163"
    },
    "/root/fullName": {
        "value": "Alan Tullins"
    },
    "/work/department": {
        "value": "209192163"
    },
    "humanReadable": {
        "fullName": "Alan Tullins",
        "creationDate": "08/09/2019",
        "work": {
            "department": "Account Receivables"
        }
    },
    "id": "2128438031986721630"
}

WebHooks

When working with WebHooks, for any list field, the webhook payload will contain the ID of the item in the list.

Then, using Bob's Lists Metadata API, you can search for the item ID to get the actual values.

Working with lists and employee data (complete flow)

Identifying list fields: HiBob's data is driven by metadata, each property in Bob has its own type, which is declared in the Fields Metadata API.

To identify all the lists in Bob, you should call the Fields Metadata API and filter the objects by type list, multi-list or hierarchy-list.

{

       "id": "work.department",

       "category": "work",

       "name": "Department",

       "description": null,

       "jsonPath": "work.department",

       "type": "list",

       "typeData": {

           "listId": "department"

       },

       "historical": true

   }

For any field in the people API with type list, Bob’s public API will return the ID of the item that is set for the employee.

E.g.

"department": "209192163",

For each field in the Search people API, lookup in the metadata to get the List ID and the value of the field.

{

       "id": "work.department",

       "category": "work",

       "name": "Department",

       "description": null,

       "jsonPath": "work.department",

       "type": "list",

       "typeData": {

           "listId": "department"

       },

       "historical": true

   }

Using "Get a specific company list by name", search for the listID that was retrieved from the metadata.

https://apidocs.hibob.com/reference/get_company-named-lists-listname

E.g.

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

Lookup by the item ID that was retrieved from the people API to get the item value.

{

 "name": "department",

 "values": [

   {

     "id": "209192163",

     "name": "Account Receivables",

     "archived": false,

     "children": []

   }