Send REST

From SMS Wiki
Revision as of 12:35, 4 February 2015 by Bzurkovic (Talk | contribs)

Jump to: navigation, search

Upsidewireless REST API

There are two endpoints of Upsidewireless REST API, https://secureapi.upsidewireless.com and http://api.upsidewireless.com. If you care about more security than performance, you should use the secure endpoint. However, in this case you will need to install certificate for secure, authenticated communication. We recommend you select the secure option.

In order to use Upsidewireless REST API, you need have an account that has API permissions and get your API credential (token and signature) on your account page. Token is similar to username and signature is similar to password. They are needed in every single call to REST API.

There are two kinds of response of each API call, JSON or XML. You can either use HTTP header ("Accept") or a special HTTP parameter ("responsetype") to specify what kind of response you want. If you want using HTTP header, set either "application/json" or "application/xml" in Accept header. If you want using HTTP parameter, set either "JSON" or "XML" to responsetype parameter. If no response type specified, default response will always be in XML format. Use HTTP header is a highly recommended way to do so.


1. SMS Message API

API URI: /RESTv1/{token}/Message

Support method: HTTP POST

The following parameters are all required in your POST to send the message:

Parameter Description
signature One of the API credential, similar to a password. It can be found in your account page.
type The message type. Different type requires a different set of additional parameters.
message The text of the message you want to send. For some types, this message must be pre-encoded

According to different type, a different set of additional parameters is required


'Additional parameters for type: "sms_test'"

Parameter Description
recipient The phone number to receive message, in E.164 format, for example 16045551212.
encoding Message encoding - 7 for GSM 7bit, 8 for Raw 8bit and 16 for Unicode

'Additional parameter for type: "sms'"

Parameter Description
recipient The phone number to receive message, in E.164 format, for example 16045551212.
encoding Message encoding - 7 for GSM 7bit, 8 for Raw 8bit and 16 for Unicode

'Additional parameters for type: "mms'"

Parameter Description
recipient The phone number to receive message, in E.164 format, for example 16045551212.
encoding Message encoding - 7 for GSM 7bit, 8 for Raw 8bit and 16 for Unicode
mediaUrl The URL of the media you wish to send out with the message. gif , png and jpeg content is currently supported. The media size limit is 5MB. If you wish to send more than one image in the message, please provide multiple URLs separated by comma in this parameter.


'Additional parameter for type: "sms_port'"

Parameter Description
recipient The phone number to receive message, in E.164 format, for example 16045551212.
port Port number – valid value is > 0 and < 65535, parameter message must be pre-encoded.


'Additional parameters for type: "sms_multi'"

Parameter Description
recipient The phone number to receive message, in E.164 format, for example 16045551212. This parameter can include multiple phone numbers, separated by comma.
encoding Message encoding - 7 for GSM 7bit, 8 for Raw 8bit and 16 for Unicode


'Additional parameters for type: "sms_group'"

Parameter Description
groupName The name of contact group in your account
encoding Message encoding - 7 for GSM 7bit, 8 for Raw 8bit and 16 for Unicode


'Additional parameters for type: "sms_service_group'"

Parameter Description
serviceName The name of your PSMS service
groupName The contact group name of your PSMS service
encoding Message encoding - 7 for GSM 7bit, 8 for Raw 8bit and 16 for Unicode


'Additional parameters for type: "sms_dedicated'"

Parameter Description
recipient The phone number to receive message, in E.164 format, for example 16045551212.
encoding Message encoding - 7 for GSM 7bit, 8 for Raw 8bit and 16 for Unicode
carrierCode The carrier code that recipient phone number belongs to. This parameter is mandatory if dedicated number is a short code.
dedicatedNumber The dedicated number which will deliver the message. It could be a long code or a short code.
tariff The amount that recipient number to be charged


'Additional parameters for type: "sms_dedicated_port'"

Parameter Description
recipient The phone number to receive message, in E.164 format, for example 16045551212.
port Port number – valid value is > 0 and < 65535, parameter message must be pre-encoded.
carrierCode The carrier code that recipient phone number belongs to. This parameter is mandatory if dedicated number is a short code.
dedicatedNumber The dedicated number which will deliver the message. It could be a long code or a short code.
tariff The amount that recipient number to be charged


'Additional parameters for type: "sms_defer'"

Parameter Description
recipient The phone number to receive message, in E.164 format, for example 16045551212.
encoding Message encoding - 7 for GSM 7bit, 8 for Raw 8bit and 16 for Unicode
DelayHours The hours to delay.
DelayMinutes The minutes to delay
label The label of this delayed event


'Additional parameters for type: "sms_flash'"

Parameter Description
recipient The phone number to receive message, in E.164 format, for example 16045551212.
The parameter message must be pre-encoded.


'Additional parameters for type: "sms_wappush'"

Parameter Description
recipient The phone number to receive message, in E.164 format, for example 16045551212.
url The pre-encoded URL


If no exception in API call, the following response (XML format) will be returned:

<RestResponse>

<HasException>false</HasException>
<Token>xxxxxxxx-8e4b-405b-998c-a580bf593b76</Token>
< SMSMessage>
<Status>QUEUED or REJECTED</Status>
< Body>sms message</ Body>
< Recipient>16047891236</ Recipient>
<Type>sms</Type>
<TrackingId>MTID256749777469712848</TrackingId>
<RejectReason> </RejectReason>
</ SMSMessage>

</RestResponse>


In SMSMessage, TrackingId and RejectReason are optional. If Status is "QUEUED", for non-multiple recipient type, a unique TrackingId is returned for future query. If Status is "REJECTED", RejectReason includes the reject reason. If type is sms_test, the successful status is "PASSED", not "QUEUED".


Or in JSON format

{ 

 "HasException": false,
 "Token": "xxxxxxxx-8e4b-405b-998c-a580bf593b76",
 "SMSMessage": {
   "Status": "QUEUED" or "REJECTED",
   "Body": "sms message",
   "Recipient": "16047891236",
   "Type": "sms",
   "TrackingId": "MTID256749777469712848",
   "RejectReason": "Failure message"
 }

}



2. SMS Contact API

API URI: /RESTv1/{token}/Contact

Support method: HTTP POST

The following parameters are required in your POST to add contact:

Parameter Description
signature One of the API credential, similar to a password. It can be found in your account page.
mobile The mobile number to be added as an SMS contact, in E.164 format, for example 16045551212. If mobile number already exists, existing record will be updated.

The following parameters are optional:

Parameter Description
type The mobile type, such as Android, iPhone.
email The email of this SMS contact.
firstname The given name of this SMS contact
lastname The surname of this SMS contact
address The living or working address of this SMS contact
city The living or working city of this SMS contact
zipcode The zipcode of this SMS contact
landline The landline of this SMS contact
title The title of this SMS contact
role The role of this SMS contact
organization The organization this SMS contact belongs to

If no exception in API call, the following response (XML format) will be returned:

<RestResponse>

<HasException>false</HasException>
<Token>xxxxxxxx-8e4b-405b-998c-a580bf593b76</Token>
<SMSContact>
<success>true or false</success>
<number>16047891236</number>
<message>Success or failure message</message>
</SMSContact>

</RestResponse>


Or in JSON format { 

 "HasException": false,
 "Token": "xxxxxxxx-8e4b-405b-998c-a580bf593b76",
 " SMSContact ": {
   "success": true or false,
   "number": "16047891236",
   "message": "Success or failure message."
 }

}


3. Number Validation API

API URI: /RESTv1/{token}/ NumberValidation

Support method: HTTP POST

The following parameters are required in your POST to do number validation:

Parameter Description
signature One of the API credential, similar to a password. It can be found in your account page.
type The validation type. There are three possible types. 1 – "quick" and it will cost 0.1 credits; 2 – "route" and it will cost 0.25 credits; 3 – "hlr" and it will cost 0.5 credits.
number The phone number to be validated, in E.164 format, for example 16045551212.


If no exception in API call, the following response (XML format) will be returned:


<RestResponse>

<HasException>false</HasException>
<Token>xxxxxxxx-8e4b-405b-998c-a580bf593b76</Token>
<NumberValidation>
<success>true or false</success>
<number>16047891236</number>
<message>Success or failure message</message>
<country>Canada</country>
<network>British Columbia</network>
<HLRLookupResultObject>
<status>OK</status>
<number>16047891236</number>
<MCC>302</MCC>
<MNC>370</MNC>
<operatorName>Microcell</operatorName>
<operatorCountry>Canada</operatorCountry>
<message></message>
</HLRLookupResultObject>
</NumberValidation>

</RestResponse>


In NumberValidation, country, network and HLRLookupResultObject are optional, depends on the query type. If type is "quick", only country returned; if type is "route", country and network returned; if type is "hlr", only HLRLookupResultObject returned.

Or in JSON format

{ 

 "HasException": false,
 "Token": "xxxxxxxx-8e4b-405b-998c-a580bf593b76",
 "NumberValidation": {
   "success": true or false,
   "number": "16047891236",
   "message": "Success or failure message.",
   "country": "Canada",
   "network": "British Columbia"
   "HLRLookupResultObject": {
     "status": "OK",
     "number": "16047891236",
     "MCC": "302",
     "MNC": "370",
     "operatorName": "Microcell",
     "operatorCountry": "Canada",
     "message": ""
   }
 }

}


The entire HLRLookupResultObject is as following:

<HLRLookupResultObject>

<status></status>
<number></number>
<MCC></MCC>
<MNC></MNC>
<operatorName></operatorName>
<operatorCountry></operatorCountry>
<IMSI></IMSI>
<MSC></MSC>
<mscOperator></mscOperator>
<mscMCC></mscMCC>
<mscMNC></mscMNC>
<mscCountry></mscCountry>
<mscLocation></mscLocation>
<message></message>

</HLRLookupResultObject>


Only status, number and message are mandatory, others are optional.


  REST API Exception


If there is any exception in REST API call, the HasException flag will be set to true and the following response (XML format) will be returned:


<RestResponse>

<HasException>true</HasException>
<Token>xxxxxxxx-8e4b-405b-998c-a580bf593b76</Token>
<RestException>
<ErrorCode>101</ErrorCode>
<Message>Unauthorized</Message>
<Status>401</Status>
</RestException>

</RestResponse>


Or in JSON format

{ 

 "HasException": true,
 "Token": "xxxxxxxx-8e4b-405b-998c-a580bf593b76",
 "RestException": {
   "ErrorCode": "101",
   "Message": "Unauthorized",
   "Status": "401"
 }

}


The Status is HTTP status code and it is optional.


ErrorCode and corresponding message:


ErrorCode Message Comments
100 Unsupported method Wrong HTTP method
101 Unauthorized API credential is wrong
102 No permission API credential passed, but no permission
103 Runtime error Runtime error during API call
200 Zero balance No credits to send a message
201 Invalid country Can’t figure out a country with the recipient number
202 Invalid carrier code The carrier code is incorrect
203 Number blocked The recipient number is blocked by our system
204 Too many messages Message is too long
205 Empty message Empty message
206 No time for defer The delay parameter is wrong
207 Unknown type Unknown message type
208 Unimplemented type The message type not implemented yet
300 Mobile phone number is invalid Invalid mobile number
301 Credit is not enough to perform validation. Please purchase more and try again


Examples

C# Example | Java Example | CSharp Example

Retrieved from "http://docs.upsidewireless.com/index.php?title=Send_REST&oldid=3352"