Trumpia API - Version 1.60

Last Updated: 11/01/12

Introduction

Trumpia's API will enable users to create applications or integrate with the user's system with some of the services and features offered by Trumpia. Users will be able to synchronize a contact list or database with their Trumpia account as well as perform most of the common tasks such as sending messages or creating and setting up keywords. Trumpia's API also offers two way SMS communication by forwarding incoming text messages that start with a user's keyword to the user's server.

Our API is a set of web pages (php) that you can call using the POST and GET methods of a form post or by constructing a query string on the URL. So any software or language that can submit a web form or call a URL and receive a response will be compatible with our API.

We will be updating and improving our API so please feel free to send us questions, comments, or feature requests and check our website for the latest version of this document as well as updates.

Getting Started

In order to use the API, you must obtain an API Key for your Trumpia account. To obtain a key, please contact us using the support request page after logging into your Trumpia account. All accounts requesting an API Key will be reviewed and upon approval an API Key will be issued. You must have a non-trial Trumpia Account to use the API. Please check our website for any changes in our application process.

Once you obtain an API Key, you will need to configure your account. Our API Account Management feature has not yet been released so this process will temporarily be done by a Trumpia Representative. To make any changes to your settings you can contact us through our support page from your Trumpia account.

If you are using two way SMS, you will need to setup a page where we can post incoming text messages to.

Using the API

Calling a Function

Each function in our API is basically a web page that you can call by a form submission using the POST or GET method or a direct http request with the parameters in the URL as a query string. The function page (.php files) will process the request and respond with an XML string.

NOTE: All function page names are completely in lower case. So the AddContact function would be addcontact.php.

Submitting a form using the POST method is recommended. The GET method and URL query string methods both expose data in the URL and also have a limit on the data that can be passed due to the limit on the length of a URL.

Example POST Method:
This html code will be running on the client's server.

<FORM ACTION="http://trumpia.com/api/addcontact.php" METHOD="POST">
 <INPUT TYPE="hidden" NAME="APIKEY" VALUE="12345">
 <INPUT TYPE="hidden" NAME="ListName" VALUE="TestList">
 <INPUT TYPE="hidden" NAME="FirstName" VALUE="John">
 <INPUT TYPE="hidden" NAME="LastName" VALUE="Doe">
 <INPUT TYPE="hidden" NAME="Email" VALUE="abc@abc.com">
  ...
 </FORM> 

Function Responses

All the API functions or web(php) pages will respond with an XML string as its content. An XML response will be returned regardless of success or failure. Each function may have different response fields and error codes so please be sure to read each function's documentation.

Example XML Response:
This is what the functions will return as the contents of the page called.

<?xml version="1.0" encoding="UTF-8" ?>
 <TRUMPIA>
	 <STATUSCODE>1</STATUSCODE>
	 <MESSAGE>
	 	<![CDATA[Add Contact Success]]>
	 </MESSAGE>
	 <MEMBERCODE>
	 	<![CDATA[1234abcd1234abcd1234abcd1234abcd]]>
	 </MEMBERCODE>
 </TRUMPIA>

Incoming SMS (via Keywords)

Our API allows two way communication for mobile text messages. When a user texts in a mobile keyword and an optional message, the text message can be forwarded to your server. Our system parses all incoming text messages and identifies the keyword and forwards to the keyword owner's server via HTTP GET.

There are many applications of this feature, including the ability to generate an automated response to a customer's text message based on the contents of the text message. You can also use this feature to trigger a procedure or some action on your servers whenever a customer sends a text message to your keywords.

Keywords can be setup from the web or the API and can be configured to accept a message after the keyword. So customers can text in the keyword followed by any message. This message is also forwarded to your server.

A simple example would be a search engine application where the keyword is "search" and the message would be the search criteria. Our system would forward this text message to the client's server and the client's server would run the query and send the results back to the customer using our API.

Setting Up Incoming SMS

To activate this service, you must have an active Trumpia account with the API setup. You will need to contact us and request this function so a representative can help you get things setup.

A URL need to be provided to which our servers will post the incoming keyword text messages. You can also adjust the settings to bypass or skip any of our current normal keyword sign up process.

Incoming SMS Settings:

• Receiving URL - This is where our system will post the incoming keyword text messages.
• Incoming Message - If you turn on this flag, our system will post xml messages to the Receiving URL.
• Signup via Keyword - If you turn off this flag, you can skip the normal sign up process. Users will not be automatically added to the list in your Trumpia account.
• Notification for Keyword Signup or Message - If you turn off this flag, you can skip the sending of notifications when there is a sign up for your account.
• Auto-responder for Keyword Signup or Message - If you turn off this flag, you can skip sending of the automated response messages for keywords. This option is usually set if you are generating your own response in your API code.
• Inbox for Keyword Messages - If you turn off this flag, you can skip storing the incoming keyword messages in your Trumpia Inbox.

Example URL Call

XML String - Passed in QueryString:

<?xml version="1.0" encoding="UTF-8" ?>
<TRUMPIA>
<PHONENUMBER>1234567890</PHONENUMBER>
<KEYWORD>keyword</KEYWORD>
<CONTENTS><![CDATA[contents]]></CONTENTS>
</TRUMPIA>

Sample URL call from our server to your URL:

http://www.yourserver.com/incomingsms.php?xml=<?xml version="1.0" encoding="UTF-8" ?><TRUMPIA> <PHONENUMBER>1234567890</PHONENUMBER> <KEYWORD>keyword</KEYWORD> <CONTENTS><![CDATA[contents]]></CONTENTS> </TRUMPIA>

XML String - Passed in QueryString:

<?xml version="1.0" encoding="UTF-8" ?>
<TRUMPIA>
<PHONENUMBER>1234567890</PHONENUMBER>
<KEYWORD />
<SUBSCRIPTION_UID />
<CONTENTS><![CDATA[contents]]></CONTENTS>
</TRUMPIA>

Sample URL call from our server to your URL:

http://www.yourserver.com/incomingsms.php?xml=<?xml version="1.0" encoding="UTF-8" ?><TRUMPIA> <PHONENUMBER>1234567890</PHONENUMBER> <KEYWORD /> <SUBSCRIPTION_UID /> <CONTENTS><![CDATA[contents]]></CONTENTS> </TRUMPIA>

API Functions

All the API functions are php pages in the directory http://trumpia.com/api/ and the file names are all case sensitive.

The final URL for each FUNCTION would be: http://trumpia.com/api/function.php

AddContact

Adds a new contact to contact list. A ContactID is returned which will be needed to update or delete the contact. There can be only one instance of a tool such as a mobile number on a list; however the same contact or some of the same contact information may exist on a different list.

NOTES: If you add the same contact info to different lists they will each be separate records with unique ContactID's. To copy, move, or other contact management, please go online to trumpia.com

View a PHP code sample.   View an ASP code sample.   View a JSP code sample.

Request Example

Response Example

AddContactToList

Adds an existing contact to a list using ContactID. You can copy the contact or use a pointer. Contacts with duplicate tool data cannot be added to the same list.

Setting the CreateCopy flag will create a new contact record and return a new ContactID. Adding the same contact to multiple lists allow for single update of the contact's data.

Request Example

Response Examples

Successful Response (CreateCopy : FALSE) :

Response Examples

Successful Response (CreateCopy : TRUE) :

Response Examples

Failed Responses:

GetContactData

This function returns the contact's information and tools registered along with the tools verification status.

View a PHP code sample.   View an ASP code sample.   View a JSP code sample.

Request Example

Response Example

GetContactID

This function can be used to find a contact record within a list with an email address, phone number, or screen name. Only one contactID will be returned since a tool is unique within a list.

Whenever possible, a contact's ContactID should be stored locally to avoid having to call this function unnecessarily.

Request Example

Response Example

UpdateContactData

This function allows you to update an existing contact record. The ContactID must be provided and this is the only way to identify which contact to update. Keep in mind that the same contact record, a duplicate, can exist in multiple lists.

NOTES: Currently distribution lists that a contact belongs to cannot be updated through the API. Distribution list management must also be done online at trumpia.com

Request Example

Response Example

DeleteContact

This function deletes the contact from your contact list and any distribution lists it was on.

Request Example

Response Example

RemoveContact

This function removes a contact by the actual contact information instead of the ContactID. This function is provided to easily remove subscriptions.

NOTE: If you omit a listname and set removeall to true, then all subscriptions associated with the tool will be deleted.

Request Example

Example Response

SendToList

This function sends a message to all the contacts in the specified list. Email, SMS, IM or any combination can be sent with one function call using the Mode flags. Multiple lists can be selected by passing multiple list names separated by commas. Messages can also be scheduled for a later time using the SendLater flag and LaterTime field.

View a PHP code sample.   View an ASP code sample.   View a JSP code sample.

Request Example

Response Example

Successful Response:

SendToContact

This function allows sending a message to a single contact or several contacts using the ContactID numbers.

Request Example

Response Example

Successful Response:

CheckKeyword

This function returns whether a keyword is available or not.

Request Example

Response Example

- Available

CreateKeyword

Request Example

Response Example

UpdateKeyword

Request Example

Response Example

DeleteKeyword

This function deletes the specified keyword from your account.

Request Example

Response Example

CreateList

This function creates a list.

Request Example

Response Example

RenameList

This function renames an existing distribution list.

Request Example

Response Example

DeleteList

This function deletes a list.

Request Example

Response Example