---
category: [Administration & Integrations, Administration & Integrations/Workday API, Platform and Product Extensions, Platform and Product Extensions/Integration]
nav: wcp_docs
parent_url: /wcp_docs/
title: >- 
  Concept: Workday REST API Date, Time, and Time Zone Handling
layout: subsection
---

Workday REST APIs support dates, datetimes, and datetimes with time zones.

## Dates

Request and response `date` fields:

-   Don’t have a time component or time zone offset.
-   Uses the format yyyy-mm-dd.
-   Can use the same format as a datetime but without a time component or time zone offset.


## Datetimes

In general, the date request fields in the POST, PATCH, and PUT endpoints of the Workday REST APIs that don't require the time zone are `dateTime` fields.

Request `dateTime` fields:

-   Must use the ISO 8601 format.
-   Can specify any time zone offset from Coordinated Universal Time (UTC).

    Example: This dateTime is in UTC with -0700 offset. This dateTime value is equivalent to 2023-07-25T16:43:15.000 (PDT).

    ```
    "dateTime" : "2023-07-25T16:43:15.000-0700"
    ```

-   Must have minutes and seconds in the time component. Seconds can have an optional fraction.

    <b>Note:</b> The time value `24:00` is not a valid time value for midnight. To represent midnight, use `23:59` instead.



Response `dateTime` fields:

-   Use the ISO 8601 format.
-   Use the Coordinated Universal Time (UTC) with no offset.

    Example:

    ```
    "dateTime": "2023-07-25T23:43:15.000Z"
    ```



## Datetimes and Time Zones

Some Workday REST APIs that require the time zone use `dateTimeZone` fields.

Request `dateTimeZone` fields:

-   Must always contain the `timeZone` and `dateTime` fields. Example:

    ```
    {
      "dateTimeZone": {
            "timeZone": "US/Eastern",
            "dateTime": "2023-11-02T10:00:00.000" 
        }
    }
    ```

    The `timeZone` field:

    -   Is required.
    -   Supports all the [Standard Time Zone Names](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
    -   Defaults to the GMT time zone and applies offset accordingly, if the given `timeZone` is invalid. If you've opted in to the Workday 32 - Time Zones feature and don't use an ISU, then Workday uses the user's local time zone.

    The `dateTime` field:

    -   Is required.
    -   Must use the [ISO 8601 date and time formats](https://www.w3.org/TR/NOTE-datetime).
    -   Precision must be in milliseconds of format YYYY-MM-DDTHH:mm:ss.SSSTZD.

        Examples:

        ```
        "2023-11-02T10:00:00.000" 
        "2023-11-02T10:00:00.000-0700"
        "2023-11-02T10:00:00" 
        ```

        <b>Note:</b> The time value `24:00:00` is not a valid time value for midnight. To represent midnight, use `23:59:59` instead.

    -   If given, the time zone offset in the `dateTime` field must be in <b>+/- HHmm or HH:mm</b> format.

        Example: -0800 or -08:00

        The request throws an exception if the `timeZone` doesn’t match the given offset in `dateTime`. If `dateTime` doesn’t include an offset, the request uses the `timeZone` offset.




Response `dateTimeZone` fields:

-   Always include the `timeZone` and `dateTime` fields.

    Example:

    ```
    {
      "dateTimeZone": {
            "timeZone": "US/Eastern",
            "dateTime": "2023-11-02T10:00:00.000-0400" 
    }
    ```

-   The `timeZone` uses the [Standard Time Zone Name](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones), as specified in the request.
-   The `dateTime` includes the offset using the format <b>+/- HHmm</b>, which matches the `timeZone` in the request.


## Examples: date and dateTime

<table><thead><tr><th>Datetime or Date Format</th><th>Example</th><th>Description</th></tr></thead><tbody><tr><td>YYYY-MM-DDThh:mm:ss.fffZ</td><td>2013-02-26T19:06:57.493Z</td><td><code>dateTime</code> with zero offset from UTC. <ul><li>fff represents a fractional second.
</li><li>T indicates a time.
</li><li>Z indicates zero offset.
</li></ul></td></tr><tr><td>YYYY-MM-DDThh:mm:ss.fff-hh:mm</td><td>2014-04-15T19:06:57.493-08:00</td><td><code>dateTime</code> with a time zone offset of -08:00 hours from UTC.</td></tr><tr><td>YYYY-MM-DDThh:mm:ss.fff+hh:mm</td><td>2014-04-15T19:06:57.493+03:30</td><td><code>dateTime</code> with a time zone offset of +03:30 hours from UTC.</td></tr><tr><td>YYYY-MM-DD</td><td>2014-02-26</td><td><code>date</code></td></tr></tbody></table><br/>

<b>Note:</b> For an example REST API call that displays a date and a datetime, see [Reference: Inbox Tasks](/wcp_docs/dan1370797988967.html).

## Examples: dateTimeZone

<table><thead><tr><th>Use cases</th><th>Request</th><th>Response</th></tr></thead><tbody><tr><td><p>Non-UTC <code>dateTimeZone</code> with offset</p> <p>Example: 02 November 2023 10:00 am US/Eastern</p></td><td>```
"dateTimeZone": {
         "timeZone": "US/Eastern",
         "dateTime": "2023-11-02T10:00:00.000-0500"  
}
```

</td><td>```
"dateTimeZone": {
        "timeZone": "US/Eastern",
        "dateTime": "2023-11-02T10:00:00.000-0500"
}
```

</td></tr><tr><td><p>Non-UTC <code>dateTimeZone</code> without offset</p> <p>Example: 02 November 2023 10:00 am US/Eastern</p></td><td>```
"dateTimeZone": {
         "timeZone": "US/Eastern",
         "dateTime": "2023-11-02T10:00:00.000"  
}
```

</td><td>```
"dateTimeZone": {
         "timeZone": "US/Eastern",
         "dateTime": "2023-11-02T10:00:00.000-0500" 
}
```

</td></tr><tr><td><p>UTC <code>dateTimeZone</code> without offset</p> <p>Example: 02 November 2023 10:00 am US/Eastern</p></td><td>```
"dateTimeZone": {
         "timeZone": "UTC",
         "dateTime": "2023-11-02T10:00:00.000" 
}

 
```

</td><td>```
"dateTimeZone": {
         "timeZone": "UTC",
         "dateTime": "2023-11-02T10:00:00Z" 
}
```

</td></tr></tbody></table><br/>

The occurrence of DayLight Savings is a special use case that handles date and time zone where there’s an overlap of time. Example: Consider PDT to PST, 5th Nov 2023 1:30 am occurs twice (PDT ends and PST starts.) Both offsets -0800 and -0700 are acceptable during the special hour. When the request includes the offset during the special hour, the response returns the same offset. Otherwise, if the request doesn’t contain the offset during this hour, the response returns the earlier offset. In this case, the response defaults to -0700. These examples illustrate the Daylight Savings for PDT/PST:

<table><thead><tr><th>Use cases</th><th>Request</th><th>Response</th></tr></thead><tbody><tr><td><p><code>dateTime</code> includes -0700 offset</p></td><td>```
"dateTimeZone": {
         "timeZone": "America/Los_Angeles",
         "dateTime": "2023-11-05T01:30:00.000-0700"
}
```

</td><td>```
dateTimeZone": {
         "timeZone": "America/Los_Angeles",
         "dateTime": "2023-11-05T01:30:00.000-07:00" 
}
```

</td></tr><tr><td><p><code>dateTime</code> includes -0800 offset</p></td><td>```
"dateTimeZone": {
         "timeZone": "America/Los_Angeles",
         "dateTime": "2023-11-05T01:30:00.000-0800" 
}
```

</td><td>```
"dateTimeZone": {
         "timeZone": "America/Los_Angeles",

    "dateTime": "2023-11-05T01:30:00.000-0800
" 
}
```

</td></tr><tr><td><p><code>dateTime</code> without offset</p></td><td>```
"dateTimeZone": {
         "timeZone": "America/Los_Angeles",
         "dateTime": "2023-11-05T01:59:00.000" 
}
```

</td><td>```
"dateTimeZone": {
         "timeZone": "America/Los_Angeles",
         "dateTime": "2023-11-05T01:59:00.000-07:00"
}
```

</td></tr><tr><td><p><code>dateTime</code> without offset</p></td><td>```
"dateTimeZone": {
         "timeZone": "America/Los_Angeles",
         "dateTime": "2023-11-05T02:00:00.000-0800" 
}
```

</td><td>```
"dateTimeZone": {
         "timeZone": "America/Los_Angeles",
         "dateTime": "2023-11-05T02:00:00.000-08:00"
}
```

</td></tr></tbody></table><br/>