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 identifier fields defined

There are two fields available to use as unique identifiers in Iterable: email and userId. When you make a project, you can choose one of these fields, or you can choose to use both (where at least one field is required for each new user and both fields are enforced as unique).

# email

The email field is defined as a user's email address. You can use this field as the unique identifier for your project instead of, or in addition to, the userId field.

Iterable validates each email address based on formatting—invalid email address formats aren't accepted (e.g., user @example.com). See Email Validation in Iterable for more information.

Iterable automatically uses this field as the recipient address when sending outbound emails—with exception to the placeholder.email domain addresses.

# userId

The userId field is 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.

Specifications for userId include:

• Maximum length of 52 characters
• Values are case sensitive
• Iterable will not generate values for this field—you must include it in your list imports and API requests.

# 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 (e.g., your CRM, or another integration that you rely on to store your user's data).
• Randomly generated universally unique identifiers (UUIDs)
  • UUID v4 is the most current version of this - learn more here.
• 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 (e.g.,10001, 10002, 10003 ... n+1)
  • Usernames or "handles"

# Available project types

There are three different schemas available to identify users:

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

The unique identifier for your project impacts how Iterable behaves in many scenarios. Here is a comparison of how each schema impacts your data:

	Email	User ID	Hybrid
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
Identify User in API requests	email or userId (more info)	userId	email or userId
Multiple users with same email	No	Yes	No
Contact lookup	email	userId	email or userId
Placeholder emails for anonymous users	Yes	No	No
GDPR forget	email	userId	email or userId

# Selecting a unique identifier

You'll 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 (e.g., CRM administrators) before creating your project in Iterable.

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

Will you typically have the email address for new users, or will 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, you can 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 will be the best choice for this!

# Impact in Iterable

Although Iterable works generally the same across all types of projects, there are some variances 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 each schema of unique identifiers.

# 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, a new user will be created 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}/user/{userId}
  • DELETE /api/subscriptions/{subscriptionGroup}/{subscriptionGroupId}/user/{userId}
  • PUT /api/subscriptions/{subscriptionGroup}/{subscriptionGroupId}?action=subscribe
• If userId only is passed (no email), and there is no matching user, Iterable will return an error. To avoid this and create a user without an email, include the parameter preferUserId with a value of true. This will add the user with an auto-generated false 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 cannot guarantee which user will be identified 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, you'll need to 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 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 will create 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}/user/{userId}
  • DELETE /api/subscriptions/{subscriptionGroup}/{subscriptionGroupId}/user/{userId}
  • PUT /api/subscriptions/{subscriptionGroup}/{subscriptionGroupId}?action=subscribe
• If an API request includes preferUserId, this parameter is ignored.
• If you try to use email to identify a user when making an API call, the request will return 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 will not 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 will create a new user.

Across Iterable

• When creating a new list, you'll need to specify a userId column, instead of an email column.
• Hosted Signup Forms are unavailable at this time.
• When previewing a template, use email or userId to populate sample data (no longer just email).
• Journey triggers can be tested by either userId or email (no longer just email).
• Iterable will not set a iterableEndUserId browser cookie, as this is becoming deprecated. This may impact your implementation of a custom subscription center and when tracking purchases and revenue.

# 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, you can 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, then userId will be used to look up the user.
• If userId and/or email are passed and there is no matching user, Iterable will create 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}/user/{userId}
  • DELETE /api/subscriptions/{subscriptionGroup}/{subscriptionGroupId}/user/{userId}
  • PUT /api/subscriptions/{subscriptionGroup}/{subscriptionGroupId}?action=subscribe
• If you are adding a user with an invalid email value, it will be rejected even if it has a userId included in the request.
• If an API request includes preferUserId, this parameter is 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 will not 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 will create a new user.

Across Iterable

• When creating a new list, you'll need to specify either a userId or an email column, at minimum, or you can upload a list with both columns.
• Hosted Signup Forms are available for static lists.
• When previewing a template, use email or userId to populate sample data (no longer just email).
• Journey triggers can be tested by either userId or email (no longer just email).
• Iterable will not set a iterableEndUserId browser cookie, as this is becoming deprecated. This may impact your implementation of a custom subscription center and when tracking purchases and revenue.

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