Sending Your First SMS with the Unifonic API

Send an SMS by making a REST API request. Before you begin, obtain a Unifonic account, an application ID (AppSid), and a registered Sender ID.

Send the request

Send an HTTP POST request to https://el.cloud.unifonic.com/rest/SMS/messages.

Request parameters

Parameter	Description	Example
AppSid	Authentication string that uniquely identifies the application.	`6v253153sxxxxxxxx`
SenderID	Sender ID displayed to the recipient. If omitted, the system uses the default Sender ID.	`Sender`
Recipient	Destination number in international format without `00` or `+`.	`96650598XXXX`
Body	Message content. Supports English and Unicode characters, including Arabic.	`Hello world!`
responseType	Response format. Only JSON is supported.	`JSON`
CorrelationID	Unique identifier attached to the request and message.	`CorrelationID`
baseEncode	Indicates whether binary data is represented in an ASCII string format.	`true`
async	Indicates whether the request is executed asynchronously.	`false`

Request examples

cURL form-encoded request

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 'async=false'

cURL request with query parameters

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'

Responses

200 OK

{
  "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": ""
  }
}

400 Bad Request

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

Status codes

Code	Description
200	Success
400	No rules matched
401	Authentication failed
402	Missing `AppSid` parameter
403	Invalid IP address
404	Incompatible API version
406	Wrong parameter format
409	Duplicate message
410	Invalid recipient format
412	Message body is too long
415	Invalid hexadecimal string
417	Wrong body format
419	Wrong date format in request
420	Page limit exceeded
421	No message body specified
422	No recipient parameter specified
423	Required `timeScheduled` parameter not provided
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` must indicate a future time
452	Specify either `messageId` or `recipient`
455	Scheduled message not found for this user
456	Wrong `correlationId` format
459	Authentication parameters are incorrectly Base64-encoded
460	Invalid encoding; use UCS2 or GSM7
480	User cannot use the specified `SenderID`
481	Country does not exist
482	Invalid destination number
483	Operator 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