---
title: "Replace Job Title Level Assignments"
method: PUT
path: "/api/v1/pay-grades-and-bands/job-titles"
tags: ["Pay Grades & Bands", "Public API"]
---

# Replace Job Title Level Assignments

`PUT /api/v1/pay-grades-and-bands/job-titles`

## Request

- Base URL: `https://companySubDomain.bamboohr.com`
- URL: `https://companySubDomain.bamboohr.com/api/v1/pay-grades-and-bands/job-titles`
- 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/job-titles/put.ts> (a function with typed inputs; its response is checked against the schema)

Replaces the complete set of draft job title-to-compensation-level assignments with the associations in the request. This is a full replacement: all existing draft job title assignments are deleted and replaced with those supplied, so any assignment omitted from the request is removed from the draft. Each entry pairs a job title with the compensation level it should map to. This endpoint writes only job-title assignments; define group and level structure with Update Compensation Level Groups and Levels (`update-compensation-level-groups-and-levels`) and set pay band values with Update Pay Bands (`update-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. Every target level must belong to a draft group, otherwise the request fails with 400. Discover job title and level IDs with Get Job Titles and Level Assignments (`get-job-title-level-assignments`). Assignments 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

- LevelsAndBandsJobTitleAssignmentsRequest: Request to bulk assign job titles to levels
  - `jobTitles` LevelsAndBandsJobTitleAssignment[], required: Array of job title assignments
    - `jobTitleId` integer, required: Job title id
    - `levelId` integer, required: Compensation level id

## Response `200`

Draft job title assignments replaced. Returns an object with a `status` field set to `success`.

- object
  - `status` string

## Other responses

- `400`: Returned when 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, 2 info
  - the request property `jobTitles/items/jobTitleId` became required
  - the request property `jobTitles/items/levelId` became required
  - api operation id `2a0b847ceec3a4f9bfe20cf27e10e81a` removed and replaced with `replace-job-title-level-assignments`
  - api tag `Pay Grades & Bands` added

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