User profiles in Iterable contain various fields that Iterable uses for specific purposes. This document describes these fields and their meanings.
NOTES
- To view the fields on a user's profile, navigate to Audience > Contact Lookup.
- All user profile fields are case-sensitive and space-sensitive.
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.
emailListIds
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.
itblInternal
Various internal fields managed by Iterable.
itblDS
An object containing information related to Iterable AI.
Its brandAffinityLabel
field represents the contact's level of engagement
with your brand, as determined by Brand Affinity™.
profileUpdatedAt
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.
receivedSMSDisclaimer
Indicates whether or not the user has received an SMS message, from the current
Iterable project, that includes SMS opt-out instructions. Receiving opt-out
instructions in a proof will not set this field to true
.
signupDate
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
How the contact was created in Iterable (for example, API
or IMPORT
).
subscribedMessageTypeIds
An array of integers that represent the opt-in message types to which a contact has subscribed. Contacts 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
IMPORTANT
subscribedMessageTypeIds
is available only for accounts or projects for which
opt-in message types have
been enabled. To do so, contact your Iterable CSM.
unsubscribedChannelIds
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
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
Fields used for sending messages
When sending messages, Iterable relies on the fields described below.
WARNING
The specific names of these fields are important. For example, Iterable uses the
phoneNumber
field when sending SMS messages; it won't recognize phone_number
or PhoneNumber
.
devices
An array of objects, each representing a mobile device/mobile app combination for which a user can (or used to be able to) receive push notifications (silently or otherwise).
Each object in the devices
array contains the following fields:
applicationName
- A string that identifies the mobile app for which the user can receive push notifications.appPackageName
- The unique application identifier associated with your app (as specified by its developers). Different for iOS and Android.appVersion
- The version of your app running on the user's device.deviceId
- A randomly generated UUID for a user's device. Generated by Iterable and stored in local storage on the device, and in Iterable itself. When the user re-installs the app, a new one is created (we don't track a device across app reinstalls).endpointEnabled
- Indicates whether or not Iterable can send push notifications to this device. If a user prevents an app from displaying push notifications, but after the app has already registered its device token with Iterable, the app's code should disable the device in Iterable by callingPOST /api/users/disableDevice
. This setsendpointEnabled
tofalse
for this device, preventing Iterable from sending future push campaigns to it. If the app does not disable the device, Iterable will continue to send push campaigns to it. The user will never see those campaigns, but they'll still be counted in the campaign's total send count. To check if Iterable can send push notifications to a given device/app combination, check itsendpointEnabled
field. Iftrue
, Iterable can send push notifications to that device.identifierForVendor
- iOS only. An alphanumeric string that uniquely identifies a device to the app’s vendor. Unique to that device for that app developer.iterableSdkVersion
- The release version of the SDK. Numbers will differ by platform (iOS, Android, React Native), correspond with the release numbers on our Github pages (iOS, Android, React Native).localizedModel
- iOS only. the model of the device. For example: "iPhone", "iPad", "iPod Touch".model
- The model name of the device. Apple examples: "iPhone", "iPad", "iPod Touch". Android example - "sdk_gphone_x86_arm".notificationsEnabled
- whether or not push notifications are enabled on the device.platform
- The platform from which the device can receive push notifications. For example,APNS_SANDBOX
.platformEndpoint
- The specific address Iterable uses to reach the device by push notification.wsystemVersion
: The version number of the device's operating system.token
- A string Iterable uses to identify the device when sending it a push notification.userInterfaceIdiom
: iOS only. The device's category. For example: "Phone", "Pad", "carPlay".
TIPS
- 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
.
email
The contacts's email address. This is the primary way to identify Iterable users
(though userId
can also also be used for this purpose).
ip
The contact's IP address.
NOTE
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
, andtimeZone
fields on a user profile when itsip
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
A contact'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.
This field should be a two-letter ISO country code for the desired language, corresponding to a locale set up in the Locales section of Settings > Project Settings.
phoneNumber
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
The ID of a user for whom there is not a known email address (and has an Iterable-created placeholder email address instead).
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
, orPOST /api/commerce/updateCart
. In the request body, setpreferUserId
totrue
and specify auserId
(preferUserId
indicates that a new user should be created for thatuserId
, if one does not already exist).When creating a user with a
userId
, Iterable also assigns that user a fake email address (using theplaceholder.email
domain). For example, callingPOST /api/users/update
to create a user with auserId
ofuser123
also gives that user anemail
similar totestUser123+-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'semail
and theuserId
.
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.
WARNING
- Before assigning a
userId
, make sure that it's unique (isn't already associated with another user in the same Iterable project). Iterable doesn't checkuserId
values for uniqueness—you must do this manually. If you associate the sameuserId
with multiple users, Iterable cannot guarantee which contact theuserId
refers to. -
userId
values are not permanent. They can be overwritten by callingPOST /api/users/update
with the user'semail
and the newuserId
.
Other reserved field names
The following field names are reserved by Iterable, and you can't manually set them:
campaignId
channelId
eventName
messageTypeId
templateId
total
Also avoid using size
as a field name. You can do it, but referencing
such a field can be unreliable, since it sometimes references the
number of items in an object or array.
Common event fields
You'll often see the following fields on Iterable system events:
-
messageId
: A unique identifier for a particular send of a particular campaign to a particular user. -
contentId
: An ID associated with the specific template revision sent to the user for a campaign. -
catalogLookupCount
: The number of times a catalog was referenced in the message. -
catalogCollectionCount
: The number of times a catalog collection was referenced in the message.
Comments
0 comments
Please sign in to leave a comment.