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.

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.

How the API works

All employer endpoints use POST search (not GET /{id}):

1. Call metadata first to learn which field IDs exist (including custom fields).
2. Call search with:
   • fields — the field IDs to return on each item (optional; defaults to a core set).
   • filters — required; send [] to return every employer the caller can view.
   • limit — page size (1–200; default 50).
   • cursor — pass response_metadata.next_cursor from the previous page to continue.

Read one employer: filter on /employer/id with operator equals and limit: 1.

Pagination: cursor-based. response_metadata.next_cursor is null on the last page. Search does not support server-side sorting — order results client-side if needed.

Field IDs: path-style keys such as /employer/legalName and /employer/country. Send ID values as JSON strings, even when they look numeric.

Country-conditional fields: /employer/country determines which tax and registration fields apply. Fields not relevant to the employer’s country are omitted from the response.

Required permissions

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

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

Rate limiting

Rate limits restrict how many requests you can make within a time window. To learn more, see Rate limiting.