Timestamp

Timestamp attributes represent a single, universal moment in time using the ISO 8601 format. Time information is stored with nanosecond precision, and UTC is the assumed timezone if one is not provided. Timestamp values will always be returned in UTC.

Every Attio object has a created_at timestamp attribute, but users can also create their own custom timestamp attributes.

All timestamp attributes are single-select.

Reading values

Timestamp attributes have a single property, value (string).

{
  "active_from": "2023-04-03T15:21:06.447000000Z",
  "active_until": null,
  "created_by_actor": {...},
  "attribute_type": "date",
  "value": "2023-11-24T15:17:48.000000000Z"
}

Writing values

Input values will be coerced into the full format. UTC is assumed if not specified. For example, the following input values would all be coerced to "2023-01-02T13:00:00.000000000Z":

• "2023"
• "2023-01"
• "2023-01-02"
• "2023-01-02T13:00"
• "2023-01-02T13:00:00"
• "2023-01-02T13:00:00.000000000"
• "2023-01-02T15:00:00.000000000+02:00

To write timestamp attribute values, you should specify the value property:

You may also pass an object with a single property, value.

{
  "my_timestamp_attribute": "2019-01-17T15:17:48.000000000Z"
}

{
  "my_timestamp_attribute": [
    {
      "value": "2019-01-17T15:17:48.000000000Z"
    }
  ]
}

Filtering

Timestamp attribute values can be filtered by their value. Unlike when writing timestamp values, both date and time components must be specified.

You can filter for an exact timestamp using the implicit syntax, or use the $eq,$gt,$gte,$lt,$lte operators with the explicit syntax.

{
  "filter": {
    "created_at": "2023-11-24T15:34:07.111222333Z"
  }
}

{
  "filter": {
    "created_at": {
      "value": {
        "$gte": "2000-01-01T00:00:00Z"
      }
    }
  }
}

Since timestamps are stored with nanosecond precision, it is often undesirable to look for an exact timestamp if you're trying to filter records with a lower precision, e.g. in a given hour or day. Here, you should use two operators to set the upper and lower bounds of the query, remembering to use the inclusive $gte for the earlier bound and the exclusive $lt for the upper bound:

{
  "filter": {
    "created_at": {
      "$gte": "2023-11-24T08:00:00Z",
      "$lt":  "2023-11-24T09:00:00Z
    }
  }
}

{
  "filter": {
    "created_at": {
      "$gte": "2023-11-24T00:00:00Z",
      "$lt":  "2023-11-25T00:00:00Z
    }
  }
}