---
updatedAt: 2026-07-21T10:21: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.

# Explore Employer API

Understand the basic concepts of Employers and Work locations in Bob and how to search and sync them with the Public API

# **Overview**

In Bob, **Employers** represent the legal entities your company operates under, each with its own registered details, tax identifiers, and contact information. Every employer can have one or more **work locations**, such as on-site locations (offices, stores) or remote location.

The **Employer API** lets you read employer and work-location data from Bob. Use it to search and sync employer and work-location data into external systems for reporting, reconciliation, payroll-per-entity, and partner integrations.

With this API you can:

* **Search** employers
* **Search** work locations under a specific employer
* **Retrieve** employer and work-location field metadata
* **Resolve** employee-reference fields, such as contact person or created by, with the People search API

The main integration pattern is **read-and-sync**: Bob remains the source of truth for employers and work locations, and your external system keeps a mirrored copy.

# **Key concepts**

<accordion title="Employers">

An **employer** is a legal entity configured in Bob under **Settings > Employers**. It stores legal, registration, tax, contact, address, and status details.

**Public API behavior:** Employers are read-only in this API. Retrieve them with employer search. Employer fields use the `/employer/...` prefix, for example `/employer/id`, `/employer/legalName`, and `/employer/country`.

</accordion>

<accordion title="Work locations">

A **work location** is an office or remote location that belongs to a specific employer. Each work location has its own address, type, and status.

**Public API behavior:** Work locations are read-only in this API. Retrieve them with work-location search under the parent employer.

</accordion>

<accordion title="Employee assignments">

This API does not manage or return employee assignments. Employee assignment to an employer or work location is part of the employee profile employment domain, not the employer domain.

To read employees that belong to a specific employer or work location, use the People search API and filter by the employee assignment fields:

* `/employee/employerId`
* `/employee/workLocationId`

</accordion>

<accordion title="Country-specific employer fields">

Some employer fields depend on `/employer/country`. US, UK, and rest-of-world employers can return different tax and registration fields. Fields that do not apply to the employer’s country are not returned.

| Field ID                               | US | UK | Rest of world |
| -------------------------------------- | -- | -- | ------------- |
| `/employer/doingBusinessAs`            | ✓  |    |               |
| `/employer/fein`                       | ✓  |    |               |
| `/employer/naics`                      | ✓  |    |               |
| `/employer/taxPayerType`               | ✓  |    |               |
| `/employer/tradingAs`                  |    | ✓  |               |
| `/employer/companiesHouseRegistration` |    | ✓  |               |
| `/employer/payeReference`              |    | ✓  |               |
| `/employer/accountsOfficeReference`    |    | ✓  |               |
| `/employer/organizationType`           |    | ✓  | ✓             |
| `/employer/taxIdentifier`              |    |    | ✓             |

`organizationType` applies to all non-US employers. `taxIdentifier` applies to non-US, non-UK employers only.

</accordion>

# **Required permissions**

Before using the Employer API, make sure your integration has the required access.

Choose one of the following authentication methods and assign the relevant permissions or scopes:

* **Service user (Basic Auth):** Recommended for customer-built or internal integrations.
  * View / search employers and work locations: Features > Settings > **Employers and work locations > View details for employers and work locations.**
* **OAuth (Bearer token):** Used for marketplace or partner apps only.
  * Read: `employers:read`

If the calling integration does not have the required permissions or scope, the API returns an authorization error, for example `403 Forbidden`.

# **Employer API endpoints**

| **Use case**               | **Public API endpoints**                                                                                                                          | **Comments**                                                                  |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| Search employers           | <Anchor target="_blank" href="https://app.notion.com/reference/post_employers-search">Search employers</Anchor>                                   | Read-only. Filter by employer fields such as country, status, or employer ID. |
| Search work locations      | <Anchor target="_blank" href="https://app.notion.com/reference/post_employers-employerid-work-locations-search">Search work locations</Anchor>    | Read-only. Search work locations under a specific employer.                   |
| Get employer metadata      | <Anchor target="_blank" href="https://app.notion.com/reference/post_employers-metadata-search">Get employer metadata</Anchor>                     | Returns available employer fields metadata.                                   |
| Get work-location metadata | <Anchor target="_blank" href="https://app.notion.com/reference/post_employers-work-locations-metadata-search">Get work location metadata</Anchor> | Returns available work-location fields metadata.                              |

To learn more about request and response schemas, rate limits, and examples, see the Employer API reference.

# **Related resources**

* <Anchor target="_blank" href="https://apidocs.hibob.com/reference/employers">Employer API reference</Anchor>
* <Anchor target="_blank" href="https://apidocs.hibob.com/docs/explore-employee-data">Explore Employee data API</Anchor>

<br />