Xanthem API Documentation

The Xanthem API is available for custom application development. The API has been tested to be stable, but we still change, update, and add methods as we receive your feedback.

The Xanthem API supports the REST format. Example requests and responses can be found for each method we support. If you need a method that we don't have, send us an email and we'll consider it.
The general format of requests is an HTTP POST that posts to: https://www.xanthem.com/api/{method_name}/
The response to API calls is delivered in standard XML.
Most methods require an API key which is found in your Xanthem account settings.

Pushing text messages to a list of individual users

Integrating SMS into your application couldn't be made simpler. Note that users must either have previously sent a message to this campaign, or have given you verbal authorization to send them text messages. No form of spam will be tolerated in the slightest.

The Request

https://www.xanthem.com/api/push

Required Agruments:

apiKey: The API Key found in your account settings
campaign: The campaign your message will be sent from
users: a comma separated list of 11 digit numerical phone numbers (usa only ex. 12085551212)
msg: the message you are sending to the user

Optional Agruments:

date: leave this blank to send this message NOW, or enter a date to schedule a message for future delivery (ex. 12/17/08 14:00)
repeat: leave this 0 to send a message only once, or enter a number to repeat the message every X days

The Response

The response will have stat="ok" if the call is successful, and stat="fail" if there is an error

Sample Response:

Pushing text messages to all users of a given campaign

Pushing message blast style to all users who have previously opted in to your campaign is easy.

The Request

https://www.xanthem.com/api/pushall

Required Agruments:

apiKey: The API Key found in your account settings
msg: the message you are sending to the user

Optional Agruments:

campaign: leave this blank to send to ALL campaigns, or specify a single campaign you wish to send to
date: leave this blank to send this message NOW, or enter a date to schedule a message for future delivery (ex. 12/17/08 14:00)
max: if this variable is not blank, the message will be sent to the oldest "x" customers based on the date of the last message they received
repeat: leave this 0 to send a message only once, or enter a number to repeat the message every X days

The Response

The response will have stat="ok" if the call is successful, and stat="fail" if there is an error

Sample Response:

<rsp method="pushall" stat="ok"> <date>{ts '2008-03-07 23:48:49'}</date> <valid count="13">Message Sent</valid> </rsp>

Adding customers to a campaign

I some cases you may want to add customers to your campaign without pushing a message to them (which adds them by deafault). The 'customeradd' method accepts a comma separated list of customers (whether in the datebase or not) and adds those who are not already subscribers of that campaign to your database.

The Request

https://www.xanthem.com/api/customeradd

Required Agruments:

apiKey: The API Key found in your account settings
campaign: The campaign your users will be added to
customers: a comma separated list of 11 digit numerical phone numbers (usa only ex. 12085551212)

The Response

The response will have stat="ok" if the call is successful, and stat="fail" if there is an error

Sample Response:

Adding campaigns to your account

For when you need to add campaigns to your account on the fly.

The Request

https://www.xanthem.com/api/campaign

Required Agruments:

apiKey: The API Key found in your account settings
campaign: The campaign you would like to add to your account
reply: The return text for this campaign. 135 char max. Note: If this is left blank and you specify a callback url we will use the text from that callback url as the return text.

Optional Agruments:

reply2: The return text for this campaign for customers who have previously interacted with this campaign. If this is left blank the value you specify in "reply" above will always be returned to the user.
notify: Either a phone number, or email address you would like to notify each time this campaign receives a message
callback: The callback url you wish to hit each time this campaign receives a message
description: A brief description of this campaign

The Response

The response will have stat="ok" if the call is successful, and stat="fail" if there is an error

Sample Response:

<rsp method="campaign" stat="ok"> <date>{ts '2008-03-07 23:48:49'}</date> <campaign>yourcampaign</campaign> <reply>Your Return Text</reply> <notify>12085551212</notify> <callback>Optional URL</callback> </rsp>

Querying for random customers

Sometimes you will want to pull random numbers from the database for prizes and/or other applications

The Request

https://www.xanthem.com/api/random

Required Agruments:

apiKey: The API Key found in your account settings
count: The number of random records that should be returned (maximum of 10)

Optional Agruments:

campaign: If specified will only select numbers from a specific campaign
start: If specified will only select new users who entered the system AFTER this date
end: If specified will only select new users who entered the system BEFORE this date

The Response

The response will have stat="ok" if the call is successful, and stat="fail" if there is an error

Sample Response:

<rsp method="random" stat="ok"> <date>{ts '2008-03-07 23:48:49'}</date> <campaign>yourcampaign</campaign> <customers count="1"> <customer> <join>2008-11-16 22:26:29.0</join> <number>12085551212</number> </customer> </customers> </rsp>

Using Callback URL's

Sometimes your application needs to be notified when a user sends a message to one of your campaigns. To accommodate this need, each campaign can have a "callback URL" to which we will send each phone number and message users send to your campaign.

Variables
%c%: The campaign the user sent the message to
%p%: The phone number of the user who sent a message to your campaign
%m%: The message they sent

Sample Callback URL
http://yourdomain.com/callback.cfm?campaign=%c%&phone=%p%&message=%m%

Returning text to the user
Each time a user sends a message to your campaign you have the option of sending a return message back to the user. This message is generally the default text stored in the campaign preferences, but it may alternatively be the text returned by your callback URL.

Campaign Widgets

If you would like your users to be able to opt-in via a form on your website we've made the process pretty painless. Each campaign has a widget key that can be passed along with a phone number to the API and the submitted user will be added to your customer database.

Sample form code: (this code is pasted into the website you would like the widget to appear)

<form method="post" action="http://www.xanthem.com/api/widget"> <input type="hidden" name="wkey" value="xxxx-xxxxxxx-xxxxxx"> Phone: <input name="phone"> <input type="submit"> </form>

Required Agruments:

wkey: The widget key assigned to the campaign that you would like the phone submitted to be added to
phone: The phone number of the user who should be inserted into the DB

Optional Agruments:

silent: By default the widget will send a message to the NEW users phone when the form is submitted, if you want to override this behavior simple send silent=1 and we wont send the message.

Returning the user to your site
When the user submits the form, in the background they are sent to the xanthem site. Once their information has been recorded they are then passed back to the page they came from and a "xanthem" variable is passed back.

Return URL

The xanthem variable can have one of several possible values and would look something like
http://yoursite.com/?xanthem=New

InvalidKey: The key submitted is incorrect
InvalidPhone: The phone number submitted is not a valid phone number
New: This is a new user record
Duplicate: This phone number has already been entered in the system