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

In email-based projects, every user has an email. To update a user's email address, call POST /api/users/updateEmail.

1. Navigate to the Iterable API Explorer and input your API key in the top-left corner.

   NOTE

   To learn more about API keys, read API Keys.

2. Navigate to the POST /api/users/updateEmail API call.

3. Specify a request body. For example:

   {
       "currentEmail": "oldEmail@example.com",
       "newEmail": "newEmail@example.com"
   }
   

4. Click Submit API Request.

# Updating User ID

You can update an existing user's userId by calling the POST /api/users/update API, placing the updated field(s) inside the dataFields object.

1. Navigate to the Iterable API Explorer and input your API key in the top-left corner.

   NOTE

   To learn more about API keys, read API Keys.

2. Navigate to the POST /api/users/update API call.

3. Specify a request body. For example:

   {
     "email": "docs@example.com",
     "dataFields": {
       "userId": "new-user-ID",
       "email": "new@example.com"
     },
     "mergeNestedObjects": true
   }
   

4. Click Submit API Request.

# UserID-based projects and hybrid projects

To update an existing user's userId and/or email, call POST /api/users/update.

# Instructions

1. Navigate to the Iterable API Explorer and input your API key in the top-left corner.

   NOTE

   To learn more about API keys, read API Keys.

2. Navigate to the POST /api/users/update API call.

3. Specify a request body. For example:

   {
     "userId": "original-user-ID",
     "dataFields": {
       "userId": "new-user-ID",
       "email": "new-email@example.com"
     },
     "mergeNestedObjects": true
   }
   

4. Click Submit API Request.

# 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@iterable.com) to newEmail@iterable.com. User does not exist",
      "code": "BadParams",
      "params": null
  }
  

• When newEmail already exists:

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

• When newEmail has been GDPR forgotten:

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

# Unique userId projects

UserID-based projects and hybrid projects enforce unique values on the userId field.

Common errors when updating the userId field in these projects may include:

• When "userId": "original-user-ID" doesn't exist, you'll receive a 200 response and a new user will be created with the "userId": "new-user-ID" value.

• When "userId": "new-user-ID" already exists:

  {
      "msg": "userId already exists: new-user-ID",
      "code": "ExternalKeyConflict",
      "params": null
  }
  

• When "userId": "original-user-ID" has been GDPR forgotten:

{
    "msg": "User with userId original-user-ID is forgotten",
    "code": "ForgottenUserError",
    "params": null
}