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
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.
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.
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
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.
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
- 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 | Search employers | Read-only. Filter by employer fields such as country, status, or employer ID. |
| Search work locations | Search work locations | Read-only. Search work locations under a specific employer. |
| Get employer metadata | Get employer metadata | Returns available employer fields metadata. |
| Get work-location metadata | Get work location metadata | 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
Updated about 10 hours ago