Update profile identifiers via API

❗️

This guide refers to Klaviyo's v1/v2 legacy APIs.

We are in the process of updating these guides, please check back later! For more information about the differences between legacy and new APIs, check out the comparison chart and [new API overview] (ref:api_overview).

Profile identifiers are fields such as $email and $phone_number that can be used to uniquely identify a profile in your account. The following fields are all considered to be identifier fields:

• Email ($email)
• Phone number ($phone_number)
• External ID ($id)

🚧

The Identify API, which accepts public API Keys and is designed to be called directly within a webpage, does not allow updates to profile identifiers directly. Protecting updates to profile identifiers (such as email address and phone number) behind an API that requires using a Private API key is designed to prevent any potential abuse of Klaviyo’s APIs.

If you are building a workflow that requires updates to profile identifiers via API, we recommend you follow the examples below to update profile identifiers securely using a private key and Klaviyo's RESTFul APIs.

To update non-identifier profile properties, check out the Identify API reference.

Update profile identifiers

If you don’t already have the Klaviyo profile ID for the profile you’d like to update, then updating profile identifiers via our RESTful APIs will require two requests to be made per profile:

1. A GET request to the /v2/people/search endpoint to look up the Klaviyo profile ID for the profile you want to update
2. A PUT call to v1/person/{person_id} to update the desired identifiers using the Klaviyo profile ID you’ve just retrieved

GET the Klaviyo profile ID

Our example profile has the external ID $id = a1b2c3. To look up the Klaviyo profile ID for this profile, make the following GET request:

curl --request GET \
     --url 'https://a.klaviyo.com/api/v2/people/search?external_id=a1b2c3&api_key=API_KEY' \
     --header 'Accept: application/json'

If this profile is found, the endpoint will return a 200 response with the corresponding Klaviyo profile ID in the body:

{
    "id": "{PROFILE_ID}"
}

Update the profile’s email address

Now that we have the profile’s Klaviyo ID, we can update their email address identifier. For this example, we will update $email for this profile to [email protected].

To update the email profile identifier, make the following PUT request:

curl --request PUT \
     --url 'https://a.klaviyo.com/api/v1/person/{PROFILE_ID}?$email=new.me%40yahoo.com&api_key=API_KEY' \
     --header 'Accept: application/json'

If the request successful, the endpoint will return the new updated profile object with its updated email address:

{
  "object": "person",
  "id": "{PROFILE_ID}",
  "$address1": "",
  "$address2": "",
  "$city": "Mount Vernon",
  "$country": "United States",
  "$latitude": "",
  "$longitude": "",
  "$region": "Virginia",
  "$zip": "22121",
  "$email": "[email protected]",
  "$title": "President",
  "$phone_number": "+13239169023",
  "$organization": "U.S. Government",
  "$first_name": "George",
  "$last_name": "Washington",
  "$timezone": "US/Eastern",
  "$id": "a1b2c3",
  "created": "2021-11-04 09:06:13",
  "updated": "2021-11-23 11:21:03"
}