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. PLEASE NOTE these endpoints ONLY add Business Units to a company. If you want to associate them with Billing Codes and/or BGC Packages you would need to add the Business Units using those endpoints using the newly added businessUnitId field in each POST endpoint.

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.
• Business Units may exist without Billing Code or Package associations.
• If associations exist, ordering workflows will 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.
• 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
  • Used to fetch all Business Units for a company to support UI display, mapping, or validation logic.
  • Used to fetch a specific Business Unit for a company to support UI display, mapping, or validation logic.
• PUT Business Units
  • Allows updates/modification of existing Business Units, including changes to names and status.
• Delete Business Units
  • Removes a Business Unit from the client’s configuration.
• Optional Associations
  • Business Units may be associated with:
    • Billing Codes
    • BGC Packages
  • 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).

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/Entity.
• 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.

Recommendations

• If a Partner has a client already using Billing Codes, Partners should continue using the billing codes under Business Units for consistency.
• If a client is not using Billing Codes for Packages today, they shouldn’t start using them under Business Units — unless the client decides to adopt Billing Codes for Packages.
  • The Partner can choose to add Billing Codes to Packages first (without Business Units) and then start using them consistently under Business Units.
• For better understanding of how the structure appears to end users, we suggest scenario testing in the Partner sandbox account.

Recommended adoption flow:

• Create Business Units using POST — after at least one Business Unit is added and is active, a new Business Unit dropdown will appear in the UI.
• Create Billing Codes with businessUnitId assigned.
  • This would filter billing codes on the UI to only those codes associated with the Business Unit.
• Create Packages with Billing Codes and businessUnitId assigned.
  • Doing this would allow for the most filtering on the UI. When the client selects the Business Unit, then only billing codes and packages associated to that would appear for the client to select for Order.
• (Optional) Update existing Packages with Billing Codes and businessUnitId if needed.