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

# Update Pay Bands

`PUT /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.write`
- TypeScript: <https://skmtc.dev/bamboohr/apis/bamboohr-api/docs/api/v1/pay-grades-and-bands/pay-bands/put.ts> (a function with typed inputs; its response is checked against the schema)

Updates the pay band values (`min`, `mid`, `max`, `percentageRange`) for compensation levels in the company's draft pay grades and bands. This is the only endpoint that persists pay band values; Update Compensation Level Groups and Levels (`update-compensation-level-groups-and-levels`) defines the group and level structure but does not save band values. Job-title assignments are set separately with Replace Job Title Level Assignments (`replace-job-title-level-assignments`). Supply the level IDs returned by Get Pay Bands (`get-pay-bands`). If no draft exists yet, one is created from the published structure and the supplied published level IDs are remapped onto the newly created draft levels, so later reads return draft-specific level IDs. When `payBandType` is `percentRange`, `min` and `max` are derived from `mid` and `percentageRange` and any supplied `min`/`max` are ignored; when `minMidMax`, the supplied `min`/`mid`/`max` are stored and `percentageRange` is cleared. Every target level must belong to a draft group, otherwise the request fails with 400. Values are written to the draft only; publish them with Publish Draft Compensation Level Groups (`publish-draft-compensation-level-groups`). Returns an object with a single `status` field set to `success`.

OAuth Scopes: pay_grades_and_bands.write

## Request body

- object
  - `payBandType` 'percentRange' | 'minMidMax': Selects how band values are interpreted. `percentRange` derives `min`/`max` from `mid` and `percentageRange`; `minMidMax` stores the supplied `min`/`mid`/`max` and clears `percentageRange`. Defaults to `minMidMax` when omitted.
  - `payBands` object[], required: Pay band values to apply, one entry per level. Each entry requires the level ID; `min`, `mid`, `max`, and `percentageRange` are the raw numeric values (not the object form returned by Get Pay Bands).
    - `levelId` integer, required: The compensation level ID to apply pay band values to. Required and must not be null.
    - `min` number, float, nullable: Minimum band value as a raw number. Ignored when `payBandType` is `percentRange`.
    - `mid` number, float, nullable: Midpoint band value as a raw number.
    - `max` number, float, nullable: Maximum band value as a raw number. Ignored when `payBandType` is `percentRange`.
    - `percentageRange` number, float, nullable: Percentage spread used when `payBandType` is `percentRange`; cleared when `minMidMax`.
    - `currencyCode` string, nullable: ISO 4217 currency code for the band values.
    - `compensationType` 'Salary' | 'Hourly', nullable: Compensation type for the level. Defaults to `Salary` when omitted.

## Response `200`

Pay bands updated. Returns an object with a `status` field set to `success`.

- object
  - `status` string

## Other responses

- `400`: Returned when a pay band entry is missing its `levelId`, `payBandType` or `compensationType` is not a recognized value, or a target level does not belong to a draft group.
- `403`: The authenticated caller lacks permission to update pay grades and bands.
- `500`: Internal server error.

## Changes

- **2026-11-03** `922fc15f43a7`: 2 breaking, 8 info
  - the request property `payBands/items/levelId` became required
  - request property `payBands/items/levelId` list-of-types was narrowed by removing types `null` from media type `application/json`
  - api operation id `ad7871529b2a9c6612f8dd3c62192c08` removed and replaced with `update-pay-bands`
  - api tag `Pay Grades & Bands` added
  - …6 more

[Operation history](https://skmtc.dev/bamboohr/apis/bamboohr-api/changes/api/v1/pay-grades-and-bands/pay-bands/put.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)