Dates and times
This page explains how the API writes dates and times, and how to read them.
What do dates look like?
Section titled “What do dates look like?”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:
curl \ -H "Authorization: Bearer sdeu_key_EXAMPLE_ONLY_NOT_A_REAL_KEY" \ https://api.example.com/v1/cases/example-case-1How do I read a date and time?
Section titled “How do I read a date and time?”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.Zmeans 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:00JavaScript:
const moment = new Date("2026-11-15T14:03:22-08:00");console.log(moment.toISOString()); // 2026-11-15T22:03:22.000ZHow do I read a date only?
Section titled “How do I read a date only?”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-15means 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 15JavaScript:
const [year, month, day] = "2026-11-15".split("-").map(Number);console.log(year, month, day); // 2026 11 15