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 type

Format

Correct examples

Incorrect examples

Date

ISO 8601

2016-04-12T17:27:20+00:00

2016-04-12T17:27:20Z

20160412T172720Z

11/11/2011

Boolean

Lower case string of true or false

true

TRUE

False

Number

Numbers without any spaces or other characters

42

$42

String

Any combination of characters

asdjhfakjhqwrwqwer#1234

N/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:

Attribute

Description

device_type

apple
android
windows

device_id

Unique mobile device identifier, used to track user activity pre-sign up

device_tokens

Push message device token (required for push messaging)

device_idfa

iOS device identifier for advertiser

device_idfv

iOS device identifier for vendor

latitude

Location latitude

longitude

Location longitude

os_name

iOS
Android

os_version

Operating system version
For example, 6.1

network_carrier

Carrier 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 64 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.

Did this page help you?