Klaviyo

Klaviyo Profiles API

profiles

GitHub OpenAPI
Business capability
Customer Data Management BC-420.10

Operations 36

Each operation below carries the questions people ask an LLM about it and the instructions they give an agent to run it. Generated by API Evangelist overlay

GET /api/profiles List and filter profiles in the account · Get Profiles #
Ask an LLM
“How do I pull every contact profile out of my Klaviyo account?”
“Can I sort profiles by when they were created or last updated?”
Tell an agent
List all profiles in my account, newest first.
Find profiles matching the filter {filter}.
POST /api/profiles Create a new profile · Create Profile #
Ask an LLM
“What's the way to add a brand-new contact profile that doesn't exist yet?”
“Is there a payload size limit when creating a single profile?”
Tell an agent
Create a new profile with these details: {profile}.
Add a brand-new contact profile for {profile} and return its subscriptions.
GET /api/profiles/{id} Get one profile by ID · Get Profile #
Ask an LLM
“How can I look up everything stored on a single profile by its ID?”
“Can I see a profile's predictive analytics along with its attributes?”
Tell an agent
Get profile {profile_id}.
Show profile {profile_id} including predictive analytics and subscriptions.
PATCH /api/profiles/{id} Update an existing profile's attributes · Update Profile #
Ask an LLM
“How do I change the attributes on a profile I already have the ID for?”
“Does sending null for a field on a profile update clear it out?”
Tell an agent
Update profile {profile_id} with {changes}.
Clear the fields listed in {changes} on profile {profile_id} by setting them to null.
GET /api/profile-bulk-import-jobs List bulk profile import jobs · Get Bulk Import Profiles Jobs #
Ask an LLM
“Where can I see all the bulk profile import jobs I've submitted?”
“Can I filter my bulk import jobs by status?”
Tell an agent
List all my bulk profile import jobs.
Show bulk profile import jobs matching {filter}.
POST /api/profile-bulk-import-jobs Bulk import up to 10,000 profiles · Bulk Import Profiles #
Ask an LLM
“How many profiles can I import in a single bulk import request?”
“What's the fastest way to create or update thousands of profiles at once?”
Tell an agent
Start a bulk import job for these profiles: {profiles}.
Bulk import {profiles} and add them to a list.
GET /api/profile-bulk-import-jobs/{job_id} Check a bulk profile import job · Get Bulk Import Profiles Job #
Ask an LLM
“How do I check whether my bulk profile import job has finished?”
“Can I see the progress of one specific import job?”
Tell an agent
Get the status of bulk profile import job {job_id}.
Check how import job {job_id} is progressing.
GET /api/profile-suppression-bulk-create-jobs List bulk profile suppression jobs · Get Bulk Suppress Profiles Jobs #
Ask an LLM
“Which bulk email suppression jobs have I run and what state are they in?”
“Can I filter suppression jobs by list or segment?”
Tell an agent
List the status of all my bulk suppression jobs.
Show bulk suppression jobs matching {filter}.
POST /api/profile-suppression-bulk-create-jobs Suppress profiles from email marketing · Bulk Suppress Profiles #
Ask an LLM
“How do I stop email marketing to a batch of email addresses regardless of consent?”
“Can I suppress every current member of a list or segment in one go?”
Tell an agent
Suppress these email addresses from marketing email: {emails}.
Suppress all current members of {list_or_segment} from email marketing.
GET /api/profile-suppression-bulk-create-jobs/{job_id} Check a bulk suppression job · Get Bulk Suppress Profiles Job #
Ask an LLM
“Did my bulk suppression request finish processing?”
“What's the current state of a single suppression job?”
Tell an agent
Get bulk suppression job {job_id}.
Check whether suppression job {job_id} has completed.
GET /api/profile-suppression-bulk-delete-jobs List bulk profile unsuppression jobs · Get Bulk Unsuppress Profiles Jobs #
Ask an LLM
“Where do I see all the jobs I ran to lift email suppressions?”
“Can I sort unsuppression jobs by creation date?”
Tell an agent
List all my bulk unsuppression jobs.
Show unsuppression jobs matching {filter}.
POST /api/profile-suppression-bulk-delete-jobs Lift manual email suppressions in bulk · Bulk Unsuppress Profiles #
Ask an LLM
“How can I remove manual suppressions so people can get marketing email again?”
“Will unsuppressing also restore profiles that unsubscribed or had invalid emails?”
Tell an agent
Unsuppress these email addresses: {emails}.
Remove user suppressions from every member of {list_or_segment}.
GET /api/profile-suppression-bulk-delete-jobs/{job_id} Check a bulk unsuppression job · Get Bulk Unsuppress Profiles Job #
Ask an LLM
“Has my request to lift suppressions finished?”
“What does a single unsuppression job report about its progress?”
Tell an agent
Get bulk unsuppression job {job_id}.
Check the status of unsuppress job {job_id}.
GET /api/push-tokens List push tokens in the account · Get Push Tokens #
Ask an LLM
“How do I see all the mobile push tokens registered for my company?”
“Can I filter push tokens by platform or profile?”
Tell an agent
List every push token in my account.
Show push tokens matching {filter}.
POST /api/push-tokens Create or update a push token · Create or Update Push Token #
Ask an LLM
“Can I migrate existing mobile push tokens from another system into Klaviyo?”
“What's the server-side way to register a device push token for a profile?”
Tell an agent
Register push token {push_token} for its profile.
Create or update the push token record {push_token}.
GET /api/push-tokens/{id} Get one push token by ID · Get Push Token #
Ask an LLM
“How do I look up a single push token by its ID?”
“What details are stored on a specific push token?”
Tell an agent
Get push token {token_id}.
Show the details of push token {token_id}.
DELETE /api/push-tokens/{id} Delete a push token · Delete Push Token #
Ask an LLM
“How do I remove a device's push token so it stops getting notifications?”
“Can I delete a stale push token by its ID?”
Tell an agent destructive · confirm first
Delete push token {token_id}.
Remove the stale push token {token_id} from my account.
POST /api/profile-import Upsert a profile by its attributes · Create or Update Profile #
Ask an LLM
“Is there a single call that creates a profile if it's new or updates it if it exists?”
“How can I tell whether an upsert created a new profile or updated an old one?”
Tell an agent
Create or update the profile for {profile}.
Upsert a profile using the email and properties in {profile}.
POST /api/profile-merge Merge a duplicate profile into another · Merge Profiles #
Ask an LLM
“How do I combine two duplicate profiles for the same person?”
“Which profile survives when I merge a source profile into a destination?”
Tell an agent destructive · confirm first
Merge the duplicate profiles described in {merge_request} into the destination profile.
Queue a merge of source and destination profiles: {merge_request}.
POST /api/profile-subscription-bulk-create-jobs Subscribe profiles to marketing channels · Bulk Subscribe Profiles #
Ask an LLM
“How do I opt people in to email, SMS, WhatsApp or push marketing in bulk?”
“Will subscribers get a confirmation message if the list uses double opt-in?”
Tell an agent
Subscribe these profiles to marketing: {subscriptions}.
Opt the contacts in {subscriptions} in to SMS and email on a list.
POST /api/profile-subscription-bulk-delete-jobs Unsubscribe profiles from marketing channels · Bulk Unsubscribe Profiles #
Ask an LLM
“How can I unsubscribe a batch of people from email or SMS marketing?”
“What happens to profiles that aren't on the list I pass when unsubscribing?”
Tell an agent destructive · confirm first
Unsubscribe these profiles from marketing: {unsubscriptions}.
Opt out the contacts in {unsubscriptions} from SMS and email.
GET /api/profiles/{id}/push-tokens List a profile's push tokens · Get Push Tokens for Profile #
Ask an LLM
“Which devices does a given profile have push tokens registered on?”
“Can I get the full push token records for one profile?”
Tell an agent
List the push tokens belonging to profile {profile_id}.
Show full push token details for profile {profile_id}.
GET /api/profiles/{id}/relationships/push-tokens Get push token IDs for a profile · Get Push Token IDs for Profile #
Ask an LLM
“Can I get just the IDs of a profile's push tokens without the full records?”
“What's the lightweight way to see which token IDs are linked to a profile?”
Tell an agent
Get only the push token IDs linked to profile {profile_id}.
Return the token ID relationships for profile {profile_id}.
GET /api/profiles/{id}/lists List the lists a profile belongs to · Get Lists for Profile #
Ask an LLM
“Which email lists is a particular person a member of?”
“Can I see full list details for every list a profile has joined?”
Tell an agent
Show the lists profile {profile_id} is a member of.
Get full list records for profile {profile_id}'s memberships.
GET /api/profiles/{id}/relationships/lists Get list IDs a profile belongs to · Get List IDs for Profile #
Ask an LLM
“Can I fetch only the list IDs a profile is on, not the whole list objects?”
“What's the quick way to check list membership IDs for a contact?”
Tell an agent
Get just the list IDs for profile {profile_id}.
Return list membership relationships for profile {profile_id}.
GET /api/profiles/{id}/segments List the segments a profile is in · Get Segments for Profile #
Ask an LLM
“Which segments does this customer currently fall into?”
“Can I see the full segment definitions a profile qualifies for?”
Tell an agent
Show the segments profile {profile_id} belongs to.
Get full segment records for profile {profile_id}'s memberships.
GET /api/profiles/{id}/relationships/segments Get segment IDs a profile is in · Get Segment IDs for Profile #
Ask an LLM
“Can I retrieve only the segment IDs for a profile?”
“Is there a lightweight check for which segment IDs a contact matches?”
Tell an agent
Get just the segment IDs for profile {profile_id}.
Return segment membership relationships for profile {profile_id}.
GET /api/profiles/{id}/conversation Get a profile's conversation · Get Conversation for Profile #
Ask an LLM
“How do I pull up the messaging conversation tied to a customer's profile?”
“Can I read the full conversation record for one profile?”
Tell an agent
Get the conversation for profile {profile_id}.
Show the full conversation record attached to profile {profile_id}.
GET /api/profiles/{id}/relationships/conversation Get a profile's conversation ID · Get Conversation ID for Profile #
Ask an LLM
“Can I get only the conversation ID linked to a profile?”
“What's the conversation relationship ID for a given contact?”
Tell an agent
Get just the conversation ID for profile {profile_id}.
Return the conversation relationship of profile {profile_id}.
GET /api/profile-bulk-import-jobs/{id}/lists Get the list a bulk import job targets · Get List for Bulk Import Profiles Job #
Ask an LLM
“Which list were the profiles in my bulk import job added to?”
“Can I see the full list record attached to an import job?”
Tell an agent
Get the list that bulk import job {job_id} adds profiles to.
Show list details for import job {job_id}.
GET /api/profile-bulk-import-jobs/{id}/relationships/lists Get list IDs for a bulk import job · Get List IDs for Bulk Import Profiles Job #
Ask an LLM
“Can I get only the list ID a bulk import job is tied to?”
“What list relationship does an import job carry?”
Tell an agent
Get just the list IDs for bulk import job {job_id}.
Return the list relationship of import job {job_id}.
GET /api/profile-bulk-import-jobs/{id}/profiles List profiles from a bulk import job · Get Profiles for Bulk Import Profiles Job #
Ask an LLM
“Which profiles were created or updated by a particular bulk import?”
“Can I page through the full profile records an import job touched?”
Tell an agent
List the profiles imported by bulk import job {job_id}.
Show {page_size} imported profiles at a time from job {job_id}.
GET /api/profile-bulk-import-jobs/{id}/relationships/profiles Get profile IDs from a bulk import job · Get Profile IDs for Bulk Import Profiles Job #
Ask an LLM
“Can I get just the profile IDs that a bulk import job processed?”
“What's the lightweight way to see which profile IDs an import touched?”
Tell an agent
Get only the profile IDs from bulk import job {job_id}.
Return profile relationships for import job {job_id}.
GET /api/profile-bulk-import-jobs/{id}/import-errors Get errors from a bulk import job · Get Errors for Bulk Import Profiles Job #
Ask an LLM
“Why did some profiles fail to import in my bulk job?”
“Where do I find the import errors for a bulk profile upload?”
Tell an agent
Show the import errors for bulk import job {job_id}.
List which rows failed in import job {job_id}.
GET /api/push-tokens/{id}/profile Get the profile that owns a push token · Get Profile for Push Token #
Ask an LLM
“Who is the customer behind a given push token?”
“Can I get the full profile record for a device token?”
Tell an agent
Get the profile that owns push token {token_id}.
Show the full customer profile for device token {token_id}.
GET /api/push-tokens/{id}/relationships/profile Get the profile ID for a push token · Get Profile ID for Push Token #
Ask an LLM
“Can I fetch only the profile ID linked to a push token?”
“What profile relationship does a device token point to?”
Tell an agent
Get just the profile ID for push token {token_id}.
Return the profile relationship of token {token_id}.

Documentation

📖
Documentation
https://developers.klaviyo.com/
📖
Authentication
https://developers.klaviyo.com/en/docs/authenticate_
📖
RateLimits
https://developers.klaviyo.com/en/docs/rate_limits_and_error_handling

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/klaviyo/refs/heads/main/openapi/klaviyo-profiles-api-openapi.yml
⚙
AsyncAPI
https://raw.githubusercontent.com/api-evangelist/klaviyo/refs/heads/main/asyncapi/klaviyo-webhooks-asyncapi.yaml

Other Resources

🔗
Reference
https://developers.klaviyo.com/en/reference/api_overview
🔗
Versioning
https://developers.klaviyo.com/en/docs/api_versioning_and_deprecation_policy
🔗
ChangeLog
https://developers.klaviyo.com/en/docs/changelog_
🔗
SDKs
https://developers.klaviyo.com/en/docs/sdk_overview
🔗
GitHub
https://github.com/klaviyo/openapi
🔗
Overlay
https://raw.githubusercontent.com/api-evangelist/klaviyo/refs/heads/main/overlays/klaviyo-profiles-api-overlay.yaml

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/klaviyo:klaviyo-profiles-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

klaviyo-profiles-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: Klaviyo Profiles API
  version: '2026-04-15'
  description: The Klaviyo REST API. Please visit https://developers.klaviyo.com for more details.
  contact:
    name: Klaviyo Developer Experience Team
    email: developers@klaviyo.com
    url: https://developers.klaviyo.com
  termsOfService: https://www.klaviyo.com/legal/api-terms
  license:
    name: License
    url: https://www.klaviyo.com/legal
servers:
- url: https://a.klaviyo.com
  description: Production
security:
- Klaviyo-API-Key: []
tags:


# --- truncated at 32 KB (282 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/klaviyo/refs/heads/main/openapi/klaviyo-profiles-api-openapi.yml