Trumpia API - Version 1.60

Last Updated: 03/11/2015

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://api.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