--- updatedAt: 2026-05-11T22:22:56.000Z agentTools: siteIndex: https://developer.paylocity.com/llms.txt projectIndex: https://developer.paylocity.com/integrations/llms.txt --- # Create Business Units > 🚧 Partner Restricted > All background check API endpoints are restricted to background check providers that have signed a Paylocity technology partnership agreement. [Please reach out to our team](https://www.paylocity.com/contact/partner-form/) if you would like to discuss partnership opportunities. **Summary Description** This endpoint inserts businessUnits and their associated status by company ID for a given client **Use Cases** - Partner wants to send over one or multiple businessUnits for a client. This can either be when onboarding a new client, or when client wants to add new businessUnits to their company - Partner wants to make bulk changes to businessUnits to make them either active or inactive for a client # OpenAPI definition ```json { "openapi": "3.0.4", "info": { "title": "Background Check API", "version": "v1" }, "servers": [ { "url": "dc1demogwext.paylocity.com" } ], "paths": { "/compliance/v1/companies/{companyId}/businessUnits": { "post": { "tags": [ "Business Unit" ], "summary": "Create Business Units", "description": "> 🚧 Partner Restricted\n> All background check API endpoints are restricted to background check providers that have signed a Paylocity technology partnership agreement. [Please reach out to our team](https://www.paylocity.com/contact/partner-form/) if you would like to discuss partnership opportunities.\n\n**Summary Description**\n\nThis endpoint inserts businessUnits and their associated status by company ID for a given client\n\n**Use Cases**\n\n- Partner wants to send over one or multiple businessUnits for a client. This can either be when onboarding a new client, or when client wants to add new businessUnits to their company\n- Partner wants to make bulk changes to businessUnits to make them either active or inactive for a client\n", "x-explorer-enabled": false, "operationId": "ComplianceBusinessUnitsCreate", "parameters": [ { "name": "companyId", "in": "path", "description": "The Paylocity Company Identifier. This is the unique value provided by Paylocity to each specific Payroll Entity.\n **Allowable Values:**\n 9 char max", "required": true, "schema": { "type": "string" }, "example": "A12345" }, { "name": "testMode", "in": "header", "description": "If true all responses are mocked and generated randomly.", "schema": { "type": "boolean" }, "example": false }, { "name": "Authorization", "in": "header", "description": "Authorization token. Ex. Bearer ...", "required": true, "schema": { "type": "string" }, "example": "Bearer " } ], "requestBody": { "description": "The Business Unit data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddBusinessUnitRequest" }, "examples": { "TwoBusinessUnits": { "summary": "Adds two business units (Finance, HR).", "value": { "businessUnits": [ { "businessUnitId": "BU-001", "businessUnitName": "Finance", "isActive": true, "description": "Finance department" }, { "businessUnitId": "BU-002", "businessUnitName": "HR", "isActive": true, "description": "Human Resources" } ] } }, "SingleInactiveBusinessUnit": { "summary": "Adds one inactive business unit (Operations).", "value": { "businessUnits": [ { "businessUnitId": "BU-003", "businessUnitName": "Operations", "isActive": false, "description": "Operations team" } ] } } } } } }, "responses": { "201": { "description": "Returns details of the add operation" }, "400": { "description": "Bad Request Error - Returns the details of the error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericErrorResponse" }, "examples": { "MissingRequiredField": { "summary": "A required field is missing in the request payload.", "value": { "correlationId": "bad-request-missing-field-correlation-id", "value": { "code": "INVALID_REQUEST", "message": "The request payload failed validation." }, "count": 1, "values": [ { "fields": "request.fieldName", "code": "INVALID_REQUEST", "message": "The request payload failed validation." } ] } }, "InvalidFieldFormat": { "summary": "A field in the request payload has an invalid format.", "value": { "correlationId": "bad-request-invalid-format-correlation-id", "value": { "code": "INVALID_REQUEST", "message": "The request payload failed validation." }, "count": 1, "values": [ { "fields": "request.otherField", "code": "INVALID_REQUEST", "message": "The request payload failed validation." } ] } } } } } }, "401": { "description": "Unauthorized" }, "415": { "description": "Unsupported Media Type - Returns the details of the error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericErrorResponse" }, "examples": { "UnsupportedXmlContentType": { "summary": "The API only supports JSON, but XML was provided.", "value": { "correlationId": "unsupported-media-type-xml-correlation-id", "value": { "code": "UNSUPPORTED_MEDIA_TYPE", "message": "The request content type is not supported." }, "count": 1, "values": [ { "fields": "Content-Type: application/xml", "code": "UNSUPPORTED_MEDIA_TYPE", "message": "The request content type is not supported." } ] } }, "MissingContentTypeHeader": { "summary": "The Content-Type header is missing or empty.", "value": { "correlationId": "unsupported-media-type-missing-header-correlation-id", "value": { "code": "UNSUPPORTED_MEDIA_TYPE", "message": "The request content type is not supported." }, "count": 1, "values": [ { "fields": "Content-Type", "code": "UNSUPPORTED_MEDIA_TYPE", "message": "The request content type is not supported." } ] } } } } } } } } } }, "components": { "schemas": { "AddBusinessUnitRequest": { "type": "object", "properties": { "businessUnits": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessUnitDto" }, "description": "Array of package businessUnits.", "nullable": true } }, "additionalProperties": false, "description": "Package Organization request payload." }, "BusinessUnitDto": { "type": "object", "properties": { "businessUnitId": { "type": "string", "description": "Business Unit External ID associated with the business unit. This ID is created on the partner side for a specific company.\n **Allowable Values:**\n 150 char max", "nullable": true }, "businessUnitName": { "type": "string", "description": "Business Unit name.\n **Allowable Values:**\n 250 char max", "nullable": true }, "isActive": { "type": "boolean", "description": "(Optional, if not provided – TRUE) A Boolean value indicating if the business unit is active.\n **Allowable Values:**\n true, false" }, "description": { "type": "string", "description": "Optional description for the business unit.", "nullable": true } }, "additionalProperties": false, "description": "Business Unit DTO payload." }, "ErrorDto": { "type": "object", "properties": { "code": { "type": "string", "description": "Error code associated with the error.", "nullable": true }, "message": { "type": "string", "description": "Descriptive message detailing the error.", "nullable": true } }, "additionalProperties": false }, "GenericErrorResponse": { "type": "object", "properties": { "correlationId": { "type": "string", "description": "A unique identifier used for tracing and correlation purposes.", "nullable": true }, "value": { "$ref": "#/components/schemas/ErrorDto" }, "count": { "type": "integer", "description": "Gets the count of items in the Values list.", "format": "int32", "nullable": true, "readOnly": true }, "values": { "type": "array", "items": { "$ref": "#/components/schemas/ValidationErrorDto" }, "description": "A list of items.", "nullable": true } }, "additionalProperties": false }, "ValidationErrorDto": { "type": "object", "properties": { "code": { "type": "string", "description": "Error code associated with the error.", "nullable": true }, "message": { "type": "string", "description": "Descriptive message detailing the error.", "nullable": true }, "fields": { "type": "string", "description": "A string detailing the fields involved in the validation error.", "nullable": true } }, "additionalProperties": false } }, "securitySchemes": { "Bearer": { "type": "apiKey", "description": "CC JWT Authorization header using the bearer scheme", "name": "Authorization", "in": "header" } } }, "security": [ { "Bearer": [] } ] } ```