📘
Partner OAuth integrations only
The Background Checks API is for approved HiBob Marketplace partners with Developer Portal access and OAuth credentials. Service users are not supported for this integration.
Bob customers building integrations for their own company should use Service users and the general Hiring API, not this partner contract.

Before you begin

Read Integrate with Retirement Partners API to learn how to use this API.

These endpoints belong to the Retirement Partners API (US Payroll Hub). Use them to discover the US employers linked to the authenticated company and to fetch employer-scoped payroll data such as deduction plans, employee rosters, and pay codes.

For the read-only Employer API (legal employers and work locations in Bob), see Employers.

Pay cycles for an employer are documented under Pay cycles.

Retirement Partners API endpoints

Resource	Endpoint
Employers	List employers
Deduction plans	List employer deduction plans
Employee roster	List employer employees
Employer pay codes	List employer pay codes

The employer plan deductionId from list deduction plans is not sent when creating an employee deduction. See Deductions.

Rate limiting

Rate limits are restrictions that our API imposes on the number of times a user can access our endpoints within a specified period of time. To learn more about rate limiting best practices, see Rate limiting.

Method	Endpoint	Limit
GET	List employers	5 requests per minute
GET	List employer deduction plans	5 requests per minute
GET	List employer employees	5 requests per minute
GET	List employer pay codes	5 requests per minute

Required permissions and scopes

To use these endpoints, your OAuth app requires the following scope:

Name	Scope	Description
Payroll Hub > Partner integration > Fetch pay cycle metadata, paystub information, and payroll-related employee data	`payrollhub.payroll:read`	Discover employers and read employer-scoped payroll configuration.