Data types and attributes

This article provides information on the data types and attributes that you can specify when you make an API call to our platform.

Our platform accepts inputs to API calls in certain formats. You can use these formats as a guideline on what and how you can send values of the API calls that you make to our platform.

Data types

Our platform accepts the following formats for date, boolean and number data. Ensure that your data is sent to our platform in the format specified below. Deviating from this format leads to the data most likely getting stored as a string that limits:

  • Your ability to query the data in segmentation
  • Your ability to format the data when you send messages to your customers
Data typeFormatCorrect examplesIncorrect examples
DateISO 86012016-04-12T17:27:20+00:00

2016-04-12T17:27:20Z

20160412T172720Z
11/11/2011
BooleanLower case string of true or falsetrueTRUE

False
NumberNumbers without any spaces or other characters42$42
StringAny combination of charactersasdjhfakjhqwrwqwer#1234N/A

How to format a date input in the ISO 8601 format using JavaScript

If your system does not use ISO 8601 compliant dates, you can format them before sending an event:

var yourDate = new Date('11/11/2011');
var yourDateInISO8601 = yourDate.toISOString(); // "2011-11-11T08:00:00.000Z"

To avoid parsing ambiguous data and handle timezones, use momentjs:

var yourDate = '11/11/2011';
var yourDateInTimezone = moment.tz('11/11/2011','MM/DD/YYYY','America/New_York');
yourDateInTimezone.format(); // "2011-11-11T00:00:00-05:00"

Mobile attributes

This table describes the inputs to the attributes of an API call to our platform:

AttributeDescription
device_typeapple
android
windows
device_idUnique mobile device identifier, used to track user activity pre-sign up
device_tokensPush message device token (required for push messaging)
device_idfaiOS device identifier for advertiser
device_idfviOS device identifier for vendor
latitudeLocation latitude
longitudeLocation longitude
os_nameiOS
Android
os_versionOperating system version
For example, 6.1
network_carrierCarrier name
For example, Verizon

Data format

The data that you send to our platform has certain checks in place. When you make an API call to our platform with the data that you send, ensure that the data adheres to the following specifications.

User data

  • Ensure that the phone_number:
    • includes the country code
    • starts with a +
    • follows the E.164 standard, contains 6 to 14 digits, and does not start with a 0
  • An email must not have more than 256 characters. For an email address [email protected], the following email syntax is acceptable according to RFC standard:
    • The username can have a maximum of 64 characters and can consist of any combination of alphabetic characters, digits, or any of the following special characters: ! # $ % & ‘ * + – / = ? ^ _ ` . { | } ~
    • The topleveldomain can have a maximum of 63 characters, cannot be all numerics and cannot start or end with a hyphen.
    • The subdomain can have a maximum of 64 characters.
    • The domain (for example .com, .gov. .edu and so on) can have a maximum of 63 characters.
  • gender should be either male/female/unknown  
  • unsubscribed is true/false (lower case)
  • joined_at must be in ISO8601 format (1980-05-19T15:22:01-07:00).  You can also format in excel/numbers using custom format to convert to ISO8601 format yyyy-mm-ddThh:mm:ss+/-00:00. Replace +/-00:00 with the time zone offset for your timezone.  If you do not include joined_at during the API call, we will infer the API call data as the joined_at.
  • Dates should be in iso8601

Product/catalog data

  • At the very least, we need product id, product name, product url (http or https), image url (http or https) and category. However, we also recommend sending us brand, in/out of stock and other custom fields you may want to use in segmentation and messaging
  • We support multiple catalogs. However, product ids must be unique within and across all catalogs
  • You can set rules in the catalog settings to set a product as out_of_stock or in_stock by mapping your column to the Availability field
  • Alternatively, for each product, you can set "start_date" and "end_date" fields in the file. The expected format is ISO8601 for these two fields. Ex: "2017-08-08", "2017-08-08T17:42:32Z". We will use them to automatically set a product to out_of_stock if the current_date does not fall within that range.
  • We use INSERT/UPDATE logic to INSERT new products and UPDATE existing products as identified by SKU/product_ID.
  • Please use true or false (lower case) for boolean values
  • Please use snake case where possible, as it's much easier to use it in the templates.
    For example, "Release_Year" instead of "Release Year".
  • The value of the product_id field must not have more than 64 characters.
  • The title of the product must not have more than 255 characters.
  • The URL that you provide in the image field must not have more than 500 characters.
  • The URL that you provide in the web_url field must not have more than 500 characters. 

Event data

  • Ensure that event names do not contain periods, are not numeric, and the event name must not have more than 64 characters. 
  • In addition, the data format limitations on the user imports are applicable to event imports as well.