Update Identifiers

Use this endpoint to update an identifier already associated with a user profile. When a user changes their email address, phone number, or custom identifier in your system, use this endpoint to update the value in Insider One without creating a duplicate profile.

Example: A user updates their email from sample@useinsider.com to sample1@useinsider.com. This endpoint updates the identifier on their existing Insider profile, preserving all associated behavioral data and attributes.

Prerequisites:

Identifiers must be configured in your Identity Resolution Management (IRM) Settings before they can be used in this endpoint. If an identifier type is not enabled in IRM Settings, requests using that identifier will return a 400 error.

Endpoint and Headers

PATCH https://unification.useinsider.com/api/user/v1/identity

Headers

Body Parameters

Each PATCH request must have an identifier type, old value, and new value specified in it. You can use either one of the default identifiers, which are uuid, email, and phone_number, or any of the custom identifiers you use.

Same-type rule:

The identifier field in old_identifier and new_identifier must be of the same type. For example, you cannot update an email identifier with a phone number value. Requests with mismatched types will return a 400 error.

Sample Requests

Update a default identifier

This request updates a user's email address from the old value to a new one.

curl --location --request PATCH 'https://unification.useinsider.com/api/user/v1/identity' \
--header 'X-PARTNER-NAME: mybrand' \
--header 'X-REQUEST-TOKEN: 1a2b3c4e5d6f' \
--header 'Content-Type: application/json' \
--data-raw '{
    "old_identifier": {
        "email": "sample@useinsider.com"
    },
    "new_identifier": {
        "email": "sample1@useinsider.com"
    }
}'

Update a custom identifier

Custom identifiers must be nested inside the custom object in both old_identifier and new_identifier.

curl --location --request PATCH 'https://unification.useinsider.com/api/user/v1/identity' \
--header 'X-PARTNER-NAME: mybrand' \
--header 'X-REQUEST-TOKEN: 1a2b3c4e5d6f' \
--header 'Content-Type: application/json' \
--data-raw '{
    "old_identifier": {
        "custom": {
            "user_loyalty_id": "xyz123"
        }
    },
    "new_identifier": {
        "custom": {
            "user_loyalty_id": "xyz456"
        }
    }
}'

Sample Responses

200 OK

A successful update returns an empty object. The identifier is updated on the user's profile immediately. The user's existing behavioral data and attributes are preserved.

{}

400 Bad Request

Returned when the old_identifier and new_identifier contain the same value. The new value must be different from the current value.

{
  "error": "identifier values are the same: bad request"
}

400 Bad Request

Returned when either old_identifier or new_identifier is missing from the request body. Both fields are required and must each contain exactly one identifier.

{
  "error": "there must be exactly 1 entry for both new and old identifiers: bad request"
}

400 Bad Request

Returned when the new_identifier value is already associated with a different user in your account. Identifier values must be unique across all profiles.

To resolve this, remove the identifier from the existing user using the Delete Identifiers API, then retry this request.

{
  "error": "new identifier already has a user assigned to it: bad request"
}

400 Bad Request

Returned when the identifier type in the request is not enabled in your Identity Resolution Management Settings.

To resolve this, verify that the identifier type you are using is enabled in IRM Settings for your panel. For example, if phone_number is not configured as an identifier for your panel, requests using it will return this error.

{
  "error": "no valid identifier: bad request"
}

429 Too Many Requests

Returned when the request rate exceeds 2,000 requests per minute. Wait before retrying. To request a higher limit, contact the Insider One team via the Help Center or refer to API Rate Limits.

{
    "error": "rejected: too many requests"
}

Limitations

• All requests must use HTTPS PATCH.

• The X-REQUEST-TOKEN header must contain a valid token. An invalid or missing token returns a 403 error.

• The X-PARTNER-NAME header value must be lowercase.

• A single request updates exactly one user. Batch updates are not supported.

• The old_identifier and new_identifier fields must use the same identifier type.

• Identifier values must be unique across all user profiles in your account.

• The entire request body must not exceed 5 MB.

• The rate limit is 2,000 requests per minute. This limit is specific to this endpoint and is separate from the shared rate limit used by the User Upsert and Delete User Attribute APIs.