HomeGuidesAPI Reference
ChangelogHelp CenterCommunityContact Us
API Reference
ChangelogHelp CenterCommunityContact Us

Lists API overview

Before you begin

Check out our general API overview to make sure you’re ready to get started with specific endpoints.

📘

When calling the Lists API, make sure your authentication key has the appropriate scopes: lists:read, lists:write. For full use of endpoints in this guide, also include tags:read, flows:read, profiles:read, profiles:write.

A list is a collection of profiles in Klaviyo, which are used when sending campaigns, to trigger flows, and to keep track of how your audience is growing over time. Lists allow you to organize your contacts and keep track of who has subscribed to each of your marketing channels. This guide will walk you through our Lists API, which has support for creating, retrieving, updating, and deleting lists. This API also supports adding and removing profiles to your lists.

Use cases

Here are some example use cases supported by the Lists API:

  • Get related resources for a list (e.g., profiles, tags, etc.).
  • Retrieve full profile information for each list member.
  • Add or remove profiles from a list.
  • Track which flows are using a list as a flow trigger.

Data model

A list has the following:

  • id

    The list ID.

  • attributes

    • name

      The name of the list.

    • created
      The timestamp of when the list was initially created. Uses the format YYYY-MM-DDT00:00:00+00:00.

    • updated
      The timestamp of when the list was last updated. Uses the format YYYY-MM-DDT00:00:00+00:00.

    • opt_in_process

      Whether the list uses single or double opt-in. Lists are set to double opt-in by default in all Klaviyo accounts. Read more about double opt-in.

Create a list

The example request to Create List creates a new list named "Newsletter." Multiple requests with the same name value will create multiple lists of the same name with unique list IDs.

curl --request POST \
     --url https://a.klaviyo.com/api/lists \
     --header 'Authorization: Klaviyo-API-Key your-private-api-key' \
     --header 'accept: application/vnd.api+json' \
     --header 'content-type: application/vnd.api+json' \
     --header 'revision: 2025-01-15' \
     --data '
{
  "data": {
    "type": "list",
    "attributes": {
      "name": "Newsletter"
    }
  }
}
'

{
  "data": {
    "type": "list",
    "id": "Y6nRLr",
    "attributes": {
      "name": "Newsletter",
      "created": "2022-11-08T00:00:00+00:00",
      "updated": "2022-11-08T00:00:00+00:00",
      "opt_in_process": "double_opt_in"
    },
    "relationships": {
      "profiles": {
        "data": [
          {
            "type": "profile",
            "id": "string"
          }
        ],
        "links": {
          "self": "string",
          "related": "string"
        }
      },
      "tags": {
        "data": [
          {
            "type": "tag",
            "id": "string"
          }
        ],
        "links": {
          "self": "string",
          "related": "string"
        }
      },
      "flow-triggers": {
        "data": [
          {
            "type": "flow",
            "id": "string"
          }
        ],
        "links": {
          "self": "string",
          "related": "string"
        }
      }
    },
    "links": {
      "self": "string"
    }
  }
}

Get list(s)

The following example is a Get Lists request to get all lists in your account:

curl --request GET \
     --url https://a.klaviyo.com/api/lists \
     --header 'Authorization: Klaviyo-API-Key your-private-api-key' \
     --header 'accept: application/vnd.api+json' \
     --header 'revision: 2025-01-15'

{
  "data": [
    {
      "type": "list",
      "id": "Y6nRLr",
      "attributes": {
        "name": "Newsletter",
        "created": "2022-11-08T00:00:00+00:00",
        "updated": "2022-11-08T00:00:00+00:00",
        "opt_in_process": "double_opt_in"
      },
      "links": {
        "self": "string"
      },
      "relationships": {
        "profiles": {
          "links": {
            "self": "string",
            "related": "string"
          }
        },
        "tags": {
          "data": [
            {
              "type": "tag",
              "id": "string"
            }
          ],
          "links": {
            "self": "string",
            "related": "string"
          }
        },
        "flow-triggers": {
          "data": [
            {
              "type": "flow",
              "id": "string"
            }
          ],
          "links": {
            "self": "string",
            "related": "string"
          }
        }
      }
    }
  ],
  "links": {
    "self": "string",
    "first": "string",
    "last": "string",
    "prev": "string",
    "next": "string"
  },
  "included": [
    {
      "type": "flow",
      "id": "string",
      "attributes": {
        "name": "string",
        "status": "string",
        "archived": true,
        "created": "2022-11-08T00:00:00+00:00",
        "updated": "2022-11-08T00:00:00+00:00",
        "trigger_type": "Added to List"
      },
      "links": {
        "self": "string"
      }
    },
    {
      "type": "tag",
      "id": "abcd1234-ef56-gh78-ij90-abcdef123456",
      "attributes": {
        "name": "My Tag"
      },
      "links": {
        "self": "string"
      }
    }
  ]
}

You can also return a specified list by passing in the list's ID.

curl --request GET \
     --url https://a.klaviyo.com/api/lists/id \
     --header 'Authorization: Klaviyo-API-Key your-private-api-key' \
     --header 'accept: application/vnd.api+json' \
     --header 'revision: 2025-01-15'

{
  "data": {
    "type": "list",
    "id": "Y6nRLr",
    "attributes": {
      "name": "Newsletter",
      "created": "2022-11-08T00:00:00+00:00",
      "updated": "2022-11-08T00:00:00+00:00",
      "opt_in_process": "double_opt_in",
      "profile_count": 0
    },
    "links": {
      "self": "string"
    },
    "relationships": {
      "profiles": {
        "links": {
          "self": "string",
          "related": "string"
        }
      },
      "tags": {
        "data": [
          {
            "type": "tag",
            "id": "string"
          }
        ],
        "links": {
          "self": "string",
          "related": "string"
        }
      },
      "flow-triggers": {
        "data": [
          {
            "type": "flow",
            "id": "string"
          }
        ],
        "links": {
          "self": "string",
          "related": "string"
        }
      }
    }
  },
  "included": [
    {
      "type": "flow",
      "id": "string",
      "attributes": {
        "name": "string",
        "status": "string",
        "archived": true,
        "created": "2022-11-08T00:00:00+00:00",
        "updated": "2022-11-08T00:00:00+00:00",
        "trigger_type": "Added to List"
      },
      "links": {
        "self": "string"
      }
    },
    {
      "type": "tag",
      "id": "abcd1234-ef56-gh78-ij90-abcdef123456",
      "attributes": {
        "name": "My Tag"
      },
      "links": {
        "self": "string"
      }
    }
  ]
}

📘

The Get List endpoint allows you to optionally request list size, i.e., profile count, using the additional-fields query parameter. Note that rate limits are stricter for this request. Learn about additional fields.

Update a list

You can update the name of a list with the Update List endpoint. In this example, we update the name of the list to "New Newsletter".

curl --request PATCH \
     --url https://a.klaviyo.com/api/lists/Y6nRLr \
     --header 'Authorization: Klaviyo-API-Key your-private-api-key' \
     --header 'accept: application/vnd.api+json' \
     --header 'content-type: application/vnd.api+json' \
     --header 'revision: 2025-01-15' \
     --data '
{
  "data": {
    "type": "list",
    "attributes": {
      "name": "New Newsletter"
    },
    "id": "Y6nRLr"
  }
}
'

{
  "data": {
    "type": "list",
    "id": "Y6nRLr",
    "attributes": {
      "name": "Newsletter",
      "created": "2022-11-08T00:00:00+00:00",
      "updated": "2022-11-08T00:00:00+00:00",
      "opt_in_process": "double_opt_in"
    },
    "relationships": {
      "profiles": {
        "data": [
          {
            "type": "profile",
            "id": "string"
          }
        ],
        "links": {
          "self": "string",
          "related": "string"
        }
      },
      "tags": {
        "data": [
          {
            "type": "tag",
            "id": "string"
          }
        ],
        "links": {
          "self": "string",
          "related": "string"
        }
      },
      "flow-triggers": {
        "data": [
          {
            "type": "flow",
            "id": "string"
          }
        ],
        "links": {
          "self": "string",
          "related": "string"
        }
      }
    },
    "links": {
      "self": "string"
    }
  }
}

Get profiles for a list

You can retrieve all profiles on a given list with the Get Profiles for List endpoint. The response includes 20 profiles per page by default, with full details including profile identifiers, additional attributes, and subscription data. Check out the Profiles API overview for more information.

📘

When calling these endpoints, make sure your authentication key has the following additional scopes: profiles:read.

curl --request GET \
     --url 'https://a.klaviyo.com/api/lists/Y6nRLr/profiles?page[size]=20' \
     --header 'Authorization: Klaviyo-API-Key your-private-api-key' \
     --header 'accept: application/vnd.api+json' \
     --header 'revision: 2025-01-15'

{
  "data": [
    {
      "type": "profile",
      "id": "01GDDKASAP8TKDDA2GRZDSVP4H",
      "attributes": {
        "email": "[email protected]",
        "phone_number": "+15005550006",
        "external_id": "string",
        "first_name": "Sarah",
        "last_name": "Mason",
        "organization": "Example Corporation",
        "locale": "en-US",
        "title": "Regional Manager",
        "image": "https://images.pexels.com/photos/3760854/pexels-photo-3760854.jpeg",
        "created": "2022-11-08T00:00:00+00:00",
        "updated": "2022-11-08T00:00:00+00:00",
        "last_event_date": "2022-11-08T00:00:00+00:00",
        "location": {
          "address1": "89 E 42nd St",
          "address2": "1st floor",
          "city": "New York",
          "country": "United States",
          "latitude": "string",
          "longitude": "string",
          "region": "NY",
          "zip": "10017",
          "timezone": "America/New_York",
          "ip": "127.0.0.1"
        },
        "properties": {
          "pseudonym": "Dr. Octopus"
        },
        "joined_group_at": "2022-11-08T00:00:00+00:00",
        "subscriptions": {
          "email": {
            "marketing": {
              "can_receive_email_marketing": true,
              "consent": "SUBSCRIBED",
              "consent_timestamp": "2023-02-21T20:07:38+00:00",
              "last_updated": "2023-02-21T20:07:38+00:00",
              "method": "PREFERENCE_PAGE",
              "method_detail": "mydomain.com/signup",
              "custom_method_detail": "marketing drive",
              "double_optin": true,
              "suppression": [
                {
                  "reason": "HARD_BOUNCE",
                  "timestamp": "2023-02-21T20:07:38+00:00"
                }
              ],
              "list_suppressions": [
                {
                  "list_id": "Y6nRLr",
                  "reason": "USER_SUPPRESSED",
                  "timestamp": "2023-02-21T20:07:38+00:00"
                }
              ]
            }
          },
          "sms": {
            "marketing": {
              "can_receive_sms_marketing": true,
              "consent": "SUBSCRIBED",
              "consent_timestamp": "2023-02-21T20:07:38+00:00",
              "method": "TEXT",
              "method_detail": "JOIN",
              "last_updated": "2023-02-21T20:07:38+00:00"
            },
            "transactional": {
              "can_receive_sms_transactional": true,
              "consent": "SUBSCRIBED",
              "consent_timestamp": "2023-02-21T20:07:38+00:00",
              "method": "TEXT",
              "method_detail": "JOIN",
              "last_updated": "2023-02-21T20:07:38+00:00"
            }
          },
          "mobile_push": {
            "marketing": {
              "can_receive_push_marketing": true,
              "consent": "SUBSCRIBED",
              "consent_timestamp": "2023-02-21T20:07:38+00:00"
            }
          }
        },
        "predictive_analytics": {
          "historic_clv": 93.87,
          "predicted_clv": 27.24,
          "total_clv": 121.11,
          "historic_number_of_orders": 2,
          "predicted_number_of_orders": 0.54,
          "average_days_between_orders": 189,
          "average_order_value": 46.94,
          "churn_probability": 0.89,
          "expected_date_of_next_order": "2022-11-08T00:00:00+00:00"
        }
      },
      "links": {
        "self": "string"
      },
      "relationships": {
        "lists": {
          "links": {
            "self": "string",
            "related": "string"
          }
        },
        "segments": {
          "links": {
            "self": "string",
            "related": "string"
          }
        }
      }
    }
  ],
  "links": {
    "self": "string",
    "first": "string",
    "last": "string",
    "prev": "string",
    "next": "string"
  }
}

If you would like to return only the profile IDs of all profiles in the specified list, use the Get Profile IDs for List endpoint.

curl --request GET \
     --url 'https://a.klaviyo.com/api/lists/id/relationships/profiles?page[size]=20' \
     --header 'Authorization: Klaviyo-API-Key your-private-api-key' \
     --header 'accept: application/vnd.api+json' \
     --header 'revision: 2025-01-15'

{
  "data": [
    {
      "type": "profile",
      "id": "01GDDKASAP8TKDDA2GRZDSVP4H"
    }
  ]
}

Add profiles to a list

The Add Profiles to List endpoint will allow you to add existing profiles to a list without changing their subscription status. We recommend only adding profiles to a list if they have already consented to appropriate marketing channels. If you need to give a profile consent to receive email marketing and/or SMS marketing, use the Subscribe Profiles endpoint.

You can send a maximum of 1000 profiles per request.

📘

When calling these endpoints, make sure your authentication key has the following additional scopes: profiles:write.

curl --request POST \
     --url https://a.klaviyo.com/api/lists/Y6nRLr/relationships/profiles \
     --header 'Authorization: Klaviyo-API-Key your-private-api-key' \
     --header 'accept: application/vnd.api+json' \
     --header 'content-type: application/vnd.api+json' \
     --header 'revision: 2025-01-15' \
     --data '
{
  "data": [
    {
      "type": "profile",
      "id": "LmN0Pq"
    }
  ]
}
'

Remove profiles from a list

If you no longer wish to have certain profiles on a list, use the Remove Profiles from List endpoint to remove profiles with the specified profile ID. The provided profile will no longer receive marketing from this particular list. Removing a profile from a list will not impact the profile's consent status or subscription status in general. To update a profile's subscription status, please use the Unsubscribe Profiles endpoint.

You can remove a maximum of 1000 profiles per request.

📘

When calling these endpoints, make sure your authentication key has the following additional scopes: profiles:write.

curl --request DELETE \
     --url https://a.klaviyo.com/api/lists/Y6nRLr/relationships/profiles \
     --header 'Authorization: Klaviyo-API-Key your-private-api-key' \
     --header 'accept: application/vnd.api+json' \
     --header 'content-type: application/vnd.api+json' \
     --header 'revision: 2025-01-15' \
     --data '
{
  "data": [
    {
      "type": "profile",
      "id": "LmN0Pq"
    }
  ]
}
'

Get tags associated with a list

Tags can be used to keep your lists organized. Retrieve the tags associated with your list using the Get Tags for List endpoint.

📘

When calling these endpoints, make sure your authentication key has the following additional scopes: tags:read.

curl --request GET \
     --url https://a.klaviyo.com/api/lists/id/tags \
     --header 'Authorization: Klaviyo-API-Key your-private-api-key' \
     --header 'accept: application/vnd.api+json' \
     --header 'revision: 2025-01-15'

{
  "data": [
    {
      "type": "tag",
      "id": "abcd1234-ef56-gh78-ij90-abcdef123456",
      "attributes": {
        "name": "My Tag"
      },
      "links": {
        "self": "string"
      },
      "relationships": {
        "tag-group": {
          "links": {
            "self": "string",
            "related": "string"
          }
        },
        "lists": {
          "links": {
            "self": "string",
            "related": "string"
          }
        },
        "segments": {
          "links": {
            "self": "string",
            "related": "string"
          }
        },
        "campaigns": {
          "links": {
            "self": "string",
            "related": "string"
          }
        },
        "flows": {
          "links": {
            "self": "string",
            "related": "string"
          }
        }
      }
    }
  ],
  "links": {
    "self": "string",
    "first": "string",
    "last": "string",
    "prev": "string",
    "next": "string"
  }
}

If you would like to return only the tag IDs of the list's associated tags, use the Get Tag IDs for List endpoint.

curl --request GET \
     --url https://a.klaviyo.com/api/lists/id/relationships/tags \
     --header 'Authorization: Klaviyo-API-Key your-private-api-key' \
     --header 'accept: application/vnd.api+json' \
     --header 'revision: 2025-01-15'

{
  "data": [
    {
      "type": "tag",
      "id": "abcd1234-ef56-gh78-ij90-abcdef123456"
    }
  ]
}

Get flows triggered by a list

The Get Flows Triggered by List endpoint will return any flows that use the list with the specified list ID as a flow trigger. The response provides the name and status of the list and the type of trigger with which the list is associated.

📘

When calling these endpoints, make sure your authentication key has the following additional scopes: flows:read.

curl --request GET \
     --url https://a.klaviyo.com/api/lists/id/flow-triggers \
     --header 'Authorization: Klaviyo-API-Key your-private-api-key' \
     --header 'accept: application/vnd.api+json' \
     --header 'revision: 2025-01-15'

{
  "data": [
    {
      "type": "flow",
      "id": "string",
      "attributes": {
        "name": "My Flow",
        "status": "live",
        "archived": true,
        "created": "2022-11-08T00:00:00+00:00",
        "updated": "2022-11-08T00:00:00+00:00",
        "trigger_type": "Added to List"
      },
      "links": {
        "self": "string"
      },
      "relationships": {
        "flow-actions": {
          "links": {
            "self": "string",
            "related": "string"
          }
        },
        "tags": {
          "links": {
            "self": "string",
            "related": "string"
          }
        }
      }
    }
  ],
  "links": {
    "self": "string",
    "first": "string",
    "last": "string",
    "prev": "string",
    "next": "string"
  }
}

If you would like to return only the flow IDs of flows using the list as a flow trigger, use the Get IDs for Flows Triggered by List endpoint.

curl --request GET \
     --url https://a.klaviyo.com/api/lists/id/relationships/flow-triggers \
     --header 'Authorization: Klaviyo-API-Key your-private-api-key' \
     --header 'accept: application/vnd.api+json' \
     --header 'revision: 2025-01-15'

{
  "data": [
    {
      "type": "flow",
      "id": "1a2b3cf"
    }
  ]
}

Additional resources

Power smarter
digital relationships
By entering your information and clicking “Sign up,” you consent to receive marketing emails (such as newsletters, blog posts, webinars, event invitations and new product updates) from Klaviyo from time to time. You can unsubscribe at any time by clicking on the “Unsubscribe” link at the bottom of our emails. For more information on how we process your personal information and what rights you have in this respect, please see our Privacy Policy.
Terms and Privacy Trademarks Security