Notebook

Table of contents¶

Introduction
Getting set up
Hello World: Get customer profiles in your account
Example use cases
4.1 Get data on a specific customer profile
4.2 Get profiles in a list
4.3 Get unsubscription events between timestamps
4.4 Finding first time buyers during BFCM
Wrapping up

FAQs¶

Who is this guide meant for?
What do I need to follow along?
What's an SDK?
What's an API private key?
What is the general structure of Klaviyo's API responses?
How is customer profile data structured specifically?
How are events and customer profiles related?
What is a Klaviyo ID?
How can I get customer profile IDs?
How can I get list or segment IDs?
What is pagination?
What's a simple example of pagination?
What does the links argument mean?
How can I filter events based on date?

1. Introduction¶

Before we begin¶

Klaviyo helps businesses collect massive amounts of data on their customers from the communications they interact with to metadata from their Active on Site sessions. Developers play a key role in unlocking the value in this data.

We will start by building a baseline understanding of concepts related to Klaviyo's APIs and build toward a step-by-step walkthrough of a complex use case centered around first-time, Black Friday customers.

This guide primarily makes requests on Klaviyo's newest generation of APIs using our Python SDK. However, direct HTTP requests are covered as well. Regardless of how you plan on interacting with Klaviyo's APIs, this guide should teach you something about how customer data in Klaviyo can be a driver for growth. Let's dive in!

Who is this guide meant for?¶

Anyone interested in how Klaviyo data is structured
New Klaviyo developers
Experienced Klaviyo developers

2. Getting set up¶

What do I need to run this notebook?¶

The steps listed above are needed if you want to execute the code snippets shown in this guide. Those who are mainly interested to learn how Klaviyo's APIs work should be able to get the information without needing to run the notebook.

It is not strictly necessary to have a sandbox account with fake customer data in order to run this notebook. However, developers who are testing new functionalities should strongly consider it. Especially for use cases where you upload or change customer data, you want to make sure that you are not negatively impacting the data you have on your customers.

What's an SDK?¶

If you haven't worked with SDKs before (Software Development Kits), think of an SDK like a small library specific to a set of API endpoints.

Klaviyo's SDKs make working with our APIs easier by providing one-line methods for common tasks (e.g. how to update a customer's profile, change subscription status, etc.).

This walkthrough will make use of the Python language and Klaviyo's Python SDK. Klaviyo has released SDKs in Node, PHP, Python, and Ruby. Developers can find more information about Klaviyo's SDKs here.

If you are using one of those languages, Klaviyo highly recommends that you use our SDK to make API requests. The SDK performs a lot of best practices automatically under the hood (e.g. retry logic).

If you want to fully customize every part of your usage of our APIs, you are always free to make the calls directly (i.e. through HTTP requests).

This guide covers both direct API requests and requests sent through Klaviyo's SDK.

Import SDK Client¶

This tutorial assumes that Klaviyo's SDK is already set up locally. To check out how this is done, select the SDK version and language you want and follow the instructions given on the SDK github. For reference, you can download the SDK with a pip install call like the one commented out below.

Setting up the SDK locally in your codebase is most important for frequent API users and/or developers setting up a production job. Developers who are just testing Klaviyo's API capabilities can start with direct HTTP requests on Klaviyo's endpoints.

This guide is best viewed on NBViewer¶

For the best user experience reading this guide, please view it on NBViewer rather than natively in Github. Interacting with the guide on NBviewer cuts down on 404 errors when clicking internal links and better formats long code printouts.

You can find Klaviyo's API guides on NBViewer here.

In [1]:

# you may need to pip install the SDK for Klaviyo's current generation of APIs
# pip install klaviyo-api

In [2]:

### Libraries needed to run requests through pure python (using requests library)
import requests
from requests.adapters import HTTPAdapter
from requests.packages.urllib3.util.retry import Retry
from datetime import datetime, timedelta
import random
import string
import json


### Library needed to run request through Klaviyo's python SDK 
from klaviyo_api import KlaviyoAPI

What is a private API key?¶

To query your customer data using Klaviyo's APIs, you will need to authenticate that request with a private API key.

A Klaviyo private API key is an authentication token that developers need to pass on most API calls to show that they have the proper permission. A private API key lets developers use API requests to do many actions usually only available manually in Klaviyo (e.g. downloading data and viewing customer orders).

That's why it is critically important to treat private API keys like passwords. They should not be publicly viewable anywhere (e.g. on your github, on your website's frontend). Developers should also consider limiting access to these keys internally in the same way that they would limit who has access to an account password.

Klaviyo accounts do not start with a private API key, they have to be generated. You can learn about how to generate a Klaviyo private API key on our Help Center.

Get your private API key¶

To run any of the API requests in this guide, you will need a private API key. For HTTP requests, this private API key is passed as an Authorization header. For SDK requests, the private key is part of the information needed to define a SDK client object.

To execute the code snippets in this notebook, please replace the private API key placeholder with your account's key.

In [3]:

# TODO: Update private_key
private_key = 'PRIVATE_API_KEY'

# NOTE: This key cannot exist in a public place. Do not push a script publicly with this key in it.

Create SDK Client¶

Now that we have imported the SDK and set an account's private API key, we next have to instantiate an SDK client. This SDK client is an intermediary between you and Klaviyo's APIs that will make your life easier.

An SDK client is necessary to run most of the examples covered in this guide.

Once this has been run, you will be able to make API requests simply by running the client object's methods.

In [4]:

# Instantiate the SDK client with your private API key
klaviyo = KlaviyoAPI(private_key, max_delay=5, max_retries=3)

Adjust Display Settings¶

The HTML code snippet below has nothing to do with Klaviyo's APIs. It simply makes the notebook render better on NBViewer.

In [5]:

%%html
<style>
.nbviewer div.output_area {
  overflow-y: auto;
  max-height: 500px; /* or value of your choosing */
}
</style>

3. Hello World: Get your customer profiles¶

Now that we've created an SDK client authorized with your Klaviyo private API key, it's time to explore your data.

Getting your account's customer profiles is a great way to get introduced to Klaviyo's data model. We will show how to make that call both through Klaviyo's SDK and through a direct HTTP request. Both methods lead to the same result.

As a reminder, Klaviyo recommends you scope new functionality with a sandbox account filled with sample data.

Hello World: SDK Version¶

The code block below shows how to do this API call using Klaviyo's SDK. It leads to the same results as a HTTP example below.

In [6]:

# NOTE: Does not include pagination (see Example 3.2); so, will not return all customers.
output = klaviyo.Profiles.get_profiles()
output

Out[6]:

{'data': [{'type': 'profile',
   'id': '01G111X7K5VMWZR03WV4MHRDAV',
   'attributes': {'email': 'kristina.stephens_138@klaviyo-demo.com',
    'phone_number': '+18409121959',
    'external_id': None,
    'anonymous_id': None,
    'first_name': 'Kristina',
    'last_name': 'Stephens',
    'organization': None,
    'title': None,
    'image': None,
    'created': '2022-04-19T13:59:05+00:00',
    'updated': '2022-04-19T14:01:10+00:00',
    'last_event_date': None,
    'location': {'address1': None,
     'address2': None,
     'city': 'Columbus',
     'country': 'United States',
     'latitude': None,
     'longitude': None,
     'region': 'Ohio',
     'zip': '18335',
     'timezone': 'America/New_York'},
    'properties': {}},
   'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X7K5VMWZR03WV4MHRDAV/'},
   'relationships': {'lists': {'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X7K5VMWZR03WV4MHRDAV/relationships/lists/',
      'related': 'https://a.klaviyo.com/api/profiles/01G111X7K5VMWZR03WV4MHRDAV/lists/'}},
    'segments': {'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X7K5VMWZR03WV4MHRDAV/relationships/segments/',
      'related': 'https://a.klaviyo.com/api/profiles/01G111X7K5VMWZR03WV4MHRDAV/segments/'}}}},
  {'type': 'profile',
   'id': '01G111X7VE1V41ZM36X2NKV02F',
   'attributes': {'email': 'julia.dixon_222@klaviyo-demo.com',
    'phone_number': '+18470101517',
    'external_id': None,
    'anonymous_id': None,
    'first_name': 'Julia',
    'last_name': 'Dixon',
    'organization': None,
    'title': None,
    'image': None,
    'created': '2022-04-19T13:59:05+00:00',
    'updated': '2022-04-19T14:01:11+00:00',
    'last_event_date': None,
    'location': {'address1': None,
     'address2': None,
     'city': 'Columbus',
     'country': 'United States',
     'latitude': None,
     'longitude': None,
     'region': 'Ohio',
     'zip': '80623',
     'timezone': 'America/New_York'},
    'properties': {}},
   'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X7VE1V41ZM36X2NKV02F/'},
   'relationships': {'lists': {'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X7VE1V41ZM36X2NKV02F/relationships/lists/',
      'related': 'https://a.klaviyo.com/api/profiles/01G111X7VE1V41ZM36X2NKV02F/lists/'}},
    'segments': {'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X7VE1V41ZM36X2NKV02F/relationships/segments/',
      'related': 'https://a.klaviyo.com/api/profiles/01G111X7VE1V41ZM36X2NKV02F/segments/'}}}},
  {'type': 'profile',
   'id': '01G111X7Y9WNVPZVY1BPZC5Q7Z',
   'attributes': {'email': 'marsha.porter_596@klaviyo-demo.com',
    'phone_number': '+14409121807',
    'external_id': None,
    'anonymous_id': None,
    'first_name': 'Marsha',
    'last_name': 'Porter',
    'organization': None,
    'title': None,
    'image': None,
    'created': '2022-04-19T13:59:05+00:00',
    'updated': '2022-04-19T14:01:11+00:00',
    'last_event_date': None,
    'location': {'address1': None,
     'address2': None,
     'city': 'Columbus',
     'country': 'United States',
     'latitude': None,
     'longitude': None,
     'region': 'Ohio',
     'zip': '81576',
     'timezone': 'America/New_York'},
    'properties': {}},
   'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X7Y9WNVPZVY1BPZC5Q7Z/'},
   'relationships': {'lists': {'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X7Y9WNVPZVY1BPZC5Q7Z/relationships/lists/',
      'related': 'https://a.klaviyo.com/api/profiles/01G111X7Y9WNVPZVY1BPZC5Q7Z/lists/'}},
    'segments': {'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X7Y9WNVPZVY1BPZC5Q7Z/relationships/segments/',
      'related': 'https://a.klaviyo.com/api/profiles/01G111X7Y9WNVPZVY1BPZC5Q7Z/segments/'}}}},
  {'type': 'profile',
   'id': '01G111X811JG59BMHDE8QZ2KEG',
   'attributes': {'email': 'tara.wagner_206@klaviyo-demo.com',
    'phone_number': '+17700006465',
    'external_id': None,
    'anonymous_id': None,
    'first_name': 'Tara',
    'last_name': 'Wagner',
    'organization': None,
    'title': None,
    'image': None,
    'created': '2022-04-19T13:59:05+00:00',
    'updated': '2022-04-19T14:01:11+00:00',
    'last_event_date': None,
    'location': {'address1': None,
     'address2': None,
     'city': 'Columbus',
     'country': 'United States',
     'latitude': None,
     'longitude': None,
     'region': 'Ohio',
     'zip': '24981',
     'timezone': 'America/New_York'},
    'properties': {}},
   'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X811JG59BMHDE8QZ2KEG/'},
   'relationships': {'lists': {'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X811JG59BMHDE8QZ2KEG/relationships/lists/',
      'related': 'https://a.klaviyo.com/api/profiles/01G111X811JG59BMHDE8QZ2KEG/lists/'}},
    'segments': {'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X811JG59BMHDE8QZ2KEG/relationships/segments/',
      'related': 'https://a.klaviyo.com/api/profiles/01G111X811JG59BMHDE8QZ2KEG/segments/'}}}},
  {'type': 'profile',
   'id': '01G111X83YE7FXWD8GDFBB8NVE',
   'attributes': {'email': 'jack.medina_603@klaviyo-demo.com',
    'phone_number': '+17235667680',
    'external_id': None,
    'anonymous_id': None,
    'first_name': 'Jack',
    'last_name': 'Medina',
    'organization': None,
    'title': None,
    'image': None,
    'created': '2022-04-19T13:59:05+00:00',
    'updated': '2022-04-19T14:01:11+00:00',
    'last_event_date': None,
    'location': {'address1': None,
     'address2': None,
     'city': 'Columbus',
     'country': 'United States',
     'latitude': None,
     'longitude': None,
     'region': 'Ohio',
     'zip': '49784',
     'timezone': 'America/New_York'},
    'properties': {}},
   'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X83YE7FXWD8GDFBB8NVE/'},
   'relationships': {'lists': {'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X83YE7FXWD8GDFBB8NVE/relationships/lists/',
      'related': 'https://a.klaviyo.com/api/profiles/01G111X83YE7FXWD8GDFBB8NVE/lists/'}},
    'segments': {'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X83YE7FXWD8GDFBB8NVE/relationships/segments/',
      'related': 'https://a.klaviyo.com/api/profiles/01G111X83YE7FXWD8GDFBB8NVE/segments/'}}}},
  {'type': 'profile',
   'id': '01G111X86STXA6NYTJ3GJJRD00',
   'attributes': {'email': 'devon.ortiz_362@klaviyo-demo.com',
    'phone_number': '+16032688420',
    'external_id': None,
    'anonymous_id': None,
    'first_name': 'Devon',
    'last_name': 'Ortiz',
    'organization': None,
    'title': None,
    'image': None,
    'created': '2022-04-19T13:59:05+00:00',
    'updated': '2022-04-19T14:01:11+00:00',
    'last_event_date': None,
    'location': {'address1': None,
     'address2': None,
     'city': 'Columbus',
     'country': 'United States',
     'latitude': None,
     'longitude': None,
     'region': 'Ohio',
     'zip': '17133',
     'timezone': 'America/New_York'},
    'properties': {}},
   'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X86STXA6NYTJ3GJJRD00/'},
   'relationships': {'lists': {'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X86STXA6NYTJ3GJJRD00/relationships/lists/',
      'related': 'https://a.klaviyo.com/api/profiles/01G111X86STXA6NYTJ3GJJRD00/lists/'}},
    'segments': {'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X86STXA6NYTJ3GJJRD00/relationships/segments/',
      'related': 'https://a.klaviyo.com/api/profiles/01G111X86STXA6NYTJ3GJJRD00/segments/'}}}},
  {'type': 'profile',
   'id': '01G111X8A4KXWMXZX564EYDAMM',
   'attributes': {'email': 'elizabeth.holland_998@klaviyo-demo.com',
    'phone_number': '+16772197540',
    'external_id': None,
    'anonymous_id': None,
    'first_name': 'Elizabeth',
    'last_name': 'Holland',
    'organization': None,
    'title': None,
    'image': None,
    'created': '2022-04-19T13:59:05+00:00',
    'updated': '2022-04-19T14:01:11+00:00',
    'last_event_date': None,
    'location': {'address1': None,
     'address2': None,
     'city': 'Columbus',
     'country': 'United States',
     'latitude': None,
     'longitude': None,
     'region': 'Ohio',
     'zip': '19422',
     'timezone': 'America/New_York'},
    'properties': {}},
   'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X8A4KXWMXZX564EYDAMM/'},
   'relationships': {'lists': {'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X8A4KXWMXZX564EYDAMM/relationships/lists/',
      'related': 'https://a.klaviyo.com/api/profiles/01G111X8A4KXWMXZX564EYDAMM/lists/'}},
    'segments': {'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X8A4KXWMXZX564EYDAMM/relationships/segments/',
      'related': 'https://a.klaviyo.com/api/profiles/01G111X8A4KXWMXZX564EYDAMM/segments/'}}}},
  {'type': 'profile',
   'id': '01G111X8D0W3H7FAF3DH7K6M5Z',
   'attributes': {'email': 'gregory.rice_105@klaviyo-demo.com',
    'phone_number': '+17053390984',
    'external_id': None,
    'anonymous_id': None,
    'first_name': 'Gregory',
    'last_name': 'Rice',
    'organization': None,
    'title': None,
    'image': None,
    'created': '2022-04-19T13:59:05+00:00',
    'updated': '2022-04-19T14:01:11+00:00',
    'last_event_date': None,
    'location': {'address1': None,
     'address2': None,
     'city': 'Columbus',
     'country': 'United States',
     'latitude': None,
     'longitude': None,
     'region': 'Ohio',
     'zip': '53670',
     'timezone': 'America/New_York'},
    'properties': {}},
   'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X8D0W3H7FAF3DH7K6M5Z/'},
   'relationships': {'lists': {'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X8D0W3H7FAF3DH7K6M5Z/relationships/lists/',
      'related': 'https://a.klaviyo.com/api/profiles/01G111X8D0W3H7FAF3DH7K6M5Z/lists/'}},
    'segments': {'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X8D0W3H7FAF3DH7K6M5Z/relationships/segments/',
      'related': 'https://a.klaviyo.com/api/profiles/01G111X8D0W3H7FAF3DH7K6M5Z/segments/'}}}},
  {'type': 'profile',
   'id': '01G111X8FV7W8EQCTNAC04K7TP',
   'attributes': {'email': 'sheila.berry_441@klaviyo-demo.com',
    'phone_number': '+11052899276',
    'external_id': None,
    'anonymous_id': None,
    'first_name': 'Sheila',
    'last_name': 'Berry',
    'organization': None,
    'title': None,
    'image': None,
    'created': '2022-04-19T13:59:05+00:00',
    'updated': '2022-04-19T14:01:12+00:00',
    'last_event_date': None,
    'location': {'address1': None,
     'address2': None,
     'city': 'Columbus',
     'country': 'United States',
     'latitude': None,
     'longitude': None,
     'region': 'Ohio',
     'zip': '15923',
     'timezone': 'America/New_York'},
    'properties': {}},
   'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X8FV7W8EQCTNAC04K7TP/'},
   'relationships': {'lists': {'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X8FV7W8EQCTNAC04K7TP/relationships/lists/',
      'related': 'https://a.klaviyo.com/api/profiles/01G111X8FV7W8EQCTNAC04K7TP/lists/'}},
    'segments': {'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X8FV7W8EQCTNAC04K7TP/relationships/segments/',
      'related': 'https://a.klaviyo.com/api/profiles/01G111X8FV7W8EQCTNAC04K7TP/segments/'}}}},
  {'type': 'profile',
   'id': '01G111X8JG0B39ARRJPN3NJ893',
   'attributes': {'email': 'terrence.jennings_421@klaviyo-demo.com',
    'phone_number': '+11232100105',
    'external_id': None,
    'anonymous_id': None,
    'first_name': 'Terrence',
    'last_name': 'Jennings',
    'organization': None,
    'title': None,
    'image': None,
    'created': '2022-04-19T13:59:06+00:00',
    'updated': '2022-04-19T14:01:12+00:00',
    'last_event_date': None,
    'location': {'address1': None,
     'address2': None,
     'city': 'Columbus',
     'country': 'United States',
     'latitude': None,
     'longitude': None,
     'region': 'Ohio',
     'zip': '43114',
     'timezone': 'America/New_York'},
    'properties': {}},
   'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X8JG0B39ARRJPN3NJ893/'},
   'relationships': {'lists': {'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X8JG0B39ARRJPN3NJ893/relationships/lists/',
      'related': 'https://a.klaviyo.com/api/profiles/01G111X8JG0B39ARRJPN3NJ893/lists/'}},
    'segments': {'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X8JG0B39ARRJPN3NJ893/relationships/segments/',
      'related': 'https://a.klaviyo.com/api/profiles/01G111X8JG0B39ARRJPN3NJ893/segments/'}}}},
  {'type': 'profile',
   'id': '01G111X8N9FG81M2Z90NMTMZTT',
   'attributes': {'email': 'gerald.harvey_101@klaviyo-demo.com',
    'phone_number': '(539)-331-2511',
    'external_id': None,
    'anonymous_id': None,
    'first_name': 'Gerald',
    'last_name': 'Harvey',
    'organization': None,
    'title': None,
    'image': None,
    'created': '2022-04-19T13:59:06+00:00',
    'updated': '2022-04-19T14:01:12+00:00',
    'last_event_date': None,
    'location': {'address1': None,
     'address2': None,
     'city': 'Hampton',
     'country': None,
     'latitude': None,
     'longitude': None,
     'region': 'South Dakota',
     'zip': '38475',
     'timezone': None},
    'properties': {}},
   'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X8N9FG81M2Z90NMTMZTT/'},
   'relationships': {'lists': {'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X8N9FG81M2Z90NMTMZTT/relationships/lists/',
      'related': 'https://a.klaviyo.com/api/profiles/01G111X8N9FG81M2Z90NMTMZTT/lists/'}},
    'segments': {'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X8N9FG81M2Z90NMTMZTT/relationships/segments/',
      'related': 'https://a.klaviyo.com/api/profiles/01G111X8N9FG81M2Z90NMTMZTT/segments/'}}}},
  {'type': 'profile',
   'id': '01G111X8QXRWDW2H56R3V9MVPN',
   'attributes': {'email': 'sherri.bryant_592@klaviyo-demo.com',
    'phone_number': '+14383706640',
    'external_id': None,
    'anonymous_id': None,
    'first_name': 'Sherri',
    'last_name': 'Bryant',
    'organization': None,
    'title': None,
    'image': None,
    'created': '2022-04-19T13:59:06+00:00',
    'updated': '2022-04-19T14:01:12+00:00',
    'last_event_date': None,
    'location': {'address1': None,
     'address2': None,
     'city': 'Columbus',
     'country': 'United States',
     'latitude': None,
     'longitude': None,
     'region': 'Ohio',
     'zip': '62723',
     'timezone': 'America/New_York'},
    'properties': {}},
   'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X8QXRWDW2H56R3V9MVPN/'},
   'relationships': {'lists': {'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X8QXRWDW2H56R3V9MVPN/relationships/lists/',
      'related': 'https://a.klaviyo.com/api/profiles/01G111X8QXRWDW2H56R3V9MVPN/lists/'}},
    'segments': {'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X8QXRWDW2H56R3V9MVPN/relationships/segments/',
      'related': 'https://a.klaviyo.com/api/profiles/01G111X8QXRWDW2H56R3V9MVPN/segments/'}}}},
  {'type': 'profile',
   'id': '01G111X8TQYQ8GK86BSV7F3516',
   'attributes': {'email': 'sylvia.diaz_301@klaviyo-demo.com',
    'phone_number': '+18807279925',
    'external_id': None,
    'anonymous_id': None,
    'first_name': 'Sylvia',
    'last_name': 'Diaz',
    'organization': None,
    'title': None,
    'image': None,
    'created': '2022-04-19T13:59:06+00:00',
    'updated': '2022-04-19T14:01:12+00:00',
    'last_event_date': None,
    'location': {'address1': None,
     'address2': None,
     'city': 'Columbus',
     'country': 'United States',
     'latitude': None,
     'longitude': None,
     'region': 'Ohio',
     'zip': '72141',
     'timezone': 'America/New_York'},
    'properties': {}},
   'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X8TQYQ8GK86BSV7F3516/'},
   'relationships': {'lists': {'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X8TQYQ8GK86BSV7F3516/relationships/lists/',
      'related': 'https://a.klaviyo.com/api/profiles/01G111X8TQYQ8GK86BSV7F3516/lists/'}},
    'segments': {'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X8TQYQ8GK86BSV7F3516/relationships/segments/',
      'related': 'https://a.klaviyo.com/api/profiles/01G111X8TQYQ8GK86BSV7F3516/segments/'}}}},
  {'type': 'profile',
   'id': '01G111X8XGBB1HVJ2MQ6SF6YAY',
   'attributes': {'email': 'yvonne.sullivan_716@klaviyo-demo.com',
    'phone_number': '+19905230491',
    'external_id': None,
    'anonymous_id': None,
    'first_name': 'Yvonne',
    'last_name': 'Sullivan',
    'organization': None,
    'title': None,
    'image': None,
    'created': '2022-04-19T13:59:06+00:00',
    'updated': '2022-04-19T14:01:12+00:00',
    'last_event_date': None,
    'location': {'address1': None,
     'address2': None,
     'city': 'Columbus',
     'country': 'United States',
     'latitude': None,
     'longitude': None,
     'region': 'Ohio',
     'zip': '10158',
     'timezone': 'America/New_York'},
    'properties': {}},
   'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X8XGBB1HVJ2MQ6SF6YAY/'},
   'relationships': {'lists': {'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X8XGBB1HVJ2MQ6SF6YAY/relationships/lists/',
      'related': 'https://a.klaviyo.com/api/profiles/01G111X8XGBB1HVJ2MQ6SF6YAY/lists/'}},
    'segments': {'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X8XGBB1HVJ2MQ6SF6YAY/relationships/segments/',
      'related': 'https://a.klaviyo.com/api/profiles/01G111X8XGBB1HVJ2MQ6SF6YAY/segments/'}}}},
  {'type': 'profile',
   'id': '01G111X9093JDHA07DDM41YKHR',
   'attributes': {'email': 'micheal.simmmons_513@klaviyo-demo.com',
    'phone_number': '+14474215178',
    'external_id': None,
    'anonymous_id': None,
    'first_name': 'Micheal',
    'last_name': 'Simmmons',
    'organization': None,
    'title': None,
    'image': None,
    'created': '2022-04-19T13:59:06+00:00',
    'updated': '2022-04-19T14:01:12+00:00',
    'last_event_date': None,
    'location': {'address1': None,
     'address2': None,
     'city': 'Columbus',
     'country': 'United States',
     'latitude': None,
     'longitude': None,
     'region': 'Ohio',
     'zip': '37232',
     'timezone': 'America/New_York'},
    'properties': {}},
   'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X9093JDHA07DDM41YKHR/'},
   'relationships': {'lists': {'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X9093JDHA07DDM41YKHR/relationships/lists/',
      'related': 'https://a.klaviyo.com/api/profiles/01G111X9093JDHA07DDM41YKHR/lists/'}},
    'segments': {'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X9093JDHA07DDM41YKHR/relationships/segments/',
      'related': 'https://a.klaviyo.com/api/profiles/01G111X9093JDHA07DDM41YKHR/segments/'}}}},
  {'type': 'profile',
   'id': '01G111X934EGZPT9QXG2E66M6C',
   'attributes': {'email': 'martha.turner_923@klaviyo-demo.com',
    'phone_number': '+10081188694',
    'external_id': None,
    'anonymous_id': None,
    'first_name': 'Martha',
    'last_name': 'Turner',
    'organization': None,
    'title': None,
    'image': None,
    'created': '2022-04-19T13:59:06+00:00',
    'updated': '2022-04-19T14:01:12+00:00',
    'last_event_date': None,
    'location': {'address1': None,
     'address2': None,
     'city': 'Columbus',
     'country': 'United States',
     'latitude': None,
     'longitude': None,
     'region': 'Ohio',
     'zip': '24648',
     'timezone': 'America/New_York'},
    'properties': {}},
   'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X934EGZPT9QXG2E66M6C/'},
   'relationships': {'lists': {'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X934EGZPT9QXG2E66M6C/relationships/lists/',
      'related': 'https://a.klaviyo.com/api/profiles/01G111X934EGZPT9QXG2E66M6C/lists/'}},
    'segments': {'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X934EGZPT9QXG2E66M6C/relationships/segments/',
      'related': 'https://a.klaviyo.com/api/profiles/01G111X934EGZPT9QXG2E66M6C/segments/'}}}},
  {'type': 'profile',
   'id': '01G111X963313P874JREC48G4Y',
   'attributes': {'email': 'kenneth.daniels_954@klaviyo-demo.com',
    'phone_number': '+15363857084',
    'external_id': None,
    'anonymous_id': None,
    'first_name': 'Kenneth',
    'last_name': 'Daniels',
    'organization': None,
    'title': None,
    'image': None,
    'created': '2022-04-19T13:59:06+00:00',
    'updated': '2022-04-19T14:01:12+00:00',
    'last_event_date': None,
    'location': {'address1': None,
     'address2': None,
     'city': 'Columbus',
     'country': 'United States',
     'latitude': None,
     'longitude': None,
     'region': 'Ohio',
     'zip': '80253',
     'timezone': 'America/New_York'},
    'properties': {}},
   'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X963313P874JREC48G4Y/'},
   'relationships': {'lists': {'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X963313P874JREC48G4Y/relationships/lists/',
      'related': 'https://a.klaviyo.com/api/profiles/01G111X963313P874JREC48G4Y/lists/'}},
    'segments': {'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X963313P874JREC48G4Y/relationships/segments/',
      'related': 'https://a.klaviyo.com/api/profiles/01G111X963313P874JREC48G4Y/segments/'}}}},
  {'type': 'profile',
   'id': '01G111X98XVAF6RQZ46BBS7TED',
   'attributes': {'email': 'catherine.sullivan_289@klaviyo-demo.com',
    'phone_number': '+16175558793',
    'external_id': None,
    'anonymous_id': None,
    'first_name': None,
    'last_name': None,
    'organization': 'Warner-Black',
    'title': 'Public relations account executive',
    'image': None,
    'created': '2022-04-19T13:59:06+00:00',
    'updated': '2022-04-19T14:01:12+00:00',
    'last_event_date': None,
    'location': {'address1': '49955 Joshua Springs',
     'address2': 'Apt. 014',
     'city': 'Columbus',
     'country': 'United States',
     'latitude': None,
     'longitude': None,
     'region': 'Ohio',
     'zip': '68533',
     'timezone': 'America/New_York'},
    'properties': {}},
   'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X98XVAF6RQZ46BBS7TED/'},
   'relationships': {'lists': {'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X98XVAF6RQZ46BBS7TED/relationships/lists/',
      'related': 'https://a.klaviyo.com/api/profiles/01G111X98XVAF6RQZ46BBS7TED/lists/'}},
    'segments': {'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X98XVAF6RQZ46BBS7TED/relationships/segments/',
      'related': 'https://a.klaviyo.com/api/profiles/01G111X98XVAF6RQZ46BBS7TED/segments/'}}}},
  {'type': 'profile',
   'id': '01G111X9BZAK6J8A67H7M871CW',
   'attributes': {'email': 'tiffany.wyatt_817@klaviyo-demo.com',
    'phone_number': '+16175559960',
    'external_id': None,
    'anonymous_id': None,
    'first_name': None,
    'last_name': None,
    'organization': 'Arnold and Sons',
    'title': 'Hospital pharmacist',
    'image': None,
    'created': '2022-04-19T13:59:06+00:00',
    'updated': '2022-04-19T14:01:12+00:00',
    'last_event_date': None,
    'location': {'address1': '739 Bishop Mountains',
     'address2': 'Apt. 785',
     'city': 'Columbus',
     'country': 'United States',
     'latitude': None,
     'longitude': None,
     'region': 'Ohio',
     'zip': '86148',
     'timezone': 'America/New_York'},
    'properties': {}},
   'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X9BZAK6J8A67H7M871CW/'},
   'relationships': {'lists': {'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X9BZAK6J8A67H7M871CW/relationships/lists/',
      'related': 'https://a.klaviyo.com/api/profiles/01G111X9BZAK6J8A67H7M871CW/lists/'}},
    'segments': {'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X9BZAK6J8A67H7M871CW/relationships/segments/',
      'related': 'https://a.klaviyo.com/api/profiles/01G111X9BZAK6J8A67H7M871CW/segments/'}}}},
  {'type': 'profile',
   'id': '01G111X9EV7DJSCR048H7KWT57',
   'attributes': {'email': 'willie.hammond_555@klaviyo-demo.com',
    'phone_number': '+16175551539',
    'external_id': None,
    'anonymous_id': None,
    'first_name': None,
    'last_name': None,
    'organization': 'Reed Group',
    'title': 'Tax adviser',
    'image': None,
    'created': '2022-04-19T13:59:06+00:00',
    'updated': '2022-04-19T14:01:12+00:00',
    'last_event_date': None,
    'location': {'address1': '41059 Gonzalez Light',
     'address2': None,
     'city': 'Columbus',
     'country': 'United States',
     'latitude': None,
     'longitude': None,
     'region': 'Ohio',
     'zip': '04505',
     'timezone': 'America/New_York'},
    'properties': {}},
   'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X9EV7DJSCR048H7KWT57/'},
   'relationships': {'lists': {'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X9EV7DJSCR048H7KWT57/relationships/lists/',
      'related': 'https://a.klaviyo.com/api/profiles/01G111X9EV7DJSCR048H7KWT57/lists/'}},
    'segments': {'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X9EV7DJSCR048H7KWT57/relationships/segments/',
      'related': 'https://a.klaviyo.com/api/profiles/01G111X9EV7DJSCR048H7KWT57/segments/'}}}}],
 'links': {'self': 'https://a.klaviyo.com/api/profiles/',
  'next': 'https://a.klaviyo.com/api/profiles/?page%5Bcursor%5D=bmV4dDo6aWQ6OjAxRzExMVg5RVY3REpTQ1IwNDhIN0tXVDU3',
  'prev': None}}

Hello World: HTTP Version¶

The code block below shows how to accomplish this API call using a direct HTTP request. It leads to the same results as a SDK example above.

If you want to see more simple HTTP code snippets, you should look through Klaviyo's API documentation. It has examples of how to make direct API calls on each of Klaviyo's endpoints in a number of frameworks including JavaScript, Node, Python, Java, PHP, and Shell among others.

In [7]:

# NOTE: Does not include pagination (see Example 3.2); so, will not return all customers.

# The headers for a direct call on the endpoint should look similar to this (with an updated revision date)
headers = {
    "accept": "application/json",
    "revision": "2022-10-17",
    "Authorization": "Klaviyo-API-Key " + private_key
}

# specify the endpoint you want to hit
url = "https://a.klaviyo.com/api/profiles/"

# execute the request
response = requests.request("GET", 
                            url, 
                            headers=headers)

# convert json string to dictionary
response_dict = json.loads(response.text)
response_dict

Out[7]:

{'data': [{'type': 'profile',
   'id': '01G111X7K5VMWZR03WV4MHRDAV',
   'attributes': {'email': 'kristina.stephens_138@klaviyo-demo.com',
    'phone_number': '+18409121959',
    'external_id': None,
    'anonymous_id': None,
    'first_name': 'Kristina',
    'last_name': 'Stephens',
    'organization': None,
    'title': None,
    'image': None,
    'created': '2022-04-19T13:59:05+00:00',
    'updated': '2022-04-19T14:01:10+00:00',
    'last_event_date': None,
    'location': {'address1': None,
     'address2': None,
     'city': 'Columbus',
     'country': 'United States',
     'latitude': None,
     'longitude': None,
     'region': 'Ohio',
     'zip': '18335',
     'timezone': 'America/New_York'},
    'properties': {}},
   'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X7K5VMWZR03WV4MHRDAV/'},
   'relationships': {'lists': {'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X7K5VMWZR03WV4MHRDAV/relationships/lists/',
      'related': 'https://a.klaviyo.com/api/profiles/01G111X7K5VMWZR03WV4MHRDAV/lists/'}},
    'segments': {'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X7K5VMWZR03WV4MHRDAV/relationships/segments/',
      'related': 'https://a.klaviyo.com/api/profiles/01G111X7K5VMWZR03WV4MHRDAV/segments/'}}}},
  {'type': 'profile',
   'id': '01G111X7VE1V41ZM36X2NKV02F',
   'attributes': {'email': 'julia.dixon_222@klaviyo-demo.com',
    'phone_number': '+18470101517',
    'external_id': None,
    'anonymous_id': None,
    'first_name': 'Julia',
    'last_name': 'Dixon',
    'organization': None,
    'title': None,
    'image': None,
    'created': '2022-04-19T13:59:05+00:00',
    'updated': '2022-04-19T14:01:11+00:00',
    'last_event_date': None,
    'location': {'address1': None,
     'address2': None,
     'city': 'Columbus',
     'country': 'United States',
     'latitude': None,
     'longitude': None,
     'region': 'Ohio',
     'zip': '80623',
     'timezone': 'America/New_York'},
    'properties': {}},
   'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X7VE1V41ZM36X2NKV02F/'},
   'relationships': {'lists': {'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X7VE1V41ZM36X2NKV02F/relationships/lists/',
      'related': 'https://a.klaviyo.com/api/profiles/01G111X7VE1V41ZM36X2NKV02F/lists/'}},
    'segments': {'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X7VE1V41ZM36X2NKV02F/relationships/segments/',
      'related': 'https://a.klaviyo.com/api/profiles/01G111X7VE1V41ZM36X2NKV02F/segments/'}}}},
  {'type': 'profile',
   'id': '01G111X7Y9WNVPZVY1BPZC5Q7Z',
   'attributes': {'email': 'marsha.porter_596@klaviyo-demo.com',
    'phone_number': '+14409121807',
    'external_id': None,
    'anonymous_id': None,
    'first_name': 'Marsha',
    'last_name': 'Porter',
    'organization': None,
    'title': None,
    'image': None,
    'created': '2022-04-19T13:59:05+00:00',
    'updated': '2022-04-19T14:01:11+00:00',
    'last_event_date': None,
    'location': {'address1': None,
     'address2': None,
     'city': 'Columbus',
     'country': 'United States',
     'latitude': None,
     'longitude': None,
     'region': 'Ohio',
     'zip': '81576',
     'timezone': 'America/New_York'},
    'properties': {}},
   'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X7Y9WNVPZVY1BPZC5Q7Z/'},
   'relationships': {'lists': {'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X7Y9WNVPZVY1BPZC5Q7Z/relationships/lists/',
      'related': 'https://a.klaviyo.com/api/profiles/01G111X7Y9WNVPZVY1BPZC5Q7Z/lists/'}},
    'segments': {'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X7Y9WNVPZVY1BPZC5Q7Z/relationships/segments/',
      'related': 'https://a.klaviyo.com/api/profiles/01G111X7Y9WNVPZVY1BPZC5Q7Z/segments/'}}}},
  {'type': 'profile',
   'id': '01G111X811JG59BMHDE8QZ2KEG',
   'attributes': {'email': 'tara.wagner_206@klaviyo-demo.com',
    'phone_number': '+17700006465',
    'external_id': None,
    'anonymous_id': None,
    'first_name': 'Tara',
    'last_name': 'Wagner',
    'organization': None,
    'title': None,
    'image': None,
    'created': '2022-04-19T13:59:05+00:00',
    'updated': '2022-04-19T14:01:11+00:00',
    'last_event_date': None,
    'location': {'address1': None,
     'address2': None,
     'city': 'Columbus',
     'country': 'United States',
     'latitude': None,
     'longitude': None,
     'region': 'Ohio',
     'zip': '24981',
     'timezone': 'America/New_York'},
    'properties': {}},
   'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X811JG59BMHDE8QZ2KEG/'},
   'relationships': {'lists': {'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X811JG59BMHDE8QZ2KEG/relationships/lists/',
      'related': 'https://a.klaviyo.com/api/profiles/01G111X811JG59BMHDE8QZ2KEG/lists/'}},
    'segments': {'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X811JG59BMHDE8QZ2KEG/relationships/segments/',
      'related': 'https://a.klaviyo.com/api/profiles/01G111X811JG59BMHDE8QZ2KEG/segments/'}}}},
  {'type': 'profile',
   'id': '01G111X83YE7FXWD8GDFBB8NVE',
   'attributes': {'email': 'jack.medina_603@klaviyo-demo.com',
    'phone_number': '+17235667680',
    'external_id': None,
    'anonymous_id': None,
    'first_name': 'Jack',
    'last_name': 'Medina',
    'organization': None,
    'title': None,
    'image': None,
    'created': '2022-04-19T13:59:05+00:00',
    'updated': '2022-04-19T14:01:11+00:00',
    'last_event_date': None,
    'location': {'address1': None,
     'address2': None,
     'city': 'Columbus',
     'country': 'United States',
     'latitude': None,
     'longitude': None,
     'region': 'Ohio',
     'zip': '49784',
     'timezone': 'America/New_York'},
    'properties': {}},
   'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X83YE7FXWD8GDFBB8NVE/'},
   'relationships': {'lists': {'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X83YE7FXWD8GDFBB8NVE/relationships/lists/',
      'related': 'https://a.klaviyo.com/api/profiles/01G111X83YE7FXWD8GDFBB8NVE/lists/'}},
    'segments': {'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X83YE7FXWD8GDFBB8NVE/relationships/segments/',
      'related': 'https://a.klaviyo.com/api/profiles/01G111X83YE7FXWD8GDFBB8NVE/segments/'}}}},
  {'type': 'profile',
   'id': '01G111X86STXA6NYTJ3GJJRD00',
   'attributes': {'email': 'devon.ortiz_362@klaviyo-demo.com',
    'phone_number': '+16032688420',
    'external_id': None,
    'anonymous_id': None,
    'first_name': 'Devon',
    'last_name': 'Ortiz',
    'organization': None,
    'title': None,
    'image': None,
    'created': '2022-04-19T13:59:05+00:00',
    'updated': '2022-04-19T14:01:11+00:00',
    'last_event_date': None,
    'location': {'address1': None,
     'address2': None,
     'city': 'Columbus',
     'country': 'United States',
     'latitude': None,
     'longitude': None,
     'region': 'Ohio',
     'zip': '17133',
     'timezone': 'America/New_York'},
    'properties': {}},
   'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X86STXA6NYTJ3GJJRD00/'},
   'relationships': {'lists': {'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X86STXA6NYTJ3GJJRD00/relationships/lists/',
      'related': 'https://a.klaviyo.com/api/profiles/01G111X86STXA6NYTJ3GJJRD00/lists/'}},
    'segments': {'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X86STXA6NYTJ3GJJRD00/relationships/segments/',
      'related': 'https://a.klaviyo.com/api/profiles/01G111X86STXA6NYTJ3GJJRD00/segments/'}}}},
  {'type': 'profile',
   'id': '01G111X8A4KXWMXZX564EYDAMM',
   'attributes': {'email': 'elizabeth.holland_998@klaviyo-demo.com',
    'phone_number': '+16772197540',
    'external_id': None,
    'anonymous_id': None,
    'first_name': 'Elizabeth',
    'last_name': 'Holland',
    'organization': None,
    'title': None,
    'image': None,
    'created': '2022-04-19T13:59:05+00:00',
    'updated': '2022-04-19T14:01:11+00:00',
    'last_event_date': None,
    'location': {'address1': None,
     'address2': None,
     'city': 'Columbus',
     'country': 'United States',
     'latitude': None,
     'longitude': None,
     'region': 'Ohio',
     'zip': '19422',
     'timezone': 'America/New_York'},
    'properties': {}},
   'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X8A4KXWMXZX564EYDAMM/'},
   'relationships': {'lists': {'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X8A4KXWMXZX564EYDAMM/relationships/lists/',
      'related': 'https://a.klaviyo.com/api/profiles/01G111X8A4KXWMXZX564EYDAMM/lists/'}},
    'segments': {'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X8A4KXWMXZX564EYDAMM/relationships/segments/',
      'related': 'https://a.klaviyo.com/api/profiles/01G111X8A4KXWMXZX564EYDAMM/segments/'}}}},
  {'type': 'profile',
   'id': '01G111X8D0W3H7FAF3DH7K6M5Z',
   'attributes': {'email': 'gregory.rice_105@klaviyo-demo.com',
    'phone_number': '+17053390984',
    'external_id': None,
    'anonymous_id': None,
    'first_name': 'Gregory',
    'last_name': 'Rice',
    'organization': None,
    'title': None,
    'image': None,
    'created': '2022-04-19T13:59:05+00:00',
    'updated': '2022-04-19T14:01:11+00:00',
    'last_event_date': None,
    'location': {'address1': None,
     'address2': None,
     'city': 'Columbus',
     'country': 'United States',
     'latitude': None,
     'longitude': None,
     'region': 'Ohio',
     'zip': '53670',
     'timezone': 'America/New_York'},
    'properties': {}},
   'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X8D0W3H7FAF3DH7K6M5Z/'},
   'relationships': {'lists': {'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X8D0W3H7FAF3DH7K6M5Z/relationships/lists/',
      'related': 'https://a.klaviyo.com/api/profiles/01G111X8D0W3H7FAF3DH7K6M5Z/lists/'}},
    'segments': {'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X8D0W3H7FAF3DH7K6M5Z/relationships/segments/',
      'related': 'https://a.klaviyo.com/api/profiles/01G111X8D0W3H7FAF3DH7K6M5Z/segments/'}}}},
  {'type': 'profile',
   'id': '01G111X8FV7W8EQCTNAC04K7TP',
   'attributes': {'email': 'sheila.berry_441@klaviyo-demo.com',
    'phone_number': '+11052899276',
    'external_id': None,
    'anonymous_id': None,
    'first_name': 'Sheila',
    'last_name': 'Berry',
    'organization': None,
    'title': None,
    'image': None,
    'created': '2022-04-19T13:59:05+00:00',
    'updated': '2022-04-19T14:01:12+00:00',
    'last_event_date': None,
    'location': {'address1': None,
     'address2': None,
     'city': 'Columbus',
     'country': 'United States',
     'latitude': None,
     'longitude': None,
     'region': 'Ohio',
     'zip': '15923',
     'timezone': 'America/New_York'},
    'properties': {}},
   'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X8FV7W8EQCTNAC04K7TP/'},
   'relationships': {'lists': {'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X8FV7W8EQCTNAC04K7TP/relationships/lists/',
      'related': 'https://a.klaviyo.com/api/profiles/01G111X8FV7W8EQCTNAC04K7TP/lists/'}},
    'segments': {'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X8FV7W8EQCTNAC04K7TP/relationships/segments/',
      'related': 'https://a.klaviyo.com/api/profiles/01G111X8FV7W8EQCTNAC04K7TP/segments/'}}}},
  {'type': 'profile',
   'id': '01G111X8JG0B39ARRJPN3NJ893',
   'attributes': {'email': 'terrence.jennings_421@klaviyo-demo.com',
    'phone_number': '+11232100105',
    'external_id': None,
    'anonymous_id': None,
    'first_name': 'Terrence',
    'last_name': 'Jennings',
    'organization': None,
    'title': None,
    'image': None,
    'created': '2022-04-19T13:59:06+00:00',
    'updated': '2022-04-19T14:01:12+00:00',
    'last_event_date': None,
    'location': {'address1': None,
     'address2': None,
     'city': 'Columbus',
     'country': 'United States',
     'latitude': None,
     'longitude': None,
     'region': 'Ohio',
     'zip': '43114',
     'timezone': 'America/New_York'},
    'properties': {}},
   'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X8JG0B39ARRJPN3NJ893/'},
   'relationships': {'lists': {'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X8JG0B39ARRJPN3NJ893/relationships/lists/',
      'related': 'https://a.klaviyo.com/api/profiles/01G111X8JG0B39ARRJPN3NJ893/lists/'}},
    'segments': {'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X8JG0B39ARRJPN3NJ893/relationships/segments/',
      'related': 'https://a.klaviyo.com/api/profiles/01G111X8JG0B39ARRJPN3NJ893/segments/'}}}},
  {'type': 'profile',
   'id': '01G111X8N9FG81M2Z90NMTMZTT',
   'attributes': {'email': 'gerald.harvey_101@klaviyo-demo.com',
    'phone_number': '(539)-331-2511',
    'external_id': None,
    'anonymous_id': None,
    'first_name': 'Gerald',
    'last_name': 'Harvey',
    'organization': None,
    'title': None,
    'image': None,
    'created': '2022-04-19T13:59:06+00:00',
    'updated': '2022-04-19T14:01:12+00:00',
    'last_event_date': None,
    'location': {'address1': None,
     'address2': None,
     'city': 'Hampton',
     'country': None,
     'latitude': None,
     'longitude': None,
     'region': 'South Dakota',
     'zip': '38475',
     'timezone': None},
    'properties': {}},
   'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X8N9FG81M2Z90NMTMZTT/'},
   'relationships': {'lists': {'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X8N9FG81M2Z90NMTMZTT/relationships/lists/',
      'related': 'https://a.klaviyo.com/api/profiles/01G111X8N9FG81M2Z90NMTMZTT/lists/'}},
    'segments': {'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X8N9FG81M2Z90NMTMZTT/relationships/segments/',
      'related': 'https://a.klaviyo.com/api/profiles/01G111X8N9FG81M2Z90NMTMZTT/segments/'}}}},
  {'type': 'profile',
   'id': '01G111X8QXRWDW2H56R3V9MVPN',
   'attributes': {'email': 'sherri.bryant_592@klaviyo-demo.com',
    'phone_number': '+14383706640',
    'external_id': None,
    'anonymous_id': None,
    'first_name': 'Sherri',
    'last_name': 'Bryant',
    'organization': None,
    'title': None,
    'image': None,
    'created': '2022-04-19T13:59:06+00:00',
    'updated': '2022-04-19T14:01:12+00:00',
    'last_event_date': None,
    'location': {'address1': None,
     'address2': None,
     'city': 'Columbus',
     'country': 'United States',
     'latitude': None,
     'longitude': None,
     'region': 'Ohio',
     'zip': '62723',
     'timezone': 'America/New_York'},
    'properties': {}},
   'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X8QXRWDW2H56R3V9MVPN/'},
   'relationships': {'lists': {'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X8QXRWDW2H56R3V9MVPN/relationships/lists/',
      'related': 'https://a.klaviyo.com/api/profiles/01G111X8QXRWDW2H56R3V9MVPN/lists/'}},
    'segments': {'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X8QXRWDW2H56R3V9MVPN/relationships/segments/',
      'related': 'https://a.klaviyo.com/api/profiles/01G111X8QXRWDW2H56R3V9MVPN/segments/'}}}},
  {'type': 'profile',
   'id': '01G111X8TQYQ8GK86BSV7F3516',
   'attributes': {'email': 'sylvia.diaz_301@klaviyo-demo.com',
    'phone_number': '+18807279925',
    'external_id': None,
    'anonymous_id': None,
    'first_name': 'Sylvia',
    'last_name': 'Diaz',
    'organization': None,
    'title': None,
    'image': None,
    'created': '2022-04-19T13:59:06+00:00',
    'updated': '2022-04-19T14:01:12+00:00',
    'last_event_date': None,
    'location': {'address1': None,
     'address2': None,
     'city': 'Columbus',
     'country': 'United States',
     'latitude': None,
     'longitude': None,
     'region': 'Ohio',
     'zip': '72141',
     'timezone': 'America/New_York'},
    'properties': {}},
   'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X8TQYQ8GK86BSV7F3516/'},
   'relationships': {'lists': {'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X8TQYQ8GK86BSV7F3516/relationships/lists/',
      'related': 'https://a.klaviyo.com/api/profiles/01G111X8TQYQ8GK86BSV7F3516/lists/'}},
    'segments': {'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X8TQYQ8GK86BSV7F3516/relationships/segments/',
      'related': 'https://a.klaviyo.com/api/profiles/01G111X8TQYQ8GK86BSV7F3516/segments/'}}}},
  {'type': 'profile',
   'id': '01G111X8XGBB1HVJ2MQ6SF6YAY',
   'attributes': {'email': 'yvonne.sullivan_716@klaviyo-demo.com',
    'phone_number': '+19905230491',
    'external_id': None,
    'anonymous_id': None,
    'first_name': 'Yvonne',
    'last_name': 'Sullivan',
    'organization': None,
    'title': None,
    'image': None,
    'created': '2022-04-19T13:59:06+00:00',
    'updated': '2022-04-19T14:01:12+00:00',
    'last_event_date': None,
    'location': {'address1': None,
     'address2': None,
     'city': 'Columbus',
     'country': 'United States',
     'latitude': None,
     'longitude': None,
     'region': 'Ohio',
     'zip': '10158',
     'timezone': 'America/New_York'},
    'properties': {}},
   'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X8XGBB1HVJ2MQ6SF6YAY/'},
   'relationships': {'lists': {'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X8XGBB1HVJ2MQ6SF6YAY/relationships/lists/',
      'related': 'https://a.klaviyo.com/api/profiles/01G111X8XGBB1HVJ2MQ6SF6YAY/lists/'}},
    'segments': {'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X8XGBB1HVJ2MQ6SF6YAY/relationships/segments/',
      'related': 'https://a.klaviyo.com/api/profiles/01G111X8XGBB1HVJ2MQ6SF6YAY/segments/'}}}},
  {'type': 'profile',
   'id': '01G111X9093JDHA07DDM41YKHR',
   'attributes': {'email': 'micheal.simmmons_513@klaviyo-demo.com',
    'phone_number': '+14474215178',
    'external_id': None,
    'anonymous_id': None,
    'first_name': 'Micheal',
    'last_name': 'Simmmons',
    'organization': None,
    'title': None,
    'image': None,
    'created': '2022-04-19T13:59:06+00:00',
    'updated': '2022-04-19T14:01:12+00:00',
    'last_event_date': None,
    'location': {'address1': None,
     'address2': None,
     'city': 'Columbus',
     'country': 'United States',
     'latitude': None,
     'longitude': None,
     'region': 'Ohio',
     'zip': '37232',
     'timezone': 'America/New_York'},
    'properties': {}},
   'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X9093JDHA07DDM41YKHR/'},
   'relationships': {'lists': {'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X9093JDHA07DDM41YKHR/relationships/lists/',
      'related': 'https://a.klaviyo.com/api/profiles/01G111X9093JDHA07DDM41YKHR/lists/'}},
    'segments': {'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X9093JDHA07DDM41YKHR/relationships/segments/',
      'related': 'https://a.klaviyo.com/api/profiles/01G111X9093JDHA07DDM41YKHR/segments/'}}}},
  {'type': 'profile',
   'id': '01G111X934EGZPT9QXG2E66M6C',
   'attributes': {'email': 'martha.turner_923@klaviyo-demo.com',
    'phone_number': '+10081188694',
    'external_id': None,
    'anonymous_id': None,
    'first_name': 'Martha',
    'last_name': 'Turner',
    'organization': None,
    'title': None,
    'image': None,
    'created': '2022-04-19T13:59:06+00:00',
    'updated': '2022-04-19T14:01:12+00:00',
    'last_event_date': None,
    'location': {'address1': None,
     'address2': None,
     'city': 'Columbus',
     'country': 'United States',
     'latitude': None,
     'longitude': None,
     'region': 'Ohio',
     'zip': '24648',
     'timezone': 'America/New_York'},
    'properties': {}},
   'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X934EGZPT9QXG2E66M6C/'},
   'relationships': {'lists': {'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X934EGZPT9QXG2E66M6C/relationships/lists/',
      'related': 'https://a.klaviyo.com/api/profiles/01G111X934EGZPT9QXG2E66M6C/lists/'}},
    'segments': {'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X934EGZPT9QXG2E66M6C/relationships/segments/',
      'related': 'https://a.klaviyo.com/api/profiles/01G111X934EGZPT9QXG2E66M6C/segments/'}}}},
  {'type': 'profile',
   'id': '01G111X963313P874JREC48G4Y',
   'attributes': {'email': 'kenneth.daniels_954@klaviyo-demo.com',
    'phone_number': '+15363857084',
    'external_id': None,
    'anonymous_id': None,
    'first_name': 'Kenneth',
    'last_name': 'Daniels',
    'organization': None,
    'title': None,
    'image': None,
    'created': '2022-04-19T13:59:06+00:00',
    'updated': '2022-04-19T14:01:12+00:00',
    'last_event_date': None,
    'location': {'address1': None,
     'address2': None,
     'city': 'Columbus',
     'country': 'United States',
     'latitude': None,
     'longitude': None,
     'region': 'Ohio',
     'zip': '80253',
     'timezone': 'America/New_York'},
    'properties': {}},
   'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X963313P874JREC48G4Y/'},
   'relationships': {'lists': {'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X963313P874JREC48G4Y/relationships/lists/',
      'related': 'https://a.klaviyo.com/api/profiles/01G111X963313P874JREC48G4Y/lists/'}},
    'segments': {'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X963313P874JREC48G4Y/relationships/segments/',
      'related': 'https://a.klaviyo.com/api/profiles/01G111X963313P874JREC48G4Y/segments/'}}}},
  {'type': 'profile',
   'id': '01G111X98XVAF6RQZ46BBS7TED',
   'attributes': {'email': 'catherine.sullivan_289@klaviyo-demo.com',
    'phone_number': '+16175558793',
    'external_id': None,
    'anonymous_id': None,
    'first_name': None,
    'last_name': None,
    'organization': 'Warner-Black',
    'title': 'Public relations account executive',
    'image': None,
    'created': '2022-04-19T13:59:06+00:00',
    'updated': '2022-04-19T14:01:12+00:00',
    'last_event_date': None,
    'location': {'address1': '49955 Joshua Springs',
     'address2': 'Apt. 014',
     'city': 'Columbus',
     'country': 'United States',
     'latitude': None,
     'longitude': None,
     'region': 'Ohio',
     'zip': '68533',
     'timezone': 'America/New_York'},
    'properties': {}},
   'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X98XVAF6RQZ46BBS7TED/'},
   'relationships': {'lists': {'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X98XVAF6RQZ46BBS7TED/relationships/lists/',
      'related': 'https://a.klaviyo.com/api/profiles/01G111X98XVAF6RQZ46BBS7TED/lists/'}},
    'segments': {'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X98XVAF6RQZ46BBS7TED/relationships/segments/',
      'related': 'https://a.klaviyo.com/api/profiles/01G111X98XVAF6RQZ46BBS7TED/segments/'}}}},
  {'type': 'profile',
   'id': '01G111X9BZAK6J8A67H7M871CW',
   'attributes': {'email': 'tiffany.wyatt_817@klaviyo-demo.com',
    'phone_number': '+16175559960',
    'external_id': None,
    'anonymous_id': None,
    'first_name': None,
    'last_name': None,
    'organization': 'Arnold and Sons',
    'title': 'Hospital pharmacist',
    'image': None,
    'created': '2022-04-19T13:59:06+00:00',
    'updated': '2022-04-19T14:01:12+00:00',
    'last_event_date': None,
    'location': {'address1': '739 Bishop Mountains',
     'address2': 'Apt. 785',
     'city': 'Columbus',
     'country': 'United States',
     'latitude': None,
     'longitude': None,
     'region': 'Ohio',
     'zip': '86148',
     'timezone': 'America/New_York'},
    'properties': {}},
   'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X9BZAK6J8A67H7M871CW/'},
   'relationships': {'lists': {'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X9BZAK6J8A67H7M871CW/relationships/lists/',
      'related': 'https://a.klaviyo.com/api/profiles/01G111X9BZAK6J8A67H7M871CW/lists/'}},
    'segments': {'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X9BZAK6J8A67H7M871CW/relationships/segments/',
      'related': 'https://a.klaviyo.com/api/profiles/01G111X9BZAK6J8A67H7M871CW/segments/'}}}},
  {'type': 'profile',
   'id': '01G111X9EV7DJSCR048H7KWT57',
   'attributes': {'email': 'willie.hammond_555@klaviyo-demo.com',
    'phone_number': '+16175551539',
    'external_id': None,
    'anonymous_id': None,
    'first_name': None,
    'last_name': None,
    'organization': 'Reed Group',
    'title': 'Tax adviser',
    'image': None,
    'created': '2022-04-19T13:59:06+00:00',
    'updated': '2022-04-19T14:01:12+00:00',
    'last_event_date': None,
    'location': {'address1': '41059 Gonzalez Light',
     'address2': None,
     'city': 'Columbus',
     'country': 'United States',
     'latitude': None,
     'longitude': None,
     'region': 'Ohio',
     'zip': '04505',
     'timezone': 'America/New_York'},
    'properties': {}},
   'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X9EV7DJSCR048H7KWT57/'},
   'relationships': {'lists': {'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X9EV7DJSCR048H7KWT57/relationships/lists/',
      'related': 'https://a.klaviyo.com/api/profiles/01G111X9EV7DJSCR048H7KWT57/lists/'}},
    'segments': {'links': {'self': 'https://a.klaviyo.com/api/profiles/01G111X9EV7DJSCR048H7KWT57/relationships/segments/',
      'related': 'https://a.klaviyo.com/api/profiles/01G111X9EV7DJSCR048H7KWT57/segments/'}}}}],
 'links': {'self': 'https://a.klaviyo.com/api/profiles/',
  'next': 'https://a.klaviyo.com/api/profiles/?page%5Bcursor%5D=bmV4dDo6aWQ6OjAxRzExMVg5RVY3REpTQ1IwNDhIN0tXVDU3',
  'prev': None}}

How are Klaviyo's API responses structured?¶

As you can see, the data is returned in a nested dictionary format (i.e. a JSON). The core information that we requested for this call lives in the data field.

The data field can take different forms depending on the data being queried. For example, the data field can map to a dictionary or a list of dictionaries depending on whether you are querying a single record or many.

Klaviyo's response for a GET request returning multiple records has the following form:

# response dictionary
{
    'data': [
        record_dict_1,
        record_dict_2,
        ...,
        record_dict_n
    ],
    'links': {
        ... # links not shown. Explained further in Example 4.2
    }
}

The content and schema of these record dicts depend on the data being requested. Regardless of the data queried, all Klaviyo API responses should follow the form shown above with a data field containing the content of the request and a links field containing pagination metadata.

Now that we have a better understanding of how API responses are structured generally, let's take a look at how the record_dicts can be structured.

How is the customer profile data model structured specifically?¶

The data field in an API response maps to a dictionary or list of dictionaries. The content and schema for the dicts themselves is dependent on the type of record being requested.

Let's take a look at how customer profile dicts are structured since they are the subject of this Hello World example. The core information about a customer account exists in the attributes field.

# this is the schema for data on an individual customer profile
{
  "type": "profile",
  "id": "string",
  "attributes": {
    "email": "string",
    "phone_number": "string",
    "external_id": "string",
    "anonymous_id": "string",
    "first_name": "string",
    "last_name": "string",
    "organization": "string",
    "title": "string",
    "image": "string",
    "created": "string (UTC-formatted datetime)",
    "updated": "string (UTC-formatted datetime)",
    "last_event_date": "string (UTC-formatted datetime)",
    "location": {
      "address1": "string",
      "address2": "string",
      "city": "string",
      "country": "string",
      "latitude": "string",
      "longitude": "string",
      "region": "string",
      "zip": "string",
      "timezone": "string"
    },
    "properties": {} # holds any custom attributes
  },
  ... # links and relationships not shown
}

Profiles in Klaviyo's database contain core attributes about these customers (e.g. address, name, communication methods) as well as unique profiles identifiers. One such identifier is a profile's Klaviyo ID, which shows up under the id field as a 26 character string.

If you have questions about how events or profiles are structured or what field names refer to, please consult Klaviyo's API documentation

Events and profiles have each been mentioned throughout this guide. Let's clarify what these terms mean.

A customer profile is a set of information unique to each of the customers of your business. Events are things that happen related to these customers (e.g. product orders or email delivery).

These events usually have data describing the specifics of what happened. For example, an Ordered Product event captures information about the product price, product name, time of purchase, among other information.

Each event is associated with a single customer profile. Profiles, however, can be associated with many events.

You can learn more about customer profiles, events, and metrics from Klaviyo's help center.

Customer events can be viewed in Klaviyo or retrieved with an API call. To make this more clear, below is a screenshot showing a single customer's timeline of events: