HIhibob
Background checks

Update background check status

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

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

Path parameters

backgroundCheckRequestIdstring required

Numeric Bob background-check ID as a string.

Request body

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>
resultstring nullable

Optional human-readable result summary (for example "Pass").

Response

No content

Changes

No recorded changes to this operation across all 1 revision of this API.