Home
Documentation
Start typing to search…

Timezone Technical Implementation (For API Users)

Working with Multi-Timezone Fields

The Multi-Timezone feature in Knack ensures that datetime values are handled consistently across different timezones. This is achieved by storing all datetime data in Coordinated Universal Time (UTC) and converting it to the user's local timezone for display. This document explains how to work with multi-timezone fields when using the Knack API.

How Multi-Timezone Works

Data Storage and Conversion

Knack processes datetime values bidirectionally to ensure data integrity:

  • Incoming Data (User to UTC): When a user submits a datetime value in their local timezone, the server converts it to UTC before storing it in the database.
  • Outgoing Data (UTC to User): When the server retrieves a UTC datetime value from the database, it converts it to the user's local timezone before sending it in the API response.

This process ensures that all datetime data is stored in a consistent format (UTC), preventing data corruption due to timezone differences.

Timezone Detection

The system uses the following methods, in order of priority, to identify the user's timezone:

  1. HTTP Header: knack-client-timezone (This is the primary method for all Next-Gen apps).
  2. Query Parameter: client_timezone (This is a legacy method and should not be used for new applications).

Using the API with Multi-Timezone Apps

When working with a multi-timezone enabled app, you must include the knack-client-timezone header in all your API requests. This ensures that all datetime values are correctly converted to and from UTC.

headers: {
  'knack-client-timezone': 'America/New_York'
}

Valid Timezone Values:

You must use IANA timezone identifiers (e.g., "America/New_York", "Europe/London"). A comprehensive list of valid timezone names can be found in the standard timezone database. If the header is missing or contains an invalid value, the system will fall back to using the application's default timezone.

Date/Time Field Processing

Input Format Handling

The Knack API intelligently processes various datetime formats:

  • ISO 8601 with Timezone Offset: If you send a properly formatted ISO 8601 timestamp with a timezone offset (e.g., 2025-09-01T16:00:00+03:00) or in UTC format (e.g., 2025-09-01T15:00:00.000Z), no further conversion is performed, as the timezone is already specified.

  • Relative Format: If you send a datetime string without timezone information (e.g., 09/01/2025 10:00 pm), the system interprets it based on either the knack-client-timezone header (if provided) or the application's default timezone (if the header is not provided).

API Response Format

API responses for multi-timezone enabled apps include a comprehensive set of timestamp information to ensure clarity and ease of use:

{
  "date": "01/15/2024",
  "date_formatted": "01/15/2024",
  "hours": "02",
  "minutes": "30",
  "am_pm": "PM",
  "unix_timestamp": 1705334200000,
  "iso_timestamp": "2024-01-15T19:30:00.000Z",
  "timestamp": "01/15/2024 02:30 PM",
  "time": 870
}

Practical Examples

Scenario: App in Madrid, User in London

Let's consider a scenario where the Knack application's timezone is set to Europe/Madrid, and the user making the API request is in London, so they provide the knack-client-timezone: Europe/London header.

App Settings:

  • Knack app timezone: Europe/Madrid
  • User header: knack-client-timezone: Europe/London

Example 1: ISO Format with Offset

  • Input: 2025-09-01T16:00:00+03:00
  • Stored in DB (UTC): 2025-09-01T13:00:00.000Z
  • User sees: 09/01/2025 02:00 pm (London time)

Example 2: UTC Format

  • Input: 2025-09-01T15:00:00.000Z
  • Stored in DB (UTC): 2025-09-01T15:00:00.000Z
  • User sees: 09/01/2025 04:00 pm (London time)

Example 3: Relative Format

  • Input: 09/01/2025 10:00 pm
  • Stored in DB (UTC): 2025-09-01T21:00:00.000Z (Interpreted as London time)
  • User sees: 09/01/2025 10:00 pm (London time)

Without the Timezone Header

When no knack-client-timezone header is provided, the system falls back to the application's default timezone.

  • Input: 09/01/2025 10:00 pm
  • Stored in DB (UTC): 2025-09-01T20:00:00.000Z (Interpreted as Madrid time)
  • User sees: 09/01/2025 10:00 pm (Madrid time - app default)

Best Practices

To ensure a smooth experience when working with multi-timezone fields, please follow these best practices:

  • Always Include the Timezone Header: For consistency and predictability, always include the knack-client-timezone header in every API request.
  • Use Standard IANA Timezone Identifiers: Stick to the standard IANA timezone names to avoid errors. A list of valid identifiers can be found on the official IANA website.
  • Plan for Fallbacks: In scenarios where the user's timezone cannot be detected, the system will default to the application's timezone. Ensure your application's default timezone is set appropriately for your primary business operations.

Troubleshooting

Common Issues

API Timezone Errors

If you encounter timezone-related errors when making API requests, check the following:

  • Verify the header name: Ensure you are using the correct header name: knack-client-timezone.
  • Validate the timezone format: Confirm that you are using a valid IANA timezone identifier (e.g., "America/New_York", not "EST").
  • Check for typos: Double-check for any typos in your timezone identifier.

Data Inconsistencies

If you notice inconsistencies in datetime values, consider the following:

  • All data is stored in UTC: Remember that all datetime data is stored in UTC in the database. Variations in display values across different timezones are expected and normal.
  • Verify input formats: Ensure that your input datetime formats are being processed correctly by the system.
  • Daylight Saving Time: Be aware of daylight saving time transitions in your timezone, as these can affect datetime conversions.

Updated November 2025

Updated 2 days ago