This article explains different values and data types for fields and events in Iterable and examples of what those types of data would look like as they are passed into Iterable.
NOTE
Data types (string, boolean, double, etc.) cannot be changed for user and
event fields once set. API calls (POST /api/users/update
and POST /api/events/track
)
that attempt to set or update an existing field with a value that cannot be
coerced into the appropriate type will fail.
Data types and segmentation
Each field in a user profile or event in Iterable has a value type: string, date, integer, long, double, or boolean. Iterable also supports arrays, objects, and geo_location values, but these must be added and updated via API calls and not through CSV uploads.
Different types of data can be segmented differently in Iterable, so its important to consider which value type you would like each field to be before you cast that data type in Iterable.
For instance, you can create age
as a field and cast it as a string the
first time the field is sent to Iterable. The data type of a field is listed
underneath each field in Audience > Segmentation.
In this case, the segmentation tool would treat the field as a string:
If a user wanted to use segmentation options given to an integer field, like the image below (such as Less Than or Greater Than), it wouldn't be possible since the field has already been cast as a string.
User field data types can also be found in Settings > Project Settings.
WARNING
Once a field is cast, the value type cannot be overwritten. Thus, it is important to set the right data type when creating fields in Iterable for the first time.
The best practice for casting the right data type of fields is to add them via API calls.
API data type examples
Below is a description of each value type and an example of how a field of
that type would look in a sample payload as it is passed into Iterable using
the POST /api/users/update
or POST /api/commerce/updateCart
API endpoint.
String
If the field is not already cast, CSV imports will automatically cast all fields as strings. Strings can contain both characters and numbers. If the field already exists in the environment, then the CSV import will match the data type of the user profile field.
When setting a string value with Iterable's API, surround its value in quotes.
The following request body for the POST /api/users/update
endpoint sets the user's first name to Justin
:
{ "email": "user@example.com", "dataFields": { "firstName": "Justin" } }
Date
A date field is a specific type of string in Iterable. Fields that are dates have many uses for segmentation in Iterable, like relative dates and date ranges. Iterable has a specific date format that must be used to segment a field by date.
Acceptable date formats include:
-
yyyy-MM-dd HH:mm:ss ZZ
2000-01-01 00:00:00 -04:00
-
yyyy-MM-dd HH:mm:ss
2000-01-01 00:00:00
-
yyyy-MM-ddTHH:mm:ss.SSSZZ
2000-01-01T00:00:00.000-04:00
-
yyyy-MM-dd
2000-01-01
The following request body for the POST /api/users/update
endpoint sets the date for the lastCartUpdateDate
field:
{ "email": "user@example.com", "dataFields": { "lastCartUpdateDate": "2015-02-03 01:20:55 +00:00" } }
Long
Longs are numbers that do not have decimal points.
The following request body for the POST /api/users/update
endpoint sets the user profile's age
field:
{ "email": "user@example.com", "dataFields": { "age": 26 } }
Boolean
True or false. Acceptable boolean values include true
and false
.
The following request body for the POST /api/users/update
endpoint sets the user profile's hasCat
field:
{ "email": "user@example.com", "dataFields": { "hasCat": false } }
Double
Doubles are numbers that have decimal points.
The following request body for the POST /api/commerce/updateCart
endpoint sets an item's price
field to a double:
{ "user": { "email": "user@example.com" }, "items": [ { "id": "123", "sku": "123", "name": "XL Pizza", "description": "Piping hot and delicious", "categories": [ "food", "pizza" ], "price": 24.99, "quantity": 1 } ] }
geo_location
A geo_location field stores a location's latitude and longitude.
The name of any field that stores a geo_location value must have a
_geo_location
suffix.
The geo_location object may only contain two fields: lat
(the latitude)
and lon
(the longitude). Do not put other fields in this object.
For example, the following request body for the POST /api/users/update
endpoint creates a work_geo_location
field on the user's profile:
{ "email": "user@example.com", "dataFields": { "work_geo_location": { "lat": 41.505493, "lon": -81.681290 } } }
NOTES
- Iterable's segmentation tool cannot perform geolocation queries (proximity, etc.). However, catalog items can contain geo_location values, and collections can use geolocation queries to compare them to the values stored on a user's profile.
- When defining a geo_location field on a catalog item, there is no need to
use the
_geo_location
suffix. The suffix only applies to geo_location values stored on user profiles and custom events.
Objects
Objects are collections of related fields. For example, to represent the various attributes of a cat, use an object.
The following request body for the POST /api/users/update
endpoint creates a cat
object on a user's profile:
{ "email": "user@example.com", "dataFields": { "cat": { "name": "Snowball", "color": "White", "age": 4, "favoriteToy": "Fluffy stick" } } }
Iterable's segmentation tool displays objects with a period between the name
of the object and the name of the field being referenced. For example, the
tool would represent the field for the above cat's name as cat.name
.
NOTE
Objects can be edited with API calls (not CSV uploads).
Arrays
Arrays are lists of objects. Arrays can contain objects, and arrays can belong to objects. For example, to represent a user's list of favorite foods, use an array.
The following request body for the POST /api/users/update
endpoint creates a favoriteFoods
array on a user's profile:
{ "email": "user@example.com", "dataFields": { "favoriteFoods": [ "Pizza", "Bánh mì", "Ramen" ] } }
NOTE
Arrays can be edited with API calls (not CSV uploads).
Comments
0 comments
Please sign in to leave a comment.