API Documentation

Our platform exposes some of its data via an Application Programming Interface (API).
Customers can use this API to gain access to their data in a programmatic fashion.

Campaign API Methods
Timed Campaign API Methods
Subscription Campaign API Methods
Vote Campaign API Methods
Account API Methods
Carrier API Methods
Testing

Authentication

All API methods require authentication. There are two ways to authenticate your API requests. The first being HTTP Basic Authentication. When authenticating via Basic Auth, you need to use the email address and password that you use to login to our platform. Almost all programming languages have a networking library that supports Basic Authentication.

The alternative is to use the API token associated with your account. Clicking on the “My Account” link in the application will show you your account information as well as your API token. Authentication using your API token is as simple as setting a header (NOTE: Not a url parameter) called api_token to the value assigned by the application. All API requests using the api_token header require SSL. If you make an api_token authentication request using http, and not https, you will get a 403 error back from the server.

Requests

All responses are relative to the context of the authenticated API user. If the user does not have access to a specific campaign or resource, they will receive an error message.

URLs

The root URL of all API requests is https://app.interactivemediums.com. If the request calls for a path
of /api/subscription_campaigns/1/subscriptions/3125551212.xml, then the full URL would be
https://app.interactivemediums.com/api/subscription_campaigns/1/subscriptions/3125551212.xml.

RESTful Resources

The API conforms to the design principles of Representational State Transfer (REST). At this time, XML and some JSON calls are the only supported format types.

Parameters

Some API methods take optional or requisite parameters. Where applicable, we’ve documented those parameters. Remember to convert to UTF-8 and URL encode parameters that take complex strings.

HTTP Requests

Methods exposed by the API require the HTTP request type that is noted, with the options
being GET, POST, PUT, DELETE. Each XML response is UTF-8 encoded. Be sure that your Content-Type HTTP header is set to “application/xml”.

HTTP Status Codes

The API attempts to return appropriate HTTP status codes for every request. Below is a
list of status codes you can expect to receive.

200 – The request was successful.

400 – Bad Request. Check to make sure you are passing valid arguments.

401 – Invalid credentials, or unauthorized access. You do not have permission to access this data.

422 – Your request could not be processed. The response message will contain a reason.

Error Response

When the API call returns an error, a message in the following format will
be returned, listing the request, and the reason for the error.

<?xml version="1.0" encoding="UTF-8"?>
<error>
   <request>/api/subscription_campaigns/1/subscriptions/destroy/3125551212.xml</request>
   <message>No user found for mobile phone 3125551212 and campaign ID 1</message>
</error>

Campaign API Methods

List

Returns a list of campaigns for this account

URL: /api/campaigns.xml

Formats: xml

HTTP Method(s): GET

Notes: Optionally, you can provide the campaign type or status that you would like returned. Valid status values include active, future, past, and deleted. Valid campaign types include SUB, INFO, VOTE, CONTEST, CHAT, AUC, TRIVIA, REQUEST, SURVEY, TIMED, and INSTWIN.

You can also provide a comma separated list of account ids via the accounts query parameter. Only your own account id or ids from the account you manage can be sent. If you don’t set this param, it defaults to your primary account’s id.

Example

A request to /api/campaigns.xml, would return a response like:


<?xml version="1.0" encoding="UTF-8"?>
<campaigns type="array">
   <campaign>
      <description>My first info campaign</description>
      <id type="integer">1</id>
      <keyword>FIRSTINFO</keyword>
      <account-id type="integer">123</account-id>
      <status>active</status>
      <campaign-type>
         <code>INFO</code>
      </campaign-type>
   </campaign>
   <campaign>
      <description>My first chat campaign</description>
      <id type="integer">2</id>
      <keyword>FIRSTCHAT</keyword>
      <account-id type="integer">123</account-id>
      <status>future</status>
      <campaign-type>
         <code>CHAT</code>
      </campaign-type>
   </campaign>
   <campaign>
      <description>My first subscription campaign</description>
      <id type="integer">3</id>
      <keyword>FIRSTSUB</keyword>
      <account-id type="integer">123</account-id>
      <status>past</status>
      <campaign-type>
         <code>SUB</code>
      </campaign-type>
   </campaign>
</campaigns>

A request to /api/campaigns.xml?status=active&type=SUB, would return a response like
the one above, but it would only include active subscription campaigns.

Timed Campaign API Methods

Show

Returns the details of a single timed campaign.

URL: /api/timed_campaigns/{campaign_id}.xml

Formats: xml

HTTP Method(s): GET

Example

A request to /api/timed_campaigns/1234.xml, would return a response like:


<?xml version="1.0" encoding="UTF-8"?>
<timed-campaign>
   <campaign-id type="integer">1234</campaign-id>
   <created-at type="timestamp">2008-12-19 19:52:00 UTC</created-at>
   <id type="integer">12</id>
   <opt-in-sms-message>This is your opt-in message</opt-in-sms-message>
   <opt-out-sms-message nil="true"></opt-out-sms-message>
   <subsequent-opt-in-attempt-sms-message>
      This is your subsequent opt-in attempt message
   </subsequent-opt-in-attempt-sms-message>
   <updated-at type="timestamp">2008-12-29 19:53:53 UTC</updated-at>
</timed-campaign>

Participants

Returns the list of participants for a given timed campaign.

URL: /api/timed_campaigns/{campaign_id}/participants.xml

Formats: xml

HTTP Method(s): GET

Notes: This request will return 250 participants at a time. If the page option is not specified, then the first
250 participants are returned. To get participants 251-500, provide the page attribute with a value of 2.
For participants 501-750, provide the page attribute with a value of 3, and so on.

Example

A request to /api/timed_campaigns/1234/participants.xml, would return a response like:


<?xml version="1.0" encoding="UTF-8"?>
<timed-campaign-users type="array">
   <timed-campaign-user>
      <created-at type="timestamp">2008-12-19 19:59:28 UTC</created-at>
      <timing-sequence-end-at type="timestamp">
        2008-12-20 02:15:00 UTC
      </timing-sequence-end-at>
      <timing-sequence-start-at type="timestamp">
        2008-12-19 19:59:28 UTC
      </timing-sequence-start-at>
      <user>
         <mobile-phone>5552435262</mobile-phone>
      </user>
   </timed-campaign-user>
   <timed-campaign-user>
      <created-at type="timestamp">2008-12-19 20:00:42 UTC</created-at>
      <timing-sequence-end-at type="timestamp">
        2008-12-20 02:15:00 UTC
      </timing-sequence-end-at>
      <timing-sequence-start-at type="timestamp">
        2008-12-19 20:00:42 UTC
      </timing-sequence-start-at>
      <user>
         <mobile-phone>5552738829</mobile-phone>
      </user>
   </timed-campaign-user>
   <timed-campaign-user>
      <created-at type="timestamp">2008-12-19 20:03:05 UTC</created-at>
      <timing-sequence-end-at type="timestamp">
        2008-12-20 02:15:00 UTC
      </timing-sequence-end-at>
      <timing-sequence-start-at type="timestamp">
        2008-12-19 20:03:05 UTC
      </timing-sequence-start-at>
      <user>
         <mobile-phone>5551112838</mobile-phone>
      </user>
   </timed-campaign-user>
</timed-campaign-users>

A request to /api/timed_campaigns/1234/participants.xml?page=2 would return
participants 251 – 500, a request to /api/timed_campaigns/1234/participants.xml?page=3
would return participants 501-750, and so on.

Subscription Campaign API Methods

List

Returns a list of subscriber records

URL: /api/subscription_campaigns/{campaign_id}/subscriptions.xml

Formats: xml

HTTP Method(s): GET

Notes

You may restrict the results to opt-ins between a given date range by using the opt_in_start and opt_in_end URL parameters. If you wish to restrict the results to only subscriptions who have opted in during a specific time frame, you must specify both of these parameters, and they must contain valid dates.

You may restrict the result to only confirmed subscriptions by setting the confirmed_only URL parameter to "true"


You may restrict the result to only unconfirmed subscriptions by setting the unconfirmed_only URL parameter to "true"

This request will return 250 subscribers at a time. If the page option is not specified, then the first

250 subscribers are returned.  To get subscribers 251-500, provide the page attribute with a value of 2.

For subscribers 501-750, provide the page attribute with a value of 3, and so on.



Example
A request to /api/subscription_campaigns/1/subscriptions.xml?opt_in_start=2010-06-02&opt_in_end=2010-06-04, would return a response like:

<?xml version="1.0" encoding="UTF-8"?>
<subscriptions current_page="1" per_page="250" total_entries="3">
   <subscription>
      <opt-in-at type="timestamp">2010-06-02 16:42:46 UTC</opt-in-at>
         <user>
         <mobile-phone type="string">3125551212</mobile-phone>
         <country-calling-code type="string">1</country-calling-code>
         <first-name type="string">Test</first-name>
         <last-name type="string">User</last-name>
         <email-address type="string">test@user.com</email-address>
         <zip-code type="string">12345</zip-code>
         <birthdate type="date">1973-01-11</birthdate>
         <gender type="string">M</gender>
         <home-phone type="string">7083321212</home-phone>
         <street-address type="string">123 Main St.</street-address>
         <city type="string">Chicago</city>
         <state type="string">IL</state>
         <account-number type="string">98765</account-number>
      </user>
   </subscription>
   <subscription>
       <opt-in-at type="timestamp">2010-06-02 18:18:34 UTC</opt-in-at>
       <user>
          <mobile-phone type="string">3125551213</mobile-phone>
          <country-calling-code type="string">1</country-calling-code>
       </user>
    </subscription>
    <subscription>
       <opt-in-at type="timestamp">2010-06-02 18:19:04 UTC</opt-in-at>
       <user>
          <mobile-phone type="string">3125551214</mobile-phone>
          <country-calling-code type="string">1</country-calling-code>
          <first-name type="string">Billy</first-name>
       </user>
    </subscription>
</subscriptions>


Create
Create a new subscription

URL
/api/subscription_campaigns/{campaign_id}/subscriptions.xml


Formats
xml


HTTP Method(s)
POST


Notes
The create API method allows you to specify values for any of the user attributes that you have configured for your account.  See the API Name column in the User Data section of the application to determine the name to use for each attribute.


Example

<subscription>
   <user>
      <mobile-phone>3125551212</mobile-phone>
      <first-name>Test</first-name>
      <last-name>User</last-name>
   </user>
</subscription>


Read
Return a single subscription record

URL
/api/subscription_campaigns/{campaign_id}/subscriptions/{mobile_phone}.xml


Formats
xml


HTTP Method(s)
GET


Example
A request to /api/subscription_campaigns/1/subscriptions/3125551212, would return a response like:

<?xml version="1.0" encoding="UTF-8"?>
<subscription>
   <opt-in-at type="timestamp">2010-06-02 16:42:46 UTC</opt-in-at>
   <user>
      <mobile-phone type="string">3125551212</mobile-phone>
      <country-calling-code type="string">1</country-calling-code>
      <first-name type="string">Test</first-name>
      <last-name type="string">User</last-name>
      <email-address type="string">test@user.com</email-address>
      <zip-code type="string">12345</zip-code>
      <birthdate type="date">1973-01-11</birthdate>
      <gender type="string">M</gender>
      <home-phone type="string">7083321212</home-phone>
      <street-address type="string">123 Main St.</street-address>
      <city type="string">Chicago</city>
      <state type="string">IL</state>
      <account-number type="string">98765</account-number>
   </user>
</subscription>




Update
Update a single subscription record

URL
/api/subscription_campaigns/{campaign_id}/subscriptions/{mobile_phone}.xml


Formats
xml


HTTP Method(s)
PUT


Notes
The update API method allows you to specify values for any of the user attributes that you have configured for your account.  See the API Name column in the User Data section of the application to determine the name to use for each attribute.


Example
The request sent to /api/subscription_campaigns/1/subscriptions/3125551212.xml, would update the subscribers first and last name.

<subscription>
   <user>
      <first-name>Test</first-name>
      <last-name>User</last-name>
   </user>
</subscription>


Delete
Delete a single subscription record

URL
/api/subscription_campaigns/{campaign_id}/subscriptions/{mobile_phone}.xml


Formats
xml


HTTP Method(s)
DELETE


Notes
Note that is is not necessary to pass any other data except for the user's mobile phone number in the URL string.


Unsubscribes
Returns a list of canceled subscriptions.

URL
/api/subscription_campaigns/{campaign_id}/unsubscribes.xml


Formats
xml


HTTP Method(s)
GET


Notes
You may restrict the results to opt-outs between a given date range by using the opt_out_start and opt_out_end URL parameters.  If you wish to restrict the results to only subscriptions who have opted out during a specific time frame, you must specify both of these parameters, and they must contain valid dates.


This request will return 250 subscribers at a time. If the page option is not specified, then the first

250 subscribers are returned.  To get subscribers 251-500, provide the page attribute with a value of 2.

For subscribers 501-750, provide the page attribute with a value of 3, and so on.


Example
A request to /api/subscription_campaigns/1/unsubscribes.xml?opt_out_start=2010-06-02&opt_out_end=2010-06-04, would return a response like:

<?xml version="1.0" encoding="UTF-8"?>
<subscriptions current_page="1" per_page="250" total_entries="3">
   <subscription>
      <opt-in-at type="timestamp">2010-06-02 16:42:46 UTC</opt-in-at>
      <opt-out-at type="timestamp">2010-06-03 16:42:46 UTC</opt-out-at>
         <user>
         <mobile-phone type="string">3125551212</mobile-phone>
         <country-calling-code type="string">1</country-calling-code>
         <first-name type="string">Test</first-name>
         <last-name type="string">User</last-name>
         <email-address type="string">test@user.com</email-address>
         <zip-code type="string">12345</zip-code>
         <birthdate type="date">1973-01-11</birthdate>
         <gender type="string">M</gender>
         <home-phone type="string">7083321212</home-phone>
         <street-address type="string">123 Main St.</street-address>
         <city type="string">Chicago</city>
         <state type="string">IL</state>
         <account-number type="string">98765</account-number>
      </user>
   </subscription>
   <subscription>
      <opt-in-at type="timestamp">2010-06-02 18:18:34 UTC</opt-in-at>
      <opt-out-at type="timestamp">2010-06-03 16:42:46 UTC</opt-out-at>
      <user>
         <mobile-phone type="string">3125551213</mobile-phone>
         <country-calling-code type="string">1</country-calling-code>
      </user>
   </subscription>
   <subscription>
      <opt-in-at type="timestamp">2010-06-02 18:19:04 UTC</opt-in-at>
      <opt-out-at type="timestamp">2010-06-03 16:42:46 UTC</opt-out-at>
      <user>
          <mobile-phone type="string">3125551214</mobile-phone>
          <country-calling-code type="string">1</country-calling-code>
          <first-name type="string">Billy</first-name>
      </user>
   </subscription>
</subscriptions>


Vote Campaign API Methods
Show
Returns the details of a single vote campaign.

URL
/api/vote_campaigns/{campaign_id}.xml


Formats
xml


HTTP Method(s)
GET


Example
A request to /api/vote_campaigns/1234.xml, would return a response like:

<?xml version="1.0" encoding="UTF-8"?>
<vote_campaign>
  <campaign_id>1234</campaign_id>
  <vote_campaign_id>786</vote_campaign_id>
  <description>My vote campaign</description>
  <start_at>2010-02-16 17:17:00 UTC</start_at>
  <end_at>2010-03-31 16:18:00 UTC</end_at>
  <question>What is your favorite color?</question>
  <vote_campaign_options>
    <vote_campaign_option>
      <option_name>blue</option_name>
      <option_keyword>BLUE</option_keyword>
      <option_vote_count>1</option_vote_count>
      <option_aliases>
        <option_alias>B</option_alias>
        <option_alias>BLU</option_alias>
      </option_aliases>
    </vote_campaign_option>
    <vote_campaign_option>
      <option_name>green</option_name>
      <option_keyword>GREEN</option_keyword>
      <option_vote_count>1</option_vote_count>
      <option_aliases>
        <option_alias>G</option_alias>
      </option_aliases>
    </vote_campaign_option>
    <vote_campaign_option>
      <option_name>red</option_name>
      <option_keyword>RED</option_keyword>
      <option_vote_count>2</option_vote_count>
    </vote_campaign_option>
  </vote_campaign_options>
</vote_campaign>


Cast Vote
Casts a vote for the specified vote option on the specified vote campaign.

URL
/api/vote_campaigns/{campaign_id}/votes.xml


Formats
xml


HTTP Method(s)
POST


Notes
 The user-id field is used to enforce that a user can only vote the number of times configured by the

vote campaign.  You must find some way of uniquely identifying a user (via IP address, or some other

piece of data collected from the user).  Then, you must pass that data in the user-id field.  The

user-id is a string, and can be up to 100 characters in length.  If no user-id field is specified, then

the maximum number of votes policy for the campaign can not be enforced. 


Example

<vote>
  <user-id>some_unique_id_to_identify_a_voter</user-id>
  <vote-option>VOTE_KEYWORD</vote-option>
</vote>



Account API Methods
List
Returns a list of accounts including the users's primary account, and all accounts managed by the user's primary account

URL
/api/accounts.xml


Formats
xml


HTTP Method(s)
GET


Example
A request to /api/accounts.xml, would return a response like:

<?xml version="1.0" encoding="UTF-8"?>
<accounts type="array">
  <account>
    <active type="boolean">true</active>
    <id type="integer">10</id>
    <managed-by-account-id type="integer">1</managed-by-account-id>
    <name>My account</name>
    <timezone>
      <code>CST</code>
    </timezone>
  </account>
  <account>
    <active type="boolean">true</active>
    <id type="integer">11</id>
    <managed-by-account-id type="integer">10</managed-by-account-id>
    <name>My first sub-account</name>
    <timezone>
      <code>CST</code>
    </timezone>
  </account>
  <account>
    <active type="boolean">true</active>
    <id type="integer">12</id>
    <managed-by-account-id type="integer">10</managed-by-account-id>
    <name>My second sub-account</name>
    <timezone>
      <code>EST</code>
    </timezone>
  </account>
</accounts>



Carrier API Methods
Please note that the Carrier API is a special feature that is enabled on a

per-account basis. Please contact sales@interactivemediums.com

if you are interested in using it.
List
Returns a list of all known Carriers

URL
/app/carriers.xml/app/carriers.json



Formats
xml, json


HTTP Method(s)
GET


Example
A request to /app/carriers.xml, would return a response like:

<?xml version="1.0" encoding="UTF-8"?>
<carriers type="array">
  <carrier>
    <id type="integer">1</id>
    <name>Alltel</name>
  </carrier>
  <carrier>
    <id type="integer">2</id>
    <name>Bell Mobility</name>
  </carrier>
</carriers>
The above was truncated for brevity.


Show
Returns an individual Carrier by it's ID

URL
/app/carriers/{id}.xml/app/carriers/{id}.json



Formats
xml, json


HTTP Method(s)
GET


Example
A request to /app/carriers/1.xml, would return a response like:

<?xml version="1.0" encoding="UTF-8"?>
<carrier>
  <id type="integer">1</id>
  <name>Alltel</name>
</carrier>


Lookup
Returns the Carrier for a given mobile number.

URL
/app/carriers/lookup/{mobile_phone}.xml/app/carriers/lookup/{mobile_phone}.json



Formats
xml, json


HTTP Method(s)
GET


Notes
Will return an HTTP status code of 404 if no carrier can be found for this mobile number.  This usually indicates an invalid mobile number.


Example
A request to /app/carriers/lookup/3125551212.xml, would return a response like:

<?xml version="1.0" encoding="UTF-8"?>
<carrier>
  <id type="integer">1</id>
  <name>Alltel</name>
</carrier>



Testing
Command line
First download this script. The script

will require a Unix variant terminal that has bash and curl installed.  Be sure to modify the

BASE variable to be http://www.textme.net. Below are some examples for you to try.

CREATE
sh test.sh POST /api/subscription_campaigns/{campaign_id}/subscriptions "<subscription><user mobile_phone='3125551212'></user></subscription>"


READ
sh test.sh GET /api/subscription_campaigns/{campaign_id}/subscriptions/3125551212.xml


UPDATE
sh test.sh PUT /api/subscription_campaigns/{campaign_id}/subscriptions/3125551212.xml "<subscription><user mobile_phone='3125551212' first_name='Test' last_name='User'></user></subscription>"


DELETE
sh test.sh DELETE /api/subscription_campaigns/{campaign_id}/subscriptions/3125551212.xml


LIST
sh test.sh GET /api/subscription_campaigns/{campaign_id}/subscriptions

PHP
Read this article, and refer to the code at the end of the article. Be sure to update the URL and username and password.


    
    



Browse Resources
Expand All | Collapse All

Resource Center

	Understanding The Role of Shared Short Codes
	Web Forms
	Getting Started
	
		Carriers Supported
		Customer Support
		Data Privacy and Security
		Fault Tolerant Technology
		Text Message Campaigns
		How It Works
		System Requirements
		Short Code Provisioning Process
		Setting Objectives
	

	Campaign How-To Guides
	
		Sweepstakes
		
			Sweepstakes Basics
		

		Subscription Lists
		Surveys
		Voting / Polling
		Auctions
		Info-on-demand / Autoresponder
		Trivia Contests
		Chat / Text-to-screen
		Timed Messages
		Instant Win
	

	Demonstration Videos
	Mobile Marketing Fundamentals
	
		Mobile Optimized Websites
		Smartphone Applications
		Keywords
		Vanity and Random Shortcodes
		Shared and Dedicated Shortcodes
		Inbound Versus Outbound Messages
		Messaging Types
		Costs to Consumers
		Supported Program Types
		Mobile Ecosystem
		Mobile Marketing Strategy
		Third Party Resources
	

	API Documentation

API Documentation

Authentication

Requests

URLs

RESTful Resources

Parameters

HTTP Requests

HTTP Status Codes

Error Response

Campaign API Methods

List

Timed Campaign API Methods

Show

Participants

Subscription Campaign API Methods

List

Create

Read

Update

Delete

Unsubscribes

Vote Campaign API Methods

Show

Cast Vote

Account API Methods

List

Carrier API Methods

List

Show

Lookup

Testing

Command line

PHP

Browse Resources

More about:

More about: