Skip to main content

Working with dates

Date and time reference

API request payloads may include details to either expire the card, or set an embargo for publishing. These details are optional.

For all dateTimes, we use the ISO 8601 format. This guide provides a summary of the standardisation, and practical examples to use with your API request payloads.

The following formats and properties are supported:

Request keyDescription
Expiryexpires using a date and time format; or expiresInterval using a duration format
Embargoembargo using the date and time format

Dates & Times Format

Use date and time format within event metadata; for expiring cards using expires, or to embargo a card using embargo.

Examples

Date & TimeSyntax
25th December 2020, at 9:10.11am, in the UTC + 13 timezone
(Auckland standard)
2020-12-25T09:10:11+13:00
1st Jan 2021, at 7:18pm UTC2021-01-01T19:18:00Z
7 March 2022, at 7:01am in the UTC + 10 timezone
(Sydney standard)
2022-03-07T07:01:00+10:00

Notation

  • Format: [YYYY]-[MM]-[DD]T[hh]:[mm]:[ss][TZ]
    • YYYYuses all four numerals
    • hh uses a 24 hour clock
    • T precedes the time portion
    • Z at the end can be used to represent UTC ( zero offset )
    • Add an offset from UTC, for example −05:00 for New York standard time; +00:00 for London; +11:00 for Melbourne or +13:00 for Auckland.
    • Use zero padding for months, days, hours, minutes, and seconds.
    • For ease of readability, use hyphens between date values, and colons between time values.

Duration Format

Use duration format for expiring a card using expiresInterval, set a default card snooze time or specify a snooze period for a snooze button.

Examples

IntervalSyntax
1 MonthP1M
2 WeeksP2W
3 DaysP3D
4 HoursPT4H
5 MinutesPT5M
55 SecondsPT55S
7 months and 9 minutesP7MT9M
Half a yearP0.5Y
1 hour 45 minutesPT1H45M
6 years, 5 months, 4 days, 3 hours,
2 minutes, and 1 second
P6Y5M4DT3H2M1S

Notation

  • Format: P[n]Y[n]M[n]DT[n]H[n]M[n]S
    • P (“period”) precedes the duration representation.
    • Y is the years designator.
    • M is the month designator.
    • W is the week designator.
    • D is the day designator.
    • T (“time”) precedes the time components (hours, minutes, seconds) of the representation.
    • H is the hour designator.
    • M is the minute designator.
    • S is the second designator.
  • Leading zeros are not required
  • Date and time elements may be omitted if their value is zero