Here's everything you need to know about integrating Hibob with Knit, getting data and making API calls.

Getting started with Hibob APIs using Knit

To get started with Hibob, first you'll need to generate the integration credentials. Hibob has two kinds of credentials:

1. Service User: An API service user is a user type in Hibob whose sole purpose is to manage APIs in Hibob. They are dedicated API users used to make API calls only, and cannot be used to log in to Hibob. To know more about how to create a Service User, refer to this link: https://apidocs.hibob.com/docs/api-service-users
2. Employee REST API Key : Admins can also generate REST API keys which can used to make some API calls. To know more about REST tokens, refer to this link: https://apidocs.hibob.com/docs/rest-api-central-token-management

Service User Permissions

Knit recommends creating a Service User and selecting all the permissions in the following sections:

• People -> Directory
• People -> Employees
• People -> Lists
• People -> About
• People -> Address
• People -> Basic info
• People -> Email
• People -> Employment
• People -> Equity
• People -> Financial
• People -> Home
• People -> Identification
• People -> Jobs
• People -> Lifecycle
• People -> Payroll
• People -> Personal
• People -> Personal contact details
• People -> Work
• People -> Work contact details
• Docs -> Confidential Docs
• Docs -> Shared Docs

Integrating Hibob with the Knit UI component

In the Knit UI component, you'll need to enter the Service User ID of the user you just created, along with the Service User Token

That's it! Click on submit, and if you've created the user correctly, you should be able to see that the Authorization has been successfully completed.

Syncing Employee Data from Hibob APIs

📘

Check out Employee Data Model

Once the integration has been successfully done, you'll be able to sync the employee data models from Hibob. Knit supports the following models for Hibob:

• employee_profile
• employee_contactInfo
• employee_orgStructure
• employee_dependent
• employee_location
• employee_bankAccount
• employee_identification
• employee_rawValues

Create an Employee API in Hibob

To create an Employee in Hibob, we'll use the Create an Employee API.

Prerequisites

We'll need to get the List of Positions available in Hibob from the Get Positions API. This API gives us the list of titles available that can be attributed to an employee.

We'll take the positionId and designation from here that we want to attribute to the employee we create.

Parameters Allowed

For this API, we can pass the following parameters:

• firstName
• lastName
• employment
  • positionId (Taken from the Get Positions API
  • designation (Taken from the Get Positions API
• workEmail
• personalEmails (Note: Hibob only takes in 1 personal email for an employee. If you pass more than one email, only the first will be taken and rest will be ignored)
• workAddress
  • id (This ID corresponds to the Work Site in Hibob. To get the list of Work Sites available in Hibob, refer to this example: https://developers.getknit.dev/docs/hibob#get-list-of-work-sites-from-hibob)

The fields not supported by this API for Hibob are:

• employment -> workShiftId
• workAddress -> addressLine1, addressLine2, city, state, country, zipCode

A cURL request to create an employee could look like this:

curl --request POST \
     --url https://api.getknit.dev/v1.0/hr.employee.create \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --header 'X-Knit-Integration-Id: <YOUR_INTEGRATION_ID>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "employment": {
    "positionId": "Developer",
    "designation": "Developer"
  },
  "workAddress": {
    "id": "New York"
  },
  "firstName": "New",
  "lastName": "Employee",
  "workEmail": "[email protected]",
  "personalEmails": [
    "[email protected]"
  ]
}
'

Update an Employee Details API in Hibob

To update an employee's details in Hibob, we'll use the Update an Empployee API.

Parameters Allowed

For this API, we can pass the following parameters:

• firstName
• lastName
• employment
  • positionId (Taken from the Get Positions API
  • designation (Taken from the Get Positions API
• workEmail
• personalEmails (Note: Hibob only takes in 1 personal email for an employee. If you pass more than one email, only the first will be taken and rest will be ignored)
• workAddress
  • id (This ID corresponds to the Work Site in Hibob. To get the list of Work Sites available in Hibob, refer to this example: https://developers.getknit.dev/docs/hibob#get-list-of-work-sites-from-hibob)

The fields not supported by this API for Hibob are:

• employment -> workShiftId
• presentAddress
• workAddress -> addressLine1, addressLine2, city, state, country, zipCode

A cURL request to update an employee could look like this:

curl --request POST \
     --url https://api.getknit.dev/v1.0/hr.employee.update \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --header 'X-Knit-Integration-Id: <YOUR_INTEGRATION_ID>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "workAddress": {
    "id": "London"
  },
  "employment": {
    "positionId": "SDE",
    "designation": "SDE"
  },
  "employeeId": "3194789896568963153",
  "firstName": "UpdateName",
  "lastName": "UpdateSurname",
  "workEmail": "[email protected]",
  "personalEmails": [
    "[email protected]"
  ]
}
'

Get List of Work Sites from Hibob

To get the list of Work Site IDs from Hibob, we can use the Passthrough Request.

Since work sites correspond to the site list, we will use the Hibob's "Get a specific company list by name' API (https://apidocs.hibob.com/reference/get_company-named-lists-listname) to get the list of sites.

A cURL request to get the sites could look like this:

curl --request POST \
     --url https://api.getknit.dev/v1.0/passthrough \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --header 'X-Knit-Integration-Id: <YOUR_INTEGRATION_ID>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "method": "GET",
  "path": "company/named-lists/site"
}
'

and the response could look like:

{
  "name": "site",
  "values": [
    {
      "id": 1,
      "value": "London",
      "name": "London",
      "archived": false,
      "children": []
    },
    {
      "id": 2,
      "value": "New York",
      "name": "New York",
      "archived": false,
      "children": []
    },
    {
      "id": 3,
      "value": "Hong Kong",
      "name": "Hong Kong",
      "archived": false,
      "children": []
    }
  ]
}

We can use the value here and provide that in the worksite.id to create or update employees.

Compensation APIs in Hibob

In Hibob, an employee can have three types of Compensations:

• Fixed : Salary
• Variable: Bonus, Commission etc
• Stock Grants: Options, RSU etc

Additionally, Hibob supports both payPeriod and frequency for Salary.

Pay Period is generally the time for which the Salary is calculated and frequency is the time periods in which it is disbursed. For eg, the payPeriod for the salary component can be Annual, but the frequency in which it is disbursed can be Monthly.

Get Employee Compensation API

We can use the Get Employee Compensation API to get the compensation items for an employee.

A sample cURL request could look like:

curl --request GET \
     --url 'https://api.getknit.dev/v1.0/hr.employees.compensation?employeeId=123&originData=false' \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --header 'X-Knit-Integration-Id: <YOUR_INTEGRATION_ID>' \
     --header 'accept: application/json'

and the response could look like:

{
  "compensation": {
    "fixed": [
      {
        "type": "SALARY",
        "planId": "SALARY",
        "amount": 150000.0,
        "percentage": null,
        "currency": "USD",
        "payPeriod": "ANNUAL",
        "frequency": "MONTHLY"
      }
    ],
    "variable": [
      {
        "type": "Bonus",
        "planId": "Bonus",
        "amount": 250.0,
        "percentage": null,
        "currency": "USD",
        "payPeriod": "ANNUAL",
        "frequency": null
      },
      {
        "type": "Commission",
        "planId": "Commission",
        "amount": 15.0,
        "percentage": null,
        "currency": "USD",
        "payPeriod": "ANNUAL",
        "frequency": null
      }
    ],
    "stock": [
      {
        "planId": "Options",
        "type": "Options",
        "targetShares": 50.0,
        "optionsPercentage": null,
        "stockPercentage": null,
        "vestingScheduleId": null,
        "vestingScheduleName": null
      },
      {
        "planId": "RSU",
        "type": "RSU",
        "targetShares": 250.0,
        "optionsPercentage": null,
        "stockPercentage": null,
        "vestingScheduleId": null,
        "vestingScheduleName": null
      }
    ]
  }
}

Update Compensation for an Employee API

To update the compensation elements for an employee, we can use the Update Compensation API

Prerequisites

First, we'll need to get the list of Variable and Stock compensation types allowed by using the Get Comensation Plans API.

A sample response for the API could look like:

{
  "fixed": [
    {
      "planId": "SALARY",
      "planName": "SALARY",
      "description": "Salary",
      "amount": null,
      "percentage": null,
      "currency": null,
      "payPeriod": null,
      "frequency": null,
      "type": "SALARY"
    }
  ],
  "variable": [
    {
      "planId": "Bonus",
      "planName": "Bonus",
      "description": "Bonus",
      "amount": null,
      "percentage": null,
      "currency": null,
      "payPeriod": null,
      "frequency": null,
      "type": "Bonus"
    },
    {
      "planId": "Executive bonus",
      "planName": "Executive bonus",
      "description": "Executive bonus",
      "amount": null,
      "percentage": null,
      "currency": null,
      "payPeriod": null,
      "frequency": null,
      "type": "Executive bonus"
    },
    {
      "planId": "Commission",
      "planName": "Commission",
      "description": "Commission",
      "amount": null,
      "percentage": null,
      "currency": null,
      "payPeriod": null,
      "frequency": null,
      "type": "Commission"
    }
  ],
  "stock": [
    {
      "planId": "Options",
      "planName": "Options",
      "description": "Options",
      "type": "Options",
      "targetShares": null
    },
    {
      "planId": "RSU",
      "planName": "RSU",
      "description": "RSU",
      "type": "RSU",
      "targetShares": null
    },
    {
      "planId": "Stock award",
      "planName": "Stock award",
      "description": "Stock award",
      "type": "Stock award",
      "targetShares": null
    }
  ]
}

From this response, we can see that the allowed types for the compensation are as follows:

• Fixed: SALARY
• Variable: Bonus, Executive Bonus, Commission
• Stocks: Options, RSU, Stock Award

We'll use this type in the Update Compensation API to specify which element we want to update.

Parameters Allowed

For this API, we can pass the following parameters:

• employeeId
• effectiveDate
• fixed (Only 1 fixed element is allowed)
  • type (Only allowed type is SALARY)
  • amount
  • currency
  • payPeriod (Eg, ANNUAL, HOURLY, DAILY, WEEKLY, MONTHLY, HALF_YEARLY, QUARTERLY, or any custom type)
  • frequency (Eg, WEEKLY, MONTHLY, BI_WEEKLY, or any custom type)
• variable (Can be multiple)
  • type (From Get Compensation Plans API)
  • amount
  • currency
  • frequency (Eg, ANNUAL, HOURLY, DAILY, WEEKLY, MONTHLY, HALF_YEARLY, QUARTERLY, or any custom type)
• stocks (Can be multiple)
  • type (From Get Compensation Plans API)
  • targetShares

A sample cURL request could be as follows:

curl --request POST \
     --url https://api.getknit.dev/v1.0/hr.employee.compensation.update \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --header 'X-Knit-Integration-Id: <YOUR_INTEGRATION_ID>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "fixed": [
    {
      "type": "SALARY",
      "amount": 150000,
      "currency": "USD",
      "payPeriod": "ANNUAL",
      "frequency": "MONTHLY"
    }
  ],
  "variable": [
    {
      "type": "Bonus",
      "amount": 500,
      "currency": "USD",
      "frequency": "ANNUAL"
    },
    {
      "type": "Commission",
      "amount": 50,
      "currency": "USD",
      "frequency": "MONTHLY"
    }
  ],
  "employeeId": "123",
  "effectiveDate": "2023-10-02",
  "stocks": [
    {
      "type": "RSU",
      "targetShares": 100
    },
    {
      "type": "Options",
      "targetShares": 50
    }
  ]
}
'

📘

Things to keep in mind about Compensation APIs in Hibob

• Only 1 compensation element is allowed in fixed, i.e. SALARY
• SALARY must have a payPeriod. Default is Annual
• Get the variable and stock types from the Get Compensation Plans API

Documents APIs in Hibob

There are two folders in which we can upload documents for each employee:

• Shared Folder
• Confidential Folder

Upload a Document for an Employee API in Hibob

To upload a document, we can use the Upload Document API

In this API, you can specify the folder in which you want to upload the document through the category parameter :

• shared : Shared Folder
• confidential: Confidential Folder

If the category is not specified, the default folder is the Shared folder.

A sample cURL request could look like:

curl --request POST \
     --url https://api.getknit.dev/v1.0/hr.employees.document.upload \
     --header 'Authorization: Bearer <YOUR_API_KEY>' \
     --header 'X-Knit-Integration-Id: <YOUR_INTEGRATION_ID>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "employeeId": "123",
  "fileName": "Test.pdf",
  "fileUrl": "url.com",
  "category": "shared"
}
'

📘

You can either specify the fileContent and contentType or the fileUrl

If the fileUrl is given, the file content and content type would be downloaded and calculated using that.

However, if the fileUrl is not specified, then be sure to specify the fileContent and contentType parameters

Get Documents for an Employee API in Hibob

To get the list of documents for an employee, we can use the Get Employee Documents API

A sample response for the API could look like:

{
  "success": true,
  "data": {
    "documents": [
      {
        "id": "123",
        "fileName": "Passport-USA.pdf",
        "comment": null,
        "url": "document_url.com"
      }
    ]
  }
}

🚧

Document URL is only accessible if user is already logged in

The URL provided by Hibob for each document is only accessible through the browser and if you are already logged in to Hibob

Hibob APIs Used by Knit for Employee Sync and Actions