Project Types and Unique Identifiers

Every Iterable project uses a specific field (email and/or userId) to uniquely identify each user. This allows an individual record to be referenced without confusion. This selection has a lasting impact on how your project works and how you access data via API.

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

# In this article

# Project types

In Iterable, you define a project type by specifying which field to use to identify users.

• Hybrid projects use email and userId as unique identifiers.
• UserID-based projects use userId as a unique identifier.
• Email-based projects use email as a unique identifier. (Limited availability: Only certain accounts have the option to create new email-based projects - learn more.)

Select your project type when you create it — you can't change this setting later.

For information about creating and managing projects, see Projects Overview.

# Comparing project types

Let's compare how different project types handle your data when creating and identifying users.

	Hybrid projects	UserID-based projects	Email-based projects
Unique identifier	email and userId (at least one of these fields is required)	userId	email
Enforce email uniqueness?	Yes	No	Yes
Enforce userId uniqueness?	Yes	Yes	No
How to identify users in API requests	email or userId	userId	email or userId
Contact lookup by...	email or userId	userId	email
Static subscription list field	userListIds	userListIds	emailListIds
"Placeholder" email addresses assigned to anonymous users	No	No	Yes
Signup form support	Yes	No	Yes
GDPR forget by...	email or userId	userId	email
EDC support	Yes	Yes	No

# Choosing a project type

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.

Consider these points when choosing a project type:

• UserID-based projects may be best when you need to...

  • Track anonymous users (see Handling Anonymous Users).
  • Support multiple users with the same email address, or single users with multiple accounts.
  • Avoid using email as a parameter in your API requests.

• Hybrid projects allow you to...

  • Maintain email uniqueness (one email per user) and keep track of anonymous users.
  • Use userId as a primary identifier while ensuring that every user's email address is unique.

# Project type availability

Originally, all Iterable projects identified users by email address. However, for greater flexibility and to encourage best practices in data management and privacy, Iterable introduced userID-based and hybrid projects. These projects can identify users by userId and/or email, depending on your data needs.

All Iterable accounts can create userID-based and hybrid projects. However, email-based projects can only be created by Iterable accounts that meet all of the following criteria:

• Organizations that are hosted in Iterable's USDC-based data center.
• Organizations that were created before May 28, 2024.
• Organizations that have created an email-based project since May 28, 2023.

If your Iterable account doesn't meet these criteria, and you need to identify users by email, create a hybrid project.

# 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
• Either field, in hybrid projects

To learn about the email and userId fields and their data requirements, see User Profile Fields Used by Iterable.

To learn about how each field is handled across Iterable in the API, see API Overview and Sample Payloads.

# Checking the unique identifier for a project

To check the unique identifier(s) for your project, you can:

• Go to Settings > Project Settings and see the identifiers underneath the project's cluster ID.

• Go to Audience > Contact Lookup and see which fields you can search for. You can only find users by unique identifiers here.

# Creating a good user ID

Iterable doesn't generate values for the userID field—if you're using it in a project (especially if it's your unique identifier), you must include a value for it when you create users. It's important to understand what makes a good user ID.

Information that we use in our daily lives to identify each other doesn't translate as unique when it enters a database—many people share the same first or last names, and dates of birth, for example. And, this type of information is also considered PII (personally identifiable information), so is generally a poor choice for identifying 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 userId field values:

• The same ID field you use to identify a 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 unique IDs.

Practices to avoid:

• Anything that is considered personally identifiable information (or PII), such as:

  • Names
  • Email addresses
  • Phone numbers
  • Dates of birth

• Any values that may be guessable, such as:

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