HomeGuidesAPI Reference
ChangelogHelp CenterCommunityContact Us
API Reference

Create Client Subscription

Creates a subscription and consent record for email and/or SMS channels based on the provided email and phone_number attributes, respectively. One of either email or phone_number must be provided.

This endpoint is specifically designed to be called from publicly-browseable, client-side environments only and requires a public API key (site ID). Never use a private API key with our client-side endpoints.

To subscribe profiles from server-side applications, please use POST /api/profile-subscription-bulk-create-jobs.

Profiles can be opted into multiple channels: email marketing, SMS marketing, and SMS transactional. You can specify the channel(s) to subscribe the profile to by providing a subscriptions object in the profile attributes.

If you include a subscriptions object, only channels in that object will be subscribed. You can use this to update email or phone on the profile without subscribing them, for example, by setting the profile property but omitting that channel in the subscriptions object. If a subscriptions object is not provided, subscriptions are defaulted to MARKETING.

Rate limits:
Burst: 100/s
Steady: 700/m

Scopes:
subscriptions:write

Query Params
string
required

Your Public API Key / Site ID. See this article for more details.

Body Params
object
required
string
required
object
required
string

A custom method detail or source to store on the consent records for this subscription.

object
required
object
required
string
required
string

Primary key that uniquely identifies this profile. Generated by Klaviyo.

object
required
string

Individual's email address

string

Individual's phone number in E.164 format

string

A unique identifier used by customers to associate Klaviyo profiles with profiles in an external system, such as a point-of-sale system. Format varies based on the external system.

string

Id that can be used to identify a profile when other identifiers are not available

string

Also known as the exchange_id, this is an encrypted identifier used for identifying a
profile by Klaviyo's web tracking.

You can use this field as a filter when retrieving profiles via the Get Profiles endpoint.

string

Individual's first name

string

Individual's last name

string

Name of the company or organization within the company for whom the individual works

string

The locale of the profile, in the IETF BCP 47 language tag format like (ISO 639-1/2)-(ISO 3166 alpha-2)

string

Individual's job title

string

URL pointing to the location of a profile image

object
string

First line of street address

string

Second line of street address

string

City name

string

Country name

Latitude coordinate. We recommend providing a precision of four decimal places.

Longitude coordinate. We recommend providing a precision of four decimal places.

string

Region within a country, such as state or province

string

Zip code

string

Time zone name. We recommend using time zones from the IANA Time Zone Database.

string

IP Address

object

An object containing key/value pairs for any custom properties assigned to this profile

string
object
object

Specify one or more patch operations to apply to existing property data

object

Append a simple value or values to this property array

string
object

Remove a simple value or values from this property array

string
string

Remove a key or keys (and their values) completely from properties

object
object

The subscription parameters to subscribe to on the "EMAIL" Channel.

object
required

The parameters to subscribe to on the "EMAIL" Channel. Currently supports "MARKETING".

string
required
date-time

The timestamp of when the profile's consent was gathered. This should only be used when syncing over historical consent info to Klaviyo; if the historical_import flag is not included, providing any value for this field will raise an error.

object

The subscription parameters to subscribe to on the "SMS" Channel.

object

The parameters to subscribe to marketing on the "SMS" Channel.

string
required
date-time

The timestamp of when the profile's consent was gathered. This should only be used when syncing over historical consent info to Klaviyo; if the historical_import flag is not included, providing any value for this field will raise an error.

object

The parameters to subscribe to transactional messaging on the "SMS" Channel.

string
required
date-time

The timestamp of when the profile's consent was gathered. This should only be used when syncing over historical consent info to Klaviyo; if the historical_import flag is not included, providing any value for this field will raise an error.

object
required
object
required
object
string
required
string
required

The list ID to add the newly subscribed profile to.

Headers
string
required
Defaults to 2025-01-15

API endpoint revision (format: YYYY-MM-DD[.suffix])

Responses
202

Success

Language