Business Units – Endpoint Overview

The Business Units endpoint introduces an optional top-level hierarchy within Paylocity's Background Check (BGC) API. Partners can use these endpoints to create and manage Business Units for clients.

This feature is designed to support clients with multi-layered organizational structures, such as departments, divisions, locations, or cost centers.

Purpose

Business Units provide a flexible way for partners to define a client's internal hierarchy and improve downstream selection flows during BGC ordering. When enabled, Business Units sit at the top of the configuration model:

Business Unit → Billing Code → Package

• All associations are optional.
• Clients may choose not to use Business Units.
• One billing code can be linked to one, many, or no Business Units.
• A billing code with no Business Unit links is global. It isn't tied to any Business Unit and is used when ordering without a Business Unit.
• Screening packages take their Business Unit(s) from their billing code. A package attached to a billing code can be ordered under every Business Unit that code is linked to.
• If associations exist, ordering workflows filter Billing Codes and Packages based on the selected Business Unit.

Why Use This Endpoint

For Partners:

• Supports enterprise-level configuration with clearer data segmentation.
• Enables more tailored ordering workflows through filtered Billing Code and Package lists.
• Eliminates duplicate billing codes by allowing one code to serve multiple Business Units.
• Reduces configuration errors and improves accuracy during background check ordering.
• Allows partners to update existing client configurations as clients adopt Business Units.

For Clients:

• Provides structure for billing, reporting, and operational organization.
• Simplifies ordering by displaying only relevant Billing Codes and Packages when associations exist.
• Supports scalability for departments, multi-location organizations, and complex internal hierarchies.

Capabilities

The Business Units API supports:

• POST Business Units
  • Partners can create Business Units for a client, providing a top-level organizational category.
• GET Business Units
  • Fetch all Business Units for a company to support UI display, mapping, or validation logic.
  • Fetch a specific Business Unit for a company to support UI display, mapping, or validation logic.
• PUT Business Units
  • Update existing Business Units, including changes to names and status.
• DELETE Business Units
  • Removes a Business Unit from the client's configuration. The unit must not be referenced by any billing code or package (see #deleting-business-units).
• Optional Associations
  • Business Units may be associated with Billing Codes (one billing code can link to many Business Units).
  • Packages inherit their Business Unit(s) from their billing code. A package-level Business Unit assignment only applies when the package has no billing code (see screening-packages section below).
  • If associated, Billing Code and Package selection is filtered by the selected Business Unit during ordering.
  • If no associations exist, clients continue to see the full list (default behavior).

Recommended Setup Order

Create your configuration in this order, which follows the API's natural dependencies:

1. Business Units via POST Business Units endpoint
2. Billing Codes referencing them via businessUnitIds using POST/PATCH Billing Codes endpoints
3. Screening Packages carrying a billingCode via POST Screening Package endpoint

Working with Billing Codes and Business Units

The businessUnitIds field works differently on Create and on Update. On Create, an omitted or empty businessUnitIds makes the billing code global. On Update, omitting it leaves the existing links unchanged, while [] clears them

Creating billing codes with multiple Business Units

POST /compliance/v1/companies/{companyId}/clientOnboarding/billing

Use the plural businessUnitIds field, a list of the Business Unit IDs you assigned when creating your Business Units:

{
  "billingCodes": [
    { "billingCode": "SHARED-01", "isActive": true, "businessUnitIds": ["BU-NORTH", "BU-SOUTH"] },
    { "billingCode": "GLOBAL-01", "isActive": true, "businessUnitIds": [] }
  ]
}

Rules:

• On Create, if businessUnitIds is empty or omitted, the billing code is global (not tied to any Business Unit).
• Create only accepts new billing codes. If a code already exists, the request returns 400 Bad Request. To change an existing code's status or Business Unit links, use the Update Billing Code endpoint (PATCH).
• Every referenced Business Unit must exist and not be deleted. Otherwise, the whole request fails with 400 Bad Request.
• IDs are deduplicated case-insensitively (bu-north and BU-NORTH count as one).
• The legacy singular businessUnitId is still accepted. If both fields are sent, the plural businessUnitIds wins.

Updating Business Unit links

PATCH /compliance/v2/companies/{companyId}/clientOnboarding/billingCode?billingCode={code}

Existing billing codes no longer need to be deleted and re-added to change their Business Unit associations. On update, the businessUnitIds field behaves differently than on create. Omitting the field does not make the code global. The field supports 3 behaviors:

Reading billing codes

GET /compliance/v1/companies/{companyId}/clientOnboarding/partner/billing

Responses include both fields:

• businessUnitIds: the full list of linked Business Unit IDs (empty for global codes)
• businessUnitId (legacy): the first linked unit, or null, kept for backward compatibility

Screening Packages

How a package gets its Business Unit(s) depends on whether it has a billing code:

• Package has a billing code (standard setup): The package's Business Units are taken from the billing code's links. Do not set a package-level businessUnitId. It is ignored.
• Package has no billing code: The package-level businessUnitId is used. This only applies to partners running in business-units-only mode (Business Units without billing codes).

When creating an order, the requested Business Unit must be one of the units linked to the selected package. Otherwise, the API returns 400 Bad Request. Orders using a global billing code are placed without a Business Unit.

Deleting Business Units

DELETE /compliance/v1/companies/{companyId}/businessUnits/{businessUnitId}

Returns 400 Bad Request while any billing code or package references the unit. Remove the links first DELETE Billing Code endpoint, then delete.

Backward Compatibility

Every existing billing code kept exactly the Business Unit link (or global status) it had before.

Use Cases

Common Partner Scenarios

• Mapping organizational units (e.g., stores, regions, departments).
• Providing cleaner dropdown selections during ordering.
• Supporting clients who require billing segmentation per Business Unit or entity.
• Sharing one billing code across several Business Units instead of maintaining duplicates.
• Migrating existing clients into a more structured hierarchy over time.

Common Client Scenarios

• Divisions requiring unique billing workflows.
• Large organizations needing reduced selection complexity for end users.
• Enterprise companies that require clearer audit trails tied to organizational structure.