This document will provide instructions on how to quickly integrate SMS messaging

services into various solutions by using HTTP application programming interface (HTTP
API). The HTTP API can be used for sending SMS messages, collecting delivery reports,
making Number Context (number validation) requests and receiving inbound SMS
messages sent from mobile phones.

API is based on REST standards, enabling you to use your browser for accessing URLs. In
order to interact with our API, any HTTP client in any programming language can be
used.

Base URL
Submit all requests to the base URL. All the requests are submitted thorough HTTP POST
or GET method.

http://api.freebusiness.sn

Content-Type & Accept header

API supports JSON and XML Content-Types and Accept criteria that should be specified
in the header. If the Content-Type is not specified you will receive a General error.
Depending which Accept type is chosen in the deader for the request, the same one will
be applied in the response.

 Content-Type: application/json or application/xml

 Accept header: application/json or application/xml

Authorization
We support basic authorization using a username and password with Base64 encoding
variation RFC2045-MIME.

The authorization header is constructed as follows:

1. Username and password are combined into a string username:password.

2. The resulting string is encoded using the RFC2045-MIME variant of Base64.

3. The authorization method and a space, like this: "Basic ", are put before the encoded string.

Example
Username: Aladdin
Password: open sesame

Base64 encoded string: QWxhZGRpbjpvcGVuIHNlc2FtZQ==

Authorization header: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

Response status and error codes

While using our API you may encounter certain status and error codes that you need to
understand or troubleshoot. This page contains a list of all codes with thorough
descriptions and action steps you need to take in case you are looking for a resolution of
the problem.

Find code name

Use page Search field or Find on page web browser feature to quickly locate the code
name you are looking for.

Code lists:

 HTTP status codes

 API Status codes

 General status codes

 Voice status codes

 Error codes

 General error codes

 Voice error codes

 Email error codes

HTTP status codes

Every HTTP transaction has a status code sent back by the server to define how the server
handled the transaction. Most common statuses you may have encountered are 200
OK and 404 Not Found

Learn more about HTTP status codes here

API Status codes
Besides standard HTTP status code, status object may be returned as part of the API
response message, delivery report or message log.

Status object example:

 JSON

{
"groupId":3,
"groupName":"DELIVERED",
"id":5,
"name":"DELIVERED_TO_HANDSET",
"description":"Message delivered to handset"
}

General status codes

PENDING (group id: 1) - general status codes
Message has been processed and sent to the next instance i.e. mobile operator.

Id Status
3 PENDING_WAITING_DELIVERY

 Message has been processed and sent to the next instance i.e. mobile operator with
request acknowledgment from their platform. Delivery report has not yet been
received, and is awaited thus the status is still pending.

7 PENDING_ENROUTE

 Message has been processed and sent to the next instance i.e. mobile operator.

26 PENDING_ACCEPTED

 Message has been accepted and processed, and is ready to be sent to the next
instance i.e. operator.

UNDELIVERABLE (group id: 2) - general status codes

Message has not been delivered.

Id Status
4 UNDELIVERABLE_REJECTED_OPERATOR

 Message has been sent to the operator, whereas the request was rejected, or a
delivery report with status "REJECTED" was reverted.

9 UNDELIVERABLE_NOT_DELIVERED

 Message has been sent to the operator, but has failed to deliver, since a delivery
report with status "UNDELIVERED" was reverted from the operator.

DELIVERED (group id: 3) - general status codes

Message has successfully been processed and delivered.

Id Status
2 DELIVERED_TO_OPERATOR

 Message has been successfully sent and delivered to the operator.

5 DELIVERED_TO_HANDSET

 Message has been successfully processed and delivered to recipient.

EXPIRED (group id: 4) - general status codes

Message has been sent, and has either expired due to being pending past its validity
period (our platform default is 48 hours), or the delivery report from the operator has
reverted the expired as a final status.

Id Status
15 EXPIRED_EXPIRED

 The message was received and sent to the operator, however it has been pending
until the validity period has expired, or the operator returned EXPIRED status in the
meantime.

29 EXPIRED_DLR_UNKNOWN
 Id Status

 The message has been received and forwarded to the operator for delivery, however
the delivery report from the operator has not been formatted correctly, or has not
been recognized as valid.

REJECTED (group id: 5) - general status codes

Message has been received, but has either been rejected by our system, or the operator
has reverted Rejected as final status.

Id Status
6 REJECTED_NETWORK

 Message has been received, but the network is either out of our coverage or not
setup on your account. Your account manager can inform you on the coverage status
or setup the network in question.

8 REJECTED_PREFIX_MISSING

 Message has been received, but has been rejected as the number is not recognized
due to either incorrect number prefix or number length. This information is different
for each network and is regularly updated.

10 REJECTED_DND

 Message has been received, and rejected due to the user being subscribed to DND
(Do Not Disturb) services, disabling any service traffic to their number.

11 REJECTED_SOURCE

 Your account is set to accept only registered sender ID-s while the sender ID defined
in the request has not been registered on your account.

12 REJECTED_NOT_ENOUGH_CREDITS

 Your account is out of credits for further submission - please top up your account.
For further assistance in topping up or applying for online account topup service you
may contact your account manager.

13 REJECTED_SENDER
Id Status

 The sender ID has been blacklisted on your account - please remove the blacklist on
your account or contact Support for further assistance.

14 REJECTED_DESTINATION

 The destination number has been blacklisted either at the operator request or on your
account - please contact Support for more information.

17 REJECTED_PREPAID_PACKAGE_EXPIRED

 Account credits have been expired past their validity period - please topup your
subaccount with credits to extend the validity period.

18 REJECTED_DESTINATION_NOT_REGISTERED

 Your account has been setup for submission only to a single number for testing
purposes - kindly contact your manager to remove the limitation.

19 REJECTED_ROUTE_NOT_AVAILABLE

 Mesage has been received on the system, however your account has not been setup
to send messages i.e. no routes on your account are available for further submission.
Your account manager will be able to setup your account based on your preference.

20 REJECTED_FLOODING_FILTER

 Message has been rejected due to a anti-flooding mechanism. By default, a single

number can only receive 20 varied messages and 6 identical messages per hour. If
there is a requirement, the limitation can be extended per account on request to your
account manager.

21 REJECTED_SYSTEM_ERROR

 The request has been rejected due to an expected system system error, please retry
submission or contact our technical support team for more details.

23 REJECTED_DUPLICATE_MESSAGE_ID

 The request has been rejected due to a duplicate message ID specified in the submit
request, while message ID-s should be a unique value.
 Id Status
24 REJECTED_INVALID_UDH

 Message has been received, while our system detected the message was formatted
incorrectly because of either an invalid ESM class parameter (fully featured binary
message API method) or an inaccurate amount of characters when using esmclass:64
(UDH). For more information feel free to visit the below articles or contact our
Support team for clarification.
https://en.wikipedia.org/wiki/User_Data_Header
https://en.wikipedia.org/wiki/Concatenated_SMS

25 REJECTED_MESSAGE_TOO_LONG

 Message has been received, but the total message length is more than 25 parts or
message text which exceeds 4000 bytes as per our system limitation.

51 MISSING_TO

 The request has been received, however the "to" parameter has not been set or it is
empty, i.e. there must be valid recipients to send the message.

52 REJECTED_INVALID_DESTINATION

 The request has been received, however the destination is invalid - the number prefix
is not correct as it does not match a valid number prefix by any mobile operator.
Number length is also taken into consideration in verifying number number validity.

Exemple:

/sms/1/text/single

 JSON

Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

Content-Type: application/json
Accept: application/json

{
"from":"InfoSMS",
"to":"41793026727",
"text":"My first SMS."
}
200 OK
{
"messages":[
{
"to":"41793026727",
"status": {
"groupId": 1,
"groupName": "PENDING",
"id": 7,
"name": "PENDING_ENROUTE",
"description": "Message sent to next instance"
},
"smsCount":1,
"messageId": "2033247207850523790"
}
]
}

BODY PARAMS

from

string

Represents sender ID and it can be alphanumeric or numeric. Alphanumeric sender ID length should
be between 3 and 11 characters (Example: CompanyName). Numeric sender ID length should be
between 3 and 14 characters.

to

array of strings

REQUIRED

Array of message destination addresses. If you want to send a message to one destination, a single
String is supported instead of an Array. Destination addresses must be in international format
(Example: 41793026727).

text

string

REQUIRED

Text of the message that will be sent.

Response format
On success, response header HTTP status code will be 200 OK and the message will be
sent.
If you try to send message without authorization, you will receive an error 401
Unauthorized.

SMSResponse
 Parameter Type Description

bulkId String The ID that uniquely identifies the request. Bulk

ID will be received only when you send a
message to more than one destination address.

messages SMSResponseDetails[] Array of sent message objects, one object per

every message.

SMSResponseDetails
Parameter Type Description

to String The message destination address.

status Status Indicates whether the message is successfully sent, not sent,
delivered, not delivered, waiting for delivery or any other
possible status.

smsCount int The number of sent message segments.

messageId String The ID that uniquely identifies the message sent.

Status

Parameter Type Description

groupId int Status group ID.

groupName String Status group name.

id int Status ID.

name String Status name.

description String Human readable description of the status.

action String Action that should be taken to eliminate the error.

Fully featured textual message

Send advanced SMS with the all available features and parameters.

post/sms/1/text/advanced
 JSON

Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

Accept: application/json
Content-Type: application/json

{
"bulkId":"BULK-ID-123-xyz",
"messages":[
{
"from":"InfoSMS",
"destinations":[
{
"to":"41793026727",
"messageId":"MESSAGE-ID-123-xyz"
},
{
"to":"41793026731"
}
],
"text":"Artık Ulusal Dil Tanımlayıcısı ile Türkçe karakterli smslerinizi raha
tlıkla iletebilirsiniz.",
"flash":false,
"language":{
"languageCode":"TR"
},
"transliteration":"TURKISH",
"intermediateReport":true,
"notifyUrl":"http://www.example.com/sms/advanced",
"notifyContentType":"application/json",
"callbackData":"DLR callback data",
"validityPeriod": 720
},
{
"from":"41793026700",
"destinations":[
{
"to":"41793026785"
}
],
"text":"A long time ago, in a galaxy far, far away... It is a period of civil
war. Rebel spaceships, striking from a hidden base, have won their first victory ag
ainst the evil Galactic Empire.",
"sendAt":"2015-07-07T17:00:00.000+01:00",
"deliveryTimeWindow": {
"from": {
"hour": 6,
"minute": 0
},
"to": {
"hour": 15,
"minute": 30
},
"days": [
"MONDAY", "TUESDAY", "WEDNESDAY", "THURSDAY", "FRIDAY", "SATURDAY", "SUND
AY"
]
}
}
],
"tracking":{
"track":"SMS",
"type":"MY_CAMPAIGN"
}
}
200 OK
{
"bulkId": "BULK-ID-123-xyz",
"trackingProcessKey": "9243E3F4BEDC719D83C2A38A483E6CB3",
"messages": [
{
"to": "41793026727",
"status": {
"groupId": 1,
"groupName": "PENDING",
 "id": 7,
"name": "PENDING_ENROUTE",
"description": "Message sent to next instance"
},
"smsCount": 1,
"messageId": "MESSAGE-ID-123-xyz"
},
{
"to": "41793026731",
"status": {
"groupId": 1,
"groupName": "PENDING",
"id": 7,
"name": "PENDING_ENROUTE",
"description": "Message sent to next instance"
},
"smsCount": 1,
"messageId": "2033912860760522207"
},
{
"to": "41793026785",
"status": {
"groupId": 1,
"groupName": "PENDING",
"id": 26,
"name": "PENDING_ACCEPTED",
"description": "Pending Accepted"
},
"messageId": "2033912860760522208"
}
]
}

BODY PARAMS

bulkId

string

The ID which uniquely identifies the request. Bulk ID will be received only when you send a message to
more than one destination address.

from

string

Represents a sender ID which can be alphanumeric or numeric. Alphanumeric sender ID length should
be between 3 and 11 characters (Example: CompanyName). Numeric sender ID length should be
between 3 and 14 characters.

to

string

REQUIRED

Message destination address. Addresses must be in international format (Example: 41793026727).

messageId

string

The ID that uniquely identifies the message sent.

text
string

Text of the message that will be sent.

flash

boolean

Can be true or false. If the value is set to true, a flash SMS will be sent. Otherwise, a normal SMS
will be sent. The default value is false.

transliteration

string

Conversion of a message text from one script to another.

Possible values: "TURKISH", "GREEK", "CYRILLIC", "CENTRAL_EUROPEAN" and "NON_UNICODE".

languageCode

string

Code for language character set of a message text.

Possible values: TR for Turkish, ES for Spanish and PT for Portuguese.

intermediateReport

boolean

The real-time Intermediate delivery report that will be sent on your callback server. Can
be true or false.

notifyUrl

string

The URL on your callback server on which the Delivery report will be sent.

notifyContentType

string

Preferred Delivery report content type. Can be application/json or application/xml.

callbackData

string

Additional client's data that will be sent on the notifyUrl. The maximum value is 200 characters.

validityPeriod

int32

The message validity period in minutes. When the period expires, it will not be allowed for the
message to be sent. Validity period longer than 48h is not supported (in this case, it will be
automatically set to 48h).
sendAt

date

Date and time when the message is to be sent. Used for scheduled SMS (SMS not sent immediately,
but at scheduled time).

deliveryTimeWindow

object

deliveryTimeWindow.from

object

Exact time of day in which the sending can start. Consists of hour and minute properties, both
mandatory. Time is expressed in the UTC timezone.

deliveryTimeWindow.to

object

Exact time of day in which the sending will end. Consists of hour and minute properties, both
mandatory. Time is expressed in the UTC timezone.

hour

int32

Hour when the time window opens when used in from property or closes when used in to property.

minute

int32

Minute when the time window opens when used in from property or closes when used in to property.

days

array of strings

Days which are included in the delivery time window. Values

are: MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY. At least one day must
be stated.

track

string

Indicates if the message has to be tracked for Conversion rates.

Possible values: SMS and URL

processKey

string

Key that uniquely identifies Conversion tracking process.

type

string

User defined type of the Conversion tracking process or flow type or message type, etc.
Example: ONE_TIME_PIN or SOCIAL_INVITES.