Retrieve Data From the API

The SMS gateway is designed to allow easy retrieval of your outbound messages and inbound messages (replies).

RETRIEVING SENT DATA - (DATA SET AND XML)

There are 5 methods for retrieving sent items:

• Sent_DS_DS (Accepts data set, returns data set)
• Sent_STR_DS (Accepts XML string, returns data set)
• Sent_STR_STR (Accepts XML string, returns XML string)
• Sent_DS_STR (Accepts data set, returns XML string)
• Sent_ZIP_ZIP (Accepts zipped stream, returns zipped stream)

Each function accepts 3 parameters

• Username (string)
• Password (string)
• XML string or data set (depending on the function you choose)

The XML object looks like this:

XML

<sent>
	<settings>
		<id>0</id>
		<max_recs></max_recs>
		<cols_returned></cols_returned>
		<date_format>yyyyMMddHHmmss</date_format>
	</settings>
</sent>

Parameter	Description	Default
*ID	The max CHANGEID from the previous call. Start with “0”	-
Max_recs	The number of records returned from the call. Values 1 to 100	100
Cols_Returned	The xml tags returned in the result. Options are: sentid, eventid, smstype, numto, data, customerid, status, statusdate. Each entry must be separated by a comma.	ChangeID
Date Format	The format of any dates that are returned.	dd/MMM/yyyy HH:mm:ss

🚧

All entries marked with * are mandatory

The output returned will be a data set or XML in the following format:

XML

<api_result>
	<data>
		<changeid></changeid>
		<sentid></sentid>
		<eventid></eventid>
		<smstype></smstype>
		<numto></numto>
		<data></data>
		<customerid></customerid>
		<status></status>
		<statusdate></statusdate>
	</data>
	<call_result>
		<result></result>
		<error/>
	</call_result>
</api_result>

XML tag	Description
changeid	A unique ID identifying the change in a message status.
sentid	A unique value for each message. You could receive the same SentID back if the message status changes.
eventid	When sending, an eventid is generated and returned in the result xml. This eventid can be for 1 or “infinity” message entries.
smstype	This is the type of message sent. (Default = SMS)
numto	The number the message was sent to.
data	The data sent to the user.
customerid	The customerid for the message when the data was sent.
status	The message status. Options are “DELIVRD”, “UNDELIV”, ”UNKNOWN”, ”EXPIRED”.
statusdate	The date and time the message was sent.

RETRIEVING REPLIES - (OVERVIEW)

The design allows the following:

• Retrieval of items you have not already pulled
• Instant retrieval of data (due to API table design and indexing)
• Customisable result formatting
• Prevention of timeouts

So how is this achieved?
The API system uses a unique identity field called “replyid” which is permanently incrementing. When an inbound message is received from the corresponding network, a new record is written to the API and the replyid will increment by 1.

In the result set, the element “replyid” will be present along with the other elements you have specified.
This needs to be stored and the maximum replyid utilised by the next call. The following is occurring within the SMS gateway:

“Select top 100 * from API_Reply_Table where replyid > @ID order by replyid asc”

📘

Tips

Start with id (replyid) = 0
Store the max replyid in your local system, permanently (database or IO system)
Only pull back data you require, using the “cols_returned” element (this will reduce bandwidth).

🚧

Limitations

Inbound messages are only retained for up to seven days, i.e. replies that were sent more than a week ago cannot be retrieved via Web Services.

Only replies to messages that were sent via Web Services, and from the account that was used for authentication, can be retrieved. E.g. sub accounts cannot retrieve each other’s messages, and replies to messages sent via FTP cannot be retrieved via Web Services.

RETRIEVING REPLIES - (DATA SET AND XML)

There are 5 methods for retrieving replies:

• Reply_DS_DS (Accepts data set, returns data set)
• Reply_STR_DS (Accepts XML string, returns data set)
• Reply_STR_STR (Accepts (XML string, returns XML string)
• Reply_DS_STR (Accepts data set, returns XML string)
• Reply_ZIP_ZIP (Accepts zipped stream, returns zipped stream)

Each function accepts 3 parameters:

• Username (string)
• Password (string)
• XML string or data set (depending on the function you choose)

The XML object looks like this:

XML

<reply>
	<settings>
		<id></id>
		<max_recs></max_recs>
		<cols_returned> </cols_returned>
		<date_format> </date_format>
	</settings>
</reply>

Parameter	Description	Default
*ID	The max REPLYID from the previous call	-
Max_recs	The number of records returned from the call. Values 1 to 100	100
Cols_Returned	The xml tags returned in the result. Options are: replyid, eventid, numfrom, receiveddata, received, sentid, sentdata, sentdatetime, sentcustomerid, optout. Each entry must be separated by a comma.	Replyid
Date Format	The format of any dates that are returned.	dd/MMM/yyyy HH:mm:ss

🚧

All entries marked with * are mandatory

The output returned will be a data set or XML in the following format:

XML

<api_result>
	<data>
		<replyid></replyid>
		<eventid></eventid>
		<numfrom></numfrom>
		<receiveddata>123</receiveddata>
		<sentid></sentid>
		<sentdata></sentdata>
		<sentcustomerid/>
		<received></received>
		<sentdatetime></sentdatetime>
	</data>
	<call_result>
		<result></result>
		<error/>
	</call_result>
</api_result>

replyid	The max unique REPLYID for each incoming message
eventid	When sending an eventid is generated and returned in the result xml. This eventid can be for 1 or “infinity” message entries.
numfrom	The number of the user that sent the incoming message
receiveddata	The data that the user returned
received	The date and time the message was received
sentid	The unique sentid for the outgoing message
sentdata	The data sent to the user
sentdatetime	The date and time the message was sent
sentcustomerid	The customerid for the message when the data was sent
optout	Contains the value 1 if the received data matched an opt-out phrase, or 0 if not.

Retrieve Your Short Code Counts

There are 4 methods for retrieving the number of messages sent to your short codes.

• • ShortCodeCount_DS_DS (Accepts data set, returns data set)
• • ShortCodeCount_STR_DS (Accepts XML string, returns data set)
• • ShortCodeCount_STR_STR (Accepts XML string, returns XML string)
• • ShortCodeCount_DS_STR (Accepts data set, returns XML string)

Each function accepts 3 parameters:

• • Username (string)
• • Password (string)
• • XML string or data set (depending on the function you choose)

The XML object looks like this:

XML

<options>
	<settings>
		<start_date>01/Jan/2018</start_date>
		<end_date>10/Jan/2018</end_date>
	</settings>
	<shortcodes>
		<shortcode>XXXXX</shortcode>
	</shortcodes>
	<shortcodes>
		<shortcode>YYYYY</shortcode>
	</shortcodes>
</options>

XML tag	Description	Default
*start_date	The start date of the query period. Start_date can be set up to 12 months in the past.	-
*end_date	The end date of the query period. The start_date and end_date must be between 1 and 31 days.	-
shortcodes	The collection of short codes. If omitted, will return all short codes assigned to you with totals for the period.	-
shortcode	A short code number.	-

The output returned will be a data set or XML in the following format :

XML

<api_result>
	<data>
		<shortcode>XXXXX</shortcode>
		<count>200</count>
	</data>
	<data>
		<shortcode>YYYYY</shortcode>
		<count>45</count>
	</data>
	<call_result>
		<result>True</result>
		<error/>
	</call_result>
</api_result>

XML tag	Description
shortcode	Your short code you received messages on.
count	The total count associated to the short code for the period.