Sending Your First SMS via Unifonic API

To use Unifonic REST API, you will need a Unifonic account, an application ID (AppSid), and a registered sender.

The URL is: https://el.cloud.unifonic.com/rest/SMS/messages, and the method is 'POST'
In the API request, you have to include the following parameters:

Parameter	Description	Value
AppSid	Authentication string that uniquely identifies your application.	6v253153sxxxxxxxx
SenderID	The SenderID identifies who has sent the SMS message, typically a brand name; in case of not adding this parameter, the system will use the default SenderID	Sender
Recipient	Destination mobile number: mobile numbers must be in international format without 00 or +. Example: (966507679351)	96650598XXXX
Body	Message body. Supports both English and Unicodes characters e.g. Arabic.	Hello world!
responseType	Supports JSON format only	JSON
CorrelationID	Unique identifier value that is attached to requests and messages.	CorrelationID
baseEncode	Binary-to-text encoding schemes that represent binary data in an ASCII string format	true
statusCallback	Filter messages report according to a specific message status, "Sent", "Queued," "Rejected," or "Failed	sent
async	It specifies that the request will be executed asynchronously as soon as it is sent	false
MessageType	Message Classification (KSA traffic only) 1-Warning (Government entities only) 3-Services 5-Promotional (For advertisement sender only *-AD) 6-Awareness See SMS Compliance	6

API request examples:

curl --location --request POST 'https://el.cloud.unifonic.com/rest/SMS/messages' \
--header 'Accept: application/json' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'AppSid=axuN0U7QlmqVPsfdgoK0mZxxxxxxxx' \
--data-urlencode 'SenderID=UNISMS' \
--data-urlencode 'Body=Hello there' \
--data-urlencode 'Recipient=96650767XXXX' \
--data-urlencode 'responseType=JSON' \
--data-urlencode 'CorrelationID=CorrelationID' \
--data-urlencode 'baseEncode=true' \
--data-urlencode 'MessageType=6'
--data-urlencode 'statusCallback=sent' \
--data-urlencode 'async=false'

curl --location --request POST 'https://el.cloud.unifonic.com/rest/SMS/messages?AppSid=axuN0U7QlmqVPsfdgoK0mZxxxxxxxx&SenderID=UNISMS&Body=Test message&Recipient=971507679351&responseType=JSON&CorrelationID=q1&baseEncode=true&statusCallback=sent&async=false&MessageType=6' \
--header 'Accept: application/json'

API response example:

{
    "success": true,
    "message": "",
    "errorCode": "ER-00",
    "data": {
        "MessageID": 42000348806924,
        "CorrelationID": "CorrelationID",
        "Status": "Sent",
        "NumberOfUnits": 0,
        "Cost": 0,
        "Balance": 0,
        "Recipient": "971507679351",
        "TimeCreated": "2022-09-06 14:06:25.979",
        "CurrencyCode": ""
    }
}

{
    "success": false,
    "message": "Dest num is too short",
    "errorCode": "ER-04",
    "data": {}
}

Unifonic API only supports JSON format. All requests must use the Content-type header set to application/json.

API RESPONSES

HTTPS Status codes

200 SUCCESS
400 No rules matched
401 Authentication failed
402 Missing parameter AppSid
403 Invalid IP Address
404 Incompatible API version
406 Wrong parameter format
409 This message is duplicate
410 Invalid recipient format
412 Message body is too long
415 Invalid hex string
417 Wrong body format
419 Wrong date format in request
420 Page limit Exceeds
421 No message body specified
422 No recipient parameter specified
423 Required timeScheduled parameter is not passed
429 Too many requests generated by this user
431 MessageId is empty
432 MessageId must be numeric
440 Wrong sender format
449 Message body is empty
450 Too many destination numbers provided
451 TimeScheduled parameter must indicate time in the future
452 User must specify either messageId or recipient parameter
455 Scheduled message not found for this User
456 Wrong correlationId format
459 Authentication parameters are incorrectly base64 encoded
460 Invalid encoding (Should be UCS2 or GSM7)
480 This user cannot use specified SenderID
481 Country does not exist
482 Invalid dest num
483 Operator is not found
499 Error in the configuration request
546 Incompatible external data type in configuration
548 Wrong dictionary configuration for response parameter
599 Request failed