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

# Evaluate Shift Claims

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

## Request

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

Asks what the scheduling rules say about a claim, without writing anything. A proposal item gives an `employeeId` and a `shiftId` and asks what happens if the employee took the shift, and a reference item gives a `shiftClaimId` and asks whether that pending claim could be approved. Each item names the `actions` to decide, and gets one evaluation per action, evaluated with the shift's published times and the employee's published commitments. A reference is evaluated for its claimant and shift as they are now. The operation writes nothing and reserves nothing. A result never authorizes a write: claiming and approving evaluate again when they commit. An employee is evaluated for the shifts `GET /api/v1/scheduling/open-shifts` would list for them, so a shift that is not open to the employee, or a projected occurrence that has no row yet, fails its item with `invalid_shift_id`. The one exception is a shift starting on a day the employee has no active employment status: the list leaves it out, and this operation evaluates it and blocks it with `EMPLOYEE_NOT_ACTIVE`, or with `RESTRICTED_REASON` when the caller may not see the employee's employment status. A reference is accepted for exactly the claims `GET /api/v1/scheduling/shift-claims` would show the caller. An employee, shift or claim that does not exist and one the caller may not see fail identically. A blocked outcome is shown to the claimant and the approver alike, and findings and coverage a caller may not see are withheld. Returns `200` when every item was evaluated and `207` when any item failed, including when every item did. A request holds at most 100 items, and proposals and references may be mixed. Evaluating fails with `open_shifts_disabled` while Open Shifts is off.

OAuth Scopes: scheduling:shifts

## Request body

- SchedulingEvaluateShiftClaimsV1: The shift claims to evaluate. Every problem that can be found from the request alone fails the whole request with no results: a malformed body, no items or too many, a duplicate or missing `ref`, an item with both forms or neither, a proposal missing `employeeId` or `shiftId`, an item missing `actions`, or an action the item's form does not support.
  - `items` SchedulingEvaluateShiftClaimsItemV1[], required: The items to evaluate. At most 100, the same cap as the page size of the open-shifts and shift-claims lists.
    - `ref` string, required: Your identifier for this item, unique within the request. The response echoes it on the item's result or error.
    - `shiftClaimId` string, nullable: Reference form: the existing claim to evaluate for approval, at its claimant and shift as they are now. Exclusive with `employeeId` and `shiftId`. A claim that does not exist and one the caller may not see both fail the item with `invalid_shift_claim_id`, and a claim that is no longer pending fails it with `shift_claim_not_pending`.
    - `employeeId` integer, nullable: Proposal form: the employee who would claim the shift. Required with `shiftId`, and exclusive with `shiftClaimId`.
    - `shiftId` string, nullable: Proposal form: the shift they would claim. Required with `employeeId`, and exclusive with `shiftClaimId`. 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 never open, so it fails the item with `invalid_shift_id`.
    - `actions` string[], required: The actions to decide. Each action gets its own evaluation in the result. A reference item takes exactly `APPROVE_SHIFT_CLAIM`, and a proposal item takes exactly `CLAIM_SHIFT`.

## Response `200`

Every item was evaluated.

- SchedulingSchedulingShiftClaimEvaluationBatchV1: The answers to an evaluation request. Every request item appears in exactly one of `results` and `errors`, echoed by `ref`. Array position carries no meaning.
  - `results` SchedulingSchedulingShiftClaimEvaluationResultV1[], required: The items that were evaluated.
    - `ref` string, required: The `ref` of the request item this result answers.
    - `evaluations` SchedulingSchedulingEvaluationV1[], required: One evaluation for each action the item requested. Find an evaluation by its decision's `action`, never by position.
      - `context` SchedulingSchedulingEvaluationContextV1, required: The business question evaluated and the scheduling basis it was evaluated on.
        - `question` string, required: The business question the server evaluated. An open-ended string. Known values: `EMPLOYEE_ASSIGNMENT`.
        - `subjects` SchedulingSchedulingEvaluationSubjectV1[], required: The subjects the question is about. `EMPLOYEE_ASSIGNMENT` has one employee and the target shift.
          - `type` string, required: The kind of subject. An open-ended string; treat an unknown value as an unrecognized subject. Known values: `EMPLOYEE`, `SHIFT`.
          - `id` string, required: The subject's ID, always a string. For `EMPLOYEE` it is the decimal string of the employee ID, which other Scheduling resources return as an integer. A `SHIFT` ID may identify a projected occurrence.
        - `state` string, required: The state assessed. `PROPOSED` assesses a hypothetical assignment. An open-ended string. Known values: `PROPOSED`.
        - `scheduleView` string, required: The schedule data the evaluation reads. `PUBLISHED` uses published times and assignments and ignores draft and staged edits. An open-ended string. Known values: `PUBLISHED`.
        - `window` SchedulingSchedulingEvaluationPeriodV1, required: A half-open period: start included, end excluded, with start strictly before end.
          - `start` string, date-time, required: UTC timestamp of the start of the period, inclusive.
          - `end` string, date-time, required: UTC timestamp of the end of the period, exclusive.
          - `timezone` string, nullable: IANA timezone that explains calendar boundaries such as a workweek. It never changes the UTC instants. Omitted when the period has no calendar meaning.
      - `evaluatedAt` string, date-time, required: UTC timestamp of when the evaluation was computed. It is not a freshness guarantee or a snapshot token.
      - `findings` SchedulingSchedulingEvaluationFindingV1[], required: The findings the caller may see. Array order has no meaning.
        - `ref` string, uuid, required: Opaque reference to this finding within the evaluation. It is not a durable ID and does not match equivalent findings across evaluations.
        - `coverageRef` string, uuid, required: The `ref` of the coverage entry that produced this finding.
        - `type` string, required: The payload family. An open-ended string. Known values: `VIOLATION`.
        - `code` string, required: The specific payload within the type. An open-ended string. Known values: `ASSIGNMENT_OVERLAP`, `EMPLOYEE_NOT_ACTIVE`.
        - `subjects` SchedulingSchedulingEvaluationSubjectV1[], required: The subjects this finding concerns.
          - `type` string, required: The kind of subject. An open-ended string; treat an unknown value as an unrecognized subject. Known values: `EMPLOYEE`, `SHIFT`.
          - `id` string, required: The subject's ID, always a string. For `EMPLOYEE` it is the decimal string of the employee ID, which other Scheduling resources return as an integer. A `SHIFT` ID may identify a projected occurrence.
        - `period` SchedulingSchedulingEvaluationPeriodV1: A half-open period: start included, end excluded, with start strictly before end.
          - `start` string, date-time, required: UTC timestamp of the start of the period, inclusive.
          - `end` string, date-time, required: UTC timestamp of the end of the period, exclusive.
          - `timezone` string, nullable: IANA timezone that explains calendar boundaries such as a workweek. It never changes the UTC instants. Omitted when the period has no calendar meaning.
        - `treatment` string, required: How the decision's action policy treats this finding. Without an action policy it is `INFORMATIONAL`. An open-ended string. Known values: `BLOCKING`.
        - `details` object, required: The payload, with a schema identified by `type` and `code`. `VIOLATION`/`ASSIGNMENT_OVERLAP` uses `Scheduling-AssignmentOverlapFindingDetails-V1`, and `VIOLATION`/`EMPLOYEE_NOT_ACTIVE` uses `Scheduling-EmployeeNotActiveFindingDetails-V1`.
      - `coverage` SchedulingSchedulingEvaluationCoverageV1[], required: Every check the evaluation recorded.
        - `ref` string, uuid, required: Opaque reference to this entry within the evaluation, referenced by findings and decision reasons.
        - `capability` string, required: The check this entry records. An open-ended string. Known values: `ASSIGNMENT_OVERLAP`, `EMPLOYMENT_STATUS`.
        - `subjects` SchedulingSchedulingEvaluationSubjectV1[], required: The subjects the check assessed.
          - `type` string, required: The kind of subject. An open-ended string; treat an unknown value as an unrecognized subject. Known values: `EMPLOYEE`, `SHIFT`.
          - `id` string, required: The subject's ID, always a string. For `EMPLOYEE` it is the decimal string of the employee ID, which other Scheduling resources return as an integer. A `SHIFT` ID may identify a projected occurrence.
        - `period` SchedulingSchedulingEvaluationPeriodV1, required: A half-open period: start included, end excluded, with start strictly before end.
          - `start` string, date-time, required: UTC timestamp of the start of the period, inclusive.
          - `end` string, date-time, required: UTC timestamp of the end of the period, exclusive.
          - `timezone` string, nullable: IANA timezone that explains calendar boundaries such as a workweek. It never changes the UTC instants. Omitted when the period has no calendar meaning.
        - `status` string, required: Whether the check completed. Treat an unknown value as incomplete. An open-ended string. Known values: `COMPLETED`.
        - `reason` SchedulingSchedulingEvaluationCoverageReasonV1: Why a check did not complete.
          - `code` string, required: Why the check did not complete. An open-ended string. Known values: none yet.
      - `decision` SchedulingSchedulingEvaluationDecisionV1, required: Whether the evaluation's requirements permit an action. It does not authorize the action: claim status, permissions, and other prerequisites are checked separately, and a write re-evaluates.
        - `action` string, required: The action decided. An open-ended string. Known values: `CLAIM_SHIFT`, `APPROVE_SHIFT_CLAIM`.
        - `outcome` string, required: The outcome. Only `ALLOWED` permits the action; treat any other or unknown value as not permitting it. An open-ended string. Known values: `ALLOWED`, `BLOCKED`.
        - `reasons` SchedulingSchedulingEvaluationDecisionReasonV1[], required: The reasons for the outcome, one per reason code.
          - `code` string, required: Why the decision has its outcome. Show generic text for an unknown value, and still honor the outcome. A reason the caller may not see is `RESTRICTED_REASON`, which references nothing. An open-ended string. Known values: `ASSIGNMENT_OVERLAP`, `EMPLOYEE_NOT_ACTIVE`, `RESTRICTED_REASON`.
          - `findingRefs` string[]: The `ref`s of the findings behind this reason. Omitted when the reason references no finding.
          - `coverageRefs` string[]: The `ref`s of the coverage entries behind this reason. Omitted when the reason references no coverage entry.
  - `errors` SchedulingSchedulingShiftClaimEvaluationErrorV1[], required: The items that could not be evaluated.
    - `ref` string, required: The `ref` of the request item that failed.
    - `status` integer, required: The HTTP status the failure would have had as a request of its own.
    - `code` string, required: Machine-readable reason. Known values: `invalid_employee_id`, `invalid_shift_id`, `invalid_shift_claim_id`, `shift_claim_not_pending`.
    - `title` string, required: Short summary of the problem.
    - `detail` string, required: Explanation of the problem.

## Other responses

- `207`: At least one item could not be evaluated, and is in `errors`: `404` with `invalid_employee_id`, `invalid_shift_id` or `invalid_shift_claim_id`, or `409` with `shift_claim_not_pending`. The other items are still evaluated and are in `results`. Every item failing is also a `207`.
- `403`: Forbidden. Open Shifts is off (`open_shifts_disabled`), which fails the whole request.
- `422`: Invalid request, with no results: a malformed body, no items or more than 100, a missing or duplicate `ref`, an item with both `shiftClaimId` and `employeeId` or `shiftId`, or with neither form, a proposal missing `employeeId` or `shiftId`, an item missing `actions`, or an action the item's form does not support, such as `APPROVE_SHIFT_CLAIM` on a proposal. `fields` names each malformed item by position, such as `items[1]`.

## Changes

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

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