---
title: "Update background check status"
method: PATCH
path: "/hiring/background-checks/{backgroundCheckRequestId}"
tags: ["Background checks"]
---

# Update background check status

`PATCH /hiring/background-checks/{backgroundCheckRequestId}`

## Request

- Base URL: `https://api.hibob.com/v1`
- URL: `https://api.hibob.com/v1/hiring/background-checks/{backgroundCheckRequestId}`
- Auth: HTTP bearer

Reports status changes and optional results for an existing
background check. The check ID is always in the path —
`backgroundCheckRequestId` is not accepted in the body.

`status` is required. `result`, `report`, and `checks` are optional.

This PATCH is the target contract; the temporary
`POST /background-checks/webhook` alias remains only for migration. After a
`backgroundCheck.cancelled` webhook, partners stop processing and do not
send further updates unless product guidance says otherwise.

When `report` is present, Bob fetches the PDF from `report.url` at PATCH
time and stores it as a candidate file. Size limits and malware scanning
follow platform file-service defaults.

**OAuth scope:** `hiring.integrations:write`

**Rate limit:** 60 calls per minute

## Path parameters

- `backgroundCheckRequestId` string, required

## Request body

- UpdateBackgroundCheckBody
  - `status` 'in_progress' | 'cleared' | 'cleared_on_review' | 'canceled' | 'failed_on_review' | 'require_action', required: Background check lifecycle status reported by the partner and shown in Bob. Possible values:<br /> <ul> <li><code>in_progress</code> – Check is underway at the provider</li> <li><code>cleared</code> – Check completed and passed</li> <li><code>cleared_on_review</code> – Check cleared after manual review</li> <li><code>canceled</code> – Check was canceled</li> <li><code>failed_on_review</code> – Check failed after manual review</li> <li><code>require_action</code> – Further action is required before the check can proceed</li> </ul>
  - `result` string, nullable: Optional human-readable result summary (for example `"Pass"`).
  - `report` BackgroundCheckReport: HTTPS reference to a PDF report that Bob fetches and stores as a candidate file (`BACKGROUND_CHECK`, `application/pdf`). Prefer short-lived or auth-gated URLs — there is no contract for long-lived public unsigned URLs.
    - `url` string, required: HTTPS URL Bob uses to download the PDF at PATCH time. The URL must be reachable by Bob when the update is processed. PDF only.
    - `filename` string, required: Filename stored on the candidate application. If a file with the same name already exists for the application, Bob reuses it and does not re-fetch the URL.
  - `checks` BackgroundCheckStep[], nullable: Optional per-step breakdown of individual checks within the package.
    - `name` string, required: Display name of the individual check step (for example `"Criminal record"`).
    - `status` string, required: Status of the individual check step. Prefer the same values as `BackgroundCheckStatus` when applicable.

## Response `204`

No content

## Other responses

- `400`: Bad request — the request body failed validation (for example an unsupported `status`, blank package `id`/`name`, or duplicate package IDs in the same catalog push).
- `401`: Unauthorized — the OAuth 2.0 access token is missing, invalid, or expired.
- `403`: Forbidden — the authenticated partner app does not have the `hiring.integrations:write` scope, or the background-check integration is not enabled for the installing company.
- `404`: Not found — no background check exists for the given `backgroundCheckRequestId` in the installing company for this partner provider.
- `429`: Too many requests — rate limit exceeded (60 calls per minute per operation). Retry after the delay indicated by the `Retry-After` header.
- `500`: Internal server error — an unexpected error occurred. Retry with exponential backoff; if the error persists, contact HiBob support with the `requestId` from the response body.

---

[API](https://skmtc.dev/hibob/apis/bob-hiring-partners-api.md) - [All operations](https://skmtc.dev/hibob/apis/bob-hiring-partners-api/llms.txt) - [OpenAPI document](https://skmtc.dev/hibob/apis/bob-hiring-partners-api/revisions/50feb9493b32?raw)