HiBob–Zluri Integration Guide: Connect via REST API (Service User Token Method) - snehilkusum/API-Documentation-Samples GitHub Wiki

🔗 HiBob–Zluri Integration Guide: Connect via REST API (Service User Token Method)

This guide walks you through the step-by-step technical process of integrating HiBob with Zluri using HiBob’s REST API and service user credentials. This secure method enables Zluri to retrieve organizational data like employee directories, time off, metadata, and more directly from HiBob.

📋 Table of Contents

  1. Overview
  2. Prerequisites
  3. Create API Service User in HiBob
  4. Set API Permissions
  5. Build Authorization Header
  6. Connect HiBob with Zluri
  7. Test the API
  8. Available API Endpoints
  9. Troubleshooting
  10. References

🔍 Overview

  • Integration Type: REST API (Token Authentication)
  • Authentication: Basic Auth (Base64 encoded ServiceUserID:Token)
  • Method: Service User with Permissions
  • Data Sync Direction: HiBob ➝ Zluri
  • Primary Use Cases: Sync employee metadata, org charts, PTO, custom fields, and job catalog data

✅ Prerequisites

  • Admin access in HiBob
  • Admin access in Zluri
  • API access enabled in your HiBob environment
  • An API Service User and Permission Group configured in HiBob

👤 Create API Service User in HiBob

  1. Log into your HiBob account as an Admin.
  2. Navigate to Settings → Integrations → Service Users
  3. Click Create Service User
  4. Name it: Zluri Integration User
  5. Once created, copy the Service User ID and Token

    ⚠️ Note: You’ll only see the token once. Store it securely.

🔐 Set API Permissions

Step 1: Create a Permission Group

  1. Go to Settings → Permission Groups
  2. Click Create Group
  3. Name it: Zluri API Group
  4. Type: Service User
  5. Add your newly created Service User to this group

Step 2: Assign Required Permissions

Assign permissions based on the type of data Zluri needs to access.

🔑 Key Permission Areas:

  • Employee Data

    • View (and Edit if needed) for:
      • Basic Info
      • Contact Info
      • Employment History
      • Work Data

  • Time Off

    • Access leave balances, requests, and policies

  • Job Catalog

    • Access job profiles and org positions

  • Reports

    • Permission to download reports via API

  • Metadata & Fields

    • View field structure and schema

⚠️ To access historical or sensitive data, enable View history or Edit accordingly.

🔑 Build Authorization Header

HiBob uses Basic Auth with a Base64-encoded string: ServiceUserID:Token

Example in Postman:

  1. Go to Authorization tab
  2. Type: Basic Auth
  3. Username: SERVICE_USER_ID
  4. Password: TOKEN
  5. Postman auto-encodes for Basic Auth

🔌 Connect HiBob with Zluri

  1. Go to Zluri Admin Console
  2. Navigate to Apps > HiBob > Connect
  3. Enter the following details:
    • Service User ID
    • API Token
    • HiBob Subdomain (e.g., yourcompany.hibob.com)
  4. Click Connect to test and validate
  5. Once connected, Zluri starts syncing supported employee data automatically

🧪 Test the API

Use Postman or HiBob API Docs (Try It!) to test endpoints.

  • URL: https://api.hibob.com/v1/profiles
  • Method: GET
  • Auth Type: Basic Auth
  • Headers: Authorization: Basic BASE64_ENCODED(ServiceUserID:Token)

✅ Success Response

[
  {
    "id": "abc123",
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "[email protected]"
  }
]

### ❌ Error Response (Invalid Token)

```json
{
  "key": "exception.authentication.tokenNotMatch",
  "error": "Token not matches."
}

🔗 Available API Endpoints (Highlights)

Endpoint Use Case
GET /people Fetch employee directory
GET /tables Retrieve custom data tables
GET /timeoff Pull time off requests/balances
GET /jobcatalog Sync org-level job roles/categories
GET /reports Download generated HiBob reports
GET /metadata View metadata and schema structure

❗ Troubleshooting

Issue Cause Solution
403 Forbidden Missing permissions Update Permission Group
401 Unauthorized Incorrect token or ID Regenerate token and retry
Timeout / Empty Network/API config issues Check logs, ensure uptime

📎 References

Got questions? Feel free to submit a ticket or contact us directly at [email protected].