User Profile Fields Used by Iterable

User profiles in Iterable contain various fields that Iterable uses for specific purposes. This document describes these fields and their meanings.

# In this article

# Fields used as unique identifiers

Each user in an Iterable project must have a unique identifier. Two fields are available in Iterable to uniquely identify users: email and userId. When you create your project, you will choose a project type. The project type determines which field(s) you can use to identify your users. It also impacts how you manage records in Iterable.

For more information, see Project Types and Unique Identifiers. For information about how these fields are used with Iterable’s APIs, see Creating and Identifying Users with Iterable APIs.

# Identifying users by email

These considerations apply for email-based projects (and hybrid projects that include the email field as a unique identifier):

• Iterable validates that the value in this field is an accepted format — invalid formats, such as user @example.com (with a space) aren't accepted. For more information, read Email Validation in Iterable.

• When sending email, Iterable automatically uses email as the recipient address, unless it's automatically generated for an anonymous user (@placeholder.email).

• You can use this field as the unique identifier for users in your project instead of, or in addition to, userId (depending on your project type).

• Each user's email must be unique.

# Identifying users by userId

The userId field stores a unique value that you've assigned to identify each user.

Iterable enforces the following requirements for the value of the userId field in all project types:

• Must be non-empty. Blank, null, or empty values are not accepted in requests to identify users.

  API requests with a userId lookup field that is blank, null, or empty are rejected. Instead, if a user doesn't have a userId value, such as in a hybrid project, use the email field to identify the user and don't include a blank userId field in the API request.

  API requests for email-based and hybrid projects that include userId with a null value in dataFields with intention to clear the data from a user profile are still accepted.

• Maximum length of 128 characters.

• Must not contain non-printable ASCII characters, such as non-breaking spaces and soft hyphens.

  Non-printable characters are typically created programmatically and aren't visible printed characters. Not to be confused with space, tab, or other whitespace characters, or with hard hyphen (also called a minus sign).

• Must not end with a space.

• Values are case-sensitive.

• Iterable doesn't generate values for this field. You must include the value when creating users.

• Values should not contain PII, such as an email or phone number.

• In userID-based and hybrid projects, each user's userId must be unique. Iterable enforces unique values.

• In email-based projects, unique values for userId are not required or enforced. In the event the same userId is associated with multiple users, there are some important considerations. To learn more, read Identifying users by userId in email-based projects

# 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 of which a user is a member. 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.

This field applies to email-based projects only. For userId and hybrid projects, Iterable uses userListIds.

# itblInternal

A collection of various internal fields managed by Iterable.

# itblInternal.phoneCountry

A two-letter code that represents the country associated with the user's phoneNumber, as defined by ISO-3166.

When you send an SMS campaign to a user, Iterable checks to see if the user has itblInternal.phoneCountry set. If it isn't set, Iterable uses phoneNumber to look up the ISO-3166 country code, and adds that country code to the user's profile.

Currently, this field is only used for reporting purposes, and is not used to determine a user's language or system actions related to a user's country.

# 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™. Its predictiveGoals field provides user conversion scores for goals that are created in Iterable's Predictive Goals.

# itblUserId

A unique identifier used internally by Iterable for hybrid and userID-based projects. Using this field to reference a user is NOT recommended. Instead, use userId, which is a field that you can access and manage.

# 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

# 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

# userListIds

An array of integers that represent the static lists of which a user is a member. 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.

This field applies to userId and hybrid projects. For email-based projects, Iterable uses emailListIds.

# Fields used for sending messages

When sending messages, Iterable relies on the fields described below.

# devices

A nested data type that contains 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 calling POST /api/users/disableDevice. This sets endpointEnabled to false 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 its endpointEnabled field. If true, 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.

• systemVersion: 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".

# email

A user's email address.

This field is validated. To learn more, see Email Validation in Iterable.

This is one of two possible fields that uniquely identify Iterable users, along with userId. To continue learning about the email field, unique identifiers, and how they work, read Project Types and Unique Identifiers

# ip

The contact's IP address.

# locale

A user's location and/or language preference. If you have multiple locale variants of a template (all with the same templateId), Iterable uses this field to determine which version to send to the user.

This field maps to the codes you set up in the Locales section of your Project Settings page.

# phoneNumber

A string that represents the user's phone number. Iterable uses this number when sending SMS messages.

Values must be formatted using E.164. For example:

• US: +14155550132
• Germany: +498999998000

When you send an SMS to the user, Iterable checks to see if the user has itblInternal.phoneCountry set. If it doesn't, Iterable uses phoneNumber to look up and add the value to the user's profile.

Iterable doesn't send SMS campaigns to users without a phoneNumber set.

# profile

To avoid confusion, do not use profile as a field name in your user profiles.

# userId

The ID of a user. This is always a value which you've either assigned or imported from another source.

This is one of two possible fields that uniquely identify Iterable users, along with email. To continue learning about the userId field, unique identifiers, and how they work, see our guide Project Types and Unique Identifiers

# 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.

# Want to learn more?

For more information about some of the topics in this article, check out this Iterable Academy course. Iterable Academy is open to everyone — you don't need to be an Iterable customer!

• Foundations: Setting Up Senders