Interpret the API reference documentation
In this section, you'll learn about the API reference documentation, which includes a page for every Klaviyo API endpoint available.
The API reference documentation lays out and defines the requirements for making a specific API call. It takes what you already know about the anatomy of API calls and provides you with the rules for structuring and customizing your call.
Check out the diagram below to see where each element of an API call shows up in the API reference documentation. Let's look at the Get Event endpoint.
The anatomy of an API doc
Read through the tabs below to learn about how to interpret and apply each piece of the documentation. API documentation is generally structured consistently across platforms, so the insights you gain from navigating Klaviyo's API documentation can be applied to others as well, equipping you to start developing in any platform.
Method and endpoint
Each endpoint's documentation displays the endpoint's name, method, and request URL.
In this example, the blue POST signifies that the Create List endpoint is a POST request, and the request URL is listed immediately under the endpoint's name.
Scopes
The scopes listed on each endpoint refer to the required scopes, or permissions, of your API key.
When you create a private API key, you can select whether the key has read or write access to different aspects of Klaviyo. If you are using the key for a specific endpoint, you can find the scopes you need in each endpoint's documentation.
You can think of scopes as analogous to user roles in Klaviyo. Your account Owner is able to access everything, but a Content Creator only has access to limited sections of the Klaviyo UI. Similarly, an API key with full access can alter every part of your Klaviyo account, while an API key with read and write access to profiles can only access and alter your Klaviyo profiles.
Parameters
All of the parameters for each endpoint are listed in the main body text of each endpoint's documentation. This includes:
- Query parameters
- Path parameters
- Body parameters
A red required badge will appear next to a parameter if it is required for the request.
The parameters section is crucial for understanding how to nest and structure the payload of your API request.
The parameters are editable within the documentation, and values you modify here will be reflected in the code example on the right-hand side of the page.
Responses
At the bottom of each endpoint's documentation, there is a section for responses. This includes the data you can expect to receive for the three main classes of response codes:
- 2xx - success
- 4xx - client error
- 5xx - server error
The responses in the documentation show what you can expect to receive with all of these response codes.
Check out our course on troubleshooting API calls for more information on what these response codes mean.
Example
Each API endpoint has an example request and response. These examples take everything from the documentation and format it in a way that you would actually see when making API calls. You can see all required headers in this example request.
When you edit parameters in the documentation, they will automatically be updated within the example request. You can refer to our JSON:API feature guides for detailed information on how to format each parameter.
Then, you can copy sections of the example request, such as the JSON body, into Postman or wherever you make API calls.
The example response shows what data you are expected to receive from each API call. This can be useful to ensure you are using the correct endpoint.