--- title: "Search employers" method: POST path: "/employers/search" tags: ["Employers"] --- # Search employers `POST /employers/search` ## Request - Base URL: `https://api.hibob.com/v1` - URL: `https://api.hibob.com/v1/employers/search` - Auth: one of: - HTTP basic - HTTP bearer Searches employers in the caller's company. Returns a page of employers matching the supplied filters. Use the employer metadata endpoint (`/v1/employers/metadata/search`) to discover available field IDs and supported filter operators. There is no single-employer endpoint — read one employer by filtering on `/employer/id`. **Before using this endpoint** - Discover readable field IDs (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 for this search endpoint. - There is no single-employer endpoint — filter on `/employer/id` with operator `equals` to read one employer. - Filterable field IDs: `/employer/id`, `/employer/legalName`, `/employer/country`, `/employer/employerStatus`, `/employer/supportsRemoteWorkers`. Any other `fieldId` in `filters` returns **400 Bad Request**. **Pagination** — cursor-based. The first page is requested without `cursor`; subsequent pages pass `next_cursor` from the previous response. `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. The default example returns all employers with a core field set. - IDs must be sent as JSON strings even when they look numeric, so that large values are not truncated by JSON number precision in clients. **OAuth scope (app-user):** `employers:read`. **IAM permission:** `Settings / Employers / View` (company-scoped). ## 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 People search API. - `/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.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)