Getting Started with Klaviyo APIs

read
Last updated at:

Overview

This getting started guide will walk you through a foundational understanding of making API calls with Klaviyo and how the Klaviyo APIs can benefit your business. Your first API calls can be accomplished in as little as 20 minutes from start to finish. In this guide, you will learn how to make a few standard calls. All examples use the List API; however, the steps can be applied to almost any available Klaviyo REST API.

Throughout this guide, we will link out to a glossary when new technical terms are introduced. If you are uncertain about the meaning of a word at any point in the guide, check out the Technical Terms Glossary.

What is a REST API?

REST API is a set of acronyms that stand for Representational State Transfer and Application Programming Interface. These terms can be more simply understood as structured requests that allow a piece of software to talk to another and pass information between them. When you make an API call, you are submitting a request to a server where information is stored, which then returns a response containing your requested data in JSON, or JavaScript Object Notation, format.

More simply, REST APIs allow you to request data stored in Klaviyo and have that data returned to you in a format that is readable by you and by computers. 

whatisanAPI_copy.png

A standard API call happens in seconds. Behind the scenes, your call will:

  1. Send a structured request for data over the internet to the API. Requests are sent via HTTP, a basic network request type that the internet is largely built around
  2. The API will receive the request, process it, and obtain the requested information from Klaviyo's databases
  3. The API then responds to the client application using JSON structured format
  4. You will receive the JSON response from your client application

Although this knowledge is helpful to understand how data transfer works, it isn't necessary to start making API calls and getting value out of what Klaviyo APIs have to offer. Everything you need to know to get started with your first API calls will be covered in the following sections.

HTTP Methods

HTTP Methods are the “verbs” by which your requests are sent. There are two HTTP Methods we will address in this guide: GET and POST.  

Although we will not use them here, it is worth noting that most REST APIs support additional HTTP Methods such as PUT, PATCH, and DELETE.

GET

A GET request can be most easily understood as a “read” request. GET requests retrieve information from the API endpoint and return it to you in a JSON-formatted response. These requests only allow you to read data, making them the safest type of request because your data cannot be modified or overwritten with this method.

POST

A POST request can be simply understood as a “write” request. POST allows you to create or add new resources. For example, a POST request to the List API can be used to create a new list in your account, while a GET request can be used to retrieve all available lists.

Klaviyo’s APIs

For a full list of Klaviyo’s available APIs, check out our API Reference docs. In this Getting Started guide, we will use the List API V2. It is worth noting that Klaviyo has two versions of the List API currently listed in the API Reference. Version 2 has a wider range of options and should be used for most purposes, and will hereafter be referred to simply as the List API.

The List API is used for creating lists, managing list memberships, and modifying list subscriptions via a set of endpoints. With the List API, you can quickly retrieve a catalog of all your account’s lists, see details of specific lists, create new lists, and add members and list subscribers.

Make Your First Call

Necessary Tools

APIs offer plenty of flexibility to your workflows and don't require you to use a specific client application or language library to achieve the desired results. Because API calls are made using HTTP requests, nearly every programming language has the ability to send this type of request natively or through a widely available language library. Additionally, depending on your machine and operating system, you can use native applications like Apple’s Terminal or Windows Command Line to make client-side API calls. However, these applications require prior knowledge of command line interfaces.

In this guide, we use a free client application called Postman. Although the platform has a variety of features, the Postman application makes it easier to set up and send an API request by inputting the endpoint, parameters, and authentication into a helpful user interface.

Some Klaviyo APIs support in-browser methods, allowing you to make requests using URL parameters or from within the developer console of your browser. We will not be covering these methods in this guide. 

Set Up Postman

The first step to starting your API journey is to download and install Postman. After installation, launch the program. Postman requires very little setup to get started. In the upper right corner, click New and select Request from the dropdown menu. 

newrequest.png

Give your request a name, and optionally a description, to help you keep track of your API calls. If this is your first time using Postman, you will also need to create a collection in which to save your new request. A collection is a convenient way to organize and keep track of your most used calls. Give your collection a name and click the orange check mark to create it. Then, select your new collection and click Save to [Collection Name]. For this example, we’ve called the new request “Get All Lists” and saved it to the collection “My First API Calls.”

If you are unable to click Save, make sure that you have a Request name filled out and a collection folder selected. The Save button will remain grayed out until you have selected a folder to save to.

savetocollection.png

Now that you have successfully set up Postman, it’s time to make your first API call. This section will walk you through setting up a GET request to retrieve all lists in your Klaviyo account using the List API. After retrieving the list, you will be able to apply some parameters to the call to pull more details about a specific list.

Send a GET Request

Start with the blank request in Postman. The List API endpoint, which can be found in the API Reference docs, is https://a.klaviyo.com/api/v2/lists. Paste the endpoint link into the request URL bar in Postman and select GET as the request method from the dropdown on the left.

listenedpoint.png

Klaviyo requires that all API requests be authenticated in order to protect your account information. Authentication can be complicated depending on the software you are interfacing with, but it is very straightforward with Klaviyo. Klaviyo uses public and private keys to keep your information safe.  

First, you will need to create a Private API Key within your Klaviyo account. If you need help locating your Private API Key, check out this guide to Managing Your API Keys.

Your Private API Key grants you access to potentially sensitive account information. This key should be kept secret at all times and never exposed to the public.

Next, add your Private API Key as a parameter to the request. Click the Params tab, below the request method dropdown. Here, you can set any number of parameters using key/value pairs. In the KEY column, enter api_key as shown below. In the VALUE column, paste your Private API Key that begins with pk_.

autheticate.png 

Postman automatically appends the new parameters to the endpoint URL above. Click Send to submit your request.  

Keep in mind, the more information that the request needs to retrieve, the longer it will take to get a response. If your request is successful, you will see the resulting JSON response in the Body response window below the Params tab. Check out the section on Troubleshooting Errors if you get an error instead.

 JSONresponse.png

Congratulations! Your first Klaviyo API call is complete. Next, let’s take a look at the data that was retrieved. 

Interpret the Response

Here’s the JSON response from the call made from a Klaviyo test account:

[
    {
        "list_name": "SMS Subscribers",
        "list_id": "QWwLBF"
    },
    {
        "list_name": "Newsletter",
        "list_id": "SCYevD"
    },
    {
        "list_name": "Klaviyo",
        "list_id": "UvQPTB"
    }
]

 Like an Excel spreadsheet, the JSON response can be interpreted as column headings, followed by the value in the cells below. Here’s another easy way to visualize the received data:

List Name

List ID

SMS Subscribers

QWwLBF

Newsletter

SCYevD

Klaviyo

UvQPTB

The List API call returned three lists in the test account, providing the name and ID for each list. 

Send a POST Request

Next, let’s try sending a POST request to “write” new information. Using the same endpoint as before, you can make a POST request to add new lists to your Klaviyo account. Adding new lists via API call is a great way to quickly add new lists.

Click New > Request to create a new request. Then, fill out the Request name and select a collection folder. 

 newrequest.png

Your new request will open in a second tab at the top of your workspace. Click into the METHOD dropdown and select POST

newlist.png

Copy and paste the same endpoint you used for your GET request into the request URL bar and add your Private API Key to the Params tab. 

To add new lists to your account, you must define the list name in the body of the request. Click on the Body tab and select form-data. This will allow you to input key/value pairs in the body of the request.

In the KEY column, enter list_name. Case does matter here; your key must use all lowercase.

In the VALUE column, enter the desired name of your new list. Keep in mind that your new list’s name will appear in your account exactly as you enter it here. The call shown below will create a new list in your Klaviyo account with the name My New List.

 bodydata.png

Click Send to submit the POST request and create your new list. 

Interpret the Response

Here’s the JSON response from the call made from a Klaviyo test account:

[
    {
        "list_name": "SMS Subscribers",
        "list_id": "QWwLBF"
    },
    {
        "list_name": "Newsletter",
        "list_id": "SCYevD"
    },
    {
        "list_name": "Klaviyo",
        "list_id": "UvQPTB"
    },
    {
        "list_name": "My New List",
        "list_id": "V9MF2z"
    }
]

In the Body response window, the list_ID of your newly created list will be shown in JSON. Your new list can be located in your Klaviyo account using the List ID or List Name provided in the response. 

Check out the section on Troubleshooting Errors if you see an error message instead of a response like the one above. 

Troubleshoot Errors

Postman also makes it easy to see your request status. A successful call will typically have a status of 200 (OK). If you’re encountering a problem when making an API call, check the status code for a hint at the root cause. 

Below are error statuses you may encounter with troubleshooting tips to help you fix these errors.

403 

The 403 (Forbidden) authentication error is common when getting started with API calls. An incorrect authentication setup, or invalid or expired credentials, can result in errors when sending your GET and POST requests. If you have used an invalid API key, you might see an error message like the following: 

403forbidden.png

To resolve this issue, double check that you are using the correct Private API key that corresponds with your Klaviyo account and have added it in the Params tab. In the Authorization tab, make sure that you select Inherit auth from parent from the dropdown menu. 

404

A request that returns a 404 (Not Found) error may be trying to retrieve information that is not available, or may contain a parameter that is not valid. For example, if you make a call to the List API (endpoint https://a.klaviyo.com/api/v2/list/LIST_ID) for details on a specific list and have used an incorrect List ID, you may get a 404 error status like the following:

listdoesnotexist.png

Check to ensure that the parameters you defined are correct. If a resource you are looking for is missing erroneously, you may need to verify within your account. After confirming the resource exists on the account side, if the error persists please contact our Support Team.

405

The 405 (Method Not Allowed) error can occur when an endpoint does not support a specific HTTP Method. For example, the List API endpoint https://a.klaviyo.com/api/v2/lists does not support the DELETE method. Making a DELETE call to this endpoint will result in an error like the one below. 

methodnotallowed.png

Refer to the API Reference docs for the supported methods of each Klaviyo API.

409

The 409 (Conflict) error, though uncommon, can result when you attempt to create a resource that already exists. If you are trying to update a resource and receive this error, you may need to use PUT or PATCH methods depending on your objective for the resource. Keep in mind that some values may not need to be unique. For example, multiple POST requests to create a new list with the name “Newsletter” will result in multiple lists created with the same List Name, but unique List IDs. 

If you are unable to resolve an error status, please contact our Support Team for further assistance.

Go a Step Further

Check out the List API V2 section of the API Reference document to see more options available from this endpoint.

Give this a try on your own! 

The endpoint https://a.klaviyo.com/api/v2/list/{LIST_ID}/members can be used to retrieve members from or add members to a given list. Try a POST request to add a new member, and then send a GET request to see the new member appear on the list. 

If you run into trouble as you explore the options available with Klaviyo’s API, please check out the additional resources below or reach out to our Support Team.

x
Was this article helpful?
13 out of 19 found this helpful