Project Types and Unique Identifiers

Every Iterable project uses a specific field to uniquely identify each user. This allows an individual record to be referenced without confusion. When you create a new project, Iterable offers the ability to choose email and/or userId as unique identifiers for your users. This selection has a lasting impact on how your project works and how you access data via API.

Continue reading to learn more about unique identifiers in Iterable, the different project types available, and how to determine the best setting for your project.

# In this article

# Unique identifiers

Each user in an Iterable project must have a unique identifier, which depends on the project type:

• email, in email-based projects
• userId, in userID-based projects
• Both fields, in hybrid projects

# email

The email field is stores a user's email address.

Iterable validates email addresses by format. Invalid email address formats, such as user @example.com (with a space), aren't accepted. For more info, read Email Validation in Iterable.

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

# userId

The userId field can contain any unique value that you assign. You can use this field as the unique identifier for your project instead of, or in addition to, email (depending on your project type).

userId specifications:

• Maximum length of 52 characters
• Case-sensitive
• Iterable doesn't generate values for this field. You must include the value when creating users.

# What makes a good user ID?

Information that we use in our daily lives to identify each other (such as our names) doesn't quite translate as unique when that information enters a database. Many people share the same first and/or last names, and dates of birth, for example—and these are also considered PII (personally identifiable information). Fields such as these would be poor choices to identify users as unique due to security concerns and lack of true uniqueness.

Ideally, user ID values are static (unchanging), not guessable, and meaningless outside of the context where it is used.

Here are some good options for your userId field values:

• The same ID field you use to identify your user in your application—assuming it meets these best practices.

• The same ID field as another, primary system of record (such as your CRM, or another integration that you rely on to store your user's data).

• Randomly generated universally unique identifiers (UUIDs). Learn more.

• Other database-generated IDs.

Practices to avoid:

• Anything that is considered PII (personally identifiable information)

• Any values that may be guessable, such as:

  • Formulas based off of PII information
  • Sequential values (10001, 10002, 10003 ... n+1)
  • Usernames or "handles"

# Project types

Iterable provides three different kinds of project, and they identify users in different ways.

• Email-based - Uses email as a unique identifier.
• UserID-based - Uses userId as a unique identifier.
• Hybrid - Uses email and userId as unique identifiers.

A project's unique identifier affects how Iterable behaves, in various ways. Here is a comparison of how each schema impacts your data:

	Email-based projects	UserID-based projects	Hybrid projects
Unique identifier	email	userId	email and userId (at least one of these fields is required)
email uniqueness?	Unique	Non-unique	Unique
userId uniqueness?	Non-unique	Unique	Unique
How to identify users in API requests?	email or userId	userId	email or userId
Multiple users with same email?	No	Yes	No
Contact lookup by...	email	userId	email or userId
Does Iterable assign "placeholder" email addresses to anonymous users?	Yes	No	No
GDPR forget by...	email	userId	email or userId
EUDC support	No	Yes	Yes

# Selecting a unique identifier

Select your project type at the time you create it:

Because the unique identifier project setting has implications across your data platforms and you can’t change it later, consult with your development teams and other interested stakeholders (such as CRM administrators) before creating your project in Iterable.

Here are some questions to guide which project type to select:

Do you typically have the email address for new users, or do you need to track anonymous users?

If your primary focus is on email marketing and you collect new users via their email addresses, then an email-based project might make the most sense.

If your organization needs to track anonymous users or other user types that don't need to provide an email, a userID-based project is a more logical choice and serves as an alternative to creating a placeholder email (see Handling Anonymous Users for more information on this).

If you find that your organization needs to maintain email uniqueness (one email per user), yet also keep track of anonymous users, then choosing a hybrid project could be the best option for you.

Do you need to support multiple users who have the same email address, or single users who have multiple accounts?

The only project type that supports multiple users sharing the same email address is the userID-based project.

Do you have other data systems that manage users with a generated unique ID field?

You can use the unique identifier values from another data system (such as your CRM) as the userId field in Iterable in all project types. However, uniqueness for the userId field is only enforced in userID-based projects and hybrid projects.

Do you want to use userId as a primary identifier, but also need to ensure that every user's email address is unique?

For this scenario, create a hybrid project to require both fields to be unique.

Do you need to avoid using email as a parameter in your API requests?

A userID-based project is the best choice for this!

# Impact in Iterable

Although Iterable works generally the same across all types of projects, there are some differences in the data required to create new users, complete GDPR forget requests, and more.

Read on to learn the variances across Iterable when you use different project types.

# Email-based projects

API Behavior

You can pass email and/or userId in requests to identify users. When you do this, the following occurs:

• If both fields are present, email is prioritized to identify the user, and the userId field is updated/overwritten for most requests that use PUT or POST methods.

• If email is passed and there is no user with that email address, Iterable creates a new user when using the following endpoints:

  • POST /api/email/target
  • POST /api/inApp/target
  • POST /api/users/update
  • POST /api/users/bulkUpdate
  • POST /api/users/updateSubscriptions
  • POST /api/users/bulkUpdateSubscriptions
  • POST /api/users/registerDeviceToken
  • POST /api/users/registerBrowserToken
  • POST /api/lists/subscribe
  • POST /api/commerce/trackPurchase
  • POST /api/commerce/updateCart
  • PATCH /api/subscriptions/{subscriptionGroup}/{subscriptionGroupId}/user/{userEmail}
  • DELETE /api/subscriptions/{subscriptionGroup}/{subscriptionGroupId}/user/{userEmail}
  • PATCH /api/subscriptions/{subscriptionGroup}/{subscriptionGroupId}/byUserId/{userId}
  • DELETE /api/subscriptions/{subscriptionGroup}/{subscriptionGroupId}/byUserId/{userId}
  • PUT /api/subscriptions/{subscriptionGroup}/{subscriptionGroupId}?action=subscribe

• If userId only is passed (and not email), and there is no matching user, Iterable returns an error. To avoid this and create a user without an email, include the parameter preferUserId with a value of true. This creates the user with an auto-generated placeholder email address using the @placeholder.email domain. For more information about placeholder email addresses, read Handling Anonymous Users.

• Uniqueness for userId is not enforced, so it's possible to create more than one user with the same userId. When the same userId is associated with multiple users, Iterable can't guarantee which user is updated when making requests based off userId only. To avoid this, make sure that a userId isn't already in use before you add or update a user with this value.

• To process a GDPR request to forget a user, use the email field with the POST /api/users/forget endpoint.

• Tracking events for an unknown user does not create a new user.

Across Iterable

• When creating a new list, specify an email column.

• Hosted Signup Forms are available for static lists.

• When previewing a template, use email to populate sample data.

• Journey triggers can be tested with email only.

• This is the only project type that creates a iterableEndUserId browser cookie (which will be deprecated at a future date). This may impact your implementation of a custom subscription center and when tracking conversions, purchases, and revenue.

# UserID-based projects

API Behavior

When your project identifies by userId only, this field is always required.

Things to know about interacting with the API for these projects:

• If you are making an API request to any endpoint that uses a unique identifier, the userId field must always be present & unique, and these policies are enforced.

• If userId is passed and there is no matching user, Iterable creates a new user when using the following endpoints:

  • POST /api/users/updateEmail
  • POST /api/events/track
  • POST /api/events/trackBulk
  • POST /api/events/trackWebPushClick
  • POST /api/events/trackPushOpen
  • POST /api/events/trackInAppOpen
  • POST /api/events/trackInAppClick
  • POST /api/events/trackInAppDelivery
  • POST /api/events/trackInAppClose
  • POST /api/workflows/triggerWorkflow
  • POST /api/email/target
  • POST /api/inApp/target
  • POST /api/users/update
  • POST /api/users/bulkUpdate
  • POST /api/users/updateSubscriptions
  • POST /api/users/bulkUpdateSubscriptions
  • POST /api/users/registerDeviceToken
  • POST /api/users/registerBrowserToken
  • POST /api/lists/subscribe
  • POST /api/commerce/trackPurchase
  • POST /api/commerce/updateCart
  • PATCH /api/subscriptions/{subscriptionGroup}/{subscriptionGroupId}/user/{userEmail}
  • DELETE /api/subscriptions/{subscriptionGroup}/{subscriptionGroupId}/user/{userEmail}
  • PATCH /api/subscriptions/{subscriptionGroup}/{subscriptionGroupId}/byUserId/{userId}
  • DELETE /api/subscriptions/{subscriptionGroup}/{subscriptionGroupId}/byUserId/{userId}
  • PUT /api/subscriptions/{subscriptionGroup}/{subscriptionGroupId}?action=subscribe

• When an API request includes the parameter preferUserId, it's ignored.

• If you try to use email to identify a user when making an API call, the request returns an error. You can only identify users with userId.

• You aren't required to provide an email for every user you upload to Iterable. Placeholder email addresses aren't necessary.

• Iterable doesn't enforce email uniqueness. In other words, many users can have the same email address.

• To process a GDPR request to forget a user, use the userId with the POST /api/users/forget endpoint.

• Tracking events for an unknown user creates a new user.

Across Iterable

# Hybrid projects

API Behavior

When your project is set up to use both email and userId as unique identifiers, the following applies:

• If you are making an API request to any endpoint that uses a unique identifier, use either the email or userId to find a user.

• Both email and userId fields must be unique, and this policy is enforced.

• If an API request includes both email and userId, Iterable looks up the user by their userId.

• If userId and/or email are passed and there is no matching user, Iterable creates a new one when using the following endpoints:

  • POST /api/users/updateEmail
  • POST /api/events/track
  • POST /api/events/trackBulk
  • POST /api/events/trackWebPushClick
  • POST /api/events/trackPushOpen
  • POST /api/events/trackInAppOpen
  • POST /api/events/trackInAppClick
  • POST /api/events/trackInAppDelivery
  • POST /api/events/trackInAppClose
  • POST /api/workflows/triggerWorkflow
  • POST /api/email/target
  • POST /api/inApp/target
  • POST /api/users/update
  • POST /api/users/bulkUpdate
  • POST /api/users/updateSubscriptions
  • POST /api/users/bulkUpdateSubscriptions
  • POST /api/users/registerDeviceToken
  • POST /api/users/registerBrowserToken
  • POST /api/lists/subscribe
  • POST /api/commerce/trackPurchase
  • POST /api/commerce/updateCart
  • PATCH /api/subscriptions/{subscriptionGroup}/{subscriptionGroupId}/user/{userEmail}
  • DELETE /api/subscriptions/{subscriptionGroup}/{subscriptionGroupId}/user/{userEmail}
  • PATCH /api/subscriptions/{subscriptionGroup}/{subscriptionGroupId}/byUserId/{userId}
  • DELETE /api/subscriptions/{subscriptionGroup}/{subscriptionGroupId}/byUserId/{userId}
  • PUT /api/subscriptions/{subscriptionGroup}/{subscriptionGroupId}?action=subscribe

• If you are adding a user with an invalid email value, it is rejected even if it has a userId included in the request.

• When an API request includes the parameter preferUserId, it's ignored.

• You aren't required to provide an email for every user you upload to Iterable—placeholder email addresses aren't necessary.

• You aren't required to provide a userId for every user, however Iterable doesn't create one when the value is missing.

• To process a GDPR request to forget a user, you can use either email or userId with the POST /api/users/forget endpoint.

• Tracking events for an unknown user creates a new user.

Across Iterable

# Checking the Unique Identifier for a Project

Most projects created prior to November 2022 use the email field as the unique identifier, however if you're unsure then it's wise to check first.

To do this, go to Settings > Project Settings and see the identifier(s) underneath the project's cluster ID.

You can also go to Audience > Contact lookup to see which field(s) are used for your project—you can only search by unique identifier(s) here.