---
title: "Get Pay Bands"
method: GET
path: "/api/v1/pay-grades-and-bands/pay-bands"
tags: ["Pay Grades & Bands", "Public API"]
---

# Get Pay Bands

`GET /api/v1/pay-grades-and-bands/pay-bands`

## Request

- Base URL: `https://companySubDomain.bamboohr.com`
- URL: `https://companySubDomain.bamboohr.com/api/v1/pay-grades-and-bands/pay-bands`
- Auth: OAuth 2
  - Authorization code: `/authorize.php`
  - Token URL: `/token.php` scopes: `pay_grades_and_bands`
- TypeScript: <https://skmtc.dev/bamboohr/apis/bamboohr-api/docs/api/v1/pay-grades-and-bands/pay-bands/get.ts> (a function with typed inputs; its response is checked against the schema)

Returns the working draft pay band configuration for every compensation level, including the pay-band-step validation `errors` and `warnings` used by the setup wizard. When no draft configuration exists, the endpoint returns the currently published configuration instead. The response is a JSON object with a `groups` array; each group carries its `levels`, and each level flattens its pay band into `min`, `mid`, `max`, and `percentageRange` value objects (each wrapping a numeric `value` plus its own `errors` and `warnings`), along with `currencyCode`, `compensationType`, and the `jobTitles` assigned to that level. A level is a percentage-based band when `percentageRange.value` is set, and a min-mid-max band when `percentageRange.value` is null. This view surfaces validation for the pay-band setup step; for the same structure with levels-step validation use List Compensation Level Groups and Levels (`list-compensation-level-groups-and-levels`), and for the published configuration without validation state use Get Published Levels and Bands (`get-published-levels-and-bands`).

OAuth Scopes: pay_grades_and_bands

## Response `200`

The working pay grades and bands configuration (the draft when one exists, otherwise the currently published configuration): pay band values with validation state, as an object with a `groups` array.

- object
  - `groups` object[]: Compensation level groups from the working configuration (the draft when one exists, otherwise the currently published configuration). Empty when none are configured.
    - `groupId` integer, nullable: Compensation level group identifier. Null for a not-yet-persisted group.
    - `groupName` string, nullable: Group name.
    - `levels` object[]: Compensation levels in this group.
      - `levelId` integer, nullable: Compensation level identifier. Null for a not-yet-persisted level.
      - `levelName` string, nullable: Level name.
      - `min` LevelsAndBandsPayBandValue: Represents a single compensation pay band value
        - `value` number, float, nullable: The value of the pay band
        - `errors` string[]: Array of validation errors for this pay band
        - `warnings` string[]: Array of validation warnings for this pay band
      - `mid` LevelsAndBandsPayBandValue: Represents a single compensation pay band value
        - `value` number, float, nullable: The value of the pay band
        - `errors` string[]: Array of validation errors for this pay band
        - `warnings` string[]: Array of validation warnings for this pay band
      - `max` LevelsAndBandsPayBandValue: Represents a single compensation pay band value
        - `value` number, float, nullable: The value of the pay band
        - `errors` string[]: Array of validation errors for this pay band
        - `warnings` string[]: Array of validation warnings for this pay band
      - `percentageRange` LevelsAndBandsPayBandValue: Represents a single compensation pay band value
        - `value` number, float, nullable: The value of the pay band
        - `errors` string[]: Array of validation errors for this pay band
        - `warnings` string[]: Array of validation warnings for this pay band
      - `currencyCode` string, nullable: ISO currency code for the pay band values.
      - `compensationType` 'Salary' | 'Hourly': Compensation type for the level.
      - `jobTitles` object[]: Job titles assigned to this level.
        - `id` integer: Job title identifier.
        - `jobTitle` string: Job title name.
      - `errors` string[]: Validation errors for this level.
      - `warnings` string[]: Validation warnings for this level.
    - `errors` string[]: Validation errors for this group.
    - `warnings` string[]: Validation warnings for this group.

## Other responses

- `403`: Insufficient permissions
- `500`: Internal server error

## Changes

- **2026-11-03** `922fc15f43a7`: 1 breaking, 2 warning, 11 info
  - the response property `groups` became optional for the status `200`
  - removed the optional property `groups/items/id` from the response with the `200` status
  - removed the optional property `groups/items/levels/items/payBand` from the response with the `200` status
  - api operation id `fb29d4d4790104b6892a4b6d6db67e19` removed and replaced with `get-pay-bands`
  - …10 more

[Operation history](https://skmtc.dev/bamboohr/apis/bamboohr-api/changes/api/v1/pay-grades-and-bands/pay-bands/get.md)

---

[API](https://skmtc.dev/bamboohr/apis/bamboohr-api.md) - [All operations](https://skmtc.dev/bamboohr/apis/bamboohr-api/llms.txt) - [OpenAPI document](https://skmtc.dev/bamboohr/apis/bamboohr-api/revisions/922fc15f43a7?raw)