Guides
Signup For Free

BambooHR

Suggest Edits

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

Getting started with BambooHR APIs using Knit

To get started with BambooHR , first you'll need to generate the integration credentials. You'll need two things to integrate with BambooHR

  • SubDomain Name
  • API Key

How to get your SubDomain Name for BambooHR

SubDomain is the name of the company or URL at which you access BambooHR. For example, if you sign in at "acme.bamboohr.com", your subdomain is "acme".

In the screenshot, for example, the subdomain would be biznews

How to generate API Key in BambooHR

To generate an API key, you should log in and click on your name in the upper right-hand corner of any page on BambooHR to get to the user context menu.
If you have sufficient permissions, there will be an "API Keys" option in that menu to go to the page.

Once on that page, you can click in Add New API Key, specify a Key Name to get your API Key

Integrating BambooHR with the Knit UI component

In the Knit UI component, you'll need to enter the API Key you just created, along with the SubDomain

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 BambooHR APIs

📘

Check out Employee Data Model

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

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

Create an Employee API in BambooHR

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

Prerequisites

We'll need to get the List of Positions available in BambooHR 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
  • workEmail
  • personalEmails (Note: BambooHR 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 Location in BambooHR. To get the list of Work Locations available in BambooHR, refer to this example: Get Locations in BambooHR

The fields not supported by this API for BambooHR 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": "Web Designer",
    "designation": "Web Designer"
  },
  "workAddress": {
    "id": "London, UK"
  },
  "firstName": "New",
  "lastName": "Employee",
  "workEmail": "[email protected]",
  "personalEmails": [
    "[email protected]"
  ]
}
'

Update an Employee Details API in BambooHR

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

Parameters Allowed

For this API, we can pass the following parameters:

  • firstName
  • lastName
  • employment
  • workEmail
  • personalEmails (Note: BambooHR 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 Location in BambooHR. To get the list of Work Locations available in BambooHR, refer to this example: Get Locations in BambooHR
  • presentAddress

The fields not supported by this API for BambooHR are:

  • employment -> workShiftId
  • 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]"
  ],
  "presentAddress": {
    "addressLine1": "Line1",
    "addressLine2": "Line2",
    "city": "New York",
    "state": "New York",
    "country": "USA",
    "zipCode": "10005"
  }
}
'

Get List of Work Locations from BambooHR

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

Since work sites correspond to the location list, we will use the BambooHR's 'Get details for list fields' API (https://documentation.bamboohr.com/reference/metadata-get-details-for-list-fields-1) to get the list of locations.

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": "meta/lists"
}
'

and the response could look like the following. The API will give us the options for all the lists in the account. Search for the one where the alias is location

[
  {
    "fieldId": 18,
    "manageable": "no",
    "multiple": "no",
    "name": "Location",
    "options": [
      {
        "id": 18235,
        "archived": "no",
        "createdDate": "2023-07-22T19:22:19+00:00",
        "archivedDate": null,
        "name": "Lindon, Utah"
      },
      {
        "id": 18238,
        "archived": "no",
        "createdDate": "2023-07-22T19:22:19+00:00",
        "archivedDate": null,
        "name": "London, UK"
      },
      {
        "id": 18352,
        "archived": "no",
        "createdDate": "2023-09-07T17:40:27+00:00",
        "archivedDate": null,
        "name": "Remote Worker"
      },
      {
        "id": 18240,
        "archived": "no",
        "createdDate": "2023-07-22T19:22:20+00:00",
        "archivedDate": null,
        "name": "Sydney, Australia"
      },
      {
        "id": 18243,
        "archived": "no",
        "createdDate": "2023-07-22T19:22:20+00:00",
        "archivedDate": null,
        "name": "Vancouver, Canada"
      }
    ],
    "alias": "location"
  }
]

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

Compensation APIs in BambooHR

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

  • Fixed : Salary
  • Variable: Commission, Hourly, Overtime

However, BambooHR allows only one type of compensation element for an employee. An employee can have only one compensation of type Salary, or Hourly or Commission.

Along with Salary and Hourly types, Overtime is allowed.

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": null,
        "amount": 150000.0,
        "percentage": null,
        "currency": "USD",
        "payPeriod": "ANNUAL",
        "frequency": "BI_WEEKLY"
      }
    ],
    "variable": [
      {
        "type": "Overtime",
        "planId": null,
        "amount": 5.0,
        "percentage": null,
        "currency": "USD",
        "payPeriod": null,
        "frequency": null
      }
    ],
    "stock": null
  }
}

Update Compensation for an Employee API

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

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
    • payPeriod (Eg, ANNUAL, WEEKLY, QUARTERLY, WEEKLY, MONTHLY, DAILY, HOURLY)
    • frequency (Eg, BI_WEEKLY, or any custom type)
  • variable
    • type (Can be Commission, Hourly or Overtime)
    • amount
    • payPeriod (Eg, ANNUAL, WEEKLY, QUARTERLY, WEEKLY, MONTHLY, DAILY, HOURLY)
    • frequency (Eg, BI_WEEKLY, or any custom type)

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"
    }
  ],
  "variable": [
    {
      "type": "Overtime",
      "amount": 500
    }
  ],
  "employeeId": "123",
  "effectiveDate": "2023-10-02"
}
'

📘

Things to keep in mind about Compensation APIs in BambooHR

  • Only 1 compensation element out of Salary, Commission or Hourly is allowed
  • Overtime element is allowed with Salary or Hourly elements only

Documents APIs in BambooHR

Upload a Document for an Employee API in BambooHR

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

Prerequisites

We'll need to get the document categories for an employee from BambooHR before we can upload a document. To do so, follow the guide here: <>

After we have the category, we can upload the document for an employee. 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": "13"
}
'

📘

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 Employee Document Categories through BambooHR API

To get the list of Employee Document Categories from BambooHR, we can use the Passthrough Request.

We will use the BambooHR's 'List employee files and categories' API (https://documentation.bamboohr.com/reference/list-employee-files-1) to get the list of Document Categories.

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": "employees/<employee id>/files/view/"
}
'

and the response could look like the following. The API will give us the options for all the lists in the account. Search for the one where the alias is location

{
  "employee": {
    "id": 116
  },
  "categories": [
    {
      "id": 13,
      "name": "Resumes and Applications",
      "canRenameCategory": "yes",
      "canDeleteCategory": "yes",
      "canUploadFiles": "yes",
      "displayIfEmpty": "yes",
      "files": []
    },
    {
      "id": 12,
      "name": "Signed Documents",
      "canRenameCategory": "yes",
      "canDeleteCategory": "yes",
      "canUploadFiles": "yes",
      "displayIfEmpty": "yes",
      "files": []
    },
    {
      "id": 11,
      "name": "Tasklist Attachments",
      "canRenameCategory": "yes",
      "canDeleteCategory": "yes",
      "canUploadFiles": "yes",
      "displayIfEmpty": "yes",
      "files": []
    },
    {
      "id": 10,
      "name": "Workflow Attachments",
      "canRenameCategory": "yes",
      "canDeleteCategory": "yes",
      "canUploadFiles": "yes",
      "displayIfEmpty": "yes",
      "files": []
    }
  ]
}

We can use the categories.id here and provide that in the category to upload a new document

Get Employee Documents API in BambooHR

To get the list of documents in BambooHR, we can use the Get Employee Documents API

A sample response could look like:

{
  "success": true,
  "data": {
    "documents": [
      {
        "id": "2897.33",
        "category": "Workflow Attachments",
        "fileName": "Passport-USA.pdf"
      }
    ]
  }
}

However, BambooHR does not provide the document content in the same API. To get the document content, we can use the Passthrough Request.

We can pick the document id from here for which we have to download the content. We will use the BambooHR's 'Get an Employee File' API (https://documentation.bamboohr.com/reference/get-employee-file-1) to get the document content

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": "employees/<employee id>/files/<document id>"
}
'

And the response would be the document content

📘

Things to keep in mind about Document APIs in BambooHR

  • Get the Employee Document Categories before uploading a document.
  • Use Passthrough Request to get the document content for a particular file

BambooHR APIs Used by Knit for Employee Sync and Actions

Used ForAPI EndpointProtocolAuthentication
Employee SyncGET
https://api.bamboohr.com/api/gateway.php/$subDomain/v1/reports/custom?format=JSON		RESTBearer - API Key
Employee DependentsGET
https://api.bamboohr.com/api/gateway.php/$subDomain/v1/employeedependents/?employeeid=$employeeId		RESTBearer - API Key
Create EmployeePOST
https://api.bamboohr.com/api/gateway.php/$subDomain/v1/employees		RESTBearer - API Key
Update EmployeePOST
https://api.bamboohr.com/api/gateway.php/$subDomain/v1/employees/$employeeId		RESTBearer - API Key
Terminate EmployeePOST
https://api.bamboohr.com/api/gateway.php/$subDomain/v1/employees/$employeeId/tables/employmentStatus		RESTBearer - API Key
Get Employee DocumentsGET
https://api.bamboohr.com/api/gateway.php/$subDomain/v1/employees/$employeeId/files/view		RESTBearer - API Key
Upload Employee DocumentPOST
https://api.bamboohr.com/api/gateway.php/$subDomain/v1/employees/$employeeId/files		RESTBearer - API Key
Update Compensation POST
https://api.bamboohr.com/api/gateway.php/$subDomain/v1/employees/$employeeId		RESTBearer - API Key

Updated 11 months ago