Overview

Your organisation's timezone setting affects how dates are handled on the Root platform, including the API, data imports, and the Root dashboard. Before changing your organisation's timezone, make sure you understand how it will impact your organisation on the platform. To change your organisation timezone follow this guide.

How dates are stored on Root

Standard date fields (excluding date of birth fields) on Root are converted and stored in UTC using the ISO 8601 date-time format. This means that standard date fields will always be returned in UTC when fetched or exported from Root. The date format for configurable fields, such as those in the quote module object, is determined by your product module code.

📘

Date conversion example

API request body

JSON

{
  "date": "2022-12-15T00:00:00+02:00"
}

API response body

JSON

{
  "date": "2022-12-14T22:00:00Z"
}

How timezones impact your organisation

API endpoints

Standard (non-configurable) endpoints

When making requests to the Root platform's standard (non-configurable) endpoints, any dates included in the request will be converted to ISO 8601 date-time format and converted to UTC.

If the timezone offset is not explicitly included in the date input, the timezone offset is assumed to be the organisation's timezone before being converted to UTC. If the timezone offset is explicitly included in the date input, the supplied timezone offset is used instead of the organisation's timezone.

📘

Date conversion example

For an organisation with a timezone of Africa/Johannesburg the timezone offset is UTC+2.
Date inputs will be converted as follows:

API request body

JSON

{
  "date_without_offset": "2022-12-15",
  "date_with_offset": "2022-12-15T00:00:00-05:00"
}

API response body

JSON

{
  "date_without_offset": "2022-12-14T22:00:00Z",
  "date_with_offset": "2022-12-15T05:00:00Z"
}

Configurable endpoints

For configurable endpoints, how the date is converted is configured in the validation hooks in the product module code using the joi library. Please refer to the validation and dates section in the product module code guide to find the tools you can use to convert dates for configurable endpoints like the quote endpoint, configured in the quote hook.

Root Dashboard

Date inputs

Date inputs for standard (non-configurable) endpoints are always converted using the organisation's timezone, regardless of the timezone configured on your user account.

Date inputs for configurable endpoints are converted based on the validation hooks in the product module code using the joi library. Please refer to the validation and dates section in the product module code guide to find the tools you can use to convert dates for configurable endpoints like the quote endpoint, configured in the quote hook.

Date display

Dates on the Root dashboard are displayed in either the user's or organisation's timezone, with the former taking precedence. If the user has not configured a timezone, dates will be displayed in the organisation's timezone. If you are only concerned with the timezone that dates are displayed on the dashobard you can update your account timezone by following this guide. Updating your account timezone won't affect how platform handles dates.

Data imports

The data imports tooling allows you to import bulk data including policies, policyholders, payments and claims. When dates for standard fields are included in an import the date is converted using the organisation timezone unless the date explicitly includes the timezone offset.