📘
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.

Overview

Background checks in Bob Hiring let recruiters order a check for a candidate, select a partner package, and track status and results in the hiring workflow.

The Background Checks API is the partner-facing Public API for marketplace background check providers. Use it to:

Register your package catalog for each installing company
Receive check lifecycle events when a recruiter orders or cancels a check
Fetch check context (candidate, requester, job opening, package, and request time)
Report status and results back to Bob

Common use cases include:

Onboarding a company after Marketplace install and publishing your check packages
Starting a provider-side check when Bob sends backgroundCheck.triggered
Updating Bob as the check progresses or completes
Stopping work when Bob sends backgroundCheck.cancelled

Before you begin

Confirm you are an approved Marketplace partner with Developer Portal access.
See Testing notes for more details on how to create and configure your OAuth app before you can test it.

Key concepts

Background check

A background check is a check ordered for a candidate in Bob Hiring. It references the candidate, the recruiter who requested it, the related job opening, and the partner package the recruiter selected.

The check ID is exposed in events and APIs as backgroundCheckRequestId. Use this ID to:

Fetch background check details after a triggered event
Report status and results with PATCH
Correlate duplicate webhook deliveries, because webhook delivery is at-least-once

Outbound webhook payloads include IDs only. Full candidate and job context is available from the GET details endpoint after authentication.

Package

A package is a partner-defined check offering that recruiters can select when ordering a background check, for example, a standard criminal check.

After a company installs your app, register or replace your package catalog with POST /hiring/recruitment-integrations/background-checks/packages.

The call is idempotent per company, so you can safely refresh names and descriptions.

When a recruiter orders a check, the selected packageId is included on the check details response.

Candidate

The candidate is the person linked to the background check.

GET check details returns a fixed set of standard fields for every provider, for example, name, email, phone, and address.

Partners do not configure which candidate fields are required, and Bob does not manage provider-specific custom fields for this integration.

If you need additional input, such as SSN, date of birth, or consent, collect it in your own flow after receiving the check.

Requester

The requester is the employee, usually a recruiter, who ordered the background check in Bob.

GET background check details returns requester identity fields such as name and email.

Job opening

The job opening is the role the candidate applied to.

GET background check details returns job opening fields such as title so you can associate the check with the hiring context.

Background check progress

Partners report progress and outcomes with PATCH on the check.

At least one of status, result, report, or checks should be provided for a meaningful update.

Supported status values:

in_progress — check is underway
cleared — check cleared
cleared_on_review — cleared after review
canceled — check canceled
failed_on_review — failed after review
require_action — action required before the check can continue

Optional fields:

result — human-readable summary
report — PDF report reference with url and filename
checks — per-step breakdown with name and status

How it works

The integration follows a notify-then-pull, then push-back model:

Setup (once per company): After the user installs you app, register your packages.
Event notification: Bob sends a webhook when a recruiter orders or cancels a check.
Pull context: On backgroundCheck.triggered, call GET details with backgroundCheckRequestId.
Run the check in your provider system.
Push updates: PATCH status and results as the check progresses or completes.
On cancel: Stop processing. Do not send further PATCH updates.

Packages setup

sequenceDiagram
    participant Partner
    participant HiBob as Bob
    Partner->>HiBob: POST /background-checks/packages
    HiBob-->>Partner: 204 No Content
    Note over Partner,HiBob: Idempotent catalog replace per company

Check lifecycle

sequenceDiagram
    participant HiBob as Recruiter in Bob
    participant Partner
    participant Provider as Partner provider system

    HiBob->>HiBob: Order background check (select package)
    HiBob-->>Partner: Webhook backgroundCheck.triggered (IDs only)
    Partner->>HiBob: GET /background-checks/{backgroundCheckRequestId}
    HiBob-->>Partner: Candidate, requester, job opening, packageId
    Partner->>Provider: Submit check
    Provider-->>Partner: Progress / completion
    Partner->>HiBob: PATCH /background-checks/{backgroundCheckRequestId}
    Note over Partner,HiBob: status, result?, report?, checks?
    HiBob-->>Partner: 204 No Content
    HiBob-->>HiBob: Updated status in UI

Cancellation

sequenceDiagram
    participant HiBob as Recruiter in Bob
    participant Partner

    HiBob->>HiBob: Cancel background check
    HiBob-->>Partner: Webhook backgroundCheck.cancelled (same ID fields)
    Note over Partner: Stop processing. Do not PATCH further updates.

Required permissions

This API supports OAuth only. Service users are not supported.

Layer	What it controls	Background check partner
OAuth scope	What the partner app token can call	`hiring.integrations:write`

Background Checks API endpoints

Use case	Method and path	Comments
Register or replace packages	`POST /v1/hiring/background-checks/packages`	Idempotent full catalog replace per company/app. Omitted packages are soft-archived; an empty catalog archives all packages. Returns `204`.
Permanently delete packages	`DELETE /v1/hiring/background-checks/packages/delete`	Deletes a subset of packages by `packageIds`; unknown IDs are ignored. Returns `204`.
Get check details	`GET /v1/hiring/background-checks/{backgroundCheckRequestId}`	Call after `backgroundCheck.triggered`. Company-scoped; returns `404` if the check does not belong to the installing company.
Update status or result	`PATCH /v1/hiring/background-checks/{backgroundCheckRequestId}`	Report progress and final results. `status` is required; `result`, `report`, and `checks` are optional. Returns `204`.

Webhooks

Bob delivers outbound events to your registered HTTPS webhook URL. Requests are signed — verify authenticity using the Bob-Signature header. See How Bob calculates the signature and Getting started with partner webhooks.

Delivery is at-least-once. Handle duplicate deliveries idempotently using backgroundCheckRequestId.

Event	When fired	Partner action
`backgroundCheck.triggered`	Recruiter orders a background check for a candidate and selects a package	GET check details; start processing at the provider
`backgroundCheck.cancelled`	Recruiter cancels an in-flight or pending check	Stop processing; do not call PATCH for terminal status unless product specifies otherwise

Delivery is at-least-once. Handle duplicate deliveries idempotently using backgroundCheckRequestId.

Example backgroundCheck.triggered payload:

{
  "version": "v2",
  "type": "backgroundCheck.triggered",
  "triggeredBy": "emp-001",
  "triggeredAt": "2026-05-28T10:00:00Z",
  "data": {
    "backgroundCheckRequestId": "550e8400-e29b-41d4-a716-446655440000"
  }
}

backgroundCheck.cancelled uses the same data shape.

Testing notes

Before you test a background check integration, complete the basic app setup in the Developer Portal. See the Quick start guide for general app setup instructions.

📘
Add app listing details before testing
Marketplace app listing details are usually completed only after an app is approved. For background check integrations, you must add them earlier.
Bob uses the app tile when a recruiter chooses a background check provider. The tile is based on your app listing details, so Bob needs those details before it can install and display the app correctly in a test company.

Before testing, make sure your app includes:

App listing details — add the provider name and description that should appear in Bob.
Logo — upload the logo Bob should show on the provider tile.
Marketplace category — choose Background screening as the integration type.
OAuth configuration — request the hiring.integrations:write scope and configure the redirect URL used for testing.
Webhook listener URL — register the HTTPS endpoint that will receive backgroundCheck.triggered and backgroundCheck.cancelled events.

After you save these details, install the app in the test company, register your package catalog, and confirm that the provider appears as an available background check option in Bob Hiring.

Related resources

Quick start guide — create and submit a Marketplace app
OAuth 2.0 — authorization code flow, tokens, and uninstall
Getting started with partner webhooks — partner webhook delivery and retries
Explore Hiring API — hiring concepts for candidates, applications, and job openings
Become a partner — join the HiBob partner program