---
title: "Register background check packages"
method: POST
path: "/hiring/background-checks/packages"
tags: ["Background checks"]
---

# Register background check packages

`POST /hiring/background-checks/packages`

## Request

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

Registers or replaces the partner's package catalog for the
installing company. The call is idempotent — safe to retry to refresh names
or descriptions.

Catalog replace semantics:
<ul>
  <li>`id` and `name` are required and non-blank; `description` is optional.</li>
  <li>Duplicate package IDs in the same request return `400`.</li>
  <li>Packages omitted from the POST are permanently deleted and cannot be selected for new checks.</li>
  <li>An empty `packages` array permanently deletes the full catalog for that company/app.</li>
  <li>In-flight checks keep their stored `packageId`; GET and PATCH on existing checks remain allowed.</li>
  <li>Validation is all-or-nothing — no partial accept.</li>
</ul>

There is no hard maximum package count in v1.

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

**Rate limit:** 60 calls per minute

## Request body

- PushBackgroundCheckPackagesBody
  - `packages` BackgroundCheckPackage[], required: Packages to keep active for the installing company after this replace.
    - `id` string, required: Partner-defined package identifier. Returned as `packageId` on triggered events and GET check details.
    - `name` string, required: Display name shown to recruiters in Bob when selecting a package.
    - `description` string, nullable: Optional longer description shown alongside the package name.

## 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.
- `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)