Mitto Docs¶
API¶
General Info¶
The API is a HTTP RESTful API based around resource oriented URLs. It uses standard HTTP verbs and returns JSON on all requests.
Base URL¶
All URLs referenced in the documentation have the following base:
https://api.mitto.io
The API is served over HTTPS. To ensure data privacy, unencrypted HTTP is not supported.
Authentication¶
HTTP requests to the API are protected with HTTP Basic authentication.
In short, you will use your API key as the username and your API secret as the password for HTTP Basic authentication.
Sample Call in NodeJS Request:
var request = require("request");
var options = {
method: "GET",
url: "/",
headers:
{ Authorization: "Basic " + new Buffer(api_key + ":" + api_secret).toString("base64") }
};
request(options, function (error, response, body) {
if (error) throw new Error(error);
console.log(body);
});
Retrieve SIM¶
Method
GETURL
/sim/:uuid
URL Params
Parameter Description uuid 15 digit Universally Unique IDentifier of the SIM Success Response
Code: 200 Content: { "uuid": "238991234567890", "pin": "1234", "puk": "12345678", "voice": true, "sms": true, "data": true }
Error Codes
Code Error 400 uuid_invalid 403 uuid_forbidden 404 sim_not_found Sample Call in NodeJS Request
var request = require("request"); var options = { method: "GET", url: "/sim/238991234567890", headers: { Authorization: "Basic " + new Buffer(api_key + ":" + api_secret).toString("base64") } }; request(options, function (error, response, body) { if (error) throw new Error(error); console.log(body); });
Create SIM¶
Method
POSTURL
/sim/:uuid
URL Params
Parameter Description uuid 15 digit Universally Unique IDentifier of the SIM Data Params
Parameter Default Description voice true Boolean to enable/disable voice sms true Boolean to enable/disable SMS data true Boolean to enable/disable data Success Response
Code: 200 Content: { "message": "OK" }
Error Codes
Code Error 400 uuid_invalid 400 voice_invalid 400 sms_invalid 400 data_invalid 403 uuid_forbidden 404 uuid_not_found 409 uuid_conflict Sample Call in NodeJS Request
var request = require("request"); var options = { method: "POST", url: "/sim/238991234567890", headers: { Authorization: "Basic " + new Buffer(api_key + ":" + api_secret).toString("base64"), "content-type": "application/x-www-form-urlencoded" }, form: { voice: true, sms: true, data: true } }; request(options, function (error, response, body) { if (error) throw new Error(error); console.log(body); });
Update SIM¶
Method
PUTURL
/sim/:uuid
URL Params
Parameter Description uuid 15 digit Universally Unique IDentifier of the SIM Data Params
Parameter Default Description voice true Boolean to enable/disable voice sms true Boolean to enable/disable SMS data true Boolean to enable/disable data Success Response
Code: 200 Content: { "message": "OK" }
Error Codes
Code Error 400 uuid_invalid 400 voice_invalid 400 sms_invalid 400 data_invalid 403 uuid_forbidden 404 uuid_not_found 409 uuid_conflict Sample Call in NodeJS Request
var request = require("request"); var options = { method: "PUT", url: "/sim/238991234567890", headers: { Authorization: "Basic " + new Buffer(api_key + ":" + api_secret).toString("base64"), "content-type": "application/x-www-form-urlencoded" }, form: { voice: true, sms: true, data: false } }; request(options, function (error, response, body) { if (error) throw new Error(error); console.log(body); });
Delete SIM¶
Method
DELETEURL
/sim/:uuid
URL Params
Parameter Description uuid 15 digit Universally Unique IDentifier of the SIM Success Response
Code: 200 Content: { "message": "OK" }
Error Codes
Code Error 400 uuid_invalid 403 uuid_forbidden 404 sim_not_found Sample Call in NodeJS Request
var request = require("request"); var options = { method: "DELETE", url: "/sim/238991234567890", headers: { Authorization: "Basic " + new Buffer(api_key + ":" + api_secret).toString("base64") } }; request(options, function (error, response, body) { if (error) throw new Error(error); console.log(body); });
Send SMS¶
Method
POSTURL
/sms/:uuid
URL Params
Parameter Description uuid 15 digit Universally Unique IDentifier of the SIM Data Params
Parameter Description from An alphanumeric string text Text in UTF-8 encoding Success Response
Code: 200 Content: { "message": "OK" }
Error Codes
Code Error 400 uuid_invalid 400 from_invalid 400 text_invalid 403 uuid_forbidden 404 sim_not_found Sample Call in NodeJS Request
var request = require("request"); var options = { method: "POST", url: "/sms/238991234567890", headers: { Authorization: "Basic " + new Buffer(api_key + ":" + api_secret).toString("base64"), "content-type": "application/x-www-form-urlencoded" }, form: { from: "Mitto", text: "Hello, World!" } }; request(options, function (error, response, body) { if (error) throw new Error(error); console.log(body); });
Webhooks¶
General Info¶
The endpoints has 15 seconds to accept the event. If a success HTTP status code has not been returned within these 15 seconds, the event will be discarded.
Authentication¶
The webhooks authenticate against the endpoints using HTTP Basic authentication:
POST /location_update
Host: www.example.com
Content-Type: application/json
Authorization: Basic SGVsbG8gV29ybGQ=
The webhooks is served over HTTPS. To ensure data privacy, unencrypted HTTP is not supported.
Location Update¶
Sample of Location Update:
{ "time": "2017-01-01 01:23:45",
"imsi": "238991234567890",
"imei": "1234567890987654",
"type": "cs",
"country_code": "dk",
"country_code_previous": "de" }
XDR¶
Sample of Voice Data Record:
{ "time": "2017-01-01 01:23:45",
"event_id": "1234567890-1234",
"type": "voice",
"country_code": "dk",
"imsi": "238991234567890"
"operation": "finalize",
"direction": "incoming",
"caller": "4512345678",
"called": "4587654321",
"ringtime": "10",
"billtime": "20",
"duration": "30",
"status": "answered",
"error": null }
Sample of SMS Data Record:
{ "time": "2017-01-01 01:23:45",
"event_id": "1234567890-1234",
"type": "sms",
"country_code": "dk",
"imsi": "238991234567890"
"operation": "finalize",
"direction": "incoming",
"caller": "4512345678",
"called": "4587654321",
"retries": "3",
"error": null }
Sample of Data Data Record:
{ "time": "2017-01-01 01:23:45",
"event_id": "1234567890-1234",
"type": "data",
"country_code": "dk",
"imsi": "238991234567890"
"operation": "finalize",
"download": "4321",
"upload": "1234" }