---
title: "Get Employee Photo"
method: GET
path: "/api/v1/employees/{employeeId}/photo/{size}"
tags: ["Photos", "Public API"]
---

# Get Employee Photo

`GET /api/v1/employees/{employeeId}/photo/{size}`

## Request

- Base URL: `https://companySubDomain.bamboohr.com`
- URL: `https://companySubDomain.bamboohr.com/api/v1/employees/{employeeId}/photo/{size}`
- Auth: one of:
  - HTTP basic
  - OAuth 2
    - Authorization code: `/authorize.php`
    - Token URL: `/token.php` scopes: `employee:photo`
- TypeScript: <https://skmtc.dev/bamboohr/apis/bamboohr-api/docs/api/v1/employees/:employeeId/photo/:size/get.ts> (a function with typed inputs; its response is checked against the schema)

Returns an employee photo at the requested size. Available sizes are: `original` (full resolution), `large` (340×340), `medium` (170×170), `small` (150×150), `xs` (50×50), and `tiny` (20×20). The response shape is selected via standard HTTP content negotiation. By default the body is the stored image bytes and the `Content-Type` response header matches the body (`image/jpeg`, `image/png`, `image/bmp`, `image/gif`, or `image/tiff`). When the caller sends `Accept: application/json`, the body is a JSON object `{ mimeType, fileBase64 }` with the same image bytes base64-encoded. The JSON variant is not recommended for AI connector use, since the base64 payload is too large for an AI model to consume reliably as text input. For AI connectors that need to display or reference a photo, use the `photoUrl` field returned by `list-employees` instead. It is a time-limited signed URL that avoids transferring image bytes through the AI model's context.

A 404 response covers three distinct cases: (1) the employee exists but has no photo on file (a normal, non-error state), (2) the employee ID does not exist, or (3) the size value is not one of the recognized options. The `x-bamboohr-error-message` response header distinguishes them: `Employee photo not found`, `Employee not found`, or `Size: "<value>" is not a valid size option. Valid sizes are: xs, small, tiny, original, medium and large.`. Treat "Employee photo not found" as a normal "no photo on file" result rather than as a bad employee ID, permission failure, or other error to debug.

OAuth Scopes: employee:photo

## Path parameters

- `employeeId` integer, required
- `size` 'original' | 'large' | 'medium' | 'small' | 'xs' | 'tiny', required

## Query parameters

- `width` integer
- `height` integer

## Headers

- `If-None-Match` string

## Response `200`

Employee photo, returned in one of two shapes via standard HTTP content negotiation: binary `image/*` bytes by default (matching the stored format), or `application/json` with `{ mimeType, fileBase64 }` when the caller sends `Accept: application/json`. The response is cacheable: send the `ETag` value back as `If-None-Match` on a later request to revalidate without re-downloading the image bytes.

- object
  - `mimeType` string, required: The actual MIME type of the underlying image (e.g. `image/jpeg`, `image/png`, `image/bmp`, `image/gif`, `image/tiff`). Use this to identify the format of the decoded bytes.
  - `fileBase64` string, byte, required: Base64-encoded image bytes. Decoding produces the same bytes returned by the binary variant of this endpoint.

## Other responses

- `304`: The caller's `If-None-Match` header matches the current photo's ETag, so the photo is unchanged and the body is omitted. Only returned when the request includes `If-None-Match`.
- `403`: The authenticated user does not have permission to view this employee's photo.
- `404`: Returned in three distinct cases: the employee does not exist, the employee has no photo on file, or the requested size is not a recognized value. The `x-bamboohr-error-message` response header reports which case applies (`Employee not found`, `Employee photo not found`, or `Size: "<value>" is not a valid size option. Valid sizes are: xs, small, tiny, original, medium and large.`). "Employee photo not found" is the expected response for an employee who simply has not uploaded a photo and should not be treated as an error to debug.

## Changes

- **2026-11-03** `922fc15f43a7`: 2 info
  - added the new optional `header` request parameter `If-None-Match`
  - added the non-success response with the status `304`

[Operation history](https://skmtc.dev/bamboohr/apis/bamboohr-api/changes/api/v1/employees/:employeeId/photo/:size/get.md)

---

[API](https://skmtc.dev/bamboohr/apis/bamboohr-api.md) - [All operations](https://skmtc.dev/bamboohr/apis/bamboohr-api/llms.txt) - [OpenAPI document](https://skmtc.dev/bamboohr/apis/bamboohr-api/revisions/922fc15f43a7?raw)