Navigate API documentation
You know what an API is, and now you know how to format JSON. How can we put this all together to make any API call we would like?
The key is in the API documentation. Every API endpoint has a reference document that includes detailed information about all of the data that you need to make an API call to that endpoint.
In addition to API reference docs, the developer portal also contains helpful guides to developing with Klaviyo. Our developer guides will walk you through best practices for implementing solutions to common business needs, like setting up custom integrations, catalogs, and more.
Dissecting the API documentation
You've seen the anatomy of an API call and how each part of an API call shows up in Postman. Each piece of an API call also has corresponding information about it in the API documentation. Read through the tabs below to learn about how to interpret and apply each piece of the documentation.
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 of the 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.
It’s best practice to narrow down the scopes of each API key to only the ones you need. If you only add necessary scopes, there are fewer repercussions if your key is accidentally stolen or hacked.
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
Beside each parameter, a red required badge will show up next to every parameter that is required.
The parameters are editable within the documentation.
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.
We will go over what these codes mean in the next section of this course.
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.
Klaviyo generally follows best practices and conventions when creating our API documentation, so the patterns here will likely help you understand how to navigate any API documentation going forward.
Differentiate between client and server
Throughout the API documentation, you may see the terms client-side and server-side used frequently. Read more about what each of these terms means below.
Client vs. Server
In the world of computing, a client refers to the entity making the request. The server is where the data is hosted and is where the request is headed.
For example, as you access the Klaviyo Academy, your computer is acting as a client. It is making requests to the server that hosts the Klaviyo Academy. The server responds to the request and returns a response to the client, allowing this web page to render on your computer.
In the case of Beantown Coffee, the business expanding into coffee seminars, the client refers to Beantown's website, which can make requests to a server that Beantown hosts separately from the webpage. The server contains custom code and can send data back that shows up on the webpage.
The image below represents the relationship between clients, servers, and APIs. First, the client uses HTTP Methods (like GET or POST) to ask the API for something. Then, it's the API’s job to provide the desired response. Behind the scenes, the API requests the data from the server, which returns data to the API. The API then formats this data in JSON and returns it to you, the client.
Client-side API calls
Client-side API calls are grouped under the Client section of the API reference documentation. These calls are run directly from the client, typically your brand's website.
Anyone on the web can access your website and its source code. Therefore, client-side API calls do not use a private API key, since private API keys are confidential. Instead, client-side API calls use a public API key, the 6 digit key that can be found in your account's API keys tab.
Note that, since our client-side endpoints are designed to be called from public-facing environments, they cannot be used to access sensitive data. Use client-side API calls to log events that do not contain any sensitive information, such as tracking when an identified customer views a product on your site. Never use a private API key with the Client API.
When you integrate Klaviyo with your website, a line of code, also known as klaviyo.js, is automatically entered on your website. This code snippet uses our client API to identify profiles and track onsite activity like Active on Site.
Server-side API calls
All other API endpoints that are not under the Client header are used for server-side API calls. The majority of your API calls will be from the server-side.
Since the code for these calls is hosted on your own server (rather than on the web), you can pass sensitive information with server-side calls, including sensitive customer data and your private API key.
Use server-side API calls for any custom coding you would like, such as sending custom order events after a customer entered their shipping information.