Difference between revisions of "Send REST"
(→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 | + | 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/ | + | |
+ | '''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 [ | + | |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 [ | + | |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 [ | + | |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 [ | + | |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 [ | + | |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 [ | + | |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 [ | + | |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 [ | + | |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 [ | + | |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 [ | + | |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> | |
− | + | :<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> | </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/ | + | |
+ | '''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 [ | + | |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> | |
− | + | :<Token>xxxxxxxx-8e4b-405b-998c-a580bf593b76</Token> | |
− | + | :<SMSContact> | |
− | + | ::<success>true or false</success> | |
− | + | ::<number>16047891236</number> | |
− | + | ::<message>Success or failure message</message> | |
− | + | :</SMSContact> | |
</RestResponse> | </RestResponse> | ||
+ | |||
Or in JSON format''' ''' | Or in JSON format''' ''' | ||
Line 246: | Line 285: | ||
} | } | ||
} | } | ||
− | ''' | + | |
− | 3. Number Validation API''' | + | |
− | '''API URI: /RESTv1/ | + | |
+ | '''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 [ | + | |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> | |
− | + | ||
− | + | :<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> | </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> | |
− | + | :<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> | </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> | |
− | + | :<Token>xxxxxxxx-8e4b-405b-998c-a580bf593b76</Token> | |
− | + | :<RestException> | |
− | + | ::<ErrorCode>101</ErrorCode> | |
− | + | ::<Message>Unauthorized</Message> | |
− | + | ::<Status>401</Status> | |
− | + | :</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|| | + | |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]] | ||
− | + | ---- | |
− | + | ||
− | + | ||
− | + | ||
− | + |
Latest revision as of 16: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. |
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