Skip to content
Draft. The API described here is not released yet, and nothing on this site has been tested against it. Details may change.

Dates and times

This page explains how the API writes dates and times, and how to read them.

The API uses two formats. Both are ISO 8601 formats, sent as text in the JSON.

Kind of value Format Example
A moment in time (a date and a time) YYYY-MM-DDThh:mm:ss and the offset from UTC 2026-11-15T14:03:22-08:00
A date only, with no time YYYY-MM-DD 2026-11-15

The API uses a date-only value when only the day matters, and not the time.

You get these values when you read data, for example a case:

Terminal window
curl \
-H "Authorization: Bearer sdeu_key_EXAMPLE_ONLY_NOT_A_REAL_KEY" \
https://api.example.com/v1/cases/example-case-1

A date and time always ends with its offset from UTC. Read the offset. Do not assume a time zone.

Example What it means The same moment in UTC
2026-11-15T14:03:22-08:00 2:03:22 PM, 8 hours behind UTC 2026-11-15T22:03:22Z
2026-07-15T09:30:00-07:00 9:30:00 AM, 7 hours behind UTC 2026-07-15T16:30:00Z

The offset can be different from one value to the next, for example in winter and in summer. So:

  • Do not cut off the offset. Without it, the time is wrong.
  • Do not replace the offset with Z. Z means UTC, which is a different moment.
  • To compare two moments, convert both to UTC first, or use a date library that reads the offset.

Python 3:

from datetime import datetime, timezone
moment = datetime.fromisoformat("2026-11-15T14:03:22-08:00")
print(moment.astimezone(timezone.utc).isoformat()) # 2026-11-15T22:03:22+00:00

JavaScript:

const moment = new Date("2026-11-15T14:03:22-08:00");
console.log(moment.toISOString()); // 2026-11-15T22:03:22.000Z

A date-only value is a day on the calendar. It has no time and no time zone. Keep it as a date.

  • Do not add a time or a time zone to it. The value 2026-11-15 means that day, wherever you are.
  • Be careful in JavaScript. new Date("2026-11-15") reads the date as midnight UTC. In a time zone behind UTC, that shows as the day before. Keep the text as it is, or split it into year, month and day.

Python 3:

from datetime import date
day = date.fromisoformat("2026-11-15")
print(day.year, day.month, day.day) # 2026 11 15

JavaScript:

const [year, month, day] = "2026-11-15".split("-").map(Number);
console.log(year, month, day); // 2026 11 15