Difference between revisions of "Send REST"

From SMS Wiki
Jump to: navigation, search
(→‎Examples)
 
(9 intermediate revisions by one user not shown)
Line 1: Line 1:
 
'''Upsidewireless REST API '''
 
'''Upsidewireless REST API '''
  
−
There are two endpoints of Upsidewireless REST API, [https://secureapi.upsidewireless.com-https://secureapi.upsidewireless.com/] and [http://api.upsidewireless.com-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.
+
There are two endpoints of Upsidewireless REST API, [https://secureapi.upsidewireless.com https://secureapi.upsidewireless.com] and [http://api.upsidewireless.com 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.
 
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.
Line 9: Line 9:
  
 
'''1. SMS Message API'''
 
'''1. SMS Message API'''
−
'''API URI: /RESTv1/\{token\}/Message'''
+
 
 +
'''API URI: /RESTv1/{token}/Message'''
 +
 
 
'''Support method: HTTP POST '''
 
'''Support method: HTTP POST '''
 +
 
The following parameters are all '''required''' in your POST to send the message:
 
The following parameters are all '''required''' in your POST to send the message:
 +
 
{|
 
{|
 
|'''Parameter'''||'''Description'''
 
|'''Parameter'''||'''Description'''
Line 23: Line 27:
 
|}
 
|}
 
According to different type, a different set of additional parameters is required
 
According to different type, a different set of additional parameters is required
 +
 +
 
'''Additional parameters for type: "sms_test''''''"'''
 
'''Additional parameters for type: "sms_test''''''"'''
 
{|
 
{|
 
|'''Parameter'''||'''Description'''
 
|'''Parameter'''||'''Description'''
 
|-
 
|-
−
|recipient||The phone number to receive message, in [<u>E.164-http://en.wikipedia.org/wiki/E.164]</u> format, for example 16045551212.
+
|recipient||The phone number to receive message, in [http://en.wikipedia.org/wiki/E.164 E.164] format, for example 16045551212.
 
|-
 
|-
 
|encoding||Message encoding - 7 for GSM 7bit, 8 for Raw 8bit and 16 for Unicode
 
|encoding||Message encoding - 7 for GSM 7bit, 8 for Raw 8bit and 16 for Unicode
Line 36: Line 42:
 
|'''Parameter'''||'''Description'''
 
|'''Parameter'''||'''Description'''
 
|-
 
|-
−
|recipient||The phone number to receive message, in [<u>E.164-http://en.wikipedia.org/wiki/E.164]</u> format, for example 16045551212.
+
|recipient||The phone number to receive message, in [http://en.wikipedia.org/wiki/E.164 E.164] format, for example 16045551212.
 
|-
 
|-
 
|encoding||Message encoding - 7 for GSM 7bit, 8 for Raw 8bit and 16 for Unicode
 
|encoding||Message encoding - 7 for GSM 7bit, 8 for Raw 8bit and 16 for Unicode
Line 45: Line 51:
 
|'''Parameter'''||'''Description'''
 
|'''Parameter'''||'''Description'''
 
|-
 
|-
−
|recipient||The phone number to receive message, in [<u>E.164-http://en.wikipedia.org/wiki/E.164]</u> format, for example 16045551212.
+
|recipient||The phone number to receive message, in [http://en.wikipedia.org/wiki/E.164 E.164] format, for example 16045551212.
 
|-
 
|-
 
|encoding||Message encoding - 7 for GSM 7bit, 8 for Raw 8bit and 16 for Unicode
 
|encoding||Message encoding - 7 for GSM 7bit, 8 for Raw 8bit and 16 for Unicode
Line 52: Line 58:
 
|-
 
|-
 
|}
 
|}
 +
 +
 
'''Additional parameter for type: "sms_port''''''"'''
 
'''Additional parameter for type: "sms_port''''''"'''
 
{|
 
{|
 
|'''Parameter'''||'''Description'''
 
|'''Parameter'''||'''Description'''
 
|-
 
|-
−
|recipient||The phone number to receive message, in [<u>E.164-http://en.wikipedia.org/wiki/E.164]</u> format, for example 16045551212.
+
|recipient||The phone number to receive message, in [http://en.wikipedia.org/wiki/E.164 E.164] format, for example 16045551212.
 
|-
 
|-
 
|port||Port number – valid value is > 0 and < 65535, parameter message must be pre-encoded.
 
|port||Port number – valid value is > 0 and < 65535, parameter message must be pre-encoded.
 
|-
 
|-
 
|}
 
|}
 +
 +
 
'''Additional parameters for type: "sms_multi''''''"'''
 
'''Additional parameters for type: "sms_multi''''''"'''
 
{|
 
{|
 
|'''Parameter'''||'''Description'''
 
|'''Parameter'''||'''Description'''
 
|-
 
|-
−
|recipient||The phone number to receive message, in [<u>E.164-http://en.wikipedia.org/wiki/E.164]</u> format, for example 16045551212. This parameter can include multiple phone numbers, separated by comma.  
+
|recipient||The phone number to receive message, in [http://en.wikipedia.org/wiki/E.164 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
 
|encoding||Message encoding - 7 for GSM 7bit, 8 for Raw 8bit and 16 for Unicode
 
|-
 
|-
 
|}
 
|}
 +
 +
 
'''Additional parameters for type: "sms_group''''''"'''
 
'''Additional parameters for type: "sms_group''''''"'''
 
{|
 
{|
Line 79: Line 91:
 
|-
 
|-
 
|}
 
|}
 +
 +
 
'''Additional parameters for type: "sms_service_group''''''"'''
 
'''Additional parameters for type: "sms_service_group''''''"'''
 
{|
 
{|
Line 90: Line 104:
 
|-
 
|-
 
|}
 
|}
 +
 +
 
'''Additional parameters for type: "sms_dedicated''''''"'''
 
'''Additional parameters for type: "sms_dedicated''''''"'''
 
{|
 
{|
 
|'''Parameter'''||'''Description'''
 
|'''Parameter'''||'''Description'''
 
|-
 
|-
−
|recipient||The phone number to receive message, in [<u>E.164-http://en.wikipedia.org/wiki/E.164]</u> format, for example 16045551212.
+
|recipient||The phone number to receive message, in [http://en.wikipedia.org/wiki/E.164 E.164] format, for example 16045551212.
 
|-
 
|-
 
|encoding||Message encoding - 7 for GSM 7bit, 8 for Raw 8bit and 16 for Unicode
 
|encoding||Message encoding - 7 for GSM 7bit, 8 for Raw 8bit and 16 for Unicode
Line 105: Line 121:
 
|-
 
|-
 
|}
 
|}
 +
 +
 
'''Additional parameters for type: "sms_dedicated_port''''''"'''
 
'''Additional parameters for type: "sms_dedicated_port''''''"'''
 
{|
 
{|
 
|'''Parameter'''||'''Description'''
 
|'''Parameter'''||'''Description'''
 
|-
 
|-
−
|recipient||The phone number to receive message, in [<u>E.164-http://en.wikipedia.org/wiki/E.164]</u> format, for example 16045551212.
+
|recipient||The phone number to receive message, in [http://en.wikipedia.org/wiki/E.164 E.164] format, for example 16045551212.
 
|-
 
|-
 
|port||Port number – valid value is > 0 and < 65535, parameter message must be pre-encoded.
 
|port||Port number – valid value is > 0 and < 65535, parameter message must be pre-encoded.
Line 120: Line 138:
 
|-
 
|-
 
|}
 
|}
 +
 +
 
'''Additional parameters for type: "sms_defer''''''"'''
 
'''Additional parameters for type: "sms_defer''''''"'''
 
{|
 
{|
 
|'''Parameter'''||'''Description'''
 
|'''Parameter'''||'''Description'''
 
|-
 
|-
−
|recipient||The phone number to receive message, in [<u>E.164-http://en.wikipedia.org/wiki/E.164]</u> format, for example 16045551212.
+
|recipient||The phone number to receive message, in [http://en.wikipedia.org/wiki/E.164 E.164] format, for example 16045551212.
 
|-
 
|-
 
|encoding||Message encoding - 7 for GSM 7bit, 8 for Raw 8bit and 16 for Unicode
 
|encoding||Message encoding - 7 for GSM 7bit, 8 for Raw 8bit and 16 for Unicode
Line 135: Line 155:
 
|-
 
|-
 
|}
 
|}
 +
 +
 
'''Additional parameters for type: "sms_flash''''''"'''
 
'''Additional parameters for type: "sms_flash''''''"'''
 
{|
 
{|
 
|'''Parameter'''||'''Description'''
 
|'''Parameter'''||'''Description'''
 
|-
 
|-
−
|recipient||The phone number to receive message, in [<u>E.164-http://en.wikipedia.org/wiki/E.164]</u> format, for example 16045551212.
+
|recipient||The phone number to receive message, in [http://en.wikipedia.org/wiki/E.164 E.164] format, for example 16045551212.
 
|-
 
|-
 
|||The parameter message must be pre-encoded.
 
|||The parameter message must be pre-encoded.
 
|-
 
|-
 
|}
 
|}
 +
 +
 
'''Additional parameters for type: "sms_wappush''''''"'''
 
'''Additional parameters for type: "sms_wappush''''''"'''
 
{|
 
{|
 
|'''Parameter'''||'''Description'''
 
|'''Parameter'''||'''Description'''
 
|-
 
|-
−
|recipient||The phone number to receive message, in [<u>E.164-http://en.wikipedia.org/wiki/E.164]</u> format, for example 16045551212.
+
|recipient||The phone number to receive message, in [http://en.wikipedia.org/wiki/E.164 E.164] format, for example 16045551212.
 
|-
 
|-
 
|url||The pre-encoded URL
 
|url||The pre-encoded URL
 
|-
 
|-
 
|}
 
|}
 +
  
 
If no exception in API call, the following response (XML format) will be returned:
 
If no exception in API call, the following response (XML format) will be returned:
 +
 
<RestResponse>
 
<RestResponse>
−
<HasException>false</HasException>
+
:<HasException>false</HasException>
−
<Token>xxxxxxxx-8e4b-405b-998c-a580bf593b76</Token>
+
:<Token>xxxxxxxx-8e4b-405b-998c-a580bf593b76</Token>
−
< SMSMessage>
+
:< SMSMessage>
−
<Status>QUEUED or REJECTED</Status>
+
::<Status>QUEUED or REJECTED</Status>
−
< Body>sms message</ Body>
+
::< Body>sms message</ Body>
−
< Recipient>16047891236</ Recipient>
+
::< Recipient>16047891236</ Recipient>
−
<Type>sms</Type>
+
::<Type>sms</Type>
−
<TrackingId>MTID256749777469712848</TrackingId>
+
::<TrackingId>MTID256749777469712848</TrackingId>
−
<RejectReason> </RejectReason>
+
::<RejectReason> </RejectReason>
−
</ SMSMessage>
+
:</ SMSMessage>
 
</RestResponse>
 
</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".
 
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''' '''
 
Or in JSON format''' '''
 +
 
{
 
{
 
   "HasException": false,
 
   "HasException": false,
Line 182: Line 213:
 
}
 
}
  
−
'''
 
  
  
−
'''
+
 
 +
 
 
'''2. SMS Contact API'''
 
'''2. SMS Contact API'''
−
'''API URI: /RESTv1/\{token\}/Contact'''
+
 
 +
'''API URI: /RESTv1/{token}/Contact'''
 +
 
 
'''Support method: HTTP POST '''
 
'''Support method: HTTP POST '''
 +
 
The following parameters are '''required''' in your POST to add contact:
 
The following parameters are '''required''' in your POST to add contact:
 +
 
{|
 
{|
 
|'''Parameter'''||'''Description'''
 
|'''Parameter'''||'''Description'''
Line 195: Line 230:
 
|signature||One of the API credential, similar to a password. It can be found in your account page.
 
|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 [<u>E.164-http://en.wikipedia.org/wiki/E.164]</u> format, for example 16045551212. If mobile number already exists, existing record will be updated.
+
|mobile||The mobile number to be added as an SMS contact, in [http://en.wikipedia.org/wiki/E.164 E.164] format, for example 16045551212. If mobile number already exists, existing record will be updated.
 
|-
 
|-
 
|}
 
|}
 +
 
The following parameters are optional:
 
The following parameters are optional:
 
{|
 
{|
Line 225: Line 261:
 
|-
 
|-
 
|}
 
|}
 +
 
If no exception in API call, the following response (XML format) will be returned:
 
If no exception in API call, the following response (XML format) will be returned:
 +
 
<RestResponse>
 
<RestResponse>
−
<HasException>false</HasException>
+
:<HasException>false</HasException>
−
<Token>xxxxxxxx-8e4b-405b-998c-a580bf593b76</Token>
+
:<Token>xxxxxxxx-8e4b-405b-998c-a580bf593b76</Token>
−
<SMSContact>
+
:<SMSContact>
−
<success>true or false</success>
+
::<success>true or false</success>
−
<number>16047891236</number>
+
::<number>16047891236</number>
−
<message>Success or failure message</message>
+
::<message>Success or failure message</message>
−
</SMSContact>
+
:</SMSContact>
 
</RestResponse>
 
</RestResponse>
 +
  
 
Or in JSON format''' '''
 
Or in JSON format''' '''
Line 246: Line 285:
 
   }
 
   }
 
}
 
}
−
'''  
+
 
−
3. Number Validation API'''
+
 
−
'''API URI: /RESTv1/\{token\}/''' '''NumberValidation'''
+
 
 +
'''3. Number Validation API'''
 +
 
 +
'''API URI: /RESTv1/{token}/''' '''NumberValidation'''
 +
 
 
'''Support method: HTTP POST '''
 
'''Support method: HTTP POST '''
 +
 
The following parameters are '''required''' in your POST to do number validation:
 
The following parameters are '''required''' in your POST to do number validation:
 +
 
{|
 
{|
 
|'''Parameter'''||'''Description'''
 
|'''Parameter'''||'''Description'''
Line 258: Line 303:
 
|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.
 
|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 [<u>E.164-http://en.wikipedia.org/wiki/E.164]</u> format, for example 16045551212.
+
|number||The phone number to be validated, in [http://en.wikipedia.org/wiki/E.164 E.164] format, for example 16045551212.
 
|-
 
|-
 
|}
 
|}
 +
 +
 
If no exception in API call, the following response (XML format) will be returned:
 
If no exception in API call, the following response (XML format) will be returned:
 +
 +
 
<RestResponse>
 
<RestResponse>
−
<HasException>false</HasException>
+
 
−
<Token>xxxxxxxx-8e4b-405b-998c-a580bf593b76</Token>
+
:<HasException>false</HasException>
−
<NumberValidation>
+
 
−
<success>true or false</success>
+
:<Token>xxxxxxxx-8e4b-405b-998c-a580bf593b76</Token>
−
<number>16047891236</number>
+
 
−
<message>Success or failure message</message>
+
:<NumberValidation>
−
<country>Canada</country>
+
 
−
<network>British Columbia</network>
+
::<success>true or false</success>
−
<HLRLookupResultObject>
+
 
−
<status>OK</status>
+
::<number>16047891236</number>
−
<number>16047891236</number>
+
 
−
<MCC>302</MCC>
+
::<message>Success or failure message</message>
−
<MNC>370</MNC>
+
 
−
<operatorName>Microcell</operatorName>
+
::<country>Canada</country>
−
<operatorCountry>Canada</operatorCountry>
+
 
−
<message></message>
+
::<network>British Columbia</network>
−
</HLRLookupResultObject>
+
 
−
</NumberValidation>
+
::<HLRLookupResultObject>
 +
 
 +
:::<status>OK</status>
 +
 
 +
:::<number>16047891236</number>
 +
 
 +
:::<MCC>302</MCC>
 +
 
 +
:::<MNC>370</MNC>
 +
 
 +
:::<operatorName>Microcell</operatorName>
 +
 
 +
:::<operatorCountry>Canada</operatorCountry>
 +
 
 +
:::<message></message>
 +
 
 +
::</HLRLookupResultObject>
 +
 
 +
:</NumberValidation>
 +
 
 
</RestResponse>
 
</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.
 
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
 
Or in JSON format
 +
 
{
 
{
 
   "HasException": false,
 
   "HasException": false,
Line 304: Line 376:
 
   }
 
   }
 
}
 
}
 +
 +
  
 
The entire HLRLookupResultObject is as following:
 
The entire HLRLookupResultObject is as following:
 +
 
<HLRLookupResultObject>
 
<HLRLookupResultObject>
−
<status></status>
+
:<status></status>
−
<number></number>
+
:<number></number>
−
<MCC></MCC>
+
:<MCC></MCC>
−
<MNC></MNC>
+
:<MNC></MNC>
−
<operatorName></operatorName>
+
:<operatorName></operatorName>
−
<operatorCountry></operatorCountry>
+
:<operatorCountry></operatorCountry>
−
<IMSI></IMSI>
+
:<IMSI></IMSI>
−
<MSC></MSC>
+
:<MSC></MSC>
−
<mscOperator></mscOperator>
+
:<mscOperator></mscOperator>
−
<mscMCC></mscMCC>
+
:<mscMCC></mscMCC>
−
<mscMNC></mscMNC>
+
:<mscMNC></mscMNC>
−
<mscCountry></mscCountry>
+
:<mscCountry></mscCountry>
−
<mscLocation></mscLocation>
+
:<mscLocation></mscLocation>
−
<message></message>
+
:<message></message>
 
</HLRLookupResultObject>
 
</HLRLookupResultObject>
 +
 +
 
Only status, number and message are mandatory, others are optional.
 
Only status, number and message are mandatory, others are optional.
 +
 +
 
 
 
 
 
'''REST API Exception'''
 
'''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:
 
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>
 
<RestResponse>
−
<HasException>true</HasException>
+
:<HasException>true</HasException>
−
<Token>xxxxxxxx-8e4b-405b-998c-a580bf593b76</Token>
+
:<Token>xxxxxxxx-8e4b-405b-998c-a580bf593b76</Token>
−
<RestException>
+
:<RestException>
−
<ErrorCode>101</ErrorCode>
+
::<ErrorCode>101</ErrorCode>
−
<Message>Unauthorized</Message>
+
::<Message>Unauthorized</Message>
−
<Status>401</Status>
+
::<Status>401</Status>
−
</RestException>
+
:</RestException>
 
</RestResponse>
 
</RestResponse>
 +
 +
 
Or in JSON format''' '''
 
Or in JSON format''' '''
 +
 
{
 
{
 
   "HasException": true,
 
   "HasException": true,
Line 345: Line 431:
 
   }
 
   }
 
}
 
}
 +
 +
 
The Status is HTTP status code and it is optional.
 
The Status is HTTP status code and it is optional.
−
ErrorCode and corresponding message:
+
 
 +
 
 +
'''ErrorCode and corresponding message:'''
 +
 
 +
 
 
{|
 
{|
 
|'''ErrorCode'''||'''Message'''||'''Comments'''
 
|'''ErrorCode'''||'''Message'''||'''Comments'''
Line 362: Line 454:
 
|200||Zero balance||No credits to send a message
 
|200||Zero balance||No credits to send a message
 
|-
 
|-
−
|201||Invalid country||Can\’t figure out a country with the recipient number
+
|201||Invalid country||Can’t figure out a country with the recipient number
 
|-
 
|-
 
|202||Invalid carrier code||The carrier code is incorrect
 
|202||Invalid carrier code||The carrier code is incorrect
Line 387: Line 479:
  
  
 +
----
 +
== '''Examples''' ==
  
 +
[[Java Example]]  |  [[CSharp Example]]  |  [[Java JSON Example]]  | [[CSharp JSON Example]]
  
−
 
+
----
−
 
+
−
[[C# Example]]
+
−
 
+
−
[[Java Example]]
+

Latest revision as of 15:56, 9 February 2018

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

Java Example | CSharp Example | Java JSON Example | CSharp JSON Example

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