---
title: "Workday Time Tracking APIs: Time Blocks & Clock Events"
description: "How to submit punches, meal breaks, reported time blocks, worktags, and attestations using Workday timeTracking v7 REST and Time_Tracking SOAP APIs."
url: https://kiweely.com/guides/workday-time-tracking-api-clock-in-out-enter-time
---

# Entering Time Blocks and Check-In/Check-Out Events via Workday Time Tracking APIs

Workday separates live punch events (POST /timeClockEvents and Put\_Time\_Clock\_Events) from complete reported time blocks (POST /workers/{ID}/workerTimeBlock and Import\_Reported\_Time\_Blocks). In timeTracking v7, timestamps require nested time-zone blocks and mutually exclusive time type fields.

-   **Checked** against Workday on November 15
-   Applies to **Workday Time Tracking APIs**
-   5 min read
-   Published November 15
-   By Kiweely

Workday Time Tracking exposes two distinct write patterns under the **Time Tracking** functional area scope: **Time Clock Events** (`POST /timeClockEvents` in `timeTracking/v7` REST or `Put_Time_Clock_Events` in `Time_Tracking` SOAP) for real-time check-in, meal-break, and check-out punches that Workday matches asynchronously, and **Reported Time Blocks** (`POST /workers/{ID}/workerTimeBlock` in REST or `Put_Reported_Time_Blocks_for_Worker` / `Import_Reported_Time_Blocks` in SOAP) for completed quantity-based or in/out timesheet entries. Picking the wrong object—or sending legacy pre-`v7` timestamp fields—causes immediate schema rejections or unmatched punch exceptions.

Whether you are wiring a shop-floor check-in screen for hourly staff at `Warehouse 4` or a Friday project timesheet entry flow for consultants, understanding how Workday’s **Time Entry Templates**, attestations, worktags, and period lockout dates govern these APIs prevents failed payroll cutoffs.

## Architectural Matrix: Punches vs. Reported Time Blocks

| API Operation | Protocol & Service | Input Model | Security Domain (`Time Tracking` Scope) | Best Use Case |
| --- | --- | --- | --- | --- |
| `POST /timeClockEvents` | REST `timeTracking/v7` | Single timestamped punch (`Check-in`, `Meal Out`, `Check-out`) + `outReason`. | `Process: Time Clock Event REST API's` | Live phone/web check-in and check-out buttons with meal/shift attestations. |
| `POST /workers/{ID}/workerTimeBlock` | REST `timeTracking/v7` | Completed block: `calendarDate` + `reportedQuantity` (quantity workers) **or** `inTimeWithTimeZone` / `outTimeWithTimeZone` (in/out workers). | `Process: Time Block REST APIs` | Entering completed daily hours, project hours, or full in/out shifts on a calendar. |
| `POST /workers/{ID}/timeReviewEvents` | REST `timeTracking/v7` | Submits unsubmitted time blocks across a period into the `Review Time` approval workflow. | `Process: Time Review Event REST APIs` / `Review Time` BP | End-of-week employee timesheet submission or manager on-behalf submission. |
| `Put_Time_Clock_Events` / `Import_Time_Clock_Events` | SOAP `Time_Tracking` | Single or high-volume batch external clock punches (`Time_Clock_Event_Data`). | Integration / Time Clock Event security (`hel1453332481385`) | Physical badge terminals or batch punch synchronization; requires matching (`Manually Schedule Time Clock Event Matching`). |
| `Import_Reported_Time_Blocks` / `Put_Reported_Time_Blocks_for_Worker` | SOAP `Time_Tracking` | Batch or single-worker `Reported_Time_Block_Data` XML. | Integration / Reported Time Block domains | Bulk timesheet loads or historical corrections. |

## Real-Time Check-In, Meal Breaks, and Attestations (`POST /timeClockEvents`)

### 1\. Check Attestation Prompts Before Punching Out

In regulated jurisdictions (such as California meal and rest break rules), workers must answer **Time Attestations** when checking out for a meal or ending a shift. If attestations apply to the worker’s **Time Entry Template**, call `GET /timeAttestationPrompts` and record the worker’s response via `POST /workerTimeAttestation` **before** posting the check-out punch to `POST /timeClockEvents`.

### 2\. Use the `v7` `dateWithTimeZone` Structure and `outReason`

Starting in `timeTracking/v7`, Workday replaced the flat `dateTime` and `timeZone` properties on `POST /timeClockEvents` with a nested `dateWithTimeZone` block. For meal breaks versus end-of-shift punches, look up valid out reasons via `GET /values/timeValues/outReason` (such as `Meal` vs. `Out`):

json

```
{
  "worker": {
    "id": "3aa5550b7fe348b98d7b5741afc6f534"
  },
  "eventType": {
    "id": "a1b2c3d4e5f61000079a35410ed9001e"
  },
  "outReason": {
    "id": "5bebcdab469a1000249e2afbf6e7028f"
  },
  "dateWithTimeZone": {
    "dateTime": "2026-11-15T12:02:00.000",
    "timeZone": "dc10e1b4446c11de98360015c5e6daf6"
  },
  "timeEntryCode": {
    "id": "ee3d887ce441100008ae7446a1ce002f"
  },
  "costCenter": {
    "id": "2c59cbf40d3510001606811b605e0217"
  }
}
```

If an employee forgets to punch out before leaving, Workday holds the lone check-in as an **Incomplete Time Block** (`incompleteTimeBlocks` in WQL—note that `GET /workerTimeBlocks` intentionally excludes incomplete time blocks) until the matching punch arrives or the worker corrects the block.

## Entering Completed Time Blocks (`POST /workers/{ID}/workerTimeBlock`)

When entering time directly onto a worker’s calendar, inspect the worker’s **Time Entry Template** behavior first:

1.  **Quantity-Based Workers (Hours Only):** Send `calendarDate` (`YYYY-MM-DD`) and `reportedQuantity` (for example, `8` or `4.5`). Do not send in/out timestamps.
2.  **In/Out Time Workers (`v7` Breaking Schema):** Version `v7` rejects the legacy flat `inTime`, `outTime`, `inTimeZone`, and `outTimeZone` fields. You must pass `inTimeWithTimeZone` and `outTimeWithTimeZone`, each carrying an IANA `timeZone` string (`America/Los_Angeles`) and an ISO-8601 `dateTime` with UTC offset—handling Daylight Saving Time transitions cleanly when an overnight shift crosses `02:00`:

json

```
{
  "calendarDate": "2026-11-15",
  "inTimeWithTimeZone": {
    "timeZone": "America/Los_Angeles",
    "dateTime": "2026-11-15T08:00:00.000-08:00"
  },
  "outTimeWithTimeZone": {
    "timeZone": "America/Los_Angeles",
    "dateTime": "2026-11-15T16:30:00.000-08:00"
  },
  "outReason": {
    "id": "5bebcdab469a1000249e2afbf6e7028f"
  },
  "timeEntryCode": {
    "id": "18442114504f100025df72b5b8260110"
  },
  "location": {
    "id": "2c59cbf40d35100016cc7c6d9f47022d"
  },
  "comment": "Regular Sunday warehouse receiving shift"
}
```

### The Mutual-Exclusivity Rule for Time Types and Worktags

Workday enforces two strict payload constraints on both `POST /timeClockEvents` and `POST /workers/{ID}/workerTimeBlock`:

-   **One Time Type Field Only:** `timeEntryCode`, `project`, and `projectPlanTask` are **mutually exclusive**. Populate valid options dynamically for that worker and date using `GET /values/timeTypes/timeEntryCodes`, `GET /values/timeTypes/projects`, or `GET /values/timeTypes/projectPlanTasks`. Sending both `timeEntryCode` and `project` in the same JSON body triggers an immediate `400` validation error.
-   **Worktag Combination Rules:** If overriding costing dimensions (`costCenter`, `location`, `grant`, `fund`, or `customWorktag01`–`customWorktag15`), you can pre-validate required related worktags via `POST /common/v1/validateWorktags` so the worker fixes missing grant or cost-center pairs before submission.

## Diagnosing Locked Periods and Custom Time Entry Validations

Even a syntactically valid payload will fail if the payroll cutoff has locked the target calendar week or if custom tenant rules reject the entry:

-   **Locked Periods (`Lockout Dates`):** Call `GET /timeTracking/v7/workers/{ID}/period?date=2026-11-15` before rendering editable inputs. Workday **Period Schedules** define lockout dates after which workers cannot add or edit `workerTimeBlock` rows via self-service (unless an administrator exempts a security group or opens prior-period adjustments; see `FAQ: How do I exempt workers from lockout dates?`).
-   **Custom Time Validations (`Maintain Time Entry Validations`):** After creating or updating blocks (`PATCH /workers/{ID}/workerTimeBlock/{subresourceID}`), call `GET /timeValidations?worker={ID}&date=2026-11-15` to surface **Critical** errors (which block `POST /workers/{ID}/timeReviewEvents` submission—such as entering worked hours while `On Leave` or exceeding daily statutory maximums) and **Warning** messages.
-   **Submitting for Manager Approval:** Creating `workerTimeBlock` rows stages them as *Not Submitted* (see [finding unsubmitted project hours with WQL](https://kiweely.com/guides/workday-project-time-tracking-unsubmitted-hours-wql)). Call `POST /workers/{ID}/timeReviewEvents` at the end of the week to trigger the `Review Time` business process so hours flow into `Get_Calculated_Time_Blocks` and Workday Payroll.

For organizations giving frontline staff or project teams faster ways to log time, **[Kiweely Leaf](https://kiweely.com/leaf)** (coming next) builds 3-button mobile clock-in and timesheet screens over these exact `timeTracking/v7` APIs without a Workday Extend license, while **[Kiweely Bridge](https://kiweely.com/bridge)** (coming next) lets workers check weekly `timeTotals` or prepare time entries in Claude, ChatGPT, and Gemini with mandatory out-of-band browser confirmation before any write hits Workday.

## Frequently asked questions

### When should you call POST /timeClockEvents versus POST /workers/{ID}/workerTimeBlock?

Use POST /timeClockEvents when a worker punches in, punches out for a meal, or punches out at the end of a shift in real time so Workday pairs the punches into a block. Use POST /workers/{ID}/workerTimeBlock when entering a completed shift duration (such as 8 hours on a date) or a completed in/out pair at once.

### What breaking payload change happened in version v7 of the Workday timeTracking REST API?

Version v7 removed the flat dateTime/timeZone and inTime/outTime/inTimeZone/outTimeZone fields. Punches in v7 require a nested dateWithTimeZone object, and in/out time blocks require nested inTimeWithTimeZone and outTimeWithTimeZone objects with IANA time zones and ISO-8601 offsets.

### Why does Workday reject a time block when both timeEntryCode and project are sent?

In both POST /timeClockEvents and POST /workers/{ID}/workerTimeBlock, timeEntryCode, project, and projectPlanTask are strictly mutually exclusive. Specify exactly one of those three fields per block based on GET /values/timeTypes/ prompt results.

### How do you check whether a worker's time period is locked before posting hours?

Call GET /timeTracking/v7/workers/{ID}/period?date=YYYY-MM-DD to inspect the worker's eligible period schedule and lockout status, and check GET /timeValidations?worker={ID}&date=YYYY-MM-DD for critical or warning rules defined in Maintain Time Entry Validations.

## Sources checked

-   [Steps: Set Up Time Tracking](https://doc.workday.com/admin-guide/en-us/human-capital-management/time-tracking/time-tracking-basics/dan1370796796458.html)
-   [Reference: Time Block and Time Clock Event Sources](https://doc.workday.com/admin-guide/en-us/human-capital-management/time-tracking/entering-and-correcting-time/references-entering-and-correcting-time/reference--time-block-and-time-clock-event-sources.html)
-   [Concept: Importing Time Clock Events](https://doc.workday.com/admin-guide/en-us/human-capital-management/time-tracking/entering-and-correcting-time/concepts-entering-and-correcting-time/dan1370797671338.html)
-   [FAQ: How do I exempt workers from lockout dates?](https://doc.workday.com/admin-guide/en-us/human-capital-management/time-tracking/time-entry-setup/time-entry-setup-basics/hel1445982184704.html)

## Related guides

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

-   [### 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.](https://kiweely.com/guides/workday-absence-management-rest-api-request-time-off)
-   [### Authenticating Workday SOAP Web Services with a User-Delegated OAuth Bearer Token Send Workday SOAP requests with an HTTP Authorization Bearer header issued from a user-delegated OAuth 2.0 Authorization Code grant and leave the SOAP XML Header element empty. Workday evaluates both the API Client Functional Area scope and the signed-in worker’s Integration Permissions.](https://kiweely.com/guides/workday-soap-api-bearer-token-user-delegated-oauth)
-   [### Finding Unsubmitted Workday Time Blocks and Project Hours with WQL Query unsubmitted and unapproved Workday time before payroll cutoff using allTimeBlocks, incompleteTimeBlocks, and projectTimesheetLinesForWorkersWithinDateRange in WQL. Pair each query with explicit data source filters so constrained managers and project leads see every permitted row.](https://kiweely.com/guides/workday-project-time-tracking-unsubmitted-hours-wql)
-   [### 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)

-   [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)
-   [Updating Preferred Name, Pronouns, and Contact Information via the Workday Person API](https://kiweely.com/guides/workday-person-api-legal-preferred-name-contact-updates)
-   [Restricting Workday OAuth Token Use by IP with Maintain IP Ranges](https://kiweely.com/guides/workday-maintain-ip-ranges-manage-authentication-policies-api)
-   [Why Browser Single-Page Apps Hit CORS and Token Limits Against Workday APIs—and How to Fix It](https://kiweely.com/guides/workday-cors-browser-api-calls-why-backend-pass-through-needed)
-   [How Workday Audits Business Processes Initiated via REST or SOAP Web Services](https://kiweely.com/guides/workday-business-process-audit-trail-initiated-via-web-service)

### From the blog on Integrations and APIs

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

-   [Turning a Messy Client Spreadsheet into a Clean Workday EIB Load in One Conversation](https://kiweely.com/blog/messy-spreadsheet-to-workday-eib-load-with-ai)
-   [Workday REST API vs. SOAP Web Services: Why Setup Work Still Needs the Task Screen](https://kiweely.com/blog/workday-rest-api-vs-soap-coverage-gaps)
-   [Untangling Inherited Workday Studio Integrations: A Practical Modernization Playbook](https://kiweely.com/blog/untangling-inherited-workday-studio-integrations)

## 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.
