HomeGuidesAPI Reference
ChangelogHelp CenterCommunityContact Us
Guides
ChangelogHelp CenterCommunityContact Us
These docs are for v2023-10-15. Click to read the latest docs for v2024-10-15.

Collect email and SMS consent via API

Learn how to collect consent and best practices

It's crucial to collect email and SMS consent properly to comply with necessary regulations and maintain a positive relationship with your customers. There are multiple ways to subscribe a profile in Klaviyo. Subscriptions can be created via our API, sign-up forms, native or third party integrations, a manual CSV import, and more. In this guide, we’ll focus on subscribing via API as well as covering the type of information you can get via API around consent and suppressions.

Obtaining email and SMS consent is essential for effective marketing, as it also allows businesses to communicate with their customers in a way that is both relevant and personalized, ultimately resulting in higher engagement rates and better return on investment.

🚧

This information is not legal advice. Klaviyo recommends that you consult with your legal counsel to make sure that you comply with applicable laws in connection with your marketing activities.

Relevant endpoints

At Klaviyo, consent status indicates whether or not someone requested to receive your SMS and/or email marketing. A profile can have a consent status of SUBSCRIBED, NEVER SUBSCRIBED, or UNSUBSCRIBED

The API endpoints we’ll cover in this article include:

  • Subscribe Profiles
    Used to subscribe a profile to email and/or SMS marketing.
  • Unsubscribe Profiles
    Used to unsubscribe a profile from email and/or SMS marketing.
  • Suppress Profiles
    Used to suppress a profile to prevent it from receiving email and/or SMS marketing regardless of consent status.
  • Unsuppress Profiles
    Used to unsuppress a profile to allow it to receive email and/or SMS marketing.
  • Add Profile to List
    Used to add a profile to a list with the given list ID.

In addition to reviewing this guide, we recommend that you make test calls to these endpoints to better understand how they work. Klaviyo maintains a Postman collection you can use to get familiar with these API calls.

Subscribe a profile via API

To subscribe a profile via API, follow these steps:

  1. Create new profiles or have existing profiles that you want to subscribe.
  2. If the profile gave consent, use the subscription endpoints to subscribe the profile to the appropriate channels (email and/or SMS).
  3. If a profile has not given explicit consent but you have implicit consent (see below for more information on implied consent) you can use the Add Profile to List endpoint to add a profile to a list without subscribing them. In this case, the profile would be added to your list, but would maintain a consent status of NEVER_SUBSCRIBED.

With a list

The example below is an API request to the Subscribe Profiles endpoint — updating email and SMS marketing consent and adding to the Y6nRLr list. Make sure to fill out placeholder information such as the private API key, etc. 

curl --request POST \
     --url https://a.klaviyo.com/api/profile-subscription-bulk-create-jobs/ \
     --header 'Authorization: Klaviyo-API-Key {your-private-api-key}' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'revision: {YYYY-MM-DD}' \
     --data '
{
  "data": {
    "type": "profile-subscription-bulk-create-job",
    "attributes": {
      "profiles": {
        "data": [
          {
            "type": "profile",
            "attributes": {
              "email":"[email protected]",
              "phone_number":"+15005550006",
              "subscriptions": {
                "email": {
                  "marketing": {
                    "consent": "SUBSCRIBED"
                  }
                },
                "sms": {
                  "marketing": {
                    "consent": "SUBSCRIBED"
                  }
                }
              }
            }
          }
        ]
      }
    },
    "relationships": {
      "list": {
        "data": {
          "type": "list",
          "id": "Y6nRLr"
        }
      }
    }
  }
}
'

📘

Due to the asynchronous nature of the API call, it may take a short amount of time for the result to display in Klaviyo or in a GET Profile(s) API call.

Without a list

As of the 2023-10-15 revision, the list relationship object on the request payload for the Subscribe Profiles endpoint is optional. If a list is not provided, Klaviyo will use the account's default opt-in settings. This will be double opt-in, unless it is explicitly updated by a user on the account.

The example below is an API request to the endpoint; this will update the profile's email and SMS marketing consent without adding it to a list:

curl --request POST \
     --url https://a.klaviyo.com/api/profile-subscription-bulk-create-jobs/ \
     --header 'Authorization: Klaviyo-API-Key {your-private-api-key}' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'revision: {YYYY-MM-DD}' \
     --data '
{
  "data": {
    "type": "profile-subscription-bulk-create-job",
    "attributes": {
      "profiles": {
        "data": [
          {
            "type": "profile",
            "attributes": {
              "email":"[email protected]",
              "phone_number":"+15005550006",
              "subscriptions": {
                "email": {
                  "marketing": {
                    "consent": "SUBSCRIBED"
                  }
                },
                "sms": {
                  "marketing": {
                    "consent": "SUBSCRIBED"
                  }
                }
              }
            }
          }
        ]
      }
    }
  }
}
'

Single vs double opt-in

With a list

When subscribing a profile via API with a list, the list's opt-in process determines the opt-in process used to subscribe the profile for that API call. The account's default opt-in settings will have no impact on the behavior here when a list is a provided.

Single opt-in

When subscribing a profile via API, if your included list is single opt-in, the profile will not need to confirm their subscription before their consent status is updated in Klaviyo.

Double opt-in

If the list is a double opt-in list, the profile being subscribed will be asked to confirm their subscription. In this case, you will not see the profile marked as consented in subsequent API requests nor will you see an update to the Channel box in the Klaviyo UI until the subscriber has finished opting in.

If you don't want the double opt-in email or SMS to be sent, make sure the list you're subscribing profiles to is set to single opt-in.

📘

If your API calls to the Subscribe Profiles endpoint are being accepted, but the consent status of a profile isn't changing, double check to see if the list they are being subscribed to is double opt-in.

Without a list

When subscribing a profile via API without a list, the opt-in process used to subscribe the profile depends on the account's default opt-in settings.

Single opt-in

If the toggle is set to single opt-in, the profile does not need to confirm their subscription before their consent status is updated in Klaviyo.

Double opt-in

If the toggle is set to double opt-in (i.e., the default), the profile will need to confirm their subscription before their consent status is updated in Klaviyo.

If you don't want the double opt-in email or SMS to be sent, make sure that your account's opt-in setting is set to single opt-in or that you're using a single opt-in list in your request as mentioned above.

About subscriptions and consent

Implicit consent is when someone gives you their contact information (e.g., email address, phone number, etc.) but does not explicitly say they want to receive marketing messages from your brand. These profiles will have the consent status NEVER_SUBSCRIBED. A common example of implicit consent is when a customer makes a purchase and provides their email at checkout. They have not explicitly said they want to receive marketing messages from the brand, but it can be inferred that they have an interest in relevant content. In this case, you have their information, but they haven’t agreed to receive marketing communications.

These profiles are able to receive emails, but you should exercise caution when contacting them. Depending on your local regulations, you may (or may not) be permitted to email these profiles if you believe they have implied consent. Read Understanding explicit vs. implicit consentto learn more, and make sure to check your local laws and regulations regarding implicit consent.

🚧

Klaviyo recommends that you only email profiles with express consent to protect your deliverability and sender reputation. Implied consent does not apply to SMS subscriptions. Consent must be explicit for SMS.

SMS-specific considerations

Configuring SMS

Before you can collect SMS consent, you must have:

  • Enabled SMS in Klaviyo.
  • Set up your sending number(s).

If you have not enabled SMS in your account or set up your sending number(s), you can learn more in How to turn on SMS in Klaviyo. If SMS setup is incomplete, you may receive a response like below when attempting to add consent data:

"SMS configuration is required to subscribe phone number only profiles."

If you receive this response from your API call, double check your account’s SMS configuration.

Phone number validation

After your Klaviyo account has been set up to collect consent, you’ll next need to validate each phone number passed via API, otherwise the API call may fail.

When passing in a phone number to our API, ensures that the phone number is:

  1. A valid (real) phone number.
  2. Your account’s sending number supports the country code.
  3. You have no spaces between numbers.

Get subscription information via API

The subscriptions object

To retrieve the subscriptions object, you must use the ?additional-fields query parameter. The following request to Get Profiles uses ?additional-fields[profile]=subscriptions to include profile-specific subscription data in the response. Note that subscriptions objects are always associated with a profile object.

curl --request GET \
     --url 'https://a.klaviyo.com/api/profiles/?additional-fields[profile]=subscriptions' \
     --header 'Authorization: Klaviyo-API-Key your-private-api-key' \
     --header 'accept: application/json' \
     --header 'revision: 2023-10-15'

{
    "data": [
        {
            "type": "profile",
            "id": "01EFPSGTVXBGERQPGM3VQ734KS",
            "attributes": {
                "email": "str",
                ...
                "location": {...},
                "properties": {
                    "Shopify Tags": [],
                    "Accepts Marketing": true,
                    "$city__transformed": "Norwalk",
                    "$country__transformed": "United States",
                    "$first_name__transformed": "Theodore",
                    "$previous_month_rfm_group": "Needs attention",
                    "$current_month_rfm_group": "Needs attention"
                },
                "subscriptions": {
                    "email": {
                        "marketing": {
                            "can_receive_email_marketing": true,
                            "consent": "NEVER_SUBSCRIBED",
                            "consent_timestamp": null,
                            "last_updated": null,
                            "method": null,
                            "method_detail": null,
                            "custom_method_detail": null,
                            "double_optin": null,
                            "suppression": [],
                            "list_suppressions": []
                        }
                    },
                    "sms": {
                        "marketing": {
                            "can_receive_sms_marketing": true,
                            "consent": "SUBSCRIBED",
                            "consent_timestamp": "2023-07-28T13:26:48.852051+00:00",
                            "method": "TEXT",
                            "method_detail": "JOIN",
                            "last_updated": "2023-07-28T13:26:48.852051+00:00"
                        }
                    }
                }
            },
            "relationships": {...},
            "links": {
                "self": "https://a.klaviyo.com/api/profiles/01EFPSGTVXBGERQPGM3VQ734KS/"
            }
        }
    ],
    "links": {
        "self": "https://a.klaviyo.com/api/profiles/?additional-fields[profile]=subscriptions",
        "next": "https://a.klaviyo.com/api/profiles/?additional-fields%5Bprofile%5D=subscriptions",
        "prev": null
    }
}

Considerations

Marketing fields

Note the following:

  • method_detail may contain additional information depending on the source used for the subscription.

  • custom_method_detail will contain any information passed into the optional custom_source field for Subscribe Profiles and Create Client Subscription.

    • custom_source is equivalent to the $source parameter in the legacy v2 Subscribe API.

  • double_optinis only set to true if the email recipient received a double opt-in message and confirmed it.

📘

It is recommended to use the channels object to explicitly set the marketing channels you want the profile to subscribe to. This object is related to the “Channel Status” Box that exists in the Klaviyo UI. See Understanding consent in profiles to learn more and see associated visual indicators.

Filtering rules

Note the following rules for filtering by subscription data:

  • You cannot mix-and-match list and global filters.

  • You may only specify a single date filter.

  • You may or may not specify a reason.

  • You must specify a list_id to filter on any list suppression properties.

Unsubscribing a profile via API

Use the Unsubscribe Profiles endpoint to unsubscribe one or more profiles from email marketing, SMS marketing, or both.

To remove someone from a list without changing their subscription status, use the Remove Profile from List endpoint.

Suppressing a profile via API

Suppressions are separate concept from consent status. Suppression status tells you if a profile is to receive your email marketing. Suppression status does not yet exist for SMS. There may be situations where you will not want to send marketing to someone, even if they previously expressed interest in receiving it. For example, you may want to suppress a consented profile if they are no longer engaged.

Use the Suppress Profiles endpoint to manually suppress one or more profiles. Such profiles will have USER_SUPPRESSED as their suppression reason. Manually suppressed profiles will not receive email marketing.

Use the Unsuppress Profiles endpoint to unsuppress one or more profiles. This will remove any manual suppressions (USER_SUPPRESSED) on these profiles. A profile may receive email marketing after a manual suppression is removed, so long as they have not revoked consent, i.e., unsubscribed.

📘

Currently, you can only suppress or unsuppress a profile via an email identifier.

Learn more about suppressed profiles in Understanding suppressed email profiles.

Additional resources

Updated about 1 year ago

Power smarter
digital relationships
By entering your information and clicking “Sign up,” you consent to receive marketing emails (such as newsletters, blog posts, webinars, event invitations and new product updates) from Klaviyo from time to time. You can unsubscribe at any time by clicking on the “Unsubscribe” link at the bottom of our emails. For more information on how we process your personal information and what rights you have in this respect, please see our Privacy Policy.
Terms and Privacy Trademarks Security