SMS API Documentation

This document describes the base API interfaces which can be used with TotalSend

The API is currently only implemented with a JSON wrapper.

These  API's can be accessed with an HTTP client independent of language. We  have provided PHP examples to demonstrate the implementation as well as  raw HTTP requests in order to assist.

Some general considerations:

= Negative number in status codes indicate an error

= HTTP Keep-Alive is supported and should be used for large numbers of queries.

= Unbilled queries are limited to 10 per minute (message_status, user_get_balance, etc)


Class Constant Summary


Method Summary

  • object address_book_contacts_get_list (string username, string password, int group_id)
  • object address_book_contact_add (string username, string password, int group_id, string phone_number, [string first_name =''], [string last_name = ''])
  • object address_book_contact_delete (string username, string password, int contact_id)
  • object address_book_contact_update (string username, string password, int contact_id, [string phone_number  = null], [string first_name = null], [string last_name = null])
  • object address_book_groups_get_list (string username, string password)
  • object address_book_group_add (string username, string password, string name)
  • object address_book_group_delete (string username, string password, int group_id)
  • object affiliate_get_default_pricing (string username, string password, string country_code, string currency_code)
  • object affiliate_list_countries (string username, string password)
  • object affiliate_register_user (string username, string password, string email_address, string  dialling_code,string phone_number, [string user_ip_address = Null],  [string user_username = Null], [string user_password = Null], [int  campaign_id = Null])
  • object affiliate_register_user_quick (string username, string password, string email_address, string  phone_number, [string ip_address = false], [integer marketing_channel_id  = '0'])
  • object affiliate_set_promotion_code (string username, string password, integer user_id, string promotion_code, [integer affiliate_id = null])
  • object batches_list (string username, string password)
  • object batch_check_status (string username, string password, int batch_id)
  • object batch_create (string username, string password, string name, [int throughput = 0],  [boolean filter = false], [string file_type = 'csv'], [string start_time  = null])
  • object batch_start (string username, string password, int batch_id)
  • object batch_stop (string username, string password, int batch_id)
  • object execute_multiple (string username, string password)
  • object get_affiliate_country_info (string username, string password, string ip_address, [boolean return_array = false], [ country_name = false])
  • object hlr_perform (string username, string password, string number, sring report_url)
  • object hlr_perform_synchronous (string username, string password, string number)
  • object inject_lead (string username, string password, integer batch_id, [string number = NULL], enum lead_type)
  • object list_actions ()
  • object messages_get (string username, string password, int last_id)
  • object messages_statistics (string username, string password, [string start_date = NULL], [string end_date = NULL], [string user_id = NULL])
  • object message_send (string username, string password, string to, string text, [string from  = null], [int report_mask = 19], [string report_url = null], [string  charset = null], [int data_coding = null], [int message_class = -1],  [int auto_detect_encoding =null])
  • object message_status (string username, string password, string message_id)
  • object ping ()
  • object route_check_price (string username, string password, string to)
  • object user_authorize_application (string application_name, [string icon_url = null], [string return_url = null])
  • object user_get_api_key (string request_key)
  • object user_get_balance (string username, string password)
  • object user_get_info (string username, string password)
  • object user_get_phone_number (string username, string password)
  • object user_transfer_funds (string username, string password, string target_username, float amount)

Methods

  • address_book_contacts_get_list
     

Gets a list of contacts for a group

object address_book_contacts_get_list ( string username, string password, int group_id)

  • string username
  • string password
  • int group_id : The ID of the group
  • address_book_contact_add
     

Add a contact to a group

object address_book_contact_add ( string username, string password, int group_id, string phone_number, [ string first_name = ''], [ string last_name = ''], string email)

  • string username
  • string password
  • int group_id : The group ID to add the record to
  • string phone_number : Phone number of the user
  • string first_name : First name of the user (optional)
  • string last_name : Last name of the user (optional)
  • string email : Email address of the user (optional)

This will then return the contact's id on the details key e.g.
{"status":0,"message":"OK","details":"17"}

  • address_book_contact_delete
     

Delete a contact

object address_book_contact_delete ( string username, string password, int contact_id)

  • string username
  • string password
  • int contact_id : The contact ID
  • address_book_contact_update
     

Update an existing contact

object address_book_contact_update ( string username, string password, int contact_id, [ string phone_number = null], [ string first_name = null], [ string last_name = null])

  • string username
  • string password
  • int contact_id : The contact ID
  • string phone_number : The new first name
  • string first_name : The new last name
  • string last_name : The new phone number
  • address_book_groups_get_list
     

Returns the group ID’s for contact lists in the user account

Example output : {"status":0,"message":"OK","details":[{"id":"1","name":"My Friends"}]}

object address_book_groups_get_list ( string username, string password)

  • string username
  • string password
  • address_book_group_add
     

Adds a new address book group

object address_book_group_add ( string username, string password, string name)

  • string username
  • string password
  • string name : The name of the group

Example Output - JSON

{ "status":0, "message":"OK", "details":"7"} 

*where detail is the newly created group's ID

  • address_book_group_delete
     

Deletes an address book group

object address_book_group_delete ( string username, string password, int group_id)

  • string username
  • string password
  • int group_id : The ID of the group
  • affiliate_get_default_pricing
     

Returns the default pricing for new registrations

object affiliate_get_default_pricing ( string username, string password, string country_code, string currency_code)

  • string username
  • string password
  • string country_code : The 3 digit ISO country code to check
  • string currency_code : The 3 digit currency code preferred
  • affiliate_list_countries
     

Returns the list of countries used by this system

object affiliate_list_countries ( string username, string password)

  • string username
  • string password
  • affiliate_register_user
     

This action allows affiliate users to create new users, please contact [email protected] if you are interested in becoming an affiliate.

Please  note that this method returns its own status codes, an English error  message will be returned to you, it is at your own discretion to  translate these strings.

Example output:  {"status":0,"message":"OK","details":{"user_id":"67","username":"testdd","password":"10jm06","message":"User  created successfully."}}

object affiliate_register_user ( string username, string password, string email_address, string  dialling_code, string phone_number, [ string user_ip_address = Null], [ string user_username = Null], [ string user_password = Null], [ int campaign_id = Null])

  • string username : Your Username
  • string password : Your Password or token
  • string email_address : New user email address
  • string dialling_code : Registrant Number prefix
  • string phone_number : New user phone_number (in format: country prefix-number ie: 798000000)
  • string user_ip_address : New Users Ip address
  • string user_username : New User Username (optional)
  • string user_password : New User Password (optional)
  • int campaign_id : Campaign Id (optional)
  • affiliate_register_user_quick
     

This action allows affiliate users to create new users, please contact [email protected] if you are interested in becoming an affiliate.

An English error message will be returned to you, it is at your own discretion to translate these strings.

When a user is created the new username will be returned and an auto generated password will be sent to them via SMS.

Example output: {"status":0,"message":"OK","details": "george"}

object affiliate_register_user_quick ( string username, string password, string email_address, string phone_number, [ string ip_address = false], [ integer marketing_channel_id = '0'])

  • string username : Your Username
  • string password : Your Password or token
  • string email_address : New user email address
  • string phone_number : New user phone_number (in format: country prefix-number ie: 798000000)
  • string ip_address : New Users Ip address
  • integer marketing_channel_id : Marketing channel ID (optional)
  • affiliate_set_promotion_code
     

Public method that sets promotion codes for new users

object affiliate_set_promotion_code (  string username, string password, integer user_id, string promotion_code, [ integer affiliate_id = null])

  • string username
  • string password
  • integer user_id : (user_id returned by affiliate_register_user)
  • string promotion_code : (promotion code supplied by TotalSend)
  • integer affiliate_id : (specify if you are part of multiple affiliate programs)
  • batches_list
     

Retrieves a list of the user batches.

Example  output:  {"status":0,"message":"OK","details":[{"id":"11","name":"test","status":32,"deletable":false},{"id":"12","name":"Relationships","status":32,"deletable":false}]}

object batches_list ( string username, string password)

  • string username
  • string password
  • batch_check_status
     

Checks the status of a batch

object batch_check_status ( string username, string password, int batch_id)

  • string username
  • string password
  • int batch_id : batch_id as returned from batches_list (or other batch API's)
  • batch_create
     

Creates a new batch, returns batch ID if successful

This action supports zip compression of files, these must be base64 encoded zip files.

object batch_create ( string username, string password, string name, [ int throughput = 0], [ boolean filter = false], [ string file_type = 'csv'], [ string start_time = null])

  • string username
  • string password
  • string name : A description / name for this batch
  • int throughput : Throughput to deliver this batch at (per second)
  • boolean filter : Filter this batch against the global blocklist
  • string file_type : File type of the upload ( csv, xls or zip accepted )
  • string start_time : If the batch must be auto-started at a given time, it must be specified here: eg: 2012-03-04 08:00:00
  • batch_start
     

Starts the given batch

object batch_start ( string username, string password, int batch_id)

  • string username
  • string password
  • int batch_id : batch_id as returned from batches_list (or other batch API's)
  • batch_stop
     

Stops/pauses the given batch

object batch_stop ( string username, string password, int batch_id)

  • string username
  • string password
  • int batch_id : batch_id as returned from batches_list (or other batch API's)
  • execute_multiple
     

This action allows you to execute multiple actions within the API with a single request.

The  payload (with all actions) must be sent in a POST request with a  variable named 'data' containing a JSON encoded array of actions to  execute.

An array of results sent in the same order they were received will be returned.

object execute_multiple ( string username, string password)

  • string username
  • string password
  • get_affiliate_country_info
     

Public method that returns affiliate country information. Primarily used for detecting number prefixes.

object get_affiliate_country_info ( string username, string password, string ip_address, [ boolean return_array = false], [ country_name = false])

  • string username
  • string password
  • string ip_address : Ip Address to get country information for.
  • boolean return_array : No need to change this.
  • country_name
  • hlr_perform
     

This performs an HLR request and gives you the result via an HTTP callback

This is the recommended method for large volumes of HLR requests

Ouput contains keys: details (request ID)

object hlr_perform ( string username, string password, string number, string report_url)

  • string username
  • string password
  • string number
  • sring report_url : This is the URL you want to be called with the resulting information.
  • hlr_perform_synchronous
     

This performs an HLR request and gives you the result immediately.

This  method is only recommended for small volumes and you will be limited to  a maximum of 5 simultaneous requests using this method.

Example output contains keys: number_status, mcc, mnc, country_code, network_name

object hlr_perform_synchronous ( string username, string password, string number)

  • string username
  • string password
  • string number
  • inject_lead
     

This is for using our free leads service to inject leads.

Although  this system filters out duplicate leads, best practise would be to  manually filter the leads yourself as we only filter on a per batch  basis.

Example output: {"status":0,"message":"OK","details":"Lead Created"}

object inject_lead ( string username, string password, integer batch_id, [ string number = NULL], enum lead_type)

  • string username
  • string password
  • integer batch_id
  • string number
  • enum lead_type : - options (1-Opt In,2-Opt Out)
  • list_actions
     

This method provides all a list of all methods currently available in the API and their parameters

object list_actions ()

  • messages_get
     

This function returns all inbound (MO) messages for the user which have an ID larger than 'last_id'.

Best  practice is to use this function starting with last_id = 0, then as  messages are received, to store last_id as the highest message ID you  receive back from the API request. Results are limited to 50 at a time.

Example  ID  {"status":0,"message":"OK","details":[{"id":"11","created":"2011-04-09  19:25:09","from":"27832659217","to":"20000","data":"Test MO  Generated","charset":"UTF-8"},{"id":"10","created":"2011-04-09  19:24:02","from":"27832659217","to":"20000","data":"Test MO  Generated","charset":"UTF-8"}]}

object messages_get ( string username, string password, int last_id)

  • string username
  • string password
  • int last_id
  • messages_statistics
     

Statistics for the user account. These are a summarized value and should only be user to provide a broad overview of statistics.

Example output: {"status":0,"message":"OK","details":{"sent":231709,"dlr_received":162,"received":5,"dlr_requested":200}}

object messages_statistics ( string username, string password, [ string start_date = NULL], [ string end_date = NULL], [ string user_id = NULL])

  • string username
  • string password
  • string user_id : the sub user id that these statistics are for
  • string start_date : start point of the statistics
  • string end_date : end point of the statistics
  • message_send
     

Send an SMS message

In the return result, if successful the details key will contain the message ID.

Example output : {"status":1,"message":"Sent","details":"8beda1a8-5c12-489f-0107-123000000003"}

object message_send ( string username, string password, string to, string text, [ string from = null], [ int report_mask = 19], [ string report_url = null], [ string charset = null], [ int data_coding = null], [ int message_class = -1], [ int auto_detect_encoding = null])

  • string username
  • string password
  • string to
  • string text : The body of your message
  • string from
  • int report_mask : Delivery report request bitmask (see delivery_report_mask_* variables)
  • string report_url : URL to call when delivery status changes
  • string charset : Character set to use (defaults to UTF-8)
  • int data_coding : Data coding (see data_coding_*)
  • int message_class : Message class
  • int  auto_detect_encoding : Auto detect the encoding and send appropriately  (useful for sending arabic, hindi, unicode etc messages) 1 = on, 0 =  off, defaults off.
  • message_status
     

Checks the status of a message

This  function can only be used 10 times per minute (to prevent bad  implementation :)) if you require status for each message you send  please use the report_url and report_mask variables when sending your  messages with message_send().

Example ouput: {"status":0,"message":"OK","details":{"status":1,"cost":0.20000,"parts":1}}

object message_status ( string username, string password, string message_id)

  • string username
  • string password
  • string message_id
  • ping
     

Function to ensure communication

object ping ()

  • route_check_price
     

This action allows you to check the price you can expect to pay for a message to the destination in 'to'

Output will contain the cost in the the details key.

object route_check_price ( string username, string password, string to)

  • string username : Your username
  • string password : Your password or API key
  • string to : The number you wish to test
  • user_authorize_application
     

This action allows a third party application to get an authentication key in order to make use of a user's account.

The  benefits of using this method is know that the application doesn't have  to worry about registration of the user account, it simply redirects  the user to a web based location (which is provided) for authentication,  once done, if the user allowed it, the application can access the API  functions using the new API token.

WARNING: Request key's  generated here can only be guaranteed to be valid for 1 hour, so you  *MUST* call user_get_api_key() after the process has been completed.

The  output details key contains 'authorize_url' where the user should be  sent to and 'request_key' which is the key to be used for API key  creation once complete.

object user_authorize_application ( string application_name, [ string icon_url = null], [ string return_url = null])

  • string application_name : The name of the application to be authorized (for the user to see)
  • string icon_url : The URL where an icon can be found for this application (optional)
  • string  return_url : The URL where the user must be returned to once complete,  if left out the window will be allowed to be closed (optional)
  • user_get_api_key
     

Once  the user_authorize_application() action is completed and the user has  returned to your application, you must call user_get_api_key() to create  a permanent API key.

Details key contains 'username' and 'key' which can be used as username and password combinations in subsequent requests.

object user_get_api_key ( string request_key)

  • string request_key : The original request key returned from user_authorize_application()
  • user_get_balance
     

Gets the user balance

object user_get_balance ( string username, string password)

  • string username
  • string password
  • user_get_info
     

Gets the user details

object user_get_info ( string username, string password)

  • string username
  • string password
  • user_get_phone_number
     

This function returns the verified phone number for the given user

Example output {"status":0,"message":"OK","details":"0832659217"}

object user_get_phone_number ( string username, string password)

  • string username
  • string password
  • user_transfer_funds
     

Transfer credit from one account to another

Example output {"status":0,"message":"OK","details":3338.50000}

object user_transfer_funds ( string username, string password, string target_username, float amount)

  • string username
  • string password
  • string target_username : The username to move funds to (this must be a sub-user of your account)
  • float amount : The amount to transfer

Class Constants

  • api_result_authentication_failed = -8
     

Authentication failure

  • api_result_could_not_save = -256
     

Could not save

  • api_result_duplicate_record = -512
     

Duplicate record found (when adding)

  • api_result_internal_error = -16
     

Internal error

  • api_result_invalid_record = -128
     

Invalid record

  • api_result_key_created = 2
     

API Request Key created

  • api_result_message_sent = 1
     

Message sent/queued

  • api_result_missing_parameter = -4
     

There was a required parameter missing from the request (see 'details' key in result for more information)

  • api_result_no_action_specified = -1
     

No action was specified in the request

  • api_result_no_such_action = -2
     

There was no matching action found

  • api_result_ok = 0
     

Generic OK

  • api_result_out_of_credit = -64
     

Out of credit

  • api_result_routing_error = -32
     

Routing error

  • api_result_timeout = -8192
     

User has exceeded the maximum number of simultaneous requests to the API

  • api_result_too_many_connections = -4096
     

User has exceeded the maximum number of simultaneous requests to the API

  • api_result_user_invalid_affiliate = -1024
     

User is not part of any affiliate program

  • api_result_user_no_hlr = -2048
     

User does not have HLR enabled on his account

  • batch_status_busy = 16
     

Batch is busy being processed

  • batch_status_error = 128
     

There was an error processing the batch

  • batch_status_filter = 256
     

The batch is waiting to be filtered

Set the batch to this status if you wish for it to be filtered

  • batch_status_filtering = 512
     

Batch is busy being filtered

  • batch_status_new = 1
     

Batch is waiting to be processed

  • batch_status_parsing = 2
     

Batch is busy being parsed

  • batch_status_parsing_paused = 4
     

Parsing of the batch has been paused

  • batch_status_paused = 32
     

Batch has been parsed and is currently paused

  • batch_status_ready = 8
     

Batch is waiting to be processed (no action required)

  • batch_status_submitted = 64
     

Batch has been submitted

  • maximum_affliate_registrations_reached = -2048
     

User has reached maximum registrations during specified period

  • message_status_acknowledged = 1
     

Message acknowledged

  • message_status_delivered = 4
     

Message has been delivered

  • message_status_does_not_exist = -1
     

Message does not exist

  • message_status_failed = 32
     

Message failed

  • message_status_filtered = 64
     

Filtered (blocked or previously failed)

  • message_status_internal_failed = 8
     

Message failed (internal error)

  • message_status_routing_error = 16
     

Routing error

  • message_status_submitted = 2
     

Message has been sent to the networks