Batch query employees

Looks up many employees by ID or work email in one call

Batch query employees

post

Query multiple employees by ID or work_email in a single request. Results are returned in the same order as queries.

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

Body

Batch query request.

Responses

200

Successful Response

application/json

Batch query response.

422

Validation Error

application/json

post/api/v1/employees/batch_query

POST /employees/api/v1/employees/batch_query HTTP/1.1
Host: api.harmony.io
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 111

{
  "queries": [
    {
      "work_email": "[e-mail]"
    },
    {
      "id": "emp123"
    }
  ],
  "fields": [
    "id",
    "work_email",
    "display_name"
  ]
}

{
  "results": [
    {
      "employee": {
        "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"
      },
      "error": "text"
    }
  ]
}