---
updatedAt: 2026-07-21T10:22:41.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 employers
Search and page through the company's employers using the flattened field contract.
# 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": "Employers",
"description": "Operations for managing Employers"
}
],
"security": [
{
"basic": []
},
{
"bearer": []
}
],
"paths": {
"/employers/search": {
"post": {
"operationId": "post_employers-search",
"tags": [
"Employers"
],
"summary": "Search employers",
"description": "Search and page through the company's employers using the flattened field contract.",
"requestBody": {
"required": true,
"description": "Request body for employer search. `filters` is required — send an empty array\n(`[]`) to return every employer the caller can view. `fields` is optional;\nomit it to return all available fields. `limit` defaults to 50.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchEmployersInput"
},
"examples": {
"default": {
"summary": "Return all employers with core fields",
"description": "Minimal first-page search. An empty `filters` array returns every employer the caller can view.",
"value": {
"fields": [
"/employer/id",
"/employer/legalName",
"/employer/country",
"/employer/employerStatus"
],
"filters": [],
"limit": 50
}
},
"filteredByCountry": {
"summary": "Filter by country, request a subset of fields",
"value": {
"fields": [
"/employer/id",
"/employer/legalName",
"/employer/country",
"/employer/employerStatus"
],
"filters": [
{
"fieldId": "/employer/country",
"operator": "equals",
"values": [
"United States"
]
}
],
"limit": 100
}
},
"byId": {
"summary": "Read a single employer by filtering on its ID",
"value": {
"fields": [
"/employer/id",
"/employer/legalName",
"/employer/country"
],
"filters": [
{
"fieldId": "/employer/id",
"operator": "equals",
"values": [
"879"
]
}
],
"limit": 1
}
},
"nextPage": {
"summary": "Continue paging with a cursor",
"value": {
"fields": [
"/employer/id",
"/employer/legalName"
],
"filters": [],
"limit": 100,
"cursor": "eyJjIjoiZXhhbXBsZS1jdXJzb3IifQ=="
}
}
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SearchEmployersOutput"
},
"examples": {
"firstPage": {
"summary": "First page (more results available)",
"value": {
"items": [
{
"/employer/id": "879",
"/employer/legalName": "Tech Solutions Inc",
"/employer/country": "United States",
"/employer/employerStatus": "active"
},
{
"/employer/id": "880",
"/employer/legalName": "Acme Ltd",
"/employer/country": "United Kingdom",
"/employer/employerStatus": "active"
}
],
"response_metadata": {
"next_cursor": "eyJjIjoiZXhhbXBsZS1jdXJzb3IifQ=="
}
}
},
"lastPage": {
"summary": "Last page",
"value": {
"items": [
{
"/employer/id": "881",
"/employer/legalName": "Globex GmbH",
"/employer/country": "Germany",
"/employer/employerStatus": "active"
}
],
"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"
}
}
},
"Employer": {
"description": "A single employer record. Each result item is keyed by path-style field\nIDs. Smithy member names cannot contain `/`, so each member uses a plain\nidentifier and `@jsonName` exposes the wire-level field-ID key.\n\nThe employer is country-conditional: `/employer/country` determines which\ntax and registration fields apply. Fields not applicable to the employer's\ncountry are absent from the item.",
"type": "object",
"properties": {
"/employer/id": {
"type": [
"string",
"null"
],
"description": "Unique identifier of the employer. Sent as a string to avoid JSON\nnumber-precision loss in clients."
},
"/employer/legalName": {
"type": [
"string",
"null"
],
"description": "Registered legal name of the employer."
},
"/employer/contactName": {
"type": [
"string",
"null"
],
"description": "Primary contact person for the employer. Returns the referenced\nemployee's ID (a string); resolve it to employee details via the\nPeople search API."
},
"/employer/employerPhoneNumber": {
"type": [
"string",
"null"
],
"description": "Contact phone number for the employer."
},
"/employer/employerEmailAddress": {
"type": [
"string",
"null"
],
"description": "Contact email address for the employer."
},
"/employer/doingBusinessAs": {
"type": [
"string",
"null"
],
"description": "Doing-business-as name — a name the employer trades under other than its\nlegal name. Present for US employers only."
},
"/employer/tradingAs": {
"type": [
"string",
"null"
],
"description": "Trading-as name — a name the employer trades under other than its legal\nname. Present for UK employers only."
},
"/employer/companiesHouseRegistration": {
"type": [
"string",
"null"
],
"description": "UK Companies House registration number. Present for UK employers only.\nFormat: 8 digits, or a company-number prefix (for example `SC`, `OC`)\nfollowed by 5–6 digits and an optional suffix (for example `12345678`,\n`SC123456`, `OC555555`)."
},
"/employer/supportsRemoteWorkers": {
"type": [
"boolean",
"null"
],
"description": "Whether the employer supports remote workers."
},
"/employer/addressLine1": {
"type": [
"string",
"null"
],
"description": "First line of the employer's registered address."
},
"/employer/addressLine2": {
"type": [
"string",
"null"
],
"description": "Second line of the employer's registered address."
},
"/employer/postalCode": {
"type": [
"string",
"null"
],
"description": "Postal / ZIP code of the employer's registered address."
},
"/employer/city": {
"type": [
"string",
"null"
],
"description": "City of the employer's registered address."
},
"/employer/stateProvinceRegion": {
"type": [
"string",
"null"
],
"description": "State, province, or region of the employer's registered address."
},
"/employer/country": {
"type": [
"string",
"null"
],
"description": "Country of the employer's registered address, as a country display name\nfrom the `countries` list (for example `United States`)."
},
"/employer/fein": {
"type": [
"string",
"null"
],
"description": "US Federal Employer Identification Number (FEIN). Present for US\nemployers only. Format: 9 digits (`123456789`) or `XX-XXXXXXX`\n(`12-3456789`)."
},
"/employer/payeReference": {
"type": [
"string",
"null"
],
"description": "UK PAYE reference. Present for UK employers only. Format: 3 digits, `/`,\nthen 1–10 alphanumerics (for example `123/A45678`)."
},
"/employer/taxIdentifier": {
"type": [
"string",
"null"
],
"description": "Local tax identifier. Present for non-US, non-UK employers only."
},
"/employer/naics": {
"type": [
"string",
"null"
],
"description": "US North American Industry Classification System (NAICS) code. Present\nfor US employers only."
},
"/employer/accountsOfficeReference": {
"type": [
"string",
"null"
],
"description": "UK Accounts Office reference. Present for UK employers only. Format: 13\ncharacters — 3 digits, `P`, a letter, 7 digits, then a digit or `X`\n(for example `123PA12345678`)."
},
"/employer/organizationType": {
"type": [
"string",
"null"
],
"description": "Organization type, as a value from the `organizationType` list. Present\nfor all non-US employers (UK and rest-of-world)."
},
"/employer/taxPayerType": {
"type": [
"string",
"null"
],
"description": "Taxpayer type, as a value from the `taxPayerType` list. Present for US\nemployers only."
},
"/employer/employerStatus": {
"type": [
"string",
"null"
],
"description": "Lifecycle status of the employer. One of `active` or `inactive`."
},
"/employer/payrollValidationStatus": {
"type": [
"string",
"null"
],
"description": "Payroll validation status of the employer."
},
"/employer/validationStatusReason": {
"type": [
"string",
"null"
],
"description": "Reason associated with the current payroll validation status, when\npresent."
}
}
},
"EmployerFilter": {
"description": "A single employer search filter.",
"type": "object",
"properties": {
"fieldId": {
"type": "string",
"description": "Field ID to filter by. Must be one of the filterable employer field IDs;\nany 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"
]
},
"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."
}
}
},
"SearchEmployersInput": {
"description": "Request body for employer search. `filters` is required — send an empty array\n(`[]`) to return every employer the caller can view. `fields` is optional;\nomit 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 employer metadata search endpoint; out-of-the-box\nfield IDs are also listed as keys on the `Employer` response schema."
},
"filters": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EmployerFilter"
},
"description": "Filters to apply. An empty list returns every employer the caller has\npermission to view."
},
"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": [
"/employer/id",
"/employer/legalName",
"/employer/country",
"/employer/employerStatus"
],
"filters": [],
"limit": 50
}
},
"SearchEmployersOutput": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Employer"
},
"description": "Page of matching employers. Each item is a flat map keyed by field ID;\nonly the requested `fields` are populated."
},
"response_metadata": {
"$ref": "#/components/schemas/ResponseMetadata",
"description": "Pagination metadata for this page."
}
},
"required": [
"items",
"response_metadata"
]
}
}
}
}
```