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.
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.
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
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
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.
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
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
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
, 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
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
, 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 touser123+-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
and providing the user'semail
and the newuserId
.
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.
Comments
0 comments
Please sign in to leave a comment.