Technical Overview

Making Requests

All requests made to our APIs must be sent over HTTPS. The SSL certificate used for the HTTPS connection is signed and all implementations should configure their SSL layer to verify it.
API requests are made to a URL that begins with
https://api.bamboohr.com/api/gateway.php/{company subdomain name}/
API requests can be throttled if BambooHR deems them to be too frequent. Implementations should always be ready for a 503 Service Unavailable response.
Implementations should also always be ready for general Internet packet loss resulting in broken connections with no HTTP response.
Each employee has an immutable employee ID that is unique within a single company that you can use to reference the employee.
All requests should be in UTF-8.

Standard HTTP Responses

Every request includes an HTTP status code with the result. The status code should be examined before the response.

Successful Status Codes (2xx)


200	OK	The request was successful.
201	Created	The resource was successfully created. Confirms a success when creating a new employee, time off request, etc.

Client Error Status Codes (4xx)


400	Bad Request	The request was invalid or could not be understood by the server. Resubmitting the request will likely result in the same error.
401	Unauthorized	Your API key is missing.
403	Forbidden	The application is attempting to perform an action it does not have privileges to access. Verify your API key belongs to an enabled user with the required permissions.
404	Not Found	The resource was not found with the given identifier. Either the URL given is not a valid API or the ID of the object specified in the request is invalid.
406	Not Acceptable	The request contains references to non-existent fields.
409	Conflict	The request attempts to create a duplicate. For employees, duplicate emails are not allowed. For lists, duplicate values are not allowed.
429	Limit Exceeded	The account has reached its employee limit. No additional employees could be added.

Server Error Status Codes (5xx)


500	Internal Error	The server encountered an error while processing your request and failed. Retrying may be appropriate.
502	Gateway Error	The load balancer or web server had trouble connecting to the BambooHR app. Please try the request again.
503	Unavailable	This endpoint is currently unavailable. Retrying may be appropriate. Commonly, this is due to rate limiting, and a "Retry-After" header may be available.

You can future proof your code by using the following ranges:
200–299 as success
400–499 as client request errors
500–599 as server errors

Errors

Most 400-level errors and some 500-level errors will include a header "X-BambooHR-Error-Message" in the response. This header may help debug errors that you receive. These messages should not be used to programmatically detect and display errors to users, but should be useful during development, and for logging in production. The text of these messages may change at any time.

Compatibility Between Versions

Every attempt will be made to make only forward compatible changes to the API. To assist this effort, API consumers should ignore any XML tags and attributes they do not recognize.

The API will support multiple major version numbers of the API. Currently, the only version is "V1." If a major API change becomes necessary, we’ll create a new major version number and communicate the change to our partners. We’ll maintain the existing "V1" API for a reasonable period of time.