Date Field Types
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 Object schemas.
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, automation, 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 automations
Schedule activities
Track service timelines
Support reporting windows
Monitor operational progress
Kizen currently supports two date field types:
date: captures a calendar date onlydatetime: 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 Object schemas.
Key Differences
The table below summarizes the core differences between date and datetime fields.
Stores time
No
Yes
Precision
Day-level
Records a millisecond-precise timestamp with timezone.
Automation Timing
Date-based
Time-based
Scheduling suitability
Limited
Ideal
Note: If timing affects execution, choose datetime. If it does not, choose date.
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 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
Automations triggered relative to a date rather than a specific timestamp
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 format:
Example of ISO 8601 Format
If a field value is left blank, it is typically omitted from API responses when retrieving a Record.
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 automation, scheduling, or reporting accuracy.
Common Use Cases
Use the datetime field when:
Scheduling meetings or activities
Logging event timestamps
Triggering time-sensitive automations
Monitoring response or resolution times
Event timing must be exact
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 format and include a timezone designator (Z for UTC or an explicit offset such as -0500).
Example of ISO 8601 Format
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 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:
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
dateanddatetimefields 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 automation, reporting, and integration requirements. Continue designing your schema with the following resources:
Last updated
Was this helpful?