Update Identifiers

The Update User Identifiers API enables you to update identifiers already associated with users. For example, if an existing user known to Insider updates their email address in your system, you can use this API to change the identifier value from the old email to the new one. In this way, it enables you to keep user identifiers up to date without creating duplicate records.

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.

Sample Request

The sample below displays a request to update a user’s identifier. In this example, the user’s email is changed 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": "sample2@useinsider.com"
    }
}'

The sample below displays a request to update a user’s identifier using a custom field. Custom identifiers must be nested inside the custom object (e.g., user_loyalty_id).

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": "xyz123"
        }
    }
}'

Sample Responses

400 Bad Request

If you enter the same value for both the old and new fields for identifiers, you will receive the following error:

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

400 Bad Request

The old_identifier and new_identifier values must be filled in the payload when making a request. Both fields are required; the following error occurs if either one is missing:

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

400 Bad Request

Identifiers are unique values, so the same value cannot be set for multiple users. If the request returns this response and you do not want to use the identifier value for another user, you need to delete that value from the other user using the Identity API, and then send that value to the new user.

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

400 Bad Request

If the request returns this response, you need to check the Identity Resolution Management Settings. You can send the identifiers if they exist in the IRM settings. For example, if the phone number is not an identifier for the panel A, you cannot send any payload with the phone number key name as identifier.

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

429 Too Many Requests

If you exceed the rate limits, you receive an error shown below:

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

Limitations

• All functions must be executed with a simple HTTPS PATCH request.
• The request token should be provided in the request header. If the token is incorrect, no operation will be executed.
• A single HTTPS PATCH request can pass only 1 record (user).
• A maximum of 2000 requests can be sent per minute.
• Identifiers that are to be replaced should be of the same type.
• The entire request must not exceed 5 MB.
• The value of X-PARTNER-NAME header should be lowercase.