Updating a User's Email Address or User ID

Sometimes you'll need to change the email address or user ID for a user—perhaps they were previously anonymous and now they have converted to a known contact, their email has changed, or you are updating your project's userId fields to standardize, correct, or otherwise update this value.

This article describes how to change these fields using Iterable's API.

# In this article

# Email-based Projects

# Updating email address in an email-based project

Email-based projects identify users by email. To update a user's email address, call POST /api/users/updateEmail, with a request body such as:

{
   "currentEmail": "current@example.com",
   "newEmail": "new@example.com"
}

In the request body, specify currentEmail or currentUserId, but not both. If you provide both, currentEmail takes precedence.

# Updating user ID in an email-based project

To add or update the userId field for a user in an email-based project, you can call POST /api/users/update.

In the request body:

• For email, specify the existing user's email address.
• In dataFields, provide a userId.

For example:

{
   "email": "existingUser@example.com",
   "dataFields": {
     "userId": "newUserId"
   }
}

For this request:

• Iterable checks to see whether your project already has a user with email set to existingUser@example.com. It not, the user is created.
• Whether the user is new or already exists, Iterable assigns a userId of newUserId to the user.

To add or update a user's userId in an email-based project, call POST /api/users/update, with the new userId value inside of dataFields.

# UserID-based projects and hybrid projects

# Updating email address in a userID-based project or hybrid project

To update an existing user's email in a userID-based or hybrid project, call POST /api/users/update, with a request body such as:

{
  "userId": "someUserId",
  "dataFields": {
     "email": "newEmail@example.com"
   }
 }

# Updating user ID in a userID-based project or hybrid project

To update an existing user's userId in a userID-based or hybrid project, call POST /api/users/update, with a request body such as:

{
  "userId": "oldUserId",
  "dataFields": {
     "userId": "newUserId"
   }
 }

# Common Errors

There may be errors encountered when you are attempting to update a unique identifier for a user. This happens because values are uniquely enforced and conflicts can result in errors.

# Unique email projects

Both email-based projects and hybrid projects enforce a unique value for the email field.

When updating the email field, watch out for these common errors:

• When currentEmail does not exist:

  {
     "msg": "Cannot change user Some(oldEmail@example.com) to newEmail@example.com. User does not exist",
     "code": "BadParams",
     "params": null
  }
  

• When newEmail already exists:

  {
     "msg": "Cannot change user Some(oldEmail@example.com) to newEmail@example.com. New email already exists",
     "code": "EmailAlreadyExists",
     "params": null
  }
  

• When newEmail has been GDPR forgotten:

  {
     "msg": "Cannot change user oldEmail@example.com to newEmail@example.com. New email is on the forgotten list",
     "code": "EmailAlreadyExists",
     "params": null
  }
  

# Unique userId projects

UserID-based projects and hybrid projects enforce unique userId values. Here are some things you may sees when updating a userId value:

• When the user you're trying to update doesn't actually exist, you'll receive a 200 response, and Iterable creates the user with the new userId.

• When the updated userId is already taken by another user:

  {
     "msg": "userId already exists: newUserId",
     "code": "ExternalKeyConflict",
     "params": null
  }
  

• When the original userId has been GDPR forgotten:

{
    "msg": "User with userId originalUserID is forgotten",
    "code": "ForgottenUserError",
    "params": null
}