Documentation

Read employee data

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

Suggest Edits

The public API allows users to access employee fields, including custom fields, based on permissions granted to the service user. The employee data retrieved via the API reflects what is shown in Bob's UI, with similar permission structures organized by field category.

Before calling the API, map the fields you want to read and assign the relevant permissions to the service user accessing 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 field metadata to find out the:

  • ID: you need to specify the field ID 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.
  • Category: You need the category of the field so the service user can access it. The search API will not return this field in the response without permission to the field's category.
  • Data type: you need to know the data type to 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, who 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 field categories: see Categories and permissions

📘

Permissions troubleshooting

  1. View assigned permissions:
    Bob Admins can view the permissions assigned to each service user. To learn more, see View the assigned permission and permission groups.
  2. Partial fetching of fields
    If you receive a '200 OK' response but notice that no, or only some of the requested fields have been fetched, this could indicate that the Service User's permissions do not cover all the requested data. The server will simply exclude any fields that the Service User cannot access.
    Important: You will not be explicitly notified that only partial permissions are available. Therefore, when testing, please ensure all expected fields are being returned and that any permission-related issues are accounted for.
  3. Moving fields between categories:
    Bob Admins can move fields to different categories. When this happens, the field will not be fetched via the "default" fetch as only the 'root' (basic fields), 'about', 'employment' and 'work' categories are fetched by default. If you can't find a field using the default query, check out Moving fields between categories.

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 in 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; alternatively, you can 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.

📘

Historical data

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. These fields include fields located in the 'root' (basic fields), 'about', 'employment', and 'work' categories.
  • filters - limit which employees to query. If you do not pass filters, the call will return all the employees that this service user can access.
  • 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 must 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 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 about 1 hour ago