---
title: "Search employers"
method: POST
path: "/employers/search"
tags: ["Employers"]
---

# Search employers

`POST /employers/search`

Search and page through the company's employers using the flattened field contract.

## Request body

- SearchEmployersInput — Request body for employer search. `filters` is required — send an empty array (`[]`) to return every employer the caller can view. `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 employer metadata search endpoint; out-of-the-box field IDs are also listed as keys on the `Employer` response schema.
  - `filters` EmployerFilter[], required — Filters to apply. An empty list returns every employer the caller has permission to view.
    - `fieldId` string, required — Field ID to filter by. Must be one of the filterable employer 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

- SearchEmployersOutput
  - `items` Employer[], required — Page of matching employers. Each item is a flat map keyed by field ID; only the requested `fields` are populated.
    - `/employer/id` string, nullable — Unique identifier of the employer. Sent as a string to avoid JSON number-precision loss in clients.
    - `/employer/legalName` string, nullable — Registered legal name of the employer.
    - `/employer/contactName` string, nullable — Primary contact person for the employer. 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>.
    - `/employer/employerPhoneNumber` string, nullable — Contact phone number for the employer.
    - `/employer/employerEmailAddress` string, nullable — Contact email address for the employer.
    - `/employer/doingBusinessAs` string, nullable — Doing-business-as name — a name the employer trades under other than its legal name. Present for US employers only.
    - `/employer/tradingAs` string, nullable — Trading-as name — a name the employer trades under other than its legal name. Present for UK employers only.
    - `/employer/companiesHouseRegistration` string, nullable — UK Companies House registration number. Present for UK employers only. Format: 8 digits, or a company-number prefix (for example `SC`, `OC`) followed by 5–6 digits and an optional suffix (for example `12345678`, `SC123456`, `OC555555`).
    - `/employer/supportsRemoteWorkers` boolean, nullable — Whether the employer supports remote workers.
    - `/employer/addressLine1` string, nullable — First line of the employer's registered address.
    - `/employer/addressLine2` string, nullable — Second line of the employer's registered address.
    - `/employer/postalCode` string, nullable — Postal / ZIP code of the employer's registered address.
    - `/employer/city` string, nullable — City of the employer's registered address.
    - `/employer/stateProvinceRegion` string, nullable — State, province, or region of the employer's registered address.
    - `/employer/country` string, nullable — Country of the employer's registered address, as a country display name from the `countries` list (for example `United States`).
    - `/employer/fein` string, nullable — US Federal Employer Identification Number (FEIN). Present for US employers only. Format: 9 digits (`123456789`) or `XX-XXXXXXX` (`12-3456789`).
    - `/employer/payeReference` string, nullable — UK PAYE reference. Present for UK employers only. Format: 3 digits, `/`, then 1–10 alphanumerics (for example `123/A45678`).
    - `/employer/taxIdentifier` string, nullable — Local tax identifier. Present for non-US, non-UK employers only.
    - `/employer/naics` string, nullable — US North American Industry Classification System (NAICS) code. Present for US employers only.
    - `/employer/accountsOfficeReference` string, nullable — UK Accounts Office reference. Present for UK employers only. Format: 13 characters — 3 digits, `P`, a letter, 7 digits, then a digit or `X` (for example `123PA12345678`).
    - `/employer/organizationType` string, nullable — Organization type, as a value from the `organizationType` list. Present for all non-US employers (UK and rest-of-world).
    - `/employer/taxPayerType` string, nullable — Taxpayer type, as a value from the `taxPayerType` list. Present for US employers only.
    - `/employer/employerStatus` string, nullable — Lifecycle status of the employer. One of `active` or `inactive`.
    - `/employer/payrollValidationStatus` string, nullable — Payroll validation status of the employer.
    - `/employer/validationStatusReason` string, nullable — Reason associated with the current payroll validation status, when present.
  - `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)