How to collect SMS consent via API

You will learn

Learn how to collect SMS consent using Klaviyo's List V2 API. 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. 

Before you begin

We recommend that you be familiar with the List V2 API before you begin.

You must have: 

• Enabled SMS in Klaviyo
• Set up your branded sender ID, also called an alphanumeric sender ID (Australia)
• Set up a sending number for the UK

Before you are able to begin collecting consent via the API, you must finish setting up SMS and, if syncing consent for people in the UK or Australia, configure your branded sender ID or other number. If you have not enabled SMS in your account or set up this 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.

“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. If double opt-in is turned on, you will not see the data until after the subscriber has finished opting in.

Sample Python code

import requests
import json
data = {
   "api_key": "PRIVATE_API_KEY",
   "profiles": [
       {
           "phone_number": "+12345678900",
           "sms_consent": True
       }
   ]
}
headers = {
   "Content-Type": "application/json",
   "Cache-Control": "no-cache"
   }
conv = json.dumps(data)
response = requests.request("POST", "https://a.klaviyo.com/api/v2/list/{LIST_ID}/subscribe", data=conv, headers=headers)
print(response.text)

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: https://a.klaviyo.com/api/v2/list/{LIST_ID}/subscribe and include a small JSON payload.

1. 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 needed, view our article on how to find a list ID.

2. 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": "youremail@gmail.com"

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

Check for prior consent

The get-members List API endpoint can be leveraged to confirm that a contact number has or has not already consented to receiving SMS. To do so, make a POST request to https://a.klaviyo.com/api/v2/list/LIST_ID/get-members?api_key=API_KEY and include the phone numbers you wish to check for SMS consent in your payload. The example below uses Python. This method can also be used to check for email consent. 

If the phone number passed to the endpoint is not returned in the response, the number has not consented to receive SMS communications from you.

import requests

url = "https://a.klaviyo.com/api/v2/list/LIST_ID/get-members?api_key=API_KEY"

payload = {
    "phone_numbers": ["+13239169023", "+12028837032"]
}
headers = {
    "Accept": "application/json",
    "Content-Type": "application/json"
}

response = requests.request("POST", url, json=payload, headers=headers)

print(response.text)

Be careful to ensure that all phone numbers are properly formatted. An improperly formatted phone number will cause the call to silently fail.

Outcome

You've now learned how to collect and remove SMS consent, and check for prior SMS consent, via Klaviyo's APIs. 

Additional resources

• Accepted phone number formats for SMS in Klaviyo
• Review your SMS settings
• Getting started with SMS and MMS for the first time