---
title: "Search work locations"
method: POST
path: "/employers/{employerId}/work-locations/search"
tags: ["Work locations"]
---

# Search work locations

`POST /employers/{employerId}/work-locations/search`

Search and page through a specific employer's work locations.

## Path parameters

- `employerId` string, required

## Request body

- SearchWorkLocationsInput — Request body for work-location search. `filters` is required — send an empty array (`[]`) to return every work location of the employer. `fields` is optional; omit it to return all available fields. `limit` defaults to 50.
  - `fields` string[], nullable — Field IDs to include in each result item. When omitted, all available fields are returned. Discover the authoritative field catalog (including custom fields) via the work-location metadata search endpoint; out-of-the-box field IDs are also listed as keys on the `WorkLocation` response schema.
  - `filters` WorkLocationFilter[], required — Filters to apply within the employer's work locations. An empty list returns every work location of the employer the caller has permission to view.
    - `fieldId` string, required — Field ID to filter by. Must be one of the filterable work-location field IDs; any other value returns 400.
    - `operator` string, required — Comparison operator for this filter. Common operators are `equals` and `in`. Unsupported operators return 400.
    - `values` string[], required — Filter values, always sent as JSON strings.
  - `limit` integer, nullable — Maximum number of items per page (allowed range 1–200). Defaults to 50.
  - `cursor` string, nullable — Opaque cursor from a previous response's `response_metadata.next_cursor`. Omit on the first request.

## Response `200`

Success

- SearchWorkLocationsOutput
  - `items` WorkLocation[], required — Page of matching work locations. Each item is a flat map keyed by field ID; only the requested `fields` are populated.
    - `/workLocation/id` string, nullable — Unique identifier of the work location. Sent as a string to avoid JSON number-precision loss in clients.
    - `/workLocation/employerId` string, nullable — Identifier of the employer this work location belongs to. Sent as a string to avoid JSON number-precision loss in clients.
    - `/workLocation/name` string, nullable — Display name of the work location.
    - `/workLocation/type` string, nullable — Work-location type. One of `Public` (a shared office) or `Remote`.
    - `/workLocation/country` string, nullable — Country of the work location, as a country display name from the `countries` list.
    - `/workLocation/addressLine1` string, nullable — First line of the work location's address.
    - `/workLocation/addressLine2` string, nullable — Second line of the work location's address.
    - `/workLocation/postalCode` string, nullable — Postal / ZIP code of the work location's address.
    - `/workLocation/city` string, nullable — City of the work location's address.
    - `/workLocation/stateProvinceRegion` string, nullable — State, province, or region of the work location's address.
    - `/workLocation/status` string, nullable — Lifecycle status of the work location. One of `Active` or `Inactive`.
    - `/workLocation/verificationStatus` string, nullable — Verification status of the work location (for example `Verified`, `Pending`, `NotVerified`).
    - `/workLocation/verificationReason` string, nullable — Reason associated with the current verification status, when present.
    - `/workLocation/createdAt` string, nullable — Timestamp the work location was created, as an ISO 8601 UTC date-time string (for example `2024-01-31T09:30:00Z`). Always serialized as a quoted JSON string.
    - `/workLocation/createdBy` string, nullable — Employee who created the work location. Returns the referenced employee's ID (a string); resolve it to employee details via the <a href="https://apidocs.hibob.com/reference/post_people-search">People search API</a>.
  - `response_metadata` ResponseMetadata, required — Pagination metadata returned on every search response.
    - `next_cursor` string, nullable — Opaque cursor that identifies the start of the next page of results. Pass this value back as `cursor` on the next request to continue paging. `null` on the last page, when there are no more results.

## Other responses

- `400` — Bad request — the request was malformed, missing required parameters, or referenced an unknown field ID or unsupported filter operator
- `401` — Unauthorized — authentication credentials are missing or invalid
- `403` — Forbidden — the caller lacks the required permission, the `employers:read` scope, or its source IP is not on the company IP trust list
- `429` — Too many requests — rate limit exceeded, retry after the indicated delay
- `500` — Internal server error — an unexpected error occurred on the server

---

[API](https://skmtc.net/hibob/apis/employee-data-api.md) · [All operations](https://skmtc.net/hibob/apis/employee-data-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/hibob/employee-data-api/revisions/0781ebbdda91/schema)