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.
NOTE
Currently, there's no way to change the unique identifier for an existing project. You can only make this selection when creating a 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
anduserId
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.
NOTES
Limitations when selecting a project type:
Email-based projects have limited availability.
Iterable doesn't support multiple email addresses or phone numbers for a single user.
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.
NOTE
Currently, there's no way to change the unique identifier for an existing project. You can only make this choice when creating a project.
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"
WARNING
You can edit values in the userId
field.
Values stored in the userId
field are not permanent in Iterable. They can be
overwritten or changed. Learn more at Updating a User's Email Address or User ID.