Retirement payroll apps sync US payroll data with Bob. They read payroll results from Bob US Payroll and send calculated deductions back, for example 401(k) contributions. The model is notify, pull, then push back.

1. When a US pay cycle is completed and paid, Bob sends the payroll.paycycle.paid webhook with a payCycleId.
2. You retrieve the pay cycle details and the paychecks for that cycle. You can also retrieve employee census data and current deductions when needed.
3. You calculate the required deductions in your system.
4. You create or update employee deductions in Bob. Changes apply from the next pay cycle.

When you connect a new customer, you first confirm the connection status, then discover the employers, employer pay codes, deduction plans, employee roster, and historical pay cycles for an initial sync.

The customer company must have Payroll Hub enabled and your app installed.

Before you build: the full guide lists the required scopes and rate limits for this API. Review it first. See Integrate with Retirement Partners API.

Applicant tracking systems, and also EOR or onboarding providers, use the Applicant API to push a hired candidate into Bob's existing ATS Pending Hires flow, where HR reviews candidates that an external system submitted before they become employees. This is a partner-push model: you own the setup experience, and there is no Bob-side configuration or field-mapping screen for these apps.

One-time setup per customer

1. The customer installs your app and approves the OAuth scopes.
2. Bob redirects to your first-time setup URL with the company_id.
3. You retrieve Bob's employee field metadata and document folders.
4. In your own UI, the customer maps their ATS fields to Bob field IDs and picks a document folder. You store the mapping.

Per hire

1. A candidate is marked hired in your system.
2. You send one applicant to POST /v1/external-hires/applicants. root.firstName and root.surname are required.
3. Bob returns 201 Created with an empty body, and the record appears in ATS Pending Hires. Bob alerts the notification recipients that the customer configured.
4. HR approves it and completes the existing New Hire flow, the Bob flow that creates the employee record.

Field mapping

Tell customers that any field they map must also be included in their Bob New Hire flow, or it will not be populated. Workforce Planning scopes are optional if you also sync open positions into your ATS.

Notifications in Bob

Customers set up notifications for new pending hires in Bob, in your app's tile in the Bob Marketplace, not in your product. Bob alerts the configured recipients when a record arrives. Add this step to your customer-facing user guide, so customers know to set up notifications after they install your app. See Set up ATS new hire notifications ↗.

If you have a Hire API integration today

Existing Hire API connections keep working, and there is no automated migration. New Marketplace partner integrations must use the Applicant API. Customers re-complete mapping in your product when they move to your Marketplace app. The guide describes the plan to block creation of new token-based Hire API connections six months after the Applicant API launch.

Before you build: the full guide lists the required scopes and rate limits for this API. Review it first. See Submit new hires to Bob with the Applicant API.

Recruiters in Bob Hiring order a check for a candidate, choose one of your packages, and track status and results in the hiring workflow. The model is notify, pull, then push back.

1. After a customer installs your app, you register your package catalog.
2. When a recruiter orders a check, Bob sends backgroundCheck.triggered. The payload contains IDs only.
3. You retrieve the check details: candidate, requester, job opening, and selected package.
4. You run the check in your system and patch the status and results back to Bob as it progresses.
5. If the recruiter cancels, Bob sends backgroundCheck.cancelled. Stop processing and do not send further updates.

Bob signs webhooks with the Bob-Signature header and delivers them at least once, so handle duplicates using backgroundCheckRequestId.

Listing details

Complete your listing details before you test. Bob shows your app as a tile when a recruiter chooses a provider, so it needs your listing details before it can display the app in a test company.

Add the provider name and description, your logo, and the Marketplace category Background screening, together with your OAuth configuration and webhook listener URL.

Before you build: the full guide lists the required scopes and rate limits for this API. Review it first. See Integrate with Bob Hiring Background Checks API.

Assessment providers, for example coding challenges or personality questionnaires, use the same notify, pull, then push back model as background checks.

1. After a customer installs your app, you register your package catalog.
2. When a recruiter orders an assessment, Bob sends assessment.triggered with the assessmentRequestId and the selected packageId.
3. You retrieve the assessment details and start the assessment at your provider.
4. You patch the status and results back to Bob. Optional result fields include a score, a verdict, a results URL, and a per-section summary.
5. If the recruiter cancels, Bob sends assessment.cancelled. Stop processing and do not send further updates.

Listing details

Complete your listing details before you test. Bob shows your app as a tile when a recruiter chooses a provider, so it needs your listing details before it can display the app in a test company.

Add the provider name and description, your logo, and the Marketplace category Candidate assessments, together with your OAuth configuration and webhook listener URL.

Before you build: the full guide lists the required scopes and rate limits for this API. Review it first. See Integrate with Bob Hiring Assessments API.