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 key | Description |
---|---|
Expiry | expires using a date and time format; or expiresInterval using a duration format |
Embargo | embargo 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 & Time | Syntax |
---|---|
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 UTC | 2021-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]
YYYY
uses all four numeralshh
uses a 24 hour clockT
precedes the time portionZ
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
Interval | Syntax |
---|---|
1 Month | P1M |
2 Weeks | P2W |
3 Days | P3D |
4 Hours | PT4H |
5 Minutes | PT5M |
55 Seconds | PT55S |
7 months and 9 minutes | P7MT9M |
Half a year | P0.5Y |
1 hour 45 minutes | PT1H45M |
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