---
updatedAt: 2026-07-21T10:22:27.000Z
---
Fetch the complete documentation index at: https://apidocs.hibob.com/llms.txt. Use this file to discover all available pages before exploring further.
# Search work locations
Search and page through a specific employer's work locations.
# OpenAPI definition
```json
{
"openapi": "3.1.1",
"info": {
"title": "Employer API",
"contact": {
"name": "Hi Bob, Inc."
},
"description": "Public read API for the employer domain — legal employers and their work\nlocations. All endpoints are read-only and search-based; there are no\nsingle-object endpoints, which keeps integrations bulk-first.\n\nAll endpoints support both service-user (basic auth) and Marketplace app\n(OAuth 2.0) callers. App-user callers must hold the `employers:read` scope.\nEvery endpoint is company-scoped and requires the IAM permission\n`Settings / Employers / View`.",
"license": {
"name": "Proprietary",
"url": "https://apidocs.hibob.com/docs/api-terms-of-use"
},
"version": "1.0.0"
},
"servers": [
{
"url": "https://api.hibob.com/v1",
"description": "Production"
},
{
"url": "https://api.sandbox.hibob.com/v1",
"description": "Sandbox"
}
],
"x-readme": {
"metrics-enabled": false
},
"tags": [
{
"name": "Work locations",
"description": "Operations for managing Work locations"
}
],
"security": [
{
"basic": []
},
{
"bearer": []
}
],
"paths": {
"/employers/{employerId}/work-locations/search": {
"post": {
"operationId": "post_employers-employerid-work-locations-search",
"tags": [
"Work locations"
],
"summary": "Search work locations",
"description": "Search and page through a specific employer's work locations.",
"parameters": [
{
"name": "employerId",
"in": "path",
"required": true,
"description": "Identifier of the parent employer whose work locations to search.",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"description": "Request body for work-location search. `filters` is required — send an empty\narray (`[]`) to return every work location of the employer. `fields` is\noptional; omit it to return all available fields. `limit` defaults to 50.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchWorkLocationsInput"
},
"examples": {
"default": {
"summary": "Return all work locations with core fields",
"description": "Minimal first-page search for an employer. An empty `filters` array returns every work location the caller can view.",
"value": {
"fields": [
"/workLocation/id",
"/workLocation/name",
"/workLocation/type",
"/workLocation/status"
],
"filters": [],
"limit": 50
}
},
"activeOnly": {
"summary": "Active work locations only, requesting a subset of fields",
"value": {
"fields": [
"/workLocation/id",
"/workLocation/name",
"/workLocation/type",
"/workLocation/status"
],
"filters": [
{
"fieldId": "/workLocation/status",
"operator": "equals",
"values": [
"Active"
]
}
],
"limit": 100
}
},
"byId": {
"summary": "Read a single work location by filtering on its ID",
"value": {
"fields": [
"/workLocation/id",
"/workLocation/name",
"/workLocation/type",
"/workLocation/status"
],
"filters": [
{
"fieldId": "/workLocation/id",
"operator": "equals",
"values": [
"200"
]
}
],
"limit": 1
}
},
"nextPage": {
"summary": "Continue paging with a cursor",
"value": {
"fields": [
"/workLocation/id",
"/workLocation/name"
],
"filters": [],
"limit": 100,
"cursor": "eyJjIjoiZXhhbXBsZS1jdXJzb3IifQ=="
}
}
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchWorkLocationsOutput"
},
"examples": {
"firstPage": {
"summary": "First page (more results available)",
"value": {
"items": [
{
"/workLocation/id": "200",
"/workLocation/name": "London HQ",
"/workLocation/type": "Public",
"/workLocation/status": "Active"
},
{
"/workLocation/id": "201",
"/workLocation/name": "Remote — UK",
"/workLocation/type": "Remote",
"/workLocation/status": "Active"
}
],
"response_metadata": {
"next_cursor": "eyJjIjoiZXhhbXBsZS1jdXJzb3IifQ=="
}
}
},
"lastPage": {
"summary": "Last page",
"value": {
"items": [
{
"/workLocation/id": "202",
"/workLocation/name": "Berlin office",
"/workLocation/type": "Public",
"/workLocation/status": "Inactive"
}
],
"response_metadata": {
"next_cursor": null
}
}
}
}
}
}
},
"400": {
"description": "Bad request — the request was malformed, missing required parameters, or referenced an unknown field ID or unsupported filter operator",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
},
"401": {
"description": "Unauthorized — authentication credentials are missing or invalid",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
},
"403": {
"description": "Forbidden — the caller lacks the required permission, the `employers:read` scope, or its source IP is not on the company IP trust list",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
},
"429": {
"description": "Too many requests — rate limit exceeded, retry after the indicated delay",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
},
"500": {
"description": "Internal server error — an unexpected error occurred on the server",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
}
},
"x-internal": false
}
}
},
"components": {
"securitySchemes": {
"basic": {
"type": "http",
"scheme": "basic"
},
"bearer": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "OAuth 2.0",
"description": "OAuth 2.0 access token. Learn more about OAuth 2.0 in HiBob"
}
},
"schemas": {
"ApiErrorResponse": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Stable machine-readable error code"
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"details": {
"type": "object",
"additionalProperties": true,
"description": "Structured error context keyed by field or domain identifier"
},
"request_id": {
"type": "string",
"description": "Request identifier for support and tracing"
}
}
},
"ResponseMetadata": {
"description": "Pagination metadata returned on every search response.",
"type": "object",
"properties": {
"next_cursor": {
"type": [
"string",
"null"
],
"description": "Opaque cursor that identifies the start of the next page of results.\nPass this value back as `cursor` on the next request to continue paging.\n`null` on the last page, when there are no more results."
}
}
},
"SearchWorkLocationsInput": {
"description": "Request body for work-location search. `filters` is required — send an empty\narray (`[]`) to return every work location of the employer. `fields` is\noptional; omit it to return all available fields. `limit` defaults to 50.",
"type": "object",
"properties": {
"fields": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "Field IDs to include in each result item. When omitted, all available\nfields are returned. Discover the authoritative field catalog (including\ncustom fields) via the work-location metadata search endpoint;\nout-of-the-box field IDs are also listed as keys on the `WorkLocation`\nresponse schema."
},
"filters": {
"type": "array",
"items": {
"$ref": "#/components/schemas/WorkLocationFilter"
},
"description": "Filters to apply within the employer's work locations. An empty list\nreturns every work location of the employer the caller has permission to\nview."
},
"limit": {
"type": [
"integer",
"null"
],
"minimum": 1,
"maximum": 200,
"default": 50,
"description": "Maximum number of items per page (allowed range 1–200). Defaults to 50."
},
"cursor": {
"type": [
"string",
"null"
],
"minLength": 1,
"maxLength": 8192,
"description": "Opaque cursor from a previous response's `response_metadata.next_cursor`.\nOmit on the first request."
}
},
"required": [
"filters"
],
"default": {
"fields": [
"/workLocation/id",
"/workLocation/name",
"/workLocation/type",
"/workLocation/status"
],
"filters": [],
"limit": 50
}
},
"SearchWorkLocationsOutput": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/WorkLocation"
},
"description": "Page of matching work locations. Each item is a flat map keyed by field\nID; only the requested `fields` are populated."
},
"response_metadata": {
"$ref": "#/components/schemas/ResponseMetadata",
"description": "Pagination metadata for this page."
}
},
"required": [
"items",
"response_metadata"
]
},
"WorkLocation": {
"description": "A single work-location record. Each result item is keyed by path-style\nfield IDs.",
"type": "object",
"properties": {
"/workLocation/id": {
"type": [
"string",
"null"
],
"description": "Unique identifier of the work location. Sent as a string to avoid JSON\nnumber-precision loss in clients."
},
"/workLocation/employerId": {
"type": [
"string",
"null"
],
"description": "Identifier of the employer this work location belongs to. Sent as a\nstring to avoid JSON number-precision loss in clients."
},
"/workLocation/name": {
"type": [
"string",
"null"
],
"description": "Display name of the work location."
},
"/workLocation/type": {
"type": [
"string",
"null"
],
"description": "Work-location type. One of `Public` (a shared office) or `Remote`."
},
"/workLocation/country": {
"type": [
"string",
"null"
],
"description": "Country of the work location, as a country display name from the\n`countries` list."
},
"/workLocation/addressLine1": {
"type": [
"string",
"null"
],
"description": "First line of the work location's address."
},
"/workLocation/addressLine2": {
"type": [
"string",
"null"
],
"description": "Second line of the work location's address."
},
"/workLocation/postalCode": {
"type": [
"string",
"null"
],
"description": "Postal / ZIP code of the work location's address."
},
"/workLocation/city": {
"type": [
"string",
"null"
],
"description": "City of the work location's address."
},
"/workLocation/stateProvinceRegion": {
"type": [
"string",
"null"
],
"description": "State, province, or region of the work location's address."
},
"/workLocation/status": {
"type": [
"string",
"null"
],
"description": "Lifecycle status of the work location. One of `Active` or `Inactive`."
},
"/workLocation/verificationStatus": {
"type": [
"string",
"null"
],
"description": "Verification status of the work location (for example `Verified`,\n`Pending`, `NotVerified`)."
},
"/workLocation/verificationReason": {
"type": [
"string",
"null"
],
"description": "Reason associated with the current verification status, when present."
},
"/workLocation/createdAt": {
"type": [
"string",
"null"
],
"description": "Timestamp the work location was created, as an ISO 8601 UTC date-time\nstring (for example `2024-01-31T09:30:00Z`). Always serialized as a\nquoted JSON string."
},
"/workLocation/createdBy": {
"type": [
"string",
"null"
],
"description": "Employee who created the work location. Returns the referenced\nemployee's ID (a string); resolve it to employee details via the\nPeople search API."
}
}
},
"WorkLocationFilter": {
"description": "A single work-location search filter. The parent employer is already scoped\nby the path `{employerId}`, so filter within it by other field IDs.",
"type": "object",
"properties": {
"fieldId": {
"type": "string",
"description": "Field ID to filter by. Must be one of the filterable work-location field\nIDs; any other value returns 400."
},
"operator": {
"type": "string",
"minLength": 1,
"maxLength": 64,
"description": "Comparison operator for this filter. Common operators are `equals` and\n`in`. Unsupported operators return 400."
},
"values": {
"type": "array",
"items": {
"type": "string"
},
"description": "Filter values, always sent as JSON strings."
}
},
"required": [
"fieldId",
"operator",
"values"
]
}
}
}
}
```