---
updatedAt: 2026-07-22T11:56:54.000Z
---

Fetch the complete documentation index at: https://apidocs.hibob.com/llms.txt. Use this file to discover all available pages before exploring further.

# Employers

An **employer** is a legal entity owned by the company, for example, a subsidiary or payroll entity. In Bob, employers sit under **Settings > Employers and work locations**.

The Employers API is a **read-only**, **search-based** public API. Use it to discover the employer field catalog and search employer records using Bob’s flattened `fieldId: value` contract. There are **no single-object endpoints** — to read one employer, filter on `/employer/id`.

<Callout icon="📘" theme="info">
  ### **Note:** This API supports **reads only**. To create or update employers and work locations, use Bob’s UI or internal integrations — not the public API.
</Callout>

# Before you begin

* Read [Explore Employer API](/docs/explore-employer-api) to learn how employers and work locations work in Bob and how to integrate with the API.
* Work locations belong to an employer. After you have employer IDs, use [Work locations](/reference/work-locations) to search sites for each employer.

# What you can do

* **Metadata** — Discover readable employer field IDs, types, validations, and custom fields via [Get employer metadata](/reference/post_employers-metadata-search).
* **Search** — Page through the company’s employers with filters via [Search employers](/reference/post_employers-search).

# Required permissions

To use the Employers API, make sure the service user or OAuth app has the following access:

| Authentication            | Permission or scope                                                                                  |
| :------------------------ | :--------------------------------------------------------------------------------------------------- |
| Service user (Basic Auth) | `Features > Settings > Employers and work locations > View details for employers and work locations` |
| Marketplace app (OAuth)   | `employers:read`                                                                                     |

If the caller lacks the required permission or scope, or its source IP is not on the company IP trust list, the API returns `403 Forbidden`. To learn more, see [Permissions](/reference/permissions).

# Employers API endpoints

| Resource      | Endpoint                                                           |
| :------------ | :----------------------------------------------------------------- |
| Metadata      | [Get employer metadata](/reference/post_employers-metadata-search) |
| Employer data | [Search employers](/reference/post_employers-search)               |

# Rate limiting

Rate limits restrict how many requests you can make within a time window. To learn more, see [Rate limiting](/reference/rate-limiting).

| Method | Endpoint                                                           | Limit per minute |
| :----- | :----------------------------------------------------------------- | :--------------: |
| POST   | [Get employer metadata](/reference/post_employers-metadata-search) |        60        |
| POST   | [Search employers](/reference/post_employers-search)               |        60        |

<br />