Klaviyo

Send survey responses to Klaviyo

The Klaviyo integration sends every completed survey response to your Klaviyo account. Each response becomes a Klaviyo event, and each answer becomes a typed property on that event. You can also save selected answers on the respondent's profile and add respondents to a list.

AppGram only sends data to Klaviyo. Nothing is read back from Klaviyo into AppGram.

Who handles what

Most setup problems come from expecting one side to do the other side's job. Here is the split.

AppGram handles	You handle in Klaviyo
Sending each survey response as an event, with one property per answer	Creating the private API key and giving it the right scopes
Matching each respondent to a Klaviyo profile (email, external ID, or anonymous ID)	Creating the list you want respondents added to, and copying its List ID
Creating or updating the profile, including the answers you chose to save on it	Building segments, flows, and campaigns that use the survey data
Adding respondents to your list (subscribing them only when you confirm consent)	Collecting marketing consent in your survey or app, if you want respondents emailed
Retrying failed requests and staying within Klaviyo's rate limits	Anything Klaviyo does after the data arrives, like sending emails, suppressions, and double opt-in

You also have one job in your own app: to match responses to real people, pass the user's ID (ideally their email) as external_user_id when submitting a survey. See How respondents are matched below.

Step 1: Create a private API key in Klaviyo

1. In Klaviyo, open Settings → API keys and click Create Private API Key.
2. Choose Custom key and give it these scopes:
   • Events: write
   • Profiles: write
   • Lists: write (only if you use a list)
   • Subscriptions: write (only if you subscribe respondents)
   • Accounts: read (optional, so AppGram can show your account name)
3. Copy the key. It starts with pk_.

Step 2: Connect Klaviyo in AppGram

1. Go to Settings → Integrations and click Connect on Klaviyo.
2. Paste the private API key. AppGram checks it with Klaviyo right away and stores it encrypted.
3. Open the integration's settings to choose what gets sent.

Step 3: Choose your settings

• Surveys: send All surveys (including ones you create later) or only Selected surveys. Click Mapping on any survey to rename its event or its property keys.
• Event: the Klaviyo metric name responses are logged under. The default is Survey Completed. Give a survey its own event name if you want to build segments and flows for that survey alone.
• Property keys: how questions are named in Klaviyo. Question text gives readable keys, Stable question ID keeps keys the same when you reword a question, and Custom keys lets you name them yourself. Klaviyo sets a property's type from the first value it receives, so choose this before real responses start flowing.
• Identity and Send anonymous responses: see the next section.
• Profile properties: answers you tick under Profile in a survey's Mapping are also saved on the Klaviyo profile, prefixed with appgram_ by default (for example appgram_nps). Use these to build segments like "NPS score is at least 9".
• List subscription: the List ID and consent checkbox. See Lists and consent below.

How respondents are matched

Klaviyo needs an identifier for every profile. AppGram uses the external_user_id your app sends with the survey response:

• Automatic (default): an email address is sent as the profile's email. Any other ID is sent as the Klaviyo external ID.
• Email only: only IDs that are email addresses are used. Any other ID is treated like an anonymous response.
• External ID: the ID is always sent as the external ID, even if it looks like an email.

If the response has no user ID, what happens depends on Send anonymous responses:

• Off (default): the response is skipped and nothing is sent to Klaviyo.
• On: the response is sent under an anonymous profile with an external ID like appgram_anon_…, based on the respondent's device. Repeat responses from the same device land on the same profile.

Anonymous profiles have no email, so Klaviyo can never email them. Use them for reporting and segmentation. To reach respondents by email, your app must pass their email as external_user_id.

Lists and consent

When you enter a List ID, respondents are added to that list differently depending on who they are:

Respondent	What AppGram does	Needs the consent checkbox?
Has an email address	Subscribes them to the list and records email marketing consent in Klaviyo	Yes. Without it, they are not added to the list.
Anonymous (requires Send anonymous responses)	Adds the profile to the list without recording any consent	No. The List ID is enough.
Has a non-email user ID	Not added to the list	n/a

Only tick My respondents have agreed to receive marketing email if your survey or app actually collects that consent. AppGram records consent in Klaviyo on your behalf. Whether Klaviyo then requires double opt-in is controlled by the list's settings in Klaviyo.

Tip: you often don't need a list. A Klaviyo segment with the condition What someone has done → Survey Completed → at least once includes every respondent automatically, anonymous or not, and it updates itself.

What an event contains

• survey_id, survey_name, project_id, response_id
• One property per answer, typed by question: numbers for ratings (plus _min and _max), true/false for yes/no, lists for checkboxes, and text for everything else
• The time the response was submitted

Each response is sent with a unique ID, so a retry never creates a duplicate event in Klaviyo.

Troubleshooting

• A response never reached Klaviyo. Check that the survey is enabled under Surveys. If the respondent had no user ID, turn on Send anonymous responses or have your app pass external_user_id.
• The profile exists, but it isn't on the list. For email respondents, both the List ID and the consent checkbox must be set. For anonymous respondents, check that the API key has the Lists: write scope. Respondents identified by a non-email ID are never added to the list.
• The integration shows an error. The API key was revoked or lacks a required scope. Use Replace API key in the integration settings.
• A property has the wrong type in Klaviyo. Klaviyo keeps the type of the first value it received. Switch to Stable question ID or Custom keys to start a new property.
• The metric doesn't appear in Klaviyo's segment builder. Klaviyo only lists a metric after it has received at least one event. Submit a test response first.

Only the event is required. If it fails, AppGram marks the integration with an error and skips the remaining steps for that response. Once the event lands, the profile and list steps are best-effort: if one of them fails, the response still counts as delivered and the integration stays healthy.