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.
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.
Before you begin
- Read 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 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.
- Search — Page through the company’s employers with filters via Search employers.
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.
Employers API endpoints
| Resource | Endpoint |
|---|---|
| Metadata | Get employer metadata |
| Employer data | Search employers |
Rate limiting
Rate limits restrict how many requests you can make within a time window. To learn more, see Rate limiting.
| Method | Endpoint | Limit per minute |
|---|---|---|
| POST | Get employer metadata | 60 |
| POST | Search employers | 60 |