Employee Search use-cases and examples

👍

Before you begin

This tutorial offers step-by-step instructions for testing and using the People Search and other employee data endpoints. Before proceeding, ensure you:

1. Review Explore employee data API to understand the basic concepts of employee data.
2. Familiarize yourself with the endpoints and their usage by reading Read employee data.

How to read default employee fields

To read employee data via the Public API, you can use the interactive API reference pages to call the relevant endpoint and test the API with your Bob workspace.

Note: The following is a usage example if the Search for employees endpoint. For a full usage guide follow the steps in Read employee data and Update employee data.

Before you begin

1. Create a service user. Copy the ID and Token as you will need them as the credentials when accessing the Public API.
2. Assign it to a permission group.

Read default employee fields

You can use the People Search Public API endpoint to access employee fields via the Public API.

📘

Default permissions:

You can call this API without specifying fields to retrieve basic employee data quickly. By default, it returns fields from the Basic Info, About, Employment, and Work categories.

Note that the service user must have permissions for these categories; otherwise, the API returns a '200' status with no data. For more details, see Permissions for default employee fields in People Search API.

1. Set the default permissions in the service user's permission group.
2. Go to the People Search Public API endpoint page.
3. Paste the Service user ID and Token in the AUTHORIZATION > Basic fields.
4. Click Try it!.

5. You should see results in the RESPONSE tile.

Read specific employee fields

To read specific fields rather than the default ones, you need to add a field's filter to the request's body parameters.

1. From the Examples pull-down in the Try it tile, select Request example.
2. This will add some example filters to the request body parameters. Since we will not filter the results in this example, we need to remove the filter parameter.

3. From the BODY PARAMS area, scroll down to the filters section and click the trash can next to the OBJECT line to remove the filters.
4. Leave the fields list as-is. This will include root.id, and root.firstName. Click Try it!
5. The results will now include only these fields.

To learn more, see how to read employee data.

👍

How to find out field IDs

If you want to include more fields, you need to specify their field ID in the query. To find out the field ID of employee fields, use the metadata endpoints, and ensure the service user can access the field's category. For details, see Categories and permissions

How to access custom fields

You can access custom fields the same way as any out-of-the-box field by specifying the field ID in the Search employee data call.

Steps to access custom field:

1. Locate the custom field ID: Use the Fields metadata endpoint to find the unique ID for the custom field. This ID is a string that uniquely identifies the field (e.g., work.custom.field_1711886937296).
2. Understand the field ID: The field ID includes the name of the original category where it was created. Moving the field to a different category will not change its ID.
3. Check permissions: Ensure the service user can access the custom field category. For details, see Categories and permissions.

How to access employee tables

To access employee tables, you first need to find out the table's type and then use the relevant endpoints.

👍

Employee tables

To learn about the types of tables and which are accessible via the API, see Data access via the Public API.

• Historical Tables:
  1. Current data: The row with the current effective date is considered as the current data of the employee. This row can be retrieved using the Search employee data API and the Fields metadata endpoint
  2. All rows: Each table has a dedicated endpoint that returns all the rows. The data includes the out-of-the-box columns and the custom column. See Employee Tables endpoints.
• Non-historical Tables:
  1. All rows: Each table has a dedicated endpoint that returns all the rows. The data includes the out-of-the-box columns and the custom column. See Employee Tables endpoints.
• Custom Tables:
  1. All rows: Use the Custom tables endpoints.
  2. Metadata: Use the Custom tables metadata endpoints.

How to update employee data

To update an employee field you should use the Update company employee endpoint.

To learn more, see Update Employee data