> For the complete documentation index, see [llms.txt](https://developer.kizen.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.kizen.com/docs/concepts/objects/custom-fields/date-field-types.md).
# Date Field Types
{% hint style="success" %}
**Audience:** Admins, Developers, Solution Architects
**Purpose:** Explains how `date` and `datetime` fields capture temporal data and helps administrators, solution architects, and developers select the appropriate field type when designing space.vars.object schemas.
{% endhint %}
## Overview
Date field types are structured fields used to capture temporal data such as deadlines, milestones, scheduled events, historical timestamps, and operational triggers. These fields support reporting, space.vars.automations, sorting, filtering, and time-based workflows across the platform.
Selecting the appropriate date field type is a foundational schema decision that affects how data is stored, interpreted, and operationalized. The level of time precision required should guide your choice.
Date-based data is commonly used to:
* Trigger space.vars.automations
* Schedule activities
* Track service timelines
* Support reporting windows
* Monitor operational progress
space.vars.Kizen\_company\_name currently supports two date field types:
* `date`**:** captures a calendar date only
* `datetime`**:** captures both the calendar date and the exact time an event occurs or is planned to occur
`datetime` fields capture timezone-aware timestamps. `date` fields capture only the calendar date; when evaluated in time-based logic or comparisons, they are interpreted as midnight in the configured business timezone.
Understanding how timezones, storage formats, and precision affect these fields is essential when designing scalable space.vars.object schemas.
### Key Differences
The table below summarizes the core differences between `date` and `datetime` fields.
| Capability | Date | DateTime |
| ------------------------------------------------------------ | ------------ | ---------------------------------------------------------------- |
| Stores time | No | Yes |
| Precision | Day-level | Records a millisecond-precise timestamp with timezone. |
| space.vars.automation Timing | Date-based | Time-based |
| Scheduling suitability | Limited | Ideal |
| API format | `YYYY-MM-DD` | [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) with timezone |
{% hint style="info" %}
**Note:** If timing affects execution, choose `datetime`. If it does not, choose `date`.
{% endhint %}
***
## Date
The `date` field captures a calendar date without an associated time value. This field is ideal when the exact time of day is irrelevant and would introduce unnecessary complexity into reporting or space.vars.automation logic.
### Common Use Cases
Use the `date` field when tracking:
* Contract start or renewal dates
* Birthdays or anniversaries
* Billing cycles
* Project milestones
* Compliance deadlines
* Processes that do not require time-of-day precision
* Reporting based on full calendar days
* space.vars.automations triggered relative to a date rather than a specific timestamp
* space.vars.automations that run at a consistent time on the selected day
Using a `date` field instead of `datetime` can simplify filtering and reduce schema complexity. Because no timestamp is stored, the value represents the entire calendar day.
### Behavior and Storage
When updating a `date` field through the API, values must be provided using the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format:
```
YYYY-MM-DD
```
#### Example of ISO 8601 Format
```
2026-10-21
```
If a field value is left blank, it is typically omitted from API responses when retrieving a space.vars.entity.
***
## DateTime
The `datetime` field captures both the calendar date and the exact time an event occurs, enabling precise operational workflows. This field is essential when the moment an event happens directly impacts space.vars.automation, scheduling, or reporting accuracy.
### Common Use Cases
Use the `datetime` field when:
* Scheduling meetings or activities
* Logging event timestamps
* Triggering time-sensitive space.vars.automations
* Monitoring response or resolution times
* Event timing must be exact
* space.vars.automations depend on a precise trigger moment
* Scheduling accuracy is required
* Analytics rely on timestamp granularity
Avoid using `datetime` when only the calendar day matters, as unnecessary precision can complicate filtering and reporting.
### Behavior and Storage
`datetime` values must be provided in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format and include a timezone designator (`Z` for UTC or an explicit offset such as `-0500`).
```
YYYY-MM-DDTHH:MM:SSZ
```
#### Example of ISO 8601 Format
```
2026-10-21T05:15:04Z
```
In the UI, time inputs are presented in 15-minute increments for consistency; however, the field can store any valid time value provided through the API.
### Timezone Interpretation
Each business defines a primary timezone that is used in system-driven contexts where user timezone is unavailable, such as space.vars.automations, reports, and emails. When user context exists, timestamps are presented relative to the user’s local timezone while the underlying value remains consistent for processing and reporting.
However, the API also accepts values with an explicit timezone offset for the `datetime` field type:
```
2024-10-09T05:00:00-0500
```
All timestamps are serialized with timezone information to prevent ambiguity across regions.
***
## Additional Information
Schema Design Best Practices
When working with temporal data:
* Select the lowest level of precision necessary
* Align fields with automation requirements early in schema design
* Ensure timezone expectations are clearly defined for distributed teams
* Avoid mixing `date` and `datetime` fields for the same operational purpose
Thoughtful planning prevents reporting inconsistencies and automation errors.
***
## What’s Next
Review field-specific documentation before implementing schema changes to ensure the selected field type supports your space.vars.automation, reporting, and integration requirements. Continue designing your schema with the following resources:
Related Topics
* [Selection Field Types](/docs/concepts/objects/custom-fields/selection-field-types.md)
* [Numerical Field Types](/docs/concepts/objects/custom-fields/numerical-field-types.md)
* [Text Field Types](/docs/concepts/objects/custom-fields/text-field-types.md)
* [Communication Field Types](/docs/concepts/objects/custom-fields/communication-field-types.md)
* [Special Field Types](/docs/concepts/objects/custom-fields/special-field-types.md)
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://developer.kizen.com/docs/concepts/objects/custom-fields/date-field-types.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.