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

# Search work locations

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

## Request

- Base URL: `https://api.hibob.com/v1`
- URL: `https://api.hibob.com/v1/employers/{employerId}/work-locations/search`
- Auth: one of:
  - HTTP basic
  - HTTP bearer

Searches the work locations of a single employer, identified by the path
parameter `{employerId}`. Returns a page of work locations matching the
supplied filters. Use the work-location metadata endpoint
(`/v1/employers/work-locations/metadata/search`) to discover
available field IDs and supported filter operators. There is no
single-work-location endpoint — read one by filtering on `/workLocation/id`.
(Work-location metadata is not employer-scoped; its endpoint is
`/v1/employers/work-locations/metadata/search`.)

**Before using this endpoint**

- Discover readable field IDs (including custom fields) via the
  <a href="https://apidocs.hibob.com/reference/post_employers-work-locations-metadata-search" target="_blank">work-location metadata search endpoint</a>.
  Out-of-the-box field IDs are also listed as keys on the `WorkLocation`
  response schema for this search endpoint.
- Provide a numeric `employerId` in the path — use the employer search
  endpoint to look up employer IDs.
- There is no single-work-location endpoint — filter on `/workLocation/id`
  with operator `equals` to read one work location.
- Filterable field IDs: `/workLocation/id`, `/workLocation/name`,
  `/workLocation/type`, `/workLocation/status`, `/workLocation/country`. Any
  other `fieldId` in `filters` returns **400 Bad Request**.

**Pagination** — cursor-based. `next_cursor` is `null` on the last page.
Search does not support sorting — order results client-side.

**Testing notes**

- Use the testing widget's **Try It!** option to test this endpoint.
- Open **Examples** and select **Request Example** to populate the request
  body. Replace the path `employerId` with a real employer ID from your
  company.
- IDs must be sent as JSON strings even when they look numeric.

**OAuth scope (app-user):** `employers:read`.
**IAM permission:** `Settings / Employers / View` (company-scoped).

## 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.dev/hibob/apis/employer-api.md) - [All operations](https://skmtc.dev/hibob/apis/employer-api/llms.txt) - [OpenAPI document](https://skmtc.dev/hibob/apis/employer-api/revisions/8d775537a41f?raw)