Web Services API (Legacy)

Overview

The web service can be referenced at https://api.smsportal.com/api5/api.asmx
The naming convention describes what the function accepts and returns. E.g.: Reply_STR_DS will accept an XML string and return a data set (.net object).
Most of the functions follow a common thread: accept 3 parameters, return XML or dataset.
The returned data will always contain the following:

</api_result>
    <call_result>
        <result>True</result>
        <error/>
    </call_result>
</api_result>

The result will be either “True” or “False”.
If “False” the error will be displayed with the “error” tag.

Sending Messages (Web Services)

To send is relatively easy, but due to the various options it can seem confusing.
In a nutshell:
If you specify a default then it will only be utilised if the entry data does not exist. If neither exists then it will throw an error.
There are 5 methods for sending your messages:

  1. Send_DS_DS (Accepts data set, returns data set)
  2. Send_STR_DS (Accepts XML string, returns data set)
  3. Send_STR_STR (Accepts XML string, returns XML string)
  4. Send_DS_STR (Accepts data set, returns XML string)
  5. Send _ZIP_ZIP (Accepts zipped stream, returns zipped stream)

Each function accepts 3 parameters

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

The XML objects looks like this:

<senddata>
    <settings>
        <live>True</live>
        <return_credits>True</return_credits>
        <return_msgs_credits_used>True</return_msgs_credits_used>
        <return_msgs_success_count>True</return_msgs_success_count>
        <return_msgs_failed_count>True</return_msgs_failed_count>
        <return_entries_success_status>True</return_entries_success_status>
        <return_entries_failed_status>True</return_entries_failed_status>
        <default_senderid/>
        <default_date>01/Jan/2018</default_date>
        <default_time>11:15</default_time>
        <default_curdate>01/Jan/2018</default_curdate>
        <default_curtime>11:15</default_curtime>
        <default_data1>This is a default msg</default_data1>
        <default_data2/>
        <default_flash>False</default_flash>
        <default_type>SMS</default_type>
        <default_costcentre>NA</default_costcentre>
        <default_validityperiod>0</default_validityperiod>
    </settings>
    <entries>
        <numto>082*******</numto>
        <customerid>UnqiueValue1</customerid>
        <senderid>Test me</senderid>
        <time>11:15</time>
        <data1>This is a test message 1!</data1>
        <data2/>
        <flash>False</flash>
        <type>SMS</type>
        <costcentre>NA</costcentre>
        <validityperiod>0</validityperiod>
    </entries>
</senddata>

XML Tag Table

The following table determines how the result is formatted, as well as defining the defaults.

live

If Live = false then it will return the result but won’t send the data. It won’t appear in your sent report.

True

return_credits

If True then the current credits count will be returned.

False

return_msgs_credits_used

If True then the amount of credits used will be returned

False

return_msgs_success_count

If True then the total success data count will appear in the result.

False

returnentries
failed_status

If True then the total failed data count will appear in the result.

False

return_entries_success_status

If True then the data that is accepted will be returned in the result.

False

return_entries_failed_status

If True then the data that is rejected will be returned in the result.

False

default_senderid

This is the default setting for the call but can be overridden by the individual entries. Only certain accounts can alter this.

Repliable

*default_date

This is the date the messages must be sent out.
Format is dd/MMM/yyyy eg: 13/apr/2009

*default_time

This is the time the messages must be sent out.
Format is HH:mm eg: 17:34

default_curdate

This is the current date on your server. It is used to determine when your messages should go out. If not used then the server date is used.

Sever Date

default_curtime

This is the current time on your server. It is used to determine when your messages should go out. If not used then the server time is used.

Server Time

default_data1

This is the default setting for the call but can be overridden by the individual entries.

default_data2

This is the default setting for the call but can be overridden by the individual entries.

default_flash

This is the default setting for the call but can be overridden by the individual entries.

False

default_type

This is the default setting for the call.

SMS

default_costcentre

Will be used in future.

""

mo_forwardemail

All incoming replies will be forwarded to this email address

""

default_validityperiod

This is the amount of time, in hours, that an SMS should remain valid. The network will continue to try to deliver the SMS for the amount of time specified.

🚧

All tags marked with * are mandatory

🚧

Post Paid Customers

Return Credits will always return a value of 1000000 on Post Paid accounts as no credit deduction occurs on this account type.

XML tag

Description

entries_failed

If this tag exists then some of the data you pushed has errors.
If will contain: “numto”, “customerid” and “reason”. The reason will be

  • numto invalid
  • senderid invalid
  • time invalid
  • flash invalid
  • costcentre invalid
  • type invalid
  • data1 invalid
  • data2 invalid
  • data1 + data2 invalid

entries_success

If this tag exists then it will contain “numto” and “customerid”.

send_info

This describes the overall data returned. It WILL contain “eventid” and COULD have “credits”, “msgs_credits_used”, “msgs_success” and “msgs_failed”.

  • Credits = credits remaining in account
  • Msgs_credits_used = the amount of credits used
  • Msgs_success = a count of the messages accepted for delivery
  • Msgs_failed = a count of the messages rejected

The output of the following will be defined by the input of the above parameters:

<api_result>
    <entries_failed>
        <numto/>
        <customerid/>
        <reason>numto invalid</reason>
    </entries_failed>
    <entries_success>
        <numto>2782*******</numto>
        <customerid>UnqiueValue1</customerid>
    </entries_success>
    <entries_success>
        <numto>2782*******</numto>
        <customerid>UnqiueValue1</customerid>
    </entries_success>
    <entries_success>
        <numto>27832297941</numto>
        <customerid>d47e1efd‐5e4f‐4832‐ba7f‐07f35d8c10f9</customerid>
    </entries_success>
    <send_info>
        <eventid>27105067</eventid>
        <credits>39763</credits>
        <msgs_credits_used>3</msgs_credits_used>
        <msgs_success>3</msgs_success>
        <msgs_failed>1</msgs_failed>
    </send_info>
    <call_result>
        <result>True</result>
        <error/>
    </call_result>
</api_result>

You can also send to a group if it exists in your group list online.
Add the send_groupid tag to your XML object.
E.g:

<senddata>
    <settings>
        <live>True</live>
        <return_credits>True</return_credits>
        <return_msgs_credits_used>True</return_msgs_credits_used>
        <return_msgs_success_count>True</return_msgs_success_count>
        <return_msgs_failed_count>True</return_msgs_failed_count>
        <return_entries_success_status>True</return_entries_success_status>
        <return_entries_failed_status>True</return_entries_failed_status>
        <default_senderid/>
        <default_date>01/Jan/2018</default_date>
        <default_time>11:15</default_time>
        <default_curdate>01/Jan/2018</default_curdate>
        <default_curtime>11:15</default_curtime>
        <default_data1>This is a default msg</default_data1>
        <default_data2/>
        <default_flash>False</default_flash>
        <default_type>SMS</default_type>
        <default_costcentre>NA</default_costcentre>
        <default_validityperiod>0</default_validityperiod>
    <send_groupid>0</send_groupid>
    </settings>

The following table determines how the result is formatted, as well as defining the defaults.

XML tag

Description

Default

live

If Live = false then it will return the result but won’t send the data. It won’t appear in your sent report.

True

return_msgs_credits_used

If True then the amount of credits used will be returned.

False

return_credits

If True then the current Credits count will be returned.

False

return_msgs_success_count

If True then the total success data count will appear in the result.

False

return_entries_failed_status

If True then the total failed data count will appear in the result.

False

return_entries_success_status

If True then the data that is accepted will be returned in the result.

False

return_entries_failed_status

This is the default setting for the call but can be overridden by the individual entries. Only certain accounts can alter this.

False

*default_date

This is the date the messages must be sent out.
Format is dd/MMM/yyyy eg: 13/apr/2009

*default_time

This is the time the messages must be sent out.
Format is HH:mm eg: 17:34

default_curdate

This is the current time on your server. It is used to determine when your messages should go out. If not used then the server time is used.

Server Date

default_curtime

This is the current time on your server. It is used to determine when your messages should go out. If not used then the server time is used.

Server Time

default_data1

This is the default setting for the call but can be overridden by the individual entries.

""

default_data2

This is the default setting for the call but can be overridden by the individual entries.

""

default_flash

This is the default setting for the call but can be overridden by the individual entries.

False

default_type

This is the default setting for the call.

SMS

default_costcentre

""

mo_forwardemail

All incoming replies will be forwarded to this email

""

default_validityperiod

The amount of time in hours an SMS should remain valid. The network will continue to try to deliver the SMS over the validity period.

*groupid

The groupid to send to

0

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:

<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, flash, 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:

<api_result>
    <data>
        <changeid></changeid>
        <sentid></sentid>
        <eventid></eventid>
        <smstype></smstype>
        <numto></numto>
        <data></data>
        <flash></flash>
        <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:

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

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

Retrieving Your Group Information (Online Groups)

There are 4 methods for retrieving your groups:

  • Groups_List_DS_DS (Accepts data set, returns data set)
  • Groups_List _STR_DS (Accepts XML string, returns data set)
  • Groups_List _STR_STR (Accepts XML string, returns XML string)
  • Groups_List _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:

<options>
    <settings>
        <cols_returned></cols_returned>
        <date_format></date_format>
    </settings>
</options>

XML tag

Description

Default

*Cols_Returned

The xml tags returned in the result. Options are: groupname, groupdesc, groupcreated. Each entry must be separated by a comma.

Groupid

Date Format

The format of any dates that are returned.

dd/MMM/yyyy HH:mm:ss

🚧

All entries marked with * are mandatory

Example XML result:

<api_result>
    <data>
        <replyid></replyid>
        <groupid>118093</groupid>
        <groupname>the name of your group</groupname>
        <groupdesc>the desc of your group</groupdesc>
        <groupcreated>13/Apr/2009 13:00:05</groupcreated>
    </data>
    <call_result>
        <result></result>
        <error/>
    </call_result>
</api_result>

XML tag

Description

groupid

A unique GROUPID for each group in the system

Groupname

The name of your group

Groupdesc

The description you gave your group

groupcreated

When the group was created

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:

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

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

Retrieve Incoming Short Code Entries

The SMS gateway is designed to allow easy retrieval of your inbound messages (shortcodes).
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 “changeid”, which is permanently incrementing.
When an inbound message is received from the corresponding network, a new record is written to the API and the changeid will increment by 1.
In the result set, the element “changeid” will be present along with the other elements you have specified. This needs to be stored and the maximum changeid utilised by the next call. The following is occurring within the SMS gateway:

“Select top 100 * from Short Code_Table where ID > @ID order by ID asc”

There are 6 methods available for retrieving replies:

  1. ShortCode_Get_DS_DS
  2. ShortCode_Get_DS_STR
  3. ShortCode_Get_DS_ZIP
  4. ShortCode_Get_STR_DS
  5. ShortCode_Get_STR_STR
  6. ShortCode_Get_STR_ZIP

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:

<options>
    <settings>
        <id>0</id>
        <date_format></date_format>
        <shortcode></shortcode>
        <keyword></keyword>
    </settings>
</options>

XML tag

Description

Default

*ID

The max ChangeID from the previous call.

Date_Format

The format of any dates that are returned.

Dd/MMM/yyyy HH:mm:ss

Shortcode

The short code (5 digit number). If nothing is specified then all short codes are returned.

0

Keyword

Search on a keyword. If a keyword has been allocated to your account eg: “test” you can specify to retrieve only these entries.

""

🚧

All entries marked with * are mandatory

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

<api_result>
    <data>
        <changeid></changeid>
        <shortcode></shortcode>
        <keyword></keyword >
        <phonenumber></phonenumber>
        <message></message>
        <received></received>
    </data>
    <call_result>
        <result></result>
        <error/>
    </call_result>
</api_result>

XML tag

Description

ChangeID

The max unique ChangeID for each incoming message.

Shortcode

The short code (5 digit number).

Keyword

If the shortcode has been separated on a keyword. it will be displayed.
Each keyword can have its own properties.

Phonenumber

The number the message was received from.

Message

The message received.

Received

The date the message was received.

Please see the list of available code examples below:

C# Example

Download

Vb.Net Example

Download

Delphi Example

Download

Check Balance (Web Services)

There are 2 methods for checking your credits:

  1. Credits_STR (Returns XML string)
  2. Credits_DS (Returns data set)

Each function accepts 2 parameters:

  • Username (string)
  • Password (string)

The return object looks like this:

<api_result>
    <data>
        <credits>xxxxx</credits>
    </data>
    <call_result>
        <result>True</result>
        <error />
    </call_result>
</api_result>

Your current credit value will be displayed between the “credits” tag.

🚧

Post Paid Customers

Credits will always return a value of 1000000 on Post Paid accounts as no credit deduction occurs on this account type.


Did this page help you?