---
title: "Workday Absence REST API: Submit & Validate Time Off"
description: "Step-by-step guide to the Workday absenceManagement v5 REST API: querying eligibleAbsenceTypes, checking validTimeOffDates, and posting requestTimeOff payloads."
url: https://kiweely.com/guides/workday-absence-management-rest-api-request-time-off
---

# Submitting and Validating Time-Off Requests with the Workday Absence REST API

Submitting time off via the Workday absenceManagement v5 REST API follows a mandatory three-step sequence: discover eligible Time Off Types, validate scheduled workdays and default daily quantities on validTimeOffDates, and POST a days array with businessProcessParameters to requestTimeOff.

-   **Checked** against Workday on November 15
-   Applies to **Workday Absence REST API**
-   5 min read
-   Published November 15
-   By Kiweely

Submitting a time-off request through the Workday **Absence Management REST API** (`absenceManagement/v5`) requires a three-call sequence: fetch the worker’s eligible absence types (`GET /workers/{ID}/eligibleAbsenceTypes`), validate the target calendar dates against their work schedule and holidays (`GET /workers/{ID}/validTimeOffDates`), and submit the daily quantities (`POST /workers/{ID}/requestTimeOff`). Skipping the date-validation step or omitting the `Submitted` action Workday ID causes avoidable `400 Bad Request` failures or leaves requests stuck unrouted.

Every endpoint in `absenceManagement/v5` operates under the **Time Off and Leave** functional area scope on your OAuth API client (`Register API Client`). When called with a user-delegated OAuth 2.0 Bearer credential, Workday automatically enforces the signed-in employee’s `Request Time Off` business process initiating policy, work schedule, balance lower limits, and approval routing.

## Required Security Domains and Business Process Permissions

Before testing the `absenceManagement/v5` endpoints, confirm both the OAuth client scope and the user’s security group permissions in Workday:

| Endpoint (`absenceManagement/v5`) | Purpose | Required Domain / Business Process Security (`Time Off and Leave` Scope) |
| --- | --- | --- |
| `GET /workers/{ID}/eligibleAbsenceTypes` | Lists Time Off Types, Absence Tables, and Leave Types the worker can request. | Domain: `FLW Service`; Business Process Type: `Request Time Off`, `Request Leave of Absence` (Initiate). |
| `GET /workers/{ID}/validTimeOffDates` | Checks whether specific dates are valid working days and returns default scheduled units. | Business Process Type: `Request Time Off` (Initiate). |
| `POST /workers/{ID}/requestTimeOff` | Creates the request and initiates the `Request Time Off` business process. | Domain: `FLW Service`; Business Process Type: `Request Time Off` (Initiate). |
| `POST /workers/{ID}/correctTimeOffEntry` | Adjusts or cancels an already approved time-off entry via `Correct Time Off`. | Domain: `FLW Service`; Business Process Type: `Correct Time Off` (Initiate). |
| `GET /workers/{ID}/timeOffDetails` | Reads submitted, pending, or approved time-off entries and statuses. | Domains: `Self-Service: Time Off`, `FLW Service`, or `Worker Data: Time Off` (for managers/HR). |

-   Security note: Even though `FLW Service` (Frontline Worker Service) appears in the REST metadata, standard self-service security groups (`Employee as Self`) must be granted `GET` / `PUT` access on `FLW Service` and `Initiate` permission on the `Request Time Off` business process security policy (`Edit Business Process Security Policy` -> `Activate Pending Security Policy Changes`) for user-delegated REST submissions to succeed.

## Step-by-Step: The Three-Call Time-Off Submission Pattern

### Step 1: Discover Eligible Time Off Types for the Worker

Never hardcode Time Off Type Workday IDs (`WID`s) across regions or worker types. A salaried employee in California, an hourly warehouse associate, and an employee in the UK qualify for completely different **Time Off Plans** and **Absence Tables**.

Call `GET /workers/{ID}/eligibleAbsenceTypes`—optionally passing `effective=YYYY-MM-DD` if the request falls in a future plan year—to retrieve only the absence types the worker is eligible to request on that date:

http

```
GET /ccx/api/absenceManagement/v5/{tenant}/workers/3aa5550b7fe348b98d7b5741afc6f534/eligibleAbsenceTypes?effective=2026-12-21 HTTP/1.1
Authorization: Bearer <user_delegated_access_credential>
Accept: application/json
```

Inspect each returned item’s `id`, `descriptor` (for example, `Paid Time Off (Hours)` or `Sick Time Off`), `unit` (`Hours` vs. `Days`), and whether `reason` or `position` selection is required when a worker holds multiple jobs.

### Step 2: Validate Target Dates Against Schedules and Holidays

Next, pass the chosen `timeOff` ID and each candidate `date` (`YYYY-MM-DD`) as repeated query parameters to `GET /workers/{ID}/validTimeOffDates`:

http

```
GET /ccx/api/absenceManagement/v5/{tenant}/workers/3aa5550b7fe348b98d7b5741afc6f534/validTimeOffDates?timeOff=9f8e7d6c5b4a3210fedcba9876543210&date=2026-12-21&date=2026-12-24&date=2026-12-25 HTTP/1.1
Authorization: Bearer <user_delegated_access_credential>
Accept: application/json
```

Workday evaluates the worker’s **Work Schedule Calendar**, **Holiday Calendar**, and—if the plan uses **Connected Experience: Scheduled Days to Include**—published **Workday Scheduling** shifts:

-   If December 25 is on the worker’s Holiday Calendar (or is a scheduled non-working Saturday/Sunday) and the Time Off Plan excludes holidays/non-workdays, `validTimeOffDates` flags or omits that date so your client does not submit paid PTO hours on a company holiday.
-   For valid workdays, the response supplies the worker’s scheduled daily quantity (such as `8` hours on a standard `5x8` schedule or `10` hours on a `4x10` shift), preventing guesswork.

### Step 3: Construct and Submit `POST /workers/{ID}/requestTimeOff`

Build one entry in the `days` array for **each valid workday** (never send a single multi-day range object; Workday creates one daily `Time Off Entry` per element in `days`). To route the request immediately into the **Request Time Off** approval workflow rather than leaving it unsubmitted, include `businessProcessParameters.action.id` set to `"d9e4223e446c11de98360015c5e6daf6"` (`Submitted`):

json

```
{
  "businessProcessParameters": {
    "action": {
      "id": "d9e4223e446c11de98360015c5e6daf6"
    }
  },
  "days": [
    {
      "date": "2026-12-21",
      "dailyQuantity": 8,
      "timeOffType": {
        "id": "9f8e7d6c5b4a3210fedcba9876543210"
      },
      "comment": "Year-end family travel"
    },
    {
      "date": "2026-12-24",
      "dailyQuantity": 4,
      "start": "08:00",
      "end": "12:00",
      "timeOffType": {
        "id": "9f8e7d6c5b4a3210fedcba9876543210"
      },
      "comment": "Half-day afternoon off"
    }
  ]
}
```

Key payload rules to watch:

-   **Unit Alignment:** `dailyQuantity` must match the plan’s **Unit of Time**. If a plan tracks `Days`, send `1` or `0.5`—sending `8` on a `Days`\-based plan requests eight full days on a single calendar date and immediately fails validation.
-   **Multiple Positions:** For position-based Time Off Plans when a worker holds more than one active job, include `"position": { "id": "<position_wid>" }` inside each day object.
-   **Partial-Day Start/End Times:** When time-off entry requires start and end timestamps for Time Tracking coordination, populate `start` and `end` alongside `dailyQuantity`.

## Handling Blackout Dates, Lower Balance Limits, and Warnings

When `POST /workers/{ID}/requestTimeOff` executes, Workday runs every delivered and custom **Time Off Validation** configured on the Time Off Plan and the `Request Time Off` business process:

1.  **Lower Balance Limit Breach (`Critical`):** If requesting `16` hours drops the worker’s projected balance as of December 24 below the plan’s **Time Off Lower Limit** (for example, `0` hours when unpaid spillover is disabled), Workday aborts the transaction with `HTTP 400` and returns the exact validation message in the `errors` array. Check `GET /balances?worker={ID}&effective=2026-12-24` beforehand so the UI can warn the user proactively (see [retrieving eligible absence plans and balances](https://kiweely.com/guides/workday-absence-balances-api-eligible-plans-for-worker)).
2.  **Blackout Periods & Minimum Increment Rules:** Custom validations configured in `Maintain Time Off Validations` (such as retail peak blackout windows, minimum half-day increments, or advance-notice rules) return structured `400` validation errors when set to **Critical**.
3.  **Warning Validations (`wd-warning-action`):** If a tenant validation is configured with severity **Warning** rather than **Critical**, inspect the response or pass the `wd-warning-action` header only after displaying the warning message to the signed-in employee and receiving explicit confirmation.

## Verifying Submitted Event Status

After submission, call `GET /workers/{ID}/timeOffDetails?fromDate=2026-12-21&toDate=2026-12-24` to display live event status (`Submitted`, `Approved`, `Denied`, or `Canceled`) to the worker. You can map status WIDs dynamically via `GET /values/timeOff/status` (for example, `Approved` corresponds to `0391102bd1b542538d996936c8fa2fa7`). Remember that **Submitted** (pending manager approval) entries already reduce the worker’s projected available balance on subsequent requests.

When building custom absence screens or AI assistant workflows on top of these endpoints, **[Kiweely Leaf](https://kiweely.com/leaf)** (coming next) wires the entire `eligibleAbsenceTypes` -> `validTimeOffDates` -> `requestTimeOff` sequence into branded web, phone, and Teams/Slack screens without a Workday Extend license, while **[Kiweely Bridge](https://kiweely.com/bridge)** (coming next) lets employees prepare time-off requests in Claude, ChatGPT, or Gemini and confirm every write on an out-of-band browser approval card showing exact before-and-after balances.

## Frequently asked questions

### Why does POST /workers/{ID}/requestTimeOff fail if you skip GET /validTimeOffDates?

Workday evaluates the worker's Work Schedule Calendar, Holiday Calendar, and published Workday Scheduling shifts per calendar day. Calling validTimeOffDates tells you which requested dates are valid working days and returns the scheduled daily quantity (such as 8 hours vs. 0 hours on a holiday).

### How do you submit a Request Time Off business process event versus saving it for later?

Include businessProcessParameters.action.id set to d9e4223e446c11de98360015c5e6daf6 (the Workday ID for Submitted) inside the POST /workers/{ID}/requestTimeOff payload so Workday initiates routing approvals immediately.

### How do you override soft warning validations when submitting time off via the Workday REST API?

Critical validations always block submission with an HTTP 400 error. For non-blocking Absence warnings, pass the wd-warning-action request header on POST /workers/{ID}/requestTimeOff after showing the warning text to the user.

### How do you modify or cancel an already approved time-off entry over REST?

Do not re-post to requestTimeOff for an existing approved date. Instead, retrieve the existing Time Off Entry ID via GET /workers/{ID}/timeOffDetails and submit an adjustment or cancellation through POST /workers/{ID}/correctTimeOffEntry.

## Sources checked

-   [Setup Considerations: Time Off Plans](https://doc.workday.com/admin-guide/en-us/human-capital-management/absence/time-off/set-up-time-off/fec1580088837938.html)
-   [Concept: Balance Projections for Time Off](https://doc.workday.com/admin-guide/en-us/human-capital-management/absence/time-off/time-off-plan-balances/dan1370797344039.html)
-   [Concept: Entering Time Off in Absence and Time Tracking](https://doc.workday.com/admin-guide/en-us/human-capital-management/absence/gev1601980493355.html)

## Related guides

[All guides](https://kiweely.com/guides)

-   [### How Workday Calculates Projected Time-Off Balances as of a Future Date Workday computes a projected time-off balance dynamically from the worker’s last stored balance date through the target future date by adding scheduled period accruals, applying carryover and upper accrual caps in sequence, and subtracting both approved and pending time-off requests.](https://kiweely.com/guides/workday-accrued-time-off-balance-as-of-future-date)
-   [### Retrieving Eligible Absence Plans and Live Balances for a Worker via Workday APIs Workday exposes worker absence balances across four API surfaces: GET /balances in absenceManagement v5 for real-time and future-dated balances across Time Off, Absence Tables, and Leave Types; GET /workers/{ID}/timeOffPlans in common v1; Absence\_Management SOAP; and WQL balance data sources.](https://kiweely.com/guides/workday-absence-balances-api-eligible-plans-for-worker)
-   [### Workday Time Off vs. Leave of Absence: Helping Employees Pick the Right Request Type Workday separates short-term accrued absences (Request Time Off) from extended or protected leaves (Request Leave of Absence). Time Off deducts daily units without changing worker status, whereas Leave of Absence can mark a worker On Leave, pause accruals, and require Request Return from Leave.](https://kiweely.com/guides/workday-leave-of-absence-vs-time-off-employee-request-routing)
-   [### Parsing Workday Business Process Custom Validation Errors Returned by REST and SOAP APIs Workday REST APIs return HTTP 400 JSON payloads containing an errors array with code, field, path, and severity (Critical or Warning), whereas Workday SOAP Web Services return HTTP 500 envelopes containing Validation\_Fault (with Xpath) or Processing\_Fault elements.](https://kiweely.com/guides/workday-business-process-validation-errors-rest-soap-responses)

### More guides on Integrations and APIs

[All 89 guides](https://kiweely.com/guides#integrations)

-   [Reading Current Benefits Elections and Dependents Through Workday Self-Service APIs](https://kiweely.com/guides/workday-view-benefits-elections-dependents-beneficiaries-api)
-   [Auditing External API Calls in Workday Sign-On History and Activity Logs](https://kiweely.com/guides/workday-view-api-client-audit-logs-sign-on-history)
-   [Entering Time Blocks and Check-In/Check-Out Events via Workday Time Tracking APIs](https://kiweely.com/guides/workday-time-tracking-api-clock-in-out-enter-time)
-   [Authenticating Workday SOAP Web Services with a User-Delegated OAuth Bearer Token](https://kiweely.com/guides/workday-soap-api-bearer-token-user-delegated-oauth)
-   [Diagnosing Workday REST API 403 Forbidden: Missing Client Scope vs. Worker Domain Security](https://kiweely.com/guides/workday-rest-api-403-forbidden-user-security-vs-client-scope)
-   [Workday Expenses REST API: create a Quick Expense, upload a receipt and submit an Expense Report](https://kiweely.com/guides/workday-expenses-rest-api-receipt-attachments-expense-lines)
-   [Designing for Workday Tenant API Concurrency and Rate Limits During Peak Employee Traffic](https://kiweely.com/guides/workday-api-rate-limits-concurrency-workforce-self-service)
-   [Calling Workday RaaS Reports with User-Delegated OAuth Instead of an ISU](https://kiweely.com/guides/workday-raas-user-delegated-oauth-vs-isu-basic-auth)

### From the blog on Integrations and APIs

[All posts](https://kiweely.com/blog)

-   [Personal AI Plus Shared ISU Credentials: The Compound Workday Failure Mode](https://kiweely.com/blog/personal-ai-plus-shared-isu-compound-failure)
-   [BYO API Keys on a Workday Consultant Laptop: Who Is the Controller?](https://kiweely.com/blog/byo-api-key-workday-consultant-laptop)
-   [Why Shared Integration System Users (ISUs) Are a Security Risk for Employee AI Chatbots](https://kiweely.com/blog/why-integration-system-users-are-dangerous-for-workday-ai)

## Let Workday check the work.

Kiweely writes WQL and builds orchestrations in your own tenant, and Workday, not Kiweely, says whether they passed.

[Start for free](https://kiweely.com/download) [See how it works](https://kiweely.com/vine/how-it-works)

## Get the next guide in your inbox.

One email a month with new guides and one Extend tip. Nothing else.
