Articles in this section

Creating and Identifying Users with Iterable APIs

The steps for creating and identifying users with Iterable’s APIs vary, depending on the type of project you’re using and the way you identify users. This article describes how to create users with the Iterable API for email-based, userID-based, and hybrid projects.

For more information about the relationship between project types and the way you choose to identify users in a project, read Project Types and Unique Identifiers.

In this article

Email-based projects

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

Email-based project behavior across Iterable

  • Lists must include 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.

  • Static list subscriptions are stored in the emailListIds field.

NOTE

This is the only type of project where Iterable 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.

Identifying users in email-based projects

Generally, API requests should identify specific users by email or userId, but not both, at the top level (outside of dataFields). If a request does include both fields, precedence rules apply.

For example, consider this request to POST /api/users/update:

{
   "email": "user@example.com",
   "userId": "user1234567",
   "dataFields": {
      "favoriteColor": "red"
   }
}

In an email-based project, email takes precedence, since it's guaranteed to be unique. So, for this request, in an email-based project, Iterable looks up or creates a user with email address user@example.com. Then, it sets their favoriteColor to red.

Creating new users in email-based projects

To create a new user and assign them a unique email address in an email-based project, make a request to one of the various endpoints that can create new users in one of these ways:

  • Update user data (individually or in bulk)
  • Target users with email and in-app campaigns
  • Update subscription information
  • Update the shopping cart and track purchases
  • Register device and browser tokens

For example, you can call POST /api/users/update with a request body such as:

{
  "email": "user@example.com",
  "dataFields": {
    "favoriteColor": "red"
  }
}

For this request:

  • If your project doesn't yet have a user with an email address of user@example.com, Iterables creates one.

  • Then, whether the user is new or already exists, Iterable sets their favoriteColor to red.

Creating new users when email is unknown

To create a new user for someone with an unknown email address (in an email-based project), provide a userId instead of an email.

For example, you can call POST /api/users/update. In the request, body:

  • Don't include an email.
  • Include a unique userId (one that doesn't yet exist in the Iterable project).
  • Set preferUserId to true, which tells the API to create a new user if the provided userId doesn't yet exist in the project.

For example:

{
  "userId": "user1234567",
  "preferUserId": true,
  "dataFields": {
    "favoriteColor": "red"
  }
}

For this request:

  • If your project doesn't have a user with a userId of user1234567, Iterable creates one.

  • Since this is an email-based project, Iterable assigns the user a unique email with a @placeholder.email domain. This is just a unique identifier, not a way to contact the user.

  • Then, whether the user is new or already exists, Iterable sets the user's favoriteColor to red.

In subsequent API calls, you can identify this user by their userId, or by the placeholder email given to them by Iterable.

Assigning a userId to an existing user

In an email-based project, you can assign a userId to an existing user who is already identified by email by making an API call to POST /api/users/update.

To learn more about how to do this, read Updating a User's Email Address or User ID.

UserID-based projects

TIP

UserID-based is often the most sensible type of project to choose, because it:

  • Is simple to use. You always identify users by userId.
  • Allows you to match Iterable userId values with user identifiers you use in other systems.
  • Allows multiple users to share the same email address, which can sometimes be useful.

UserID-based projects identify users by userId. In these projects, email is not a user identifier. You can assign email addresses to your users (just like you can assign any other field, like favoriteColor), but you can't use email to look up or modify users (in Iterable's web UI or when making API calls). Because email is just like any other field, multiple users can have the same email address.

It's important to know the following things about interacting with the API for userID-based projects:

UserID-based project behavior across Iterable

  • When creating a new list, 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.

  • Journey triggers can be tested with email or userID.

  • Iterable doesn't set a iterableEndUserId browser cookie.

  • To identify users when you create a custom subscription center, pass userId as a URL parameter using the following Handlebars in the hosted unsubscribe URL project setting:

    {{userId}}

  • To identify users when tracking conversions, purchases, and revenue, add a URL parameter with a Key of userId and Value of:

    {{userId}}

  • When a user unsubscribes from a link in an email (emailUnSubscribe, hostedUnsubscribeClick, or emailComplaint event), Iterable attributes the unsubscribe to the user's unique userId, not the email address that received the message. This is important when you have users who share an email address.

  • Static list subscriptions are stored in the userListIds field.

  • When sending a proof to an unknown email address (including when sending a proof "to myself" for the first time), Iterable creates a new user and automatically assigns a userID with the value itbl_generated_ (where the email address is part of the userId).

    TIP

    To look up users by email address in a userID-based project, use the segmentation tool and segment by the contact property email.

Identifying users in userID-based projects

In a userID-based project, userId is the only valid user identifier, and it's guaranteed to be unique. So, for the following request to POST /api/users/update, in a userID-based project, Iterable looks up or creates a user with a userId of user1234567. Then, it sets their favoriteColor to red.

{
   "email": "user@example.com",
   "userId": "user1234567",
   "dataFields": {
      "favoriteColor": "red"
   }
}

As a convenience for this request, Iterable also sets the user's email to user@example.com. However, since email is not a user identifier in userID-based projects, the API does not verify its uniqueness. In this scenario, Iterable could possibly create two users with different userId values and the same email.

Creating new users in userID-based projects

In userID-based projects, when you make an API request that includes a userId not yet used by your project, some endpoints create new users:

  • Update user data (individually or in bulk)
  • Target users with email and in-app campaigns
  • Update subscription information
  • Update the shopping cart and track purchases
  • Register device and browser tokens
  • Track events (individually or in bulk)
  • Trigger workflows

NOTE

In API calls to userID-based projects, the API ignores the preferUserId parameter that's sometimes used in API calls to email-based projects. There's no need to include this parameter.

For example, call POST /api/users/update, with a request body such as:

{
  "userId": "user1234567",
  "dataFields": {
    "favoriteColor": "red"
  }
}

For this request:

  • If there's no user with userId set to user1234567, Iterable creates one.
  • Whether the user is new or already exists, Iterable sets their favoriteColor to red.

Assigning email in userID-based projects

You may assign an email to each user in a userID-based project, but it's not a required field and isn't used to identify unique users.

NOTE

Since email is not a required field in userID-based projects, Iterable does not automatically assign @placeholder.email addresses like it does in email-based projects.

To do this, call POST /api/users/update, with a request body such as:

{
  "userId": "user1234567",
  "dataFields": {
    "email": "user@example.com"
  }
}

For this request:

  • If there's no user with userId set to user1234567, Iterable creates one.

  • Whether the user is new or already exists, Iterable sets their email to user@example.com.

    NOTE

    In userID-based projects, Iterable does not enforce email uniqueness. This allows you to give the same email to many users in the same project, which can sometimes be useful.

Hybrid projects

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

Hybrid project behavior across Iterable

  • When creating a new list, specify either a email or userId column, at minimum, or 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.

  • Journey triggers can be tested with email or userID.

  • Iterable doesn't set a iterableEndUserId browser cookie.

  • To identify users when you create a custom subscription center, pass userId as a URL parameter using Handlebars () in the hosted unsubscribe URL project setting.

  • To identify users when tracking conversions, purchases, and revenue, add a URL parameter with a Key of userId and Value of .

  • Static list subscriptions are stored in the userListIds field.

  • When sending a proof to an unknown email address (including when sending a proof "to myself" for the first time), Iterable creates a new user.

Identifying users in hybrid projects

In a hybrid project, userId and email are both valid user identifiers that are guaranteed to be unique. However, userId takes precedence. So, in this example, Iterable interprets a request to POST /api/users/update to mean, "Find or create a user with a userId of user1234567, and set their favoriteColor to red."

{
   "email": "user@example.com",
   "userId": "user1234567",
   "dataFields": {
      "favoriteColor": "red"
   }
}

Iterable also attempts to set the user's email to user@example.com (even though that value is specified outside of dataFields.) However, since hybrid projects enforce uniqueness on email, Iterable first checks whether or not the project already has a user with an email of user@example.com.

  • If user@example.com is not yet in use, the request succeeds. Iterable creates or updates a user with a userId of user1234567, setting email to user@example.com and favoriteColor to red.

  • If user@example.com is already in use, the entire request fails with an HTTP status code 409. You can't reuse an email address that already belongs to another user.

Creating new users in hybrid projects

In hybrid projects, when you make an API request that references a non-existent userId or email, some endpoints create new user profiles:

  • Update user data (individually or in bulk)
  • Target users with email and in-app campaigns
  • Update subscription information
  • Update the shopping cart and track purchases
  • Register device and browser tokens
  • Track events (individually or in bulk)
  • Trigger workflows

For example, you can call POST /api/users/update with a request body such as:

{
  "email": "user@example.com",
  "dataFields": {
     "favoriteColor": "red"
  }
}

For this request:

  • If there's no user with an email of user@example.com, Iterable creates one.
  • Whether the user is new or already exists, Iterable sets their favoriteColor to red.

Another example request:

POST /api/users/update

{
  "userId": "user1234567",
  "dataFields": {
     "favoriteColor": "red"
  }
}

For this request:

  • If there's no user with a userId of user1234567, Iterable creates one.
  • Whether the user is new or already exists, Iterable sets their favoriteColor to red.

NOTE

In userID-based projects, Iterable's API ignores the preferUserId parameter used in email-based projects for some endpoints.

Want to learn more?

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

Iterable Academy

Support docs

Related articles