You can use Listrak's SMS REST API to manage subscriptions to your SMS program. Listrak's REST API can subscribe net-new contacts, resubscribe contacts, and unsubscribe contacts. This guide outlines the specific API calls you will use to manage the subscription for each of these use cases.
Before You Begin
Integration Setup
Before you can manage subscription using Listrak's API, you will need to set up the SMS REST API.
💡 The SMS REST API utilizes Bearer tokens to authenticate your requests.
If you have not created a SMS REST API Integration, follow the steps below:
Access the Integration Dashboard by navigating to Integrations > Integration Management.
Click New Integration.
Select the SMS API card > click Integrate.
Open the SetUp tab at the top.
Enter an Integration Name.
Now, you can configure the IP address(es) that are permitted to access the integration by following step 5a. You may also disable the whitelist, if desired, by following step 5b.
To configure a whitelist:
Select on the following options - Single IP Address, Wildcard Match, or IP Address Range.
Add IP Address(es)
Disable the IP Address(es) that have been whitelisted.
Check the box to disable any previously whitelisted IP addresses
When clicking save you will be required to confirm that you want to disable whitelisting.
This will NOT delete the IP addresses listed. You can re-enable at any time by unchecking the box.
💡 You can enable or disable the whitelist settings at any time.
Click Save to complete the setup.
Copy your Client ID and Secret for use in authenticating your API.
SMS API Authentication
After your integration has been set up, you're ready to authenticate your REST API Integration. The instructions below use Postman, but you can authenticate in languages such as PHP or JAVA.
💡 You will need to re-authenticate every 60 minutes.
In Postman, paste the following value in the Request URL box: https://auth.listrak.com/OAuth2/Token
Select the POST type.
Save the authentication request.
In the popup that appears:
Give the request a name.
Select an existing collection, or create new.
Click save to confirm your settings.
In the body section of the request:
Select the x-www-form-urlencoded type.
In the key specifications enter the following:
Key 1: grant_type
Value 1: client_credentials
Key 2: client_id
Value 2: Unique client ID copied during the integration
Key 3: client_secret
Value 3: Unique client secret copied during the integration
Save your integration.
Use the Send function to generate your bearer access token.
In the authorization tab, select the bearer access type.
Paste the bearer access token into the field.
📖 Additional API Resources
Subscription Calls
Call #1: Current Subscription Status Check
The first call you need to make when a contact inputs their phone number that you want to send to Listrak via API is to check their current subscription status.
Use the Get Contact call to identify the current subscription status from the optedOut field. The call will include one of three values in a successful response.
Call Response | Subscription Status |
OptedOut = False | Currently subscribed |
OptedOut = True | Currently unsubscribed |
ERROR_PHONE_NUMBER_NOT_SUBSCRIBED (ERROR_PHONE_NUMBER_NOT_FOUND) | Phone number is not identified Phone number has never been subscribed and is net-new to the short code |
Call #2 Subscribe a Contact
The specific call you will need to make for a contact will differ based on their subscription status.
Re-subscribing a Contact
To re-subscribe a contact who has previously opted out, use the Subscribe Contact call. This will re-subscribe the contact to the specified list and short code.
💡 Need to add additional data to the contact's profile? Use the Update Contact call outlined in Call #3.
Subscribing a Net-new Contact
To add a new phone number to the specified list and short code, use the Create Contact call. This will add the new phone number to the list.
⚠️ Make sure you include the OptedOut = False parameter in the call. If no value is provided, the API will default the status to true and the contact will not be subscribed.
💡 You can include additional profile data to a contact record during the subscription as part of the create contact call. To add profile data at a later time, use the Update Contact Call.
Call #3 Add Additional Profile Data (Optional)
After you have re-subscribed a known contact or added a net-new contact, you can append additional data to a contact's profile. You can save data to the profile field associated with the phone number using the Update Contact call and including the values you would like to save in each segmentation field.
⚠️ You must make the re-subscribe call prior to making an update call.
Opt-Out Call
To opt a contact out of the short code so they no longer receive messages, use the Update Contact call. You will need to pass the value of false in the OptedOut parameter.