Overview

The Retirement Partners API is a partner-facing layer on top of Bob US Payroll. It lets external partners retrieve payroll data from Bob and submit calculated deductions back to payroll.

The current implementation targets retirement partner use-cases, for example, partners who need paycheck data to calculate retirement contributions and then create or update 401(k) deductions in Bob.

With this API you can:

1. Verify connectivity during onboarding and ongoing health checks
2. Discover employers, employer-specific pay codes, deduction plans, and employee rosters
3. Discover pay cycles, including historical cycles for initial sync
4. Fetch employee census data and paycheck details for a completed pay cycle
5. Read, create, and update employee deductions (changes apply from the next pay cycle)
6. Receive webhook notifications when a pay cycle is paid and ready to process

Common use cases include:

• Onboarding a new customer — map employer pay codes, discover available 401(k) deduction plans, and retrieve the employee roster
• Backfilling historical pay-cycle data after onboarding
• Identifying active, pending, and inactive employees when rolling out 401(k) enrollment
• Calculating 401(k) contributions after each pay run
• Creating missing 401(k) deductions or updating contribution rates
• Verifying that a prior deduction update was applied correctly

How it works

The API uses a notify-then-pull, then push-back model:

1. Event notification via webhook: Bob sends a webhook when a US pay cycle is completed and paid (payroll.paycycle.paid).
2. Controlled data retrieval: Your system calls the API to fetch pay-cycle metadata, employee paychecks, census data, and current deductions.
3. Process on your terms: Calculate required deduction changes in your system.
4. Submit results: Create or update deductions in Bob US Payroll. Deduction changes take effect from the next pay cycle.

sequenceDiagram
    participant Bob as Bob US Payroll
    participant Partner as Partner
    Bob-->>Partner: Webhook payroll.paycycle.paid (payCycleId)
    Partner->>Bob: GET pay cycle metadata
    Partner->>Bob: GET paychecks for pay cycle
    Partner->>Bob: GET employee census / deductions (as needed)
    Note over Partner: Calculate 401(k) deductions
    Partner->>Bob: POST or PUT employee deductions

Core workflows

Partner onboarding

Use this flow when connecting a new customer:

1. Authenticate via OAuth and obtain an access token.
2. Call Get connection status to confirm the integration is active.
3. Call List employers to discover the employerId(s) for the company.
4. For each employer, call List employer pay codes to retrieve earnings pay codes configured for that employer and map them in your UI.
5. Call List employer deduction plans to discover employer-level deduction plans (for example, 401(k) plans) — their names, deductionType codes, and active status. Use this to understand which plans exist before enrolling employees; you do not pass the plan's deductionId when creating employee deductions.
6. Call List employer employees to retrieve the employee roster, including assignment dates and onboarding status (active, pending, or inactive). Page through results with cursor and limit.
7. Call List pay cycles for employer to discover historical pay cycles for an initial data sync.
8. For each relevant cycle, fetch paychecks and employee census data as needed.

Note: List pay codes returns a company-wide curated list of standard US payroll pay codes. Use List employer pay codes when you need the earnings pay codes configured for a specific employer.

Ongoing pay-cycle processing

This is the primary recurring flow after onboarding:

1. Bob completes a pay cycle in US Payroll.
2. You receive the Pay cycle paid webhook with data.payCycleId.
3. Fetch pay cycle metadata for the cycle window (periodStart, periodEnd, payDate).
4. Fetch paychecks for the pay cycle — use cursor and limit to page through all employees.
5. Optionally fetch employee census data or current deductions when you need fresh profile or deduction state.
6. Calculate required 401(k) changes in your system.
7. Create or update deductions in Bob. Changes apply from the next pay cycle.

Employee roster and profile access

Use two complementary endpoints depending on what you need:

• Employee roster (onboarding): Call List employer employees to discover all employees assigned to an employer, their assignment dates, and onboarding status. This is the starting point when enrolling a new customer or identifying which employees still need 401(k) setup (pending status).
• Employee profile details: When you need demographic or employment data for specific employees — for example after identifying them from the roster or during a pay-cycle run — call Get employee census data with up to 25 employeeIds per request.

API resources

Reference IDs are consistent across endpoints: employerId scopes employer-level calls, payCycleId identifies a pay cycle, and employeeId identifies an employee.

Two different deductionId values: List employer deduction plans returns an employer plan deductionId. Create employee deduction does not accept a plan ID — the server assigns a new employee deduction deductionId in the response. Store that returned ID for updates.

Endpoints and webhooks

Required permissions and scopes

To use the Partners of Payroll API, your OAuth app requires:

The customer company must have Payroll Hub enabled and your app installed. See OAuth scopes mapping to endpoints for scope details.

Rate limits and pagination

• Most read endpoints: 5 requests per minute per company/partner.
• Create and update deduction endpoints: 200 requests per minute (no bulk mutation support in MVP).
• List endpoints use cursor-based pagination — pass cursor from responseMetadata.nextCursor on the next request. Page sizes vary by endpoint (see each reference page).

Best practices

When implementing a Partners of Payroll integration:

• Persist webhooks before handling them and process asynchronously
• Verify webhook signatures before acting on payload data
• Page through paycheck, pay-cycle, and employer employee results — do not assume a single response contains all employees
• Store employee deduction IDs from create responses — Create employee deduction returns a new deductionId per employee; use it as the path parameter on update. Do not confuse this with the employer plan deductionId from List employer deduction plans, which is not sent on create.
• Treat deduction create/update as per-employee calls in the MVP (no bulk mutation endpoint)
• Remember deduction changes apply from the next pay cycle, not the cycle you just processed
• Cache OAuth tokens according to OAuth best practices
• Respect rate limits and retry with backoff on 429 responses
• For general webhook guidance, see HiBob's webhooks guide for partners