---
title: "List Employees"
method: GET
path: "/v1/employees"
tags: ["Employees"]
---

# List Employees

`GET /v1/employees`

## Request

- Base URL: `https://api.bluehive.com`
- URL: `https://api.bluehive.com/v1/employees`
- Auth: API key in header `Authorization`
- TypeScript: <https://skmtc.dev/bluehive-health/apis/bluehive-api/docs/v1/employees/get.ts> (a function with typed inputs; its response is checked against the schema)

List all employees for a given employer with pagination.

## Query parameters

- `employerId` string, required
- `limit` string
- `offset` string

## Response `200`

Employees retrieved successfully

- object: Employees retrieved successfully
  - `success` boolean, required
  - `employees` object[], required: List of employees
    - `_id` string, required: Unique identifier
    - `firstName` string, required: First name
    - `lastName` string, required: Last name
    - `email` string, required: Email address
    - `dob` string: Date of birth
    - `title` string: Job title
    - `activeAccount` 'Active' | 'Inactive': Account status
    - `blurb` string: Brief description or bio
    - `address` object: Employee address
      - `street1` string, required: Street address line 1
      - `street2` string: Street address line 2
      - `city` string, required: City
      - `state` string, required: State
      - `postalCode` string, required: Postal code
      - `county` string: County
      - `country` string: Country
    - `phone` object[]: Contact phone numbers
      - `number` string, required: Phone number
      - `type` 'Cell' | 'Home' | 'Work' | 'Other', required: Type of phone number
    - `employer_id` string, required: ID of associated employer
    - `departments` string[]: List of department names
    - `extendedFields` object[]: Additional custom fields
      - `name` string, required: Field name
      - `value` string, required: Field value
    - `createdAt` string, date-time: Creation timestamp
    - `createdBy` string: ID of user who created the employee
    - `updatedAt` string, date-time: Last update timestamp
    - `updatedBy` string: ID of user who last updated the employee
  - `total` number, required: Total number of employees returned
  - `message` string, required

## Other responses

- `400`: Validation error
- `401`: Authentication error
- `404`: Employer not found
- `500`: Server error

## Changes

- **2026-10-16** `a8bcbdf02e33`: 2 warning
  - deleted the `query` request parameter `activeAccount`
  - deleted the `query` request parameter `search`
- **2026-03-17** `4abf46539e83`: 2 info
  - added the new optional `query` request parameter `activeAccount`
  - added the new optional `query` request parameter `search`
- **2025-10-03** `2e0dd34abf24`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/bluehive-health/apis/bluehive-api/changes/v1/employees/get.md)

---

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