Relationships
Learn more about resource relationships available with the JSON:API standard.
What are relationships?
Klaviyo’s modern APIs offer powerful new functionality via the relationships
object, a thorough set of syntax offered by JSON:API for modeling relationships between resources. This syntax allows developers to efficiently query specific groups of related resources, eliminating the need to perform redundant queries.
Relationships can be to-one or to-many.
Because of the myriad ways our partners and customers model and sync data to and from Klaviyo, the JSON:API relationship syntax used by the new APIs accounts for a wide variety of use cases. Keep in mind that a full relationship mapping may not always be required for all resources.
The include
query parameter
include
query parameterYou can use ?include=resource1,resource2
as a query parameter to include related resource(s) in a response. For example, a call to Get Event with ?include=profile,metric
will include related profile and metric data for each event in the response. To determine which relationships a specific resource supports, refer to the endpoint’s supported include
values in the endpoint description.
The specified resources must be in a comma-separated list. You cannot use
?include
more than once in your request, i.e,?include=resource1&include=resource2
. Use?include=resource1,resource2
for including multiple related resources. Watch out for whitespaces before or after each comma.
Note that include
values may be singular or plural depending on the relationship between resources:
- Singular (to-one)
GET /api/events/?include=profile
Includes each profile related to each event. - Plural (to-many)
GET /api/profiles/{profile_id}/?include=lists
Includes lists related to a single profile.
Example request and response
In the example request to Get Profile below, ?include=lists,segments
returns any related list and/or segment object(s) related to a specific profile in the included
field of the response:
curl --request GET \
--url 'https://a.klaviyo.com/api/profiles/01HD2CCW560NWG693CYF6KF28S/?include=lists,segments' \
--header 'Authorization: Klaviyo-API-Key your-private-api-key' \
--header 'accept: application/json' \
--header 'revision: 2023-10-15'
{
"data": {
"type": "profile",
"id": "01HD2CCW560NWG693CYF6KF28S",
"attributes": {
"email": "[email protected]",
"first_name": "John",
"last_name": "Appleseed",
"created": "2023-10-18T21:52:18+00:00",
"updated": "2023-10-19T14:03:29+00:00"
},
"relationships": {
"lists": {
"data": [
{
"type": "list",
"id": "TE8Gur"
}
],
"links": {
"self": "https://a.klaviyo.com/api/profiles/01HD2CCW560NWG693CYF6KF28S/relationships/lists/",
"related": "https://a.klaviyo.com/api/profiles/01HD2CCW560NWG693CYF6KF28S/lists/"
}
},
"segments": {
"data": [
{
"type": "segment",
"id": "Wu2ui7"
}
],
"links": {
"self": "https://a.klaviyo.com/api/profiles/01HD2CCW560NWG693CYF6KF28S/relationships/segments/",
"related": "https://a.klaviyo.com/api/profiles/01HD2CCW560NWG693CYF6KF28S/segments/"
}
}
},
"links": {
"self": "https://a.klaviyo.com/api/profiles/01HD2CCW560NWG693CYF6KF28S/"
}
},
"included": [
{
"type": "list",
"id": "TE8Gur",
"attributes": {
"name": "Newsletter",
"created": "2023-08-10T14:59:46+00:00",
"updated": "2023-08-10T14:59:46+00:00"
},
"relationships": {
"profiles": {
"links": {
"self": "https://a.klaviyo.com/api/lists/TE8Gur/relationships/profiles/",
"related": "https://a.klaviyo.com/api/lists/TE8Gur/profiles/"
}
},
"tags": {
"links": {
"self": "https://a.klaviyo.com/api/lists/TE8Gur/relationships/tags/",
"related": "https://a.klaviyo.com/api/lists/TE8Gur/tags/"
}
}
},
"links": {
"self": "https://a.klaviyo.com/api/lists/TE8Gur/"
}
},
{
"type": "segment",
"id": "Wu2ui7",
"attributes": {
"name": "Loyal Customers",
"created": "2023-10-19T20:03:28+00:00",
"updated": "2023-10-19T20:04:09+00:00"
},
"relationships": {
"profiles": {
"links": {
"self": "https://a.klaviyo.com/api/segments/Wu2ui7/relationships/profiles/",
"related": "https://a.klaviyo.com/api/segments/Wu2ui7/profiles/"
}
},
"tags": {
"links": {
"self": "https://a.klaviyo.com/api/segments/Wu2ui7/relationships/tags/",
"related": "https://a.klaviyo.com/api/segments/Wu2ui7/tags/"
}
}
},
"links": {
"self": "https://a.klaviyo.com/api/segments/Wu2ui7/"
}
}
]
}
Scopes
When using relationships, you must use an API key with Read-only (for GET requests) or Full (for GET and POST requests) permissions to both the requested endpoint and its related resource.
For example, to call GET /api/profiles/{profile_id}/?include=lists
the scope of your API key must include read access to both the profiles endpoint and the lists endpoint.
Check out the guide to API scopes to learn more about creating and using scopes.
Relationship support
When a relationship between two resources is defined, there are two main ways of querying this relationship: single source and collection-level.
Single resource relationship support
Let's use /profiles
and /lists
as an example. A common use case for many Klaviyo developers is getting all lists a profile belongs to. With the new APIs, this could be accomplished the following ways:
GET /api/profiles/{profile_id}/lists
Get the lists for a single profile directly. Do this if you do not need the profile resource itself, you only need the list.GET /api/profiles/{profile_id}/?include=lists
Include the lists for a single profile. Do this if you need both the profile resource, and its corresponding lists.GET /api/profiles/{profile_id}/relationships/lists
Get just the relationship object (the ID mapping) to the corresponding list ID.
Do this if you only need the list IDs for a profile's lists, and do not need either the profile resource or its corresponding lists.
This is also the endpoint you can use to create, update or delete relationships, if these operations are supported for the relationship in question.
Example request & response
In this example, we have requested all lists related to the specified profile ID. This request returns the list resources only.
curl --request GET \
--url 'https://a.klaviyo.com/api/profiles/{profile_id}/lists' \
--header 'Accept: application/json'
--header 'Authorization: Klaviyo-API-Key {your-private-api-key}'
--header 'Revision: YYYY-MM-DD.pre'
{
"data": [
{
"type": "list",
"id": "V7Raqa",
"attributes": {
"name": "Sample Data List",
"created": "2022-06-15T16:01:12+00:00",
"updated": "2022-06-15T16:01:12+00:00"
},
"links": {
"self": "https://a.klaviyo.com/api/lists/V7Raqa/"
}
}
],
"links": {
"self": "https://a.klaviyo.com/api/v3/profiles/01G5MDK0GX6K293W4647RNEGXB/lists/",
"next": null,
"prev": null
}
}
Collection-level relationship support
Additionally, certain endpoints support include
parameters for top-level GET
endpoints. Refer to our API reference documentation for more information on which endpoints support include
parameters.
Use include
if you need all resources from a particular endpoint (paginated) AND all of their corresponding resources from the relationship.
Example request & response
In this example, we have requested a specific event ID, and have included all profiles related to that event.
curl --request GET \
--url 'https://a.klaviyo.com/api/events/{event-ID}/?include=profile' \
--header 'Accept: application/json'
--header 'Authorization: Klaviyo-API-Key {your-private-api-key}'
--header 'Revision: YYYY-MM-DD.pre'
{
"data": {
"type": "event",
"id": "3pAMewFCZAT",
"attributes": {
"metric_id": "PQ4zJA",
"profile_id": "01G5MDK0GX6K293W4647RNEGXB",
"timestamp": 1655321496,
"event_properties": {
"ProductName": "A Tale of Two Cities",
"ProductID": "1112",
"Categories": [
"Fiction",
"Classics"
],
"ImageURL": "http://www.example.com/path/to/product/image.png",
"URL": "http://www.example.com/path/to/product",
"Brand": "Harcourt Classics",
"Price": 19.99,
"CompareAtPrice": 19.99,
"$event_id": "sample_data_gen:d3c56774-845a-43fa-a720-632c5e28901c"
},
"datetime": "2022-06-15 19:31:36+00:00",
"uuid": "c5161c00-ece1-11ec-8001-323081228ece"
},
"relationships": {
"profiles": {
"data": [
{
"type": "profiles",
"id": "01G5MDK0GX6K293W4647RNEGXB"
}
]
}
},
"links": {
"self": "https://a.klaviyo.com/api/events/3pAMewFCZAT/"
}
},
"included": [
{
"type": "profile",
"id": "01G5MDK0GX6K293W4647RNEGXB",
"attributes": {
"email": "[email protected]",
"phone_number": null,
"external_id": null,
"anonymous_id": null,
"first_name": "Lindsey",
"last_name": "Smith (Sample)",
"organization": "Klaviyo",
"title": "engineer",
"image": null,
"created": "2022-06-15T19:31:34+00:00",
"updated": "2022-06-15T19:31:36+00:00",
"last_event_date": "2022-06-15T19:31:36+00:00",
"location": {
"address1": "302 W 3rd St",
"address2": "Unit 600",
"city": "Cincinnati",
"country": "USA",
"latitude": null,
"longitude": null,
"region": "OH",
"zip": "45202",
"timezone": null
},
"properties": {
"$latitude": "39.1031",
"$longitude": "84.5120",
"klaviyo_sample_data_gen": true
}
},
"links": {
"self": "https://a.klaviyo.com/api/profiles/01G5MDK0GX6K293W4647RNEGXB/"
}
}
]
}
Modify a relationship
You can not only read relationships, you can also create and delete them.
Create a relationship
To create a new relationship between two resources, make a POST
request to the endpoint with the relationship specified in the request body. In this example, we add a profile to a list by sending a POST to that profiles’ list relationship URL, specifying the list ID in the body.
curl --request POST \
--url 'https://a.klaviyo.com/api/profiles/{profile_id}/relationships/lists' \
--header 'Accept: application/json'
--header 'Authorization: Klaviyo-API-Key {your-private-api-key}'
--header 'Revision: YYYY-MM-DD.pre'
--data '
{
"type": "list",
"id": "{list_id}"
}
’
Delete a relationship
To delete a relationship, make a DELETE
request to the endpoint with the relationship specified in the request body. In this example, we are removing the relationship between a profile and the list ID defined in the request body.
curl --request DELETE \
--url 'https://a.klaviyo.com/api/profiles/{profile_id}/relationships/lists' \
--header 'Accept: application/json'
--header 'Authorization: Klaviyo-API-Key {your-private-api-key}'
--header 'Revision: YYYY-MM-DD.pre'
--data '
{
"type": "list",
"id": "{list_id}"
}
’
Updated 8 months ago