The Photos API allows you to retrieve employee photos. There is a standard API-based mechanism for retrieving the photo binary data.

There is also a browser-based mechanism that does not require API authentication. This can be used to serve employee photos for any person you have an email address for, without having to make an API call to BambooHR.

Get an employee photo
HTTP Method:
/api/gateway.php/{company}/v1/employees/{employee id}/photo/small
Returns the binary data for the employee photo.

The "small" indicates the cropped photo that is used in BambooHR. In the future other photo sizes, such as the uncropped photo, may be added.

{employee id} represents the BambooHR numeric employee ID for the employee.

The small image will always be of content type "image/jpeg".

The small image will always be 150x150.

Sample Request:
GET /api/gateway.php/test/v1/employees/1/photo/small
Upload an employee photo
HTTP Method:
/api/gateway.php/{company}/v1/employees/{employee id}/photo
Success response:

201 - if the file was successfully uploaded.

Failure response:

404 - if the employee doesn't exist

413 - if the file is too big.

415 - if the file is not in a supported file format or if the width doesn't match the height.

Stores a new employee photo

The width and height of the photo must be the same number of pixels.

The API user must have photo uploading permission.

The source photo must be a jpg, gif, or png.

The photo file may not be larger than 20MB.

Special Notes:
The file upload methods accept multi-part forms. To build a multi-part form concatenate the individual sections together separated by a boundary. Then take the length of the resulting body and use that as the Content-Length for the submission. (See here, here, and here.)

Sample Request: (with HTTP headers shown, binary photo data not shown)

POST /api/gateway.php/sample/v1/employees/1/photo/ HTTP/1.0
Content-Type: multipart/form-data; boundary=----BambooHR-MultiPart-Mime-Boundary----
Content-Length: 520

Content-Disposition: form-data; name="file"; filename="photo.jpg"
Content-Type: text/plain

... binary file data ...

Using a photo from BambooHR's servers
HTTP Method:

https://{company}{hashed email}
http://{company}{hashed email}

It is now possible to add photos to your web pages that reference a given employee's photo in BambooHR. This is done by requesting a special URL from our servers. No authentication is required, you can simply link to the employee photo.

{hashed email} is the hash of the employee's work email. If they don't have a work email then the hash of the home email will work. If they do have a work email then the home email will not work.

The email address must be representable in ASCII.

The hash is computed as the following md5(strtolower(trim($email))), where the trim() function eliminates ASCII whitespace, the strtolower() function converts ASCII text to lowercase and the md5 function produces a hex string representing the MD5 hash of the data. In PHP you can use these exact functions, in other languages there will be equivalent functions you can use.

The image will always be of content type "image/jpeg".

The image will always be 150x150.

If the employee doesn't have a photo, or if the hash doesn't identify an employee, then a 301 redirect will be returned and pointing to a blank employee photo.

API demo photo

Sample Usage:

<img src="" />

Have more questions? We're here to help, so please contact us.