# BambooHR — HRIS API: gotchas

> Canonical URL: https://developers.apideck.com/apis/hris/bamboohr/gotchas

## GET /hris/employees

The employment role field will return "other" for list calls when the employee is terminated. To fetch the correct employment role data, you need to call the employee detail endpoint.

BambooHR does not publish its rate limits and throttles at its discretion. When BambooHR throttles the
request for the record or list you asked for, Unify returns HTTP 429. When BambooHR includes a retry
delay, the 429 carries `Retry-After` (seconds to wait) and `x-downstream-ratelimit-reset` (Unix epoch
time in milliseconds after which to retry). No limit or remaining-request headers are provided.

## POST /hris/employees

BambooHR does not publish its rate limits and throttles at its discretion. When BambooHR throttles the
request to create the employee, Unify returns HTTP 429. When BambooHR includes a retry delay, the 429
carries `Retry-After` (seconds to wait) and `x-downstream-ratelimit-reset` (Unix epoch time in
milliseconds after which to retry). No limit or remaining-request headers are provided.

## POST /hris/employees

BambooHR has no primary email or phone field, so only these `emails[].type` and `phone_numbers[].type`
values are written: emails `work` → Work Email and `personal` → Home Email; phone numbers `work` → Work
Phone (with `extension` → Work Phone Extension), `mobile` → Mobile Phone and `home` → Home Phone. Any
other type, including `primary`, is ignored and that email or phone number is not saved.

List Employees and Get Employee return a `primary` email that is a read-only copy of the work email. To
change it, send the `work` email.

## GET /hris/employees/{id}

BambooHR does not publish its rate limits and throttles at its discretion. When BambooHR throttles the
request for the record or list you asked for, Unify returns HTTP 429. When BambooHR includes a retry
delay, the 429 carries `Retry-After` (seconds to wait) and `x-downstream-ratelimit-reset` (Unix epoch
time in milliseconds after which to retry). No limit or remaining-request headers are provided.

## PATCH /hris/employees/{id}

BambooHR does not publish its rate limits and throttles at its discretion. When BambooHR throttles the
request to update the employee, Unify returns HTTP 429. When BambooHR includes a retry delay, the 429
carries `Retry-After` (seconds to wait) and `x-downstream-ratelimit-reset` (Unix epoch time in
milliseconds after which to retry). No limit or remaining-request headers are provided.

## PATCH /hris/employees/{id}

BambooHR has no primary email or phone field, so only these `emails[].type` and `phone_numbers[].type`
values are written: emails `work` → Work Email and `personal` → Home Email; phone numbers `work` → Work
Phone (with `extension` → Work Phone Extension), `mobile` → Mobile Phone and `home` → Home Phone. Any
other type, including `primary`, is ignored and that email or phone number is not saved.

If nothing else in the update maps to a BambooHR field (for example, a request that only contains
`primary` entries), BambooHR rejects the empty update with a 400 `Malformed JSON` error.

List Employees and Get Employee return a `primary` email that is a read-only copy of the work email. To
change it, send the `work` email.

## GET /hris/companies

BambooHR only allows access to company data for the currently authorized connection.

BambooHR does not publish its rate limits and throttles at its discretion. When BambooHR throttles the
request for the record or list you asked for, Unify returns HTTP 429. When BambooHR includes a retry
delay, the 429 carries `Retry-After` (seconds to wait) and `x-downstream-ratelimit-reset` (Unix epoch
time in milliseconds after which to retry). No limit or remaining-request headers are provided.

## GET /hris/companies/{id}

BambooHR does not publish its rate limits and throttles at its discretion. When BambooHR throttles the
request for the record or list you asked for, Unify returns HTTP 429. When BambooHR includes a retry
delay, the 429 carries `Retry-After` (seconds to wait) and `x-downstream-ratelimit-reset` (Unix epoch
time in milliseconds after which to retry). No limit or remaining-request headers are provided.

## GET /hris/departments

BambooHR does not expose a total record count in department list responses. `meta.total_count` will not appear.

BambooHR does not publish its rate limits and throttles at its discretion. When BambooHR throttles the
request for the record or list you asked for, Unify returns HTTP 429. When BambooHR includes a retry
delay, the 429 carries `Retry-After` (seconds to wait) and `x-downstream-ratelimit-reset` (Unix epoch
time in milliseconds after which to retry). No limit or remaining-request headers are provided.

## GET /hris/departments/{id}

BambooHR does not publish its rate limits and throttles at its discretion. When BambooHR throttles the
request for the record or list you asked for, Unify returns HTTP 429. When BambooHR includes a retry
delay, the 429 carries `Retry-After` (seconds to wait) and `x-downstream-ratelimit-reset` (Unix epoch
time in milliseconds after which to retry). No limit or remaining-request headers are provided.

## GET /hris/schedules/employees/{employee_id}

The employment role field will return "other" for list calls when the employee is terminated. To fetch the correct employment role data, you need to call the employee detail endpoint.
## GET /hris/time-off-requests

BambooHR requires start_date and end_date parameters to successfully retrieve time off requests. These optional Unify parameters can be sent as filters[start_date] and filters[end_date]. If there are not present, they are sent to BambooHR with the default values of '1900-01-01' & '2100-12-31' respectively.

BambooHR does not publish its rate limits and throttles at its discretion. When BambooHR throttles the
request for the record or list you asked for, Unify returns HTTP 429. When BambooHR includes a retry
delay, the 429 carries `Retry-After` (seconds to wait) and `x-downstream-ratelimit-reset` (Unix epoch
time in milliseconds after which to retry). No limit or remaining-request headers are provided.

## GET /hris/time-off-requests/employees/{employee_id}/time-off-requests/{id}

BambooHR does not publish its rate limits and throttles at its discretion. When BambooHR throttles the
request for the record or list you asked for, Unify returns HTTP 429. When BambooHR includes a retry
delay, the 429 carries `Retry-After` (seconds to wait) and `x-downstream-ratelimit-reset` (Unix epoch
time in milliseconds after which to retry). No limit or remaining-request headers are provided.


[API reference](https://developers.apideck.com/apis/hris/reference.md) · [Coverage matrix](https://developers.apideck.com/apis/hris/coverage)