Overview
Our API offers an opportunity to configure automated SMS notifications directly from any software, CRM or application.
For the API server communication, a HTTP protocol is used, including secure SSL support. Requests are sent using GET and POST methods, and the server responds in either XML or JSON format, depending on your preference.
Connecting to the API
In order to be able to execute API requests, you need to enable and configure this function in the Mobizon Control Panel:
- Open API Settings in the Control Panel:
- Check Enable access to the API:
- Specify IP addresses which should be allowed to send API requests.
After enabling the access, you will see your API Key. Use this key in your application in order to execute API requests.
Your private key should not be written down or passed on to other persons unless necessary as anyone with knowledge of your key can perform any operations with your account via API.
In order to ensure the security of your account, it is recommended to specify a list of IP addresses assigned to your servers allowed to access the API. List your servers’ IP addresses in the List of IP addresses for access to the API field, separated by comma, e.g.: 192.12.34.56,23.45.67.89,123.123.123.123.
If this field is left empty, API access is allowed from any IP address, which could be a security threat.
You can change the API key by clicking the Update API key button next to the key. All applications using the old key would not be able to access the API anymore. You will need to replace the old key with the new one in the configuration of your applications.
Using the API
API entry point
All API requests are performed via the address: https://api.mobizon.com.br/service/
You can choose to use HTTP or HTTPS protocol for your requests. We recommend sending all requests via secure HTTPS protocol, however if your software does not support creation of secure HTTP requests, you can use the non-encrypted HTTP protocol. In this case, the requests should be directed to http://api.mobizon.com.br/service/.
Required parameters
Each API request must contain at least the module name, method, and API key:
https://api.mobizon.com.br/service/user/getownbalance?apiKey=KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK
where:
- user is the API module,
- getownbalance is the API method,
and additional parameters are listed after the question mark; in this case there is only one additional parameter, apiKey.
Please note that there is no slash (/) before the question mark, as such a request would be invalid:
https://api.mobizon.com.br/service/user/getownbalance/?apiKey=KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK
Optional parameters
- output: server response format.
Two formats are currently supported:
- json for JSON string (default value);
- xml for XML document.
Request example:
https://api.mobizon.com.br/service/user/getownbalance?output=json&api=v1&apiKey=KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK
- api: API version.
v1 is the current API version, and the default value.
Request example:
https://api.mobizon.com.br/service/user/getownbalance?output=json&api=v1&apiKey=KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK
- Other parameters.
Any other parameters, including method-related, can be sent as GET or POST parameters. Since there is a limitation to the maximum length of a GET request, and the responses to such requests can be cached by the intermediary network nodes, we recommend using only POST requests for API access.
All values of parameters supplied to the API must be in URL encoded format. Please refer to the documentation to your specific system or programming language for an instructions as to how to convert your parameters to this format.
API server response format
The server response is a string in the chosen data format (XML or JSON) containing an object that comprises three elements: code, data and message. Here are some response examples in JSON format:
{
"code":0,
"data":{
"balance":"4043.0656",
"currency":"BRL"
},
"message":""
}
A response in XML format looks like this:
<?xml version="1.0" encoding="UTF-8"?>
<root>
<code>0</code>
<data>
<balance>123.4567</balance>
<currency>BRL</currency>
</data>
<message></message>
</root>
where:
- code is the API response code (see API documentation for the reponse code values);
- data is the returned data in a format corresponding to the API method invoked or, in case of an error, it may contain data related to the cause of error (e.g. a list of fields containing incorrect data including descriptions of the errors these fields contain, in case of a validation error);
- message is the status text that usually generally describes the error, in case one has occurred.
API response codes
The result returned by an API call always contains a code field with a numeric value indicating the request processing result:
- 0 means success.
- 100 means there is no error, and the operation is being processed in background mode. In this case, the data field contains the ID of the background process. You can track the progress and status of the operation using the API requests taskqueue/getstatus.
- Any other response code means that an error occurred while processing the request. Please refer to this documentation page for the error codes.
PHP client library
You can use the official MobizonApi PHP client. Usage examples.
Another option is connecting this module via Composer.
Examples of API PHP client module usage
If you have your own working examples, please send them to us, and we will be glad to post them on the website. Just send your link or code example to support@mobizon.com.br
GET request usage example
If your application does not support POST requests, use GET requests in the following format:
https://api.mobizon.com.br/service/message/sendsmsmessage?recipient=NNNNNNNNNNN&from=PPPPPPP&text=Message+text+here%21&apiKey=KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK
where:
- NNN...NNN is the recipient's phone number in international format (not including the + character), e.g. 5511963928063.
- PPP...PPP - is your Sender ID (alphanumeric signature). If none is supplied, your default Sender ID will be used or, if you do not have any, the default system Sender ID.
- Message+text+here%21 is your SMS message text in URL encoded string format: “Message text here!”.
- KKK...KKK is your API key (you need to get it in your Control Panel).
