How to use Public API to read employee data

Learn how to retrieve and process employee data using Bob’s API

Suggest Edits

The employee data you read via the API reflects the employee data shown in Bob's UI. In the same way, the permissions required in order to read the data via the API are similarly organized based on the field's category in the UI.

Before actually calling the API, you should first map the fields you want to read and assign the relevant permissions to the service user you use to access the API.

Note: if this is the first time you are using Bob's API, check out the API Service Users guide first.

To read employee data, follow these steps:

Step 1: Map the fields for your query

Employee data in Bob consists of fields, tables, custom fields and custom tables.

First, you need to map which fields and tables you need to retrieve. You can look into Bob's employee data in the UI and decide which fields you need to access.

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

Step 2: Fetch fields metadata

In this step you need to fetch the fields metadata to find out their:

  • ID: you need specify the field id in the query you send to the search API. Fetching fields 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.
  • Category: you need the category of the field in order to the service user. Without permissions to the field's category, the search API will not return this field in the response.
  • Data type: you need to know the data type so you can process the field values correctly in the response payload.

To learn more about fetching the field properties, see Fields metadata

Step 3: Set authorization and permissions

When using the Bob API you need to authenticate with a Service User.

Service users are special users in Bob which are used only for the API. The permissions assigned to a service user determine the scope of data that can be accessed.

Each endpoint may require different permissions based on the type of data you need to access. For example, accessing personal data requires different permissions than accessing an employee’s work history.

To define the permissions you need to:

  1. Define service users: see API Service Users.
  2. Set permissions based on the fields categories: see Categories and permissions

Step 4: Call the API

In this step you will build your query based on the field Ids you fetched.

Bob’s api allows you to retrieve employee data is the following ways:

  • Search endpoints: Allow reading data for several employees at a time, and filtering the results based on your input. Returns a fixed set of fields by default, and you can alternatively specify which fields you want to fetch.
  • Webhooks: Allow you to subscribe to events in Bob and be notified in real-time. Returns only a fixed set of fields and usually requires calling more endpoints to retrieve the complete data.

Note: The data you read using the Search endpoint returns the current snapshot of data about the employee. Data that is stored in historical tables will return only the "effective" entry. To read historical data, use the Employee Tables endpoints.

Call Search API

The employee /search endpoint requires the following parameters:

  • fields - specify which fields you want to retrieve. If you do not provide this parameter, the call will return the default set of fields defined for this endpoint, as defined in the endpoint response.
  • filters - limit which employees to query. If you do not pass filters, the call will return all the employees that can be accessed by this service user.
  • humanReadable - determines the data format which will be returned in the fields in the response payload: machine format (default) or human readable format.
  • showInactive - whether the response should include inactive employees.

Example: fetch all default fields for all employees (based on the service user's permissions):

POST /v1/people/search  
{}

Example: fetch specific fields for a specific employee (based on the service user's permissions):

POST /v1/people/search  
{  
  "fields": [  
    "/root/id",  	// you can use either `/` or `.` in the field id notation
    "root.firstName",  
    "work.department"  
  ],  
  "filters": \[  
    {  
      "fieldPath": "root.id",  
      "operator": "equals",  
      "values": [  
        "77634555747646",  
      ]  
    }  
}

To learn more about calling the search API, see Bob's reference guide.

Use Webhooks

Webhook events will notify you when an event occurs and will send relevant data in the event's payload. The payload returns only machine-readable format, which means you always need to find out the field types using the metadata and then convert to human-readable values.

To learn more about using Webhooks, see Getting started with Webhooks.

Step 5: Process payload

The payload that the search returns in the response includes the employee fields that were requested in the request.

Use the field metadata you fetched in step 2 in order to process the values in the fields correctly, whether the value is a number, date or an item from a list, will affects how you treat this value.

Important!

Fields containing list items need to be converted from the numeric ID to the human readable value.

See Step 6: Fetch lists metadata.

Step 6: Fetch lists metadata

Fields containing list items need to be converted from the numeric ID to the human readable value. To do that you need to fetch the list items and find the item with this ID.

For example, the "department" field that contains a numeric IDs such as "209192163" should be converted to the "human readable" value "Account Receivables".

To learn more, see Converting list items to human readable format

Step 7: Read tables data (optional - for historical data)

If you need to fetch table data (e.g. Work table entries), you need to call additional API endpoints.

You can fetch table entries for a single employee or for several employees at at time (using 'bulk' endpoints).

To learn more, see Employee tables.

Step 8: Set rate limits

To ensure the stability and reliability of our platform, we have implemented rate limiting on API endpoints. These rate limits are designed to prevent misuse and overloading of the API.

When integrating with our API, it's crucial to follow these limits to us maintain optimal performance and availability for all users of the platform.

To learn more about best practices, see Rate limiting for best practices and more information.

Updated 2 days ago