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.

# In this article

# Email-based Projects

# Updating email address

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": "old@example.com",
   "newEmail": "newEmail@example.com"
}

# Updating user ID

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

For example:

{
  "email": "old@example.com",
  "dataFields": {
    "userId": "newUserID",
    "email": "new@example.com"
  },
  "mergeNestedObjects": true
}

# UserID-based projects and hybrid projects

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

{
  "userId": "oldUserId",
  "dataFields": {
     "userId": "newUserId",
     "email": "newEmail@example.com"
   },
   "mergeNestedObjects": true
 }

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