TextMe API Documentation

TextMe 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. For the time being, HTTP Basic Authentication is the only supported authentication scheme. When authenticating via Basic Auth, you need to use the email address and password that you use to login to TextMe. Other login types (ex: session cookies, parameter-based login) are not supported.

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 http://www.textme.net. If the request calls for a path of /api/subscription_campaigns/1/subscriptions/3125551212.xml, then the full URL would be http://www.textme.net/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.

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 unauthoized 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

Example

A request to /api/subscription_campaigns/1/subscriptions.xml, would return a response like:

<subscriptions>
   <subscription>
      <confirmed-at type="timestamp" nil="true"/>
      <opt-in-at type="timestamp">Wed Oct 01 04:19:17 UTC 2008</opt-in-at>
      <user>
         <birthday-on type="date" nil="true"/>
         <carrier-id type="integer" nil="true"/>
         <email nil="true"/>
         <first-name nil="true"/>
         <gender nil="true"/>
         <last-name nil="true"/>
         <mobile-phone>3125551212</mobile-phone>
         <postal-code nil="true"/>
         <timezone-id type="integer" nil="true"/>
      </user>
   </subscription>
</subscriptions>
        

Create

Create a new subscription

URL

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

Formats

xml

HTTP Method(s)

POST

Example

<subscription>
   <user>
      <mobile-phone>3125551212</mobile-phone>
   </user>
</subscription>
      

Read

Return a single subscription record

URL

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

Formats

xml

HTTP Method(s)

GET

Notes

In this example, the only data that has been set (aside from the campaign identifier) is the mobile phone and the time the user was opted in. Note that if the confirmed_at element is empty, the user has not yet confirmed their subscription by replying to the initial subscription request.

Example

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

<subscription>
   <confirmed-at type="timestamp" nil="true"/>
   <opt-in-at type="timestamp">Wed Oct 01 04:19:17 UTC 2008</opt-in-at>
   <user>
      <birthday-on type="date" nil="true"/>
      <carrier-id type="integer" nil="true"/>
      <email nil="true"/>
      <first-name nil="true"/>
      <gender nil="true"/>
      <last-name nil="true"/>
      <mobile-phone>3125551212</mobile-phone>
      <postal-code nil="true"/>
      <timezone-id type="integer" nil="true"/>
   </user>
</subscription>
      

Update

Update a single subscription record

URL

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

Formats

xml

HTTP Method(s)

PUT

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>
      <first-name>User</first-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.

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

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.