List, create, and update employee deductions. Changes apply from the next pay cycle.
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.
Employee deductions are per-employee records (for example 401(k) contribution rates). They are not the same as employer-level deduction plans. Discover plans under Employers. Store the deductionId returned by create — that ID is what you pass on update.
Changes apply from the next pay cycle, not the cycle you just processed.
Retirement Partners API endpoints
| Resource | Endpoint |
|---|---|
| List employee deductions | List employee deductions |
| Create employee deduction | Create employee deduction |
| Update employee deduction | Update employee deduction |
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 employee deductions | 5 requests per minute |
| POST | Create employee deduction | 200 requests per minute |
| PUT | Update employee deduction | 200 requests per minute |
Create and update are per-employee calls. There is no bulk mutation endpoint in this MVP.
Required permissions and scopes
To use these endpoints, your OAuth app requires the following scope:
| Name | Scope | Description |
|---|---|---|
| Payroll Hub > Partner integration > Fetch and update employee-level 401(k) deductions | payrollhub.deductions:write | Read, create, and update employee deductions. |