Field Data Types

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.

# 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.

# 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 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": "docs@iterable.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": "docs@iterable.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": "docs@iterable.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": "docs@iterable.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": "docs@iterable.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": "docs@iterable.com",
    "dataFields": {
        "work_geo_location": {
            "lat": 41.505493, 
            "lon": -81.681290
        }
    }
}

# 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": "docs@iterable.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.

# 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": "docs@iterable.com",
    "dataFields": {
        "favoriteFoods": [
            "Pizza",
            "Bánh mì",
            "Ramen"
        ]
    }
}