Skip to main content

KlaviyoProNew in 5.15.30+

This guide assumes you have a Klaviyo account already.

​Compatibility

Uses revision 2026-07-15 of the REST API.

​Supported Features

  • Subscribe email addresses to a selected Klaviyo list.
  • Create profiles or update existing profiles using the submitted email address.
  • Map profile fields, including names, phone numbers, company details, and location.
  • Map custom profile properties by name. Custom values are sent as text; multiple selected options are joined with commas.
  • Use an optional opt-in checkbox and Freeform integration rules.

Does your project require something else?   Contact Us

​Behavior

  • Profiles are created or updated first. This does not change the profile's subscription status by itself.
  • List opt-in settings still apply. Double opt-in subscribers must confirm before they are subscribed.
  • Previously unsubscribed profiles may be resubscribed. Only enable subscriptions on forms where the user has provided consent. Use an opt-in checkbox when signup is optional.
  • Blank or unmapped fields are ignored. Existing Klaviyo values are left unchanged.
  • Subscription requests are processed asynchronously. If subscribing fails after the profile is updated, the profile changes remain in Klaviyo. Check Freeform's integration logs for details.
  • Email subscriptions only. SMS subscriptions, events, and ecommerce data are not supported.

​Setup Instructions

1

​Create a Private API Key

  • Create a private API key in your Klaviyo API key settings with these scopes:
    • List: Full Access
    • Profiles: Full Access
    • Subscriptions: Full Access

A public API key (site ID) cannot be used for this integration.

2

​Configure the Integration

  • In Freeform, create a new Klaviyo email marketing integration.
  • Enter the key in Private API Key, or reference an environment variable containing the key.
  • If you want to map custom properties, enter their exact names in Custom Profile Properties, one per line. For example: 
    Favorite Color
    Membership Level
    Referral Source

    Names are case-sensitive. These properties are account-wide and can be created when a profile is sent to Klaviyo. They do not need to exist on a profile beforehand.

  • Click the Save button.
3

​Authorize the Integration

  • After the integration is saved, you will see an Authorize button appear.
  • Click the Authorize button.
  • If authorized successfully, you'll see a green Authorized status at the top beside the integration name.
4

​Configure the Form

To use this integration on your form(s), you'll need to configure each form individually.

  • Open the form builder and select Integrations → Klaviyo.
  • Enable the integration, choose the Target Email Field, and select a mailing list.
  • If subscribing is optional, select the Opt-in Field. An unchecked or missing opt-in field skips both the profile update and subscription. Without an opt-in field, every submission that passes the integration rules is sent to Klaviyo.
  • Map Profile Fields and Custom Profile Properties as needed.
  • Save the form.
  • After changing custom property names in the integration settings, refresh the fields in the form builder to update the available mappings. Use Klaviyo's exact property names; do not prefix custom names with properties..
  • Phone numbers must use E.164 format, such as +12045550123. Timezones should use IANA identifiers, such as America/Winnipeg. Map these values only when they are available in the required format.
Page Feedback