Skip to main content

​
About HiBob

HiBob (Bob) is a modern human resources information system (HRIS) designed for mid-sized and enterprise companies. It helps organizations manage the entire employee lifecycle, including onboarding, time off, compensation, performance, and workforce planning.

​
What the HiBob integration enables

CapabilityDescription
Workflow AutomationBuild Serval workflows to automate anything accessible via HiBob’s REST APIs
All resources exposed by the HiBob API are available to Serval workflows using Service User authentication.

Key Features

  • Manage employee data and profiles
  • Automate time off requests and approvals
  • Track attendance and work schedules
  • Handle onboarding and offboarding workflows

Common Use Cases

  • Automated employee onboarding provisioning
  • Time off synchronization across systems
  • Employee data sync with other HR tools
  • Workforce planning automation

​
HiBob configuration (in HiBob)

​
Prerequisites

Before configuring the HiBob integration in Serval, ensure you have:
  • Admin access to your HiBob (Bob) account
  • Permissions to create API Service Users
  • Permissions to create and manage Permission Groups

​
Understanding HiBob API authentication

HiBob uses Service User authentication for API access. Service Users are special accounts that exist solely for API authentication—they aren’t tied to actual employees and cannot log in to Bob.
HiBob discontinued the legacy “API Access Token” authentication method on October 31, 2024. The Service User method is now the exclusive means for API authentication.

​
Step 1: Create a Service User

1

Access the Service Users page

  1. Log in to your HiBob account as an Admin
  2. Navigate to Settings → Integrations → Service Users
  3. Click Add Service User
If you don’t see the Service Users option, contact your HiBob administrator to grant you the necessary permissions.
2

Create the service user

  1. Provide a descriptive name (e.g., “Serval Integration”)
  2. Click Create
  3. Copy both the Service User ID and Token immediately
The token is only displayed once when created. Store both the Service User ID and Token securely—you’ll need them to configure the integration in Serval. If you lose the token, you’ll need to regenerate it.

​
Step 2: Create a Permission Group

By default, new service users have no access permissions. You must create a dedicated Permission Group and add the Service User to it.
1

Create a new permission group

  1. Go to Settings → Account → Permission Groups
  2. Click Add Permission Group
  3. Name it something descriptive (e.g., “Serval API Access”)
2

Add the service user to the group

  1. In the Permission Group settings, add the Service User you created
  2. This group should only contain permissions required for your Serval workflows

​
Step 3: Configure Permissions

Permissions in HiBob are organized by categories. When you grant access to a category, you grant access to all fields within that category.
1

Configure Feature permissions

  1. Click Edit on your permission group
  2. Under Features, select the areas of Bob you need to access
  3. For example, enable Reports if you need to access reporting endpoints
2

Configure People's Data permissions

Grant access to employee data categories based on your needs:
Permission TypeDescription
View all employees’ [Category] sectionsRequired for reading employee data
View all employees’ [Category] section historiesRequired for accessing historical data (e.g., lifecycle or work table entries)
Edit all employees’ [Category] sectionsRequired for updating data or accessing sensitive fields
For basic employee data access via the People Search API, assign the Default Employee Fields permissions. This includes access to the “root,” “about,” “employment,” and “work” categories.
3

Configure Access Rights

Define whose data the service user can access:
  1. Go to People’s Data → Access data for
  2. Choose the scope:
    • Everyone: All active employees
    • Select by condition: Filter by specific criteria
    • Select by name: Choose specific employees
By default, service users can only access active employees. To access inactive employees, edit the access conditions and remove the “Lifecycle status equals Employed” filter.

​
Serval configuration

Once you have your HiBob Service User credentials, follow these steps to configure the integration in Serval:
1

Navigate to HiBob integration

  1. In Serval, go to Applications → Available → HiBob
  2. Click Connect
  3. The HiBob configuration form will appear
2

Enter configuration details

Fill in the following fields:
FieldDescriptionExample
Service User IDThe ID of your HiBob API Service Usera1b2c3d4-e5f6-7890-abcd-ef1234567890
Service User TokenThe token generated for your Service User••••••••••••••••••••
Both credentials are combined and Base64-encoded to create the Basic Authentication header. Serval handles this automatically—just enter the raw credentials.
3

Submit the configuration

  1. Click Submit to complete the integration setup
  2. Serval will verify the connection by making a test API request
  3. Once verified, you can start building workflows with HiBob

​
How authentication works

HiBob uses Basic Access Authentication. When Serval makes API requests to HiBob on your behalf, it:
  1. Combines your Service User ID and Token as SERVICE-USER-ID:TOKEN
  2. Base64 encodes the combined string
  3. Sends the header: Authorization: Basic <encoded-credentials>
This is handled automatically by Serval—you only need to provide the raw credentials during setup.

​
Using HiBob in workflows

Once connected, you can use HiBob in your Serval workflows to automate HR processes:
  • Employee management: Search employees, read profiles, create new employees, update employee data
  • Time off: Submit time off requests, check balances, manage approvals
  • Attendance: Import attendance data, manage time tracking
  • Tasks: Read and complete tasks, manage onboarding checklists
  • Reports: Access and download reports
  • Documents: Upload and manage employee documents
  • Workforce planning: Manage positions and openings
The HiBob integration provides access to all endpoints in the HiBob Public API. Explore the API documentation to discover all available capabilities.

​
Troubleshooting

If you receive authentication errors:
  • Verify the Service User ID and Token are correct
  • Ensure the Service User hasn’t been deleted or deactivated
  • Check that the Service User is assigned to a Permission Group with appropriate permissions
  • If you’ve lost the token, regenerate it in HiBob and update Serval
If requests fail with permission errors:
  • Review the Permission Group settings for your Service User
  • Ensure the required category permissions are enabled (View, Edit, or View History)
  • Check the Access Rights to confirm the Service User can access the specific employees
  • Consult the HiBob API documentation for required permissions per endpoint
By default, Service Users only have access to active employees. To access inactive employees:
  1. Edit the Permission Group’s Access Rights
  2. Go to Access data for → Select by condition
  3. Remove the “Lifecycle status equals Employed” condition

​
Additional Resources

HiBob API Documentation

Complete API reference and guides for HiBob

API Service Users Guide

Learn how to create and manage API Service Users
Need help? Contact [email protected] for assistance with your HiBob integration.