List employees

Lists employees with filters, sorting and offset pagination

Get all employees

get

Get all employees with pagination and optional filters

Authorizations

AuthorizationstringRequired

Harmony access key, sent as Authorization: AccessKey <your-key>. Create keys in Settings > Access Keys. The tenant is resolved from the key.

Query parameters

include_custom_fields_configbooleanOptional

Include custom field config metadata

Default: false

limitinteger · min: 1 · max: 10000OptionalDefault: 100

offsetintegerOptionalDefault: 0

idstring[] · nullableOptional

work_emailstring · email[] · nullableOptional

sync_statusstring · enum · nullableOptional

Employee sync status.

Values: SYNCED: Employee data synchronized from external systems. This is the default and main use-case.

LOCAL: Employee created manually via API,
       not synced. This usually happens whenever
       a resource related employee was not found
       in the local system.
       'LOCAL' employees will usually have
       missing data, and may not refer to real
       employees in the organization.
       The status may change later to 'SYNCED'
       automatically.

Possible values:

custom_field_filtersstring · nullableOptional

any_statusbooleanOptionalDefault: false

include_deletedbooleanOptionalDefault: false

qstring · min: 1 · max: 200 · nullableOptional

sort_bystring · enumOptionalDefault: work_emailPossible values:

custom_field_sort_bystring · nullableOptional

custom_field_sort_typestring · enum · nullableOptionalPossible values:

sort_directionstring · enumOptional

Sort direction.

Default: ascPossible values:

is_vipboolean · nullableOptional

locationstring[] · nullableOptional

departmentstring[] · nullableOptional

manager_idstring[] · nullableOptional

levelstring[] · max: 250 · nullableOptional

Level(s) to filter by

employment_start_date_fromstring · date · nullableOptional

Filter employees with start date on or after this date

employment_start_date_tostring · date · nullableOptional

Filter employees with start date on or before this date

employment_end_date_fromstring · date · nullableOptional

Filter employees with end date on or after this date

employment_end_date_tostring · date · nullableOptional

Filter employees with end date on or before this date

Responses

200

Successful Response

application/json

total_countintegerRequired

The total number of items available to return for this query.

422

Validation Error

application/json

get/api/v1/employees/

GET /employees/api/v1/employees/ HTTP/1.1
Host: api.harmony.io
Authorization: YOUR_API_KEY
Accept: */*

{
  "total_count": 1,
  "items": [
    {
      "first_name": "text",
      "last_name": "text",
      "job_title": "text",
      "department": "text",
      "location": "text",
      "location_details": {
        "name": "text",
        "city": "text",
        "state": "text",
        "country": "text",
        "country_code": "text"
      },
      "timezone": "text",
      "manager_name": "text",
      "manager_id": "text",
      "photo_url": "text",
      "phone_numbers": [
        {
          "type": "mobile",
          "number": "text"
        }
      ],
      "employment_status": "active",
      "employment_start_date": "2026-01-01",
      "employment_end_date": "2026-01-01",
      "employment_role": "text",
      "employment_type": "full_time",
      "level": "text",
      "id": "text",
      "work_email": "[e-mail]",
      "sync_status": "SYNCED",
      "type": "person",
      "display_name": "text",
      "settings": {
        "is_vip": false
      },
      "custom_fields": {
        "ANY_ADDITIONAL_PROPERTY": {
          "ANY_ADDITIONAL_PROPERTY": "text"
        }
      },
      "custom_fields_with_config": {
        "ANY_ADDITIONAL_PROPERTY": {
          "ANY_ADDITIONAL_PROPERTY": {
            "value": "text",
            "label": "text",
            "type": "number",
            "required": false,
            "options": [
              "text"
            ]
          }
        }
      },
      "sources": [
        {
          "external_id": "123",
          "name": "okta"
        },
        {
          "external_id": "456",
          "name": "hibob"
        }
      ],
      "last_login": "text",
      "deleted_at": "2026-01-01T00:00:00.000Z"
    }
  ]
}