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.
CAUTION
Whenever making changes to a user's profile, such as with
POST /api/users/update
,
we recommend adding a buffer of at least 60s to account for processing time
prior to making additional calls, such as
POST /api/email/target
.
If you are making requests to POST /api/users/forget
for GDPR forget requests, these need approximately ten minutes to process.
These measures will help to prevent race conditions from causing problems such as sending a campaign to the wrong email address!
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
.
-
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.
Navigate to the
POST /api/users/updateEmail
API call.-
Specify a request body. For example:
{ "currentEmail": "oldEmail@example.com", "newEmail": "newEmail@example.com" }
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.
-
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.
Navigate to the
POST /api/users/update
API call.-
Specify a request body. For example:
{ "email": "docs@example.com", "dataFields": { "userId": "new-user-ID", "email": "new@example.com" }, "mergeNestedObjects": true }
Click Submit API Request.
IMPORTANT
The userId
field is not enforced as a unique value in email-based projects.
This means that you will not receive an error if you update a user to have a
non-unique userId
value, and a duplicate userId
will exist in your user
database. This may cause problems when making API calls based on userId
.
If you need this field to carry unique values, consider creating a userID-based project or a hybrid project.
Read Project Types and Unique Identifiers to learn more.
UserID-based projects and hybrid projects
To update an existing user's userId
and/or email
, call
POST /api/users/update
.
Instructions
-
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.
Navigate to the
POST /api/users/update
API call.-
Specify a request body. For example:
{ "userId": "original-user-ID", "dataFields": { "userId": "new-user-ID", "email": "new-email@example.com" }, "mergeNestedObjects": true }
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.
email
projects
Unique 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 }
userId
projects
Unique 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 }
Comments
0 comments
Please sign in to leave a comment.