Docs For Class PanaceaApi

Panacea Mobile API

Description

This document describes the base API interfaces which can be used with Panacea Mobile.

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)

Constants / Codes

api_result_authentication_failed = -8

api_result_could_not_save = -256

api_result_duplicate_record = -512

api_result_internal_error = -16

api_result_invalid_record = -128

api_result_key_created = 2

api_result_message_sent = 1

api_result_missing_parameter = -4

api_result_no_action_specified = -1

api_result_no_such_action = -2

api_result_ok = 0

api_result_out_of_credit = -64

api_result_routing_error = -32

api_result_user_invalid_affiliate = -1024

batch_status_busy = 16

batch_status_error = 128

batch_status_filter = 256

batch_status_filtering = 512

batch_status_new = 1

batch_status_parsing = 2

batch_status_parsing_paused = 4

batch_status_paused = 32

batch_status_ready = 8

batch_status_submitted = 64

maximum_affliate_registrations_reached = -2048

message_status_acknowledged = 1

message_status_delivered = 4

message_status_does_not_exist = -1

message_status_failed = 32

message_status_filtered = 64

message_status_internal_failed = 8

message_status_routing_error = 16

message_status_submitted = 2

Action 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_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_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'])

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, ip_address, [ return_array = false])

object list_actions ()

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

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 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_phone_number (string username, string password)

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

Actions

address_book_contacts_get_list

Get's a list of contacts for a particular group

example: Generic HTTP Address book usage examples
example: PHP API Address book usage examples

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

example: Generic HTTP Address book usage examples
example: PHP API Address book usage examples

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

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)

address_book_contact_delete

Delete a contact

example: Generic HTTP Address book usage examples
example: PHP API Address book usage examples

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

example: Generic HTTP Address book usage examples
example: PHP API Address book usage examples

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

Retrieves a list of address book groups

return: Example: {"status":0,"message":"OK","details":[{"id":"1","name":"My Friends"}]}
example: Generic HTTP Address book usage examples
example: PHP API Address book usage examples

object address_book_groups_get_list (string username, string password)

string username
string password

address_book_group_add

Add's a new address book group

example: Generic HTTP Address book usage examples
example: PHP API Address book usage examples

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

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

address_book_group_delete

Delete's an address book group

example: Generic HTTP Address book usage examples
example: PHP API Address book usage examples

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_register_user

This action affiliate users to create new users, please contact support@panaceamobile.com 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.

return: Example: {"status":0,"message":"OK","details":{"user_id":"67","username":"testdd","password":"10jm06","message":"User created successfully."}}
example: Generic HTTP Address book usage examples
example: example not found

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_set_promotion_code

Public method that sets promotion codes for new users

example: Generic HTTP Address book usage examples
example: example not found

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 panacea)
integer affiliate_id: (specify if you are part of multiple affiliate programs)

batches_list

Retrieves a list of the user batches.

return: Example: {"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

example: HTTP trace for checking a batch status
example: Perform batch functions using PHP API

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

Create's a new batch, returns batch ID if successful

example: HTTP trace for creating a batch
example: Perform batch functions using PHP API

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

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 or xls accepted )

batch_start

Starts the given batch

example: HTTP trace for starting a batch
example: Perform batch functions using PHP API

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.

return: details key contains an array of results sent in the same order they were received.
example: Perform execute_multiple using PHP API
example: JSON HTTP trace example

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.

example: Generic HTTP Address book usage examples
example: example not found

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

string username
string password
ip_address
return_array

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.

return: {"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

message_send

Send an SMS message

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

return: Example: {"status":1,"message":"Sent","details":"8beda1a8-5c12-489f-0107-123000000003"}
example: Sending an SMS using the Java API
example: Sending an SMS using the PHP/HTTP API
example: Sending an SMS via JSON HTTP GET

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

return: Example: {"status":0,"message":"OK","details":{"status":1,"cost":0.00000,"parts":1}}
example: Checking message status with the Java API

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'

return: details key contains the cost (in your account currency)
example: An example using the PHP class to perform a route_check_price call
example: A generic HTTP request illustrating the use and response of route_check_price

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 allow's 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.

return: 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.
example: A generic HTTP request illustrating the use and response of user_get_api_key()
example: A PHP based example on how to generate a usable API Key based on a successful authorization
example: A PHP based example on how to generate an API Key request token and redirect the user

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.

return: details key contains 'username' and 'key' which can be used as username and password combinations in subsequent requests.
example: A generic HTTP request illustrating the use and response of user_get_api_key()
example: A PHP based example on how to generate a usable API Key based on a successful authorization
example: A PHP based example on how to generate an API Key request token and redirect the user

object user_get_api_key (string request_key)

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

user_get_balance

Get's the user balance

return: Example: {"status":0,"message":"OK","details":3338.50000}
example: Checking user balance using the Java API

object user_get_balance (string username, string password)

string username
string password

user_get_phone_number

This function returns the verified phone number for the given user

return: {"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

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

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

string username
string password
target_username
amount

Constants / Codes

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_user_invalid_affiliate = -1024

User is not part of any affiliate program

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

Failed

var @int

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

Documentation generated on Tue, 03 May 2011 16:17:12 +0200 by Panacea Mobile