HiBob is an HR platform that helps businesses manage their workforce. It’s a centralized, user-friendly system for handling HR operations, from employee onboarding to performance tracking and time-off management. The HiBob API can also integrate with other platforms, including payroll systems, applicant tracking software, and custom business applications, to manage data, automate workflows, and sync information. The API is flexible enough to adjust to your specific HR needs, whether you're syncing employee data with your payroll system, connecting HiBob to your internal analytics dashboard, or building custom workflows.

This article explores HiBob API's capabilities and potential integration challenges. You’ll also learn how to integrate with the API using two examples, which you can find in this Postman collection.

HiBob API Overview

The HiBob API gives you access to the core features of the HiBob platform, including endpoints for managing employee data, time-off requests, reports, and workforce planning. It also supports webhooks, which can provide real-time notifications for specific events and sync external systems with changes to employee data. The API uses a RESTful interface and JSON for data exchange, which allows you to interact with various resources in the HiBob HR platform. So, you're free to integrate it using any tech stack or language you choose.

You can integrate with the HiBob API as a customer (for your organization) or a partner (offering HR solutions to clients). The partnership program grants you access to detailed API documentation, support resources, and the necessary credentials for authentication. It enables users to build integrations securely and effectively while maintaining the integrity and security of HiBob's platform and user data.

Challenges and Complexities of the HiBob API

While the HiBob API is a powerful tool for integrating HR functionalities, developers may encounter several challenges and complexities during implementation. These range from authentication intricacies to handling custom fields and rate limits:

• Authentication and credential security: Like many modern APIs, HiBob employs secured basic authentication using service user accounts. You must implement secure storage for these credentials, and if you fail to manage tokens properly, it can ultimately lead to the compromise of your application and data within your HiBob account.
• Request and response complexity: Understanding the request-and-response structure can be challenging, particularly in dealing with complex data models and nested objects. You need to familiarize yourself thoroughly with the API documentation and test your requests extensively to ensure you are sending and receiving data in the expected format.
• Error handling: You must implement comprehensive error-handling routines to manage these responses effectively. These involve parsing error messages, logging them for debugging, and providing meaningful feedback to users or applications.
• Fetching custom fields: HiBob allows custom fields, which require careful mapping to internal systems. This process can be time-consuming and prone to errors and also requires a solid understanding of HiBob's rate limits.
• Rate limiting: Like most APIs, HiBob implements rate limits to prevent abuse and ensure fair usage. Due to this, you must design your integrations to implement retry logic and backoff strategies in order to avoid exceeding the limits.

Integrating with the HiBob API

In this section, you will explore how to make API calls to integrate your systems with HiBob, including how to set up authentication and authorization.

Authentication

To interact with the HiBob API, you need to authenticate your requests. HiBob uses basic auth, which requires obtaining an access token to authorize API requests from your backend. This process involves creating an API service user and building the authorization header for your API calls.

Creating an API Service User

First, you need to create a service user account, which will provide you with the ID and token required for authentication and authorization. This requires administrative privileges and access to a HiBob instance or approval from your organization's administrator.

You also need to provide permissions to the respective HiBob data that you intend to interact with via API. You can find more details on how to create a service account with the right permissions in the documentation.

Building the Authorization Header

Once you have provisioned an API service user, you use the ID and token of the service account as credentials for your API requests. This enables the HiBob API to identify information specific to your requests, such as who you are and what organization and data you're associated with.

To form the credentials, you append the token to your service user ID separated by a colon, as seen below:

SERVICE_USER_ID:TOKEN

You also need to encode this in Base64. Depending on your programming language, implementation will vary.

In Postman, after you create a collection, click on the authorization tab of the collection and select the Basic Auth option for Auth Type. This will provide you with two fields where you enter the service user's ID and the token as password, as seen in the image below:

Postman will automatically perform the Base64 encoding of the credentials for authorization when you make a request.

Using Your Authorization Headers for HiBob API Calls

Generally, integration into external systems from your apps requires API calls. The only thing that may change across the various calls is the operation and data exchanged via the request. However, authentication remains the same across all HiBob API calls. Below, you're going to look at two examples demonstrating how you can integrate with the HiBob API via HTTP calls. You will also see how to make the HTTP requests using the credentials you just set or encoded in the previous section. Note that you must have the required permissions to interact with the data that each endpoint provides.

The Employee Data API

In this first example, you'll use the employee data API to read employees' public profiles. You'll view all active employees using the GET profiles endpoint and present them in your application without having to duplicate records. From a list of profiles, you can quickly obtain an employee ID to perform further operations, as you will see in the next example.

To make this API call using Postman, start by creating a new request. Enter the endpoint URL, https://api.hibob.com/v1/profiles and select the GET method. Navigate to the Auth tab and ensure Type is set to Inherit auth from parent. This allows Postman to use the credentials defined earlier in the collection for authentication.

If your credentials are correct, once you send the request, the API should return a successful response displaying a list of employee objects with various attributes, as shown in the example below:

However, if your credentials are wrong, you should see a 401 Unauthorized error response with the output similar to the snippet below:

{
    "key": "exception.authentication.tokenNotMatch",
    "error": "Token not matches.",
    "args": []
}

In this example, the request is simplified using Postman, but in an actual application, you would have to create various classes or types to handle and manage the data for further operations.

You will also have to write substantial code to handle errors and exceptions, as mentioned earlier.

Time and Attendance API

In this example, you'll use the Time off API to manage time off for an employee. This API is useful when you need to integrate time-off management into your company's project management tool. It helps track employee absences to prevent scheduling conflicts and ensure workload coverage. To make informed decisions, you'll typically start by retrieving a list of existing time-off requests. This allows you to confirm that coverage is available before approving new requests. Then, using the employee ID (which you learned how to get in the previous example), you can submit a new time-off request for that employee.

You'll perform two API requests, one to show all time-off requests and the other to create a time-off request for a specific employee.

To get started, open Postman and create a new GET request using the Who's out API with the endpoint URL https://api.hibob.com/v1/timeoff/whosout . This endpoint requires you to specify the period within which you want to see the existing requests. You can do that by setting the following parameters:

• from: The start date for the time-off requests (eg "2024-09-16").
• to: The end date for the time-off requests (eg "2024-09-25").
• includePending: Set this to true to include pending requests.

Ensure that the checkboxes next to "from", "to", and "includePending" are selected in Postman before you send the request. The request uses the same authentication setup as before.

Once the existing time-off request data is displayed on your application's frontend, the user can decide to submit a new request for a specific employee.

Create a POST request to submit a new time-off request using the endpoint URL https://api.hibob.com/v1/timeoff/employees/{{id}}/requests. The {{ID}} must be replaced with the actual employee ID. This endpoint requires you to specify the following parameters:

• startDatePortion: To specify what part of the start date the request commences (eg"all_day").
• endDatePortion: The time of the last day within which the request ends (eg"morning").
• requestRangeType: The unit of period for the time off (eg “days").
• policyType: Specific type of time-off policy available for the employee (eg"Holiday")
• startDate: The start date for the time off for this request (eg “2024-05-29").
• endDate: The end date for the time off for this request (eg “2024-06-03").
• description: Some explanation or relevant details for this request (eg "Worn out from work").

All other parameters are detailed in the documentation.

In Postman, locate the "Body" tab of your request. Click the raw radio button option and ensure the input type set is JSON. Paste the following JSON snippet into the body field:

{
  "startDatePortion": "all_day",
  "endDatePortion": "morning",
  "requestRangeType": "days",
  "policyType": "Holiday",
  "startDate": "2024-05-29",
  "endDate": "2024-06-03",
  "description": "Worn out from work"
}

Modify the above to your case and send the request. The image below shows an example:

Again, you need to ensure the service user has the necessary permissions, or you'll encounter a 403 error. It's also important to note that you could run into "400 - Bad Request" errors for various reasons usually stated in the error message, such as in the following example:

{
   "key":"loa.timeoff.request.policy_type_does_not_exist_for_employee",
   "error":"Employee isn't assigned to policy type Sick on 29/05/2024",
   "args":[
      "Sick",
      "29/05/2024"
   ]
}

In the above case, you need to make sure the specified policy type exists and is configured for the respective employee.

Additional Hibob API Features to Explore

The features covered here are only a small sample of Hibob API’s capabilities. Here are a few more worth exploring:

• Tasks API: For managing and monitoring tasks assigned to employees. With this you can reassign tasks to different employees, monitor progress and mark them as completed. Suitable for integration with your project management software.

• Docs API: Document management is a key feature in Hibob’s system. This API can streamline workflows with other systems that may need to access various relevant documents. These documents could be shared folders, confidential folders or other custom permissioned folders.

• Reports API: This API can automate and seamlessly retrieve reports data that provide valuable insights about your organization’s workforce. This can be used to integrate with various analytics systems.

• Workforce Planning API: You can use this API to programmatically access various provisions for managing your workforce, such as budgets, positions, and position openings. It's great for tracking vacancies.

• Job Catalogue API: For interacting with the database of Job profiles, hierarchy and roles, and job content library for your organization.

Conclusion

As you’ve seen, the Hibob API offers a variety of tools to help you optimize and automate HR workflows. However, to ensure the data received from the API can be processed and used for further operations, you need to define the right data structures for each request. You must also follow best practices for error handling, request formation, and response parsing to maintain reliability and accuracy.

To simplify this process, you can use SDKs from unified API services like Apideck. Apideck provides a single integration layer that simplifies HiBob's API integration among other enterprise solutions. Its user-friendly interface and prebuilt connectors reduce development effort while maintaining quality and efficiency. Pricing is flexible based on your scale. Sign up today.