User Profile Fields Used by Iterable

User profiles in Iterable contain various fields that have predetermined definitions and formats, and are used by Iterable for specific purposes. This document describes these fields and their meanings.

# Table of contents

# Fields managed by Iterable

Iterable manages the fields described below. These fields are visible in the responses to various API calls, but (unless otherwise noted) they should not be included in calls to POST /api/users/update or other endpoints that update user profiles.

# createdAt

Each event stored on a user's Iterable profile has a createdAt field. This field indicates when the event occurred.

When creating an event by calling POST /api/events/track, it's possible to manually set this value to a given Unix timestamp. If you do not provide a createdAt value, Iterable uses the time at which it creates the event.

# emailListIds

emailListIds is an array of integers that represent the static lists to which a user is subscribed. The values in this array change as the user is added to or removed from lists. This array does not contain IDs for dynamic lists.

# profileUpdatedAt

profileUpdatedAt represents the most recent time at which a user's profile was updated (via CSV upload or API call). This field is a date, and it has the following format: 2016-08-02 18:53:45 +00:00. For more information, read Field Data Types.

# signupDate

signupDate contains the date when the user's profile was created in Iterable. This field is a date, and it has the following format: 2016-08-02 18:53:45 +00:00. For more information, read Field Data Types.

# signupSource

signupSource is a string that describes how the user entered the Iterable database (for example, API or IMPORT).

# subscribedMessageTypeIds

subscribedMessageTypeIds is an array of integers that represent the opt-in message types to which a user has subscribed.

Users will receive messages associated with opt-in message types only if both of the following are true:

• They have subscribed to those opt-in message types
• They have not unsubscribed from the channels associated with those types

# unsubscribedChannelIds

unsubscribedChannelIds is an array of integers that represent the message channels from which a user has unsubscribed.

Users will not receive messages from any message type belonging to a message channel from which they have unsubscribed.

# unsubscribedMessageTypeIds

unsubscribedMessageTypeIds is an array of integers that represent the opt-out message types from which a user has unsubscribed.

Users will receive messages from opt-out message types only if both of the following are true:

• They have not unsubscribed from those opt-out message types
• They have not unsubscribed from the channels associated with those types

# itblDS

itblDS is an object that contains fields related to Iterable AI. Its brandAffinityLabel field represents the contact's level of engagement with your brand, as determined by Brand Affinity™.

# Special fields

When sending messages, Iterable relies on the fields described below. To modify the values stored in these fields, use Iterable's API.

# devices

devices is an array of objects, each of which represents a mobile device/ mobile app combination on which a user can (or used to be able to) receive push notifications (silently or otherwise).

Each object in the array must include the following fields:

• platform: The platform from which the device can receive push notifications. For example, APNS_SANDBOX.
• token: A string Iterable uses to identify the device when sending it a push notification.
• applicationName: A string that identifies the mobile app for which the user can receive push notifications.

To add a device to this list (or re-enable one that is already there), call POST /api/users/registerDeviceToken.

To disable a device on the list, so that it will no longer receive messages, call POST /api/users/disableDevice.

To check if Iterable is set up to send push notifications to a given device/app combination, check its endpointEnabled field. If true, Iterable can send push notifications to that device.

# email

email is a string that represents the user's email address. This is the primary way to identify Iterable users, though userId can also be used for this purpose.

# ip

A user's IP address.

In Settings > Project Settings, two settings impact IP addresses and corresponding geo-location lookups:

• Enable User IP to Location Lookup: If enabled, Iterable populates the city, country, region, and timeZone fields on a user profile when its ip field is modified.

• Automatically Update IP in User Profile From Inbound Events: If enabled, Iterable saves the IP address received on inbound email click events (which can trigger another location lookup, depending on the previous setting).

Including ip or timeZone on a user profile allows Iterable to send messages with consideration to a user's local time.

# locale

locale represents's a user's language preference. If you have multiple versions of a template—all having the same templateId, but each one corresponding to a different locale—Iterable uses this field to determine which version to send to the user.

locale should be a string—the two-letter ISO country code for the desired language, corresponding to a locale set up in the Locales section of Settings > Project Settings.

# phoneNumber

phoneNumber is a string that represents the user's phone number. Iterable uses this number when sending SMS messages. It should have a format such as: 15552223333.

To learn more about sending SMS messages, read SMS Overview.

# userId

userId values are strings used to identify users. They provide a way to create and reference users who do not have a known email address, and instead have an Iterable-created placeholder email address.

Iterable does not automatically assign a userId to every user. To specify a userId, take one of the following approaches:

• Provide the userId when creating the user.

  To do this, use APIs such as POST /api/users/update, POST /api/users/registerDeviceToken, or POST /api/commerce/updateCart. In the request body, set preferUserId to true and specify a userId (preferUserId indicates that a new user should be created for that userId, if one does not already exist).

  When creating a user with a userId, Iterable also assigns that user a fake email address (using the placeholder.email domain). For example, calling POST /api/users/update to create a user with a userId of user123 also gives that user an email similar to user123+-147178873@placeholder.email.

  When sending email, Iterable automatically excludes placeholder.email addresses. For more information about placeholder email addresses, read Handling Anonymous Users.

• Assign a userId to an existing user.

  To do this, call POST /api/users/update. In the request body, provide the user's email and the userId.

When calling Iterable's APIs, reference users by email (whether placeholder or not) or userId, depending on which is supported by the endpoint in question. For more details about any particular endpoint, read Iterable's API documentation.

• A userId value can have a maximum length of 52 characters.

# Reserved field names

The following field names are reserved by Iterable:

• campaignId
• channelId
• eventName
• messageTypeId
• templateId
• total

Do not attempt to set them on a user profile, since Iterable will not do so.

Additionally, avoid using size as a field name. While it's possible to do so, referencing such a field can be unreliable, since it sometimes references the number of items in the current object or array.