¶ Introduction
This section gives details on how to make calls to our BMS API for sending either SMS or Text Email Messages.
¶ Sequence Diagram [SMS]
Below is the diagram showing the message exchange between our API and your system. The diagram below is when the customer system is sending and SMS message. Note that the sequence is similar when the customer is sending Email message:
¶ End Points
¶ Test
- BMS API : No Files https://test-bms.orbitmobile.co.zm/json.php
- BMS API : Allow Files https://test-bms.orbitmobile.co.zm/file.php
¶ Production
- BMS API : No Files https://bms.orbitmobile.co.zm/json.php
- BMS API : Allow Files https://bms.orbitmobile.co.zm/file.php
¶ API Keys
The API only processes requests sent with valid username and key parameters. After a successful creation of the test account, the account gets to be allowed to send 100 free SMSs and 200 free Emails for testing.
¶ Json API Endpoint
The JSON API Endpoint accepts requests sent with JSON payload. The payload contains all the required details i.e. authentication and message details.
¶ Url
The URL used to access this API Endpoint is the one listed above, which does not allow files.
¶ Sample request
| Description | Details |
|---|---|
| HTTP Method | POST |
| HTTP Special Headers | Content-Type : application/json |
¶ Sample Payload
{
"auth": {
"username":"ACCOUNT_USERNAME",
"key":"API_KEY"
},
"request":{
"query":"send",
"params":{
"messages":{
"1": {
"msisdn": "260XXXX",
"msg": "Testing message",
"source": "Test",
"channel":"SMS",
"country_code": "ZM"
}
}
}
}
}
¶ Request Parameters
Below is the description of each payload parameters:
| Param Name | Type | Mandatory | Description |
|---|---|---|---|
auth |
Object |
Y | Holds authentication details |
auth.username |
String |
Y | Holds the authentication username value |
auth.password |
String |
Y | Holds the authentication key value |
request |
Object |
Y | Holds the request details |
request.query |
String |
Y | Holds the string value of the query. Possible values are [send]. |
request.params |
Object |
Y | Holds the request parameter details. |
request.params.messages |
Object |
N | Holds a list of messages, each indexed using a numeric ID |
request.params.messages.id |
String |
N | Holds the message details |
request.params.messages.id.msisdn |
String |
N | Holds the receivers mobile number |
request.params.messages.id.msg |
String |
N | Holds the message details |
request.params.messages.id.source |
String |
N | Holds the string to be used as the Sender ID |
request.params.messages.id.channel |
String |
N | Holds string to identify the channel to use. Possible values are [SMS, EMAIL] |
request.params.messages.id.country_code |
String |
N | Holds the country code string. The value of this field is very important for SMS Messages |
¶ Sample response
| Description | Details |
|---|---|
| Success HTTP response code | 200 |
¶ Sample Payload
{
"status": {
"code": "417",
"msg": "1 Msg out of 1 Msgs sent! Remaining balances are, SMS : -0.5, Email : 0"
}
}
¶ Response Parameters
Below is the description of each payload parameters:
| Param Name | Type | Mandatory | Description |
|---|---|---|---|
status |
Object |
Y | Holds response details |
status.code |
String |
Y | Holds the response code. See below list for possible response/error codes |
status.msg |
String |
Y | Holds description of the response code. The message also contains the SMS and Email balances after the request |
¶ Error Codes
Below is the list of available response codes that can be returned in the status.code field of the response payload.
| Code | Status | Description |
|---|---|---|
| 404 | Error | No Authentication details specified |
| 405 | Error | No Request parameters specified |
| 406 | Error | Empty Request query specified |
| 407 | Error | Invalid Query specified |
| 408 | Error | Invalid Query parameter specified |
| 409 | Error | More than required Query parameters specified |
| 410 | Error | Missing required Query parameters |
| 411 | Error | Invalid Query parameter data type specified |
| 417 | Success | Details of SMSs sent |
¶ File API Endpoint
Coming soon. This feature is coming in our BMS V2 API.
¶ Conclusion
This section presents the details of our BMS API. Please feel free to reach us on it-support@orbitmobile.co.zm 
if you have any queries.