Discover pay cycles for an employer, fetch a cycle by ID, and list its paychecks.
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.
Typical flow after a pay run:
- Receive the Pay cycle paid webhook (
data.payCycleId). - Fetch pay cycle metadata for the period and pay date.
- Page through paychecks for that cycle.
Use List pay cycles for employer during onboarding to backfill historical cycles.
Retirement Partners API endpoints
| Resource | Endpoint |
|---|---|
| Pay cycles for employer | List pay cycles for employer |
| Pay cycle by ID | Get pay cycle by ID |
| Paychecks | List paychecks for pay cycle |
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 pay cycles for employer | 5 requests per minute |
| GET | Get pay cycle by ID | 5 requests per minute |
| GET | List paychecks for pay cycle | 5 requests per minute |
List pay cycles and list paychecks use cursor pagination. Do not assume a single response contains every employee.
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 | Read pay-cycle metadata and paycheck data. |