Iterable automatically creates and maintains some field on each user's profile. In most cases, these fields do not need to be edited by the client, and there's no need to include them when updating a user's profile. All of these fields are case sensitive and space sensitive.
The following fields will be ignored by Iterable (i.e. no changes will be made to the field value) if passed in a user update call:
Using the name
size (at the top level or as part of an object) is not
recommended because even though you will be able to set the value of that
field, referencing it in a template may be unreliable as
sometimes reference an internal value equal to the number of fields in the
current object context.
Fields that Iterable manages
These fields do not need to be included in any updates to the user profile, nor should they be overwritten.
userId values are strings used to identify users. They provide a way to
create and reference users who do not have known email addresses.
Iterable does not automatically assign a
userId to every user. To specify a
userId, take one of the following approaches:
userIdwhen creating the user.
To do this, use APIs such as
POST /api/users/registerDeviceToken, or
POST /api/commerce/updateCart. In the request body, set
trueand specify a
preferUserIdindicates 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.emaildomain). For example, calling
POST /api/users/updateto create a user with a
user123also gives that user an
When sending email, Iterable automatically excludes
placeholder.emailaddresses. For more information about placeholder email addresses, read Handling Anonymous Users.
userIdto an existing user.
To do this, call
POST /api/users/update. In the request body, provide the user's
When calling Iterable's APIs, reference users by
userId, depending on which is supported by the endpoint in
question. For more details about any particular endpoint, read Iterable's
userId value can have a maximum length of 52 characters.
- 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 check
userIdvalues for uniqueness—you must do this manually. If you associate the same
userIdwith multiple users, Iterable cannot guarantee which contact the
userIdvalues are not permanent. They can be overwritten by calling
POST /api/users/updateand providing the user's
profileUpdatedAt is the date the user profile was last updated, either via
CSV upload or API call. The data type is Date and the format looks like
"2016-08-02 18:53:45 +00:00". For more information, read
Field Data Types.
signupDate is the date when the user profile was created in Iterable.
The data type is date, and the format looks like
2016-08-02 18:53:45 +00:00.
For more information, read Field Data Types.
signupSource is how the user entered the Iterable database. Includes
IMPORT. The data type is string.
emailListIds is an array of integers, each representing a static list to
which the user belongs. The values in this array change as a user is added
or removed from lists.
emailListIds includes only static list IDs, not dynamic list IDs.
unsubscribedChannelIds is an array of integers, each representing a channel
to which the user has unsubscribed. Users will not receive messages
associated with types belonging to channels from which they have
unsubscribedMessageTypelIds is an array of integers, each representing a
message type from which the user has unsubscribed. Users will receive
messages from opt-out message types only if they have not unsubscribed
from those types or their associated channels.
subscribedMessageTypelIds is an array of integers, each representing a
message type to which the user has subscribed. Users will receive messages
associated with opt-in message types only if they have subscribed to those
types and have not unsubscribed from the channels associated with those
subscribedMessageTypeIds is only available if your account or project
has enabled the opt-in message types
feature. To enable it, contact your Iterable CSM.
createdAt indicates a timestamp of when the event was indexed into
Iterable. This field can be updated via API, though one thing to note is the
value will need to be in Unix timestamp, instead of an ISO-formatted string.
All of these fields are case sensitive and space sensitive. For example,
phone_number will add a separate field to your users' profiles; it will not
allow Iterable to send SMS to them.
phoneNumber is the phone number of the user, used to send SMS messages. The
data type is String and the format looks like
16503926753. To learn more
about SMS requirements, read
devices is an array of objects of the user's devices, used for push
notifications. Each object in the array must include at least the following
To learn more about push notifications, read Sending Push Notifications.
This field must be added by calling the
ip is included on a user profile, Iterable will, by default, add and
update fields on the user profile for
timeZone. These fields can be edited if desired, but Iterable will update
and overwrite them if
ip is updated, which can happen when a user opens or
clicks on an email. This setting can be adjusted by going to
Settings > Project Settings. These fields are all strings.
timeZone will allow messages to be sent at a user's local time.
ip can also be automatically added to the user profile by Iterable if you
toggle on Automatically Update IP in User Profile from Inbound Events
in Settings > Project Settings. We will detect the user's ip from email
click events and add it to the user profile.
locale is used to represent which language preference a person should
receive when send a message. You can create multiple versions of a template,
one for each locale, while maintaining the same
templateId. The value of
locale should be a string, and should be the
two-letter ISO country code
for the language desired. These will correspond to the options you add to the locales
section of your project's settings.