Klaviyo data reference

Updated 1 month ago6 min readIntegrations

Summary

The Klaviyo integration is one-way and read-only: data flows from Klaviyo to Loop and never the other way. Access is granted with OAuth 2.0 (authorization code with PKCE) using exactly three scopes: accounts:read, segments:read and profiles:read.

Permissions (OAuth scopes)

Scope	Klaviyo API calls made	Why Loop needs it
`accounts:read`	`GET /api/accounts/`	Read the account ID and name once at connection time to show “Connected — <Account name>”.
`segments:read`	`GET /api/segments/`, `GET /api/segments/{id}/`	List your segments for the dropdown and read the selected segment’s profile count (estimated reach).
`profiles:read`	`GET /api/segments/{id}/profiles/`	Read the members of the one segment a campaign uses, so Loop knows who to call.

Data read from Klaviyo

Segments

Field	Klaviyo attribute	How Loop uses it
Segment ID	`id`	Identifies the segment chosen for a campaign
Segment name	`attributes.name`	Shown in the segment dropdown
Segment type	`attributes.definition`	Display only
Last updated	`attributes.updated`	Display only
Profile count	`profile_count`	Shown as “estimated reach” when you pick a segment

Segment member profiles

Read only for the one segment a campaign uses.

Field	Klaviyo attribute	Needed to be called?	How Loop uses it
Profile ID	`id`	Yes	Contact’s external reference; prevents calling the same person twice in one campaign
Phone number	`phone_number`	Yes	The number dialled; must parse to a valid E.164 number
First name	`first_name`	No	Greeting; available to the agent as `{{first_name}}`
Last name	`last_name`	No	Combined with first name as the customer name on the call log
Email	`email`	No	Stored on the call log for identification and reporting
External ID	`external_id`	No	Best-effort match to your existing Loop customer record (Shopify customer ID)

Members without a usable phone number are skipped and never contacted.

Data written to Klaviyo

None. Loop never creates, updates or deletes profiles, events or metrics, lists, segments, flows, or consent settings. The only non-GET requests Loop makes are the OAuth token exchange, token refresh and token revocation.

Data Loop stores

Where	What	Why	When deleted
Workspace (Klaviyo connection)	Encrypted access token, encrypted refresh token, access-token expiry, granted scopes, Klaviyo account ID, account name, connected-at timestamp	To keep the connection alive and show who is connected	Immediately on disconnect, or when Klaviyo reports the grant revoked
Campaign	Chosen Klaviyo segment ID and a paging cursor	To know which segment to call and how far the run has progressed	With the campaign
Campaign contact (called member)	Klaviyo profile ID, phone number, first/last name, email, `first_name` merge value	These become the customer details on the call log	Retention period: TODO to be confirmed

Freshness and timing

The segment list is cached for 5 minutes; “Refresh” forces a re-read.
Segment membership is read live at run time, in pages of 100 profiles.
Profile counts are fetched on demand for the selected segment only, one request at a time, to respect Klaviyo rate limits.
Access tokens (about 1 hour) are refreshed automatically; refresh tokens rotate.
Klaviyo expires a refresh token after 90 days without use — reconnect if that happens.

Filtering before a call

Members with no phone number, or a number that cannot be parsed into valid E.164, are skipped.
When the campaign’s Do-Not-Contact exclusion is on, numbers on the workspace’s Do Not Contact list are skipped.
Duplicate phone numbers within one campaign are called once.

Technical details

Klaviyo API endpoints used+

GET /api/accounts/
GET /api/segments/
GET /api/segments/{id}/ with additional-fields[segment]=profile_count
GET /api/segments/{id}/profiles/ with fields[profile]=email,phone_number,external_id,first_name,last_name and page[size]=100