Guide to Collecting SMS Consent via API

Last updated at:


You can use Klaviyo's v2 List API to collect SMS consent. This is particularly helpful if you want to gather phone numbers for SMS marketing with a non-Klaviyo signup form. For details on how to leverage APIs for SMS, the instructions below provide sample Python code that you can quickly implement. We recommend that you be familiar with the List V2 API before you begin.

Setup Requirements

You must finish setting up SMS in Klaviyo before you are able to begin collecting consent via the API. If you have not enabled SMS in your account or set up an SMS sending number, you will not be able to issue consent for phone numbers or send SMS messages. Please refer to our guide to Getting Started with SMS.

If SMS setup is incomplete, you may receive a response like the following when attempting to add consent data. If you receive this response from your API call, double check your account’s SMS configuration.
“SMS configuration is required to subscribe phone number only profiles.”

Collecting SMS consent utilizes the List V2 API’s Subscribe endpoint to add a phone number and its corresponding consent data to a subscription list. 

As with email, you can add subscribers with the List API regardless of your account’s double opt-in settings. If double opt-in is turned off for your list, your API response data will contain the subscribed profile’s ID number along with the list of added records such as email and phone number.

Sample Code

import requests
import json
data = {
   "api_key": "PRIVATE_API_KEY",
   "profiles": [
           "$consent": ["sms"],
           "phone_number": "+12345678900",
           "sms_consent": True
headers = {
   "Content-Type": "application/json",
   "Cache-Control": "no-cache"
conv = json.dumps(data)
response = requests.request("POST", "{LIST_ID}/subscribe", data=conv, headers=headers)

Setup Code Variables

This example uses Python; however, any code language can be used to implement SMS consent via API. Because we are using Python in the code snippet above, true is set to True. If you require only the JSON portion of the above code, be sure to use true.

To add an SMS subscriber, the script will make a POST request to the Subscribe endpoint:{LIST_ID}/subscribe and include a small JSON payload.

Update API Key and List ID

Update the PRIVATE_API_KEY value to a private API key from your Klaviyo account. Then, locate the Subscribe endpoint at the end of the script. Update the LIST_ID in the endpoint URL with your chosen list. If you need help locating your list ID, check out our guide here.

Include Phone Number and Consent Status

Pass in a phone number in E.164 format and set sms_consent to True:

"phone_number": "+12345678900",
"sms_consent": True

You can also capture email consent with the same form by adding an email object to the payload:

"email": ""

Add GDPR Consent

If you are a GDPR-compliant business, you will need to include the $consent property in your API call. $consent is a Klaviyo-specific property and only accepts the following values:

  • sms — Consent to receive communication via text message
  • email — Consent to receive communication via email
  • web — Consent to receive communication via website
  • directmail — Consent to receive direct mail communications
  • mobile — Consent to receive communication on mobile devices

You can use $consent for segmentation to indicate GDPR compliance.

"$consent": ["sms"],
"sms_consent": True

The property must be used in addition to, not in place of, sms_consent, which is required to add consent to a profile.

Remove SMS Consent via API

If you would like to remove SMS consent from a profile without removing it from the list, you can use a similar API call to update the profile's SMS consent again.

In your JSON payload, set sms_consent to false and submit a POST request to the same List V2 Subscribe endpoint as used in the sample code above. Ensure that you are using the correct LIST_ID in the endpoint URL.

"sms_consent": False
Was this article helpful?
28 out of 44 found this helpful