---
title: "Claim a Shift"
method: POST
path: "/api/v1/scheduling/shift-claims"
tags: ["Scheduling", "Public API"]
---

# Claim a Shift

`POST /api/v1/scheduling/shift-claims`

## Request

- Base URL: `https://companySubDomain.bamboohr.com`
- URL: `https://companySubDomain.bamboohr.com/api/v1/scheduling/shift-claims`
- Auth: one of:
  - HTTP basic
  - OAuth 2
    - Authorization code: `/authorize.php`
    - Token URL: `/token.php` scopes: `scheduling:shifts.write`
- TypeScript: <https://skmtc.dev/bamboohr/apis/bamboohr-api/docs/api/v1/scheduling/shift-claims/post.ts> (a function with typed inputs; its response is checked against the schema)

Claims a shift for the authenticated employee. There is no employee parameter: the claimant is always the caller, and a caller with no employee record gets `claimant_not_an_employee`. When the shift requires approval the claim is created `pending` and the employee is not assigned. Otherwise the claim is `approved` and the employee is assigned in the same request. A recurring occurrence is identified by a composite ID, `<definitionUuid>_<Ymd\THis>`, and can be claimed once it has a row; an occurrence that has no row yet is not claimable and returns `shift_not_claimable`. A success body carries the claim only, with no evaluation data. Claiming fails with `open_shifts_disabled` while Open Shifts is off.

OAuth Scopes: scheduling:shifts.write

## Request body

- SchedulingCreateSchedulingShiftClaimV1: Request object for claiming a shift. The claimant is always the authenticated employee.
  - `shiftId` string, required: The ID of the shift to claim. A recurring occurrence has a composite ID, <definitionUuid>_<Ymd\THis>, which resolves to the occurrence once it has a row. A projected occurrence that has no row yet is not claimable.

## Response `201`

The claim was created.

- SchedulingSchedulingShiftClaimV1: An employee's claim on an open shift. A claim is deliberately thin: who claimed, which shift, and where it stands. The policy that governs how a claim is handled lives on the shift.
  - `id` string, uuid, required: The unique ID of this claim.
  - `shiftId` string, uuid, required: The ID of the shift being claimed.
  - `employeeId` integer, required: The ID of the employee who claimed the shift.
  - `status` 'pending' | 'approved' | 'declined' | 'withdrawn', required: Where the claim stands. Only a pending claim can be withdrawn. A first-come-first-served claim is never pending because it is approved when it is created.
  - `resolutionReason` 'manager_denied' | 'shift_filled' | 'shift_deleted' | 'claiming_disabled' | 'assignment_blocked', nullable, required: Why the claim was declined. Kept separate from status so that being denied and the shift filling are distinguishable.
  - `createdAt` string, date-time, required: UTC timestamp when the claim was received. This is the single source of truth for queue order.
  - `updatedAt` string, date-time, nullable, required: UTC timestamp when the claim was last updated.

## Other responses

- `403`: Forbidden. The caller is not on the shift's schedule or is previewing as another user, or Open Shifts is off (`open_shifts_disabled`).
- `404`: No shift has that ID (`invalid_shift_id`).
- `409`: The claim conflicts with the shift's current state: `shift_full`, `employee_already_assigned`, `shift_claim_already_exists`, `shift_claim_previously_declined`, or `assignment_evaluation_blocked` when the claim would overlap the employee's other shifts or the employee has no active employment status on the day the shift starts. A blocked response is plain `application/json` and also carries an `evaluation` member explaining the block, with `RESTRICTED_REASON` in place of a reason the caller may not see.
- `422`: Invalid input: `shiftId` is missing or empty, or the shift cannot be claimed: `claimant_not_an_employee`, `shift_not_claimable`, `shift_already_started`.

## Changes

- **2026-11-03** `922fc15f43a7`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/bamboohr/apis/bamboohr-api/changes/api/v1/scheduling/shift-claims/post.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)