VertexSMS LLM-readable site index
We use cookies to improve your experience on this site and serve more relevant content to you. By continuing to browse our site you agree to our use of cookies, revised Privacy Policy and Terms of Service.  More information about cookies
· est. 2006
Login Talk to Us
api documentation

Build it your way.
We'll wire it up.

Clean documentation, simple authentication, real-time callbacks.

Sending SMS

POSThttps://api.vertexsms.com/sms

Submits message(s) for sending. If successful - returns HTTP status code 200 OK and an array of IDs of messages added to the sending queue.

Required parameters

FieldTypeDescription
tostringDestination address (recipient)
fromstringSource address (originator)
messagestringMessage body. If optional parameter udh is not used - length is not limited: messages will be split automatically. Otherwise, max. text length depends on characters used - see here for more info.

Optional parameters

FieldTypeDescription
dlrUrlurlWhere to transfer delivery report of each submitted message. Delivery report will contain the same message ID, which is returned after submitting the message for sending.
prioritystringChange priority of sms. Possible values:
  • high - use this for registration forms, password reminders and other important sms.
  • normal - default priority for sms'es
  • low - use this priority for mass messages
scheduledstringMSchedule message sending in specified time. Date and time must be set in ISO 8601 ex.: 2015-01-01T13:00:00+02:00
udhstringUser Data Header of the message. Used to send long/concatenated messages. Each hex pair should be prefixed with % - see examples. For more info on UDH - see here and here for SMS concatenation.
Attention!If you specify udh - automatic message splitting will be disabled and you will also have to include field coding.
codingintegerUsed to specify encoding of the message text. Possible values:
  • 0 - 7 Bits GSM7 Alphabet and more info here
  • 1 - 8 Bits
  • 2 - UCS-2
Attention!If you specify coding - automatic message splitting will be disabled and you will also have to include field udh if the message exceeds character limit (160 - for text encoded with GSM-7; 70 - with UCS-2).
testModestringUse this to test API without sending real message to handset. Possible values:
  • 1 - Use this value to emulate success delivery
  • 2 - Use this value to emulate failed delivery
expireInintegerUse this to set time in seconds after which the message expires (is not attempted sent anymore).
Values can be in range [360, 432000].
correctBystringFix recipient number by a given country. Example: fix the 6xxxxxxx to 3706xxxxxxx if LT country iso passed.
Possible value: country code in ISO 3166-1 alpha-2 format

Request example:

REQUEST EXAMPLEPOST
POST /sms HTTP/1.1 Host: api.vertexsms.com Content-Type: application/json Accept: application/json X-VertexSMS-Token: eB52vNTPL9fO3rDrx8pYmVnj6nqceHNhnqceHNh { "to": "37069912345", "from": "API", "message": "Test SMS 001" }

Response example:

RESPONSE · 200 OK
HTTP/1.1 200 OK Content-Type: application/json Cache-control: no-cache X-VertexSMS-Amount-Sent: 1 ["1281532560"]

Message Text, Encoding and Length

A standard SMS (using GSM-7 character set) can contain a maximum of 160 characters. If you will include unicode characters (Chinese, Cyrillic, etc) in your message text - our API will detect that and switch encoding automatically to UCS-2 (coding=2). Unicode characters take up more space, so as a result, maximum length of the message text shrinks to 70 characters.

You can, of course, send text longer than that, however if you do so, our API will automatically split the text into parts. Each split is considered as a separate SMS, and is billed at the same rate as a normal SMS to the same destination.

When message is split into parts, user data headers (UDH) are added to each message, which contain information about message concatenation so that all separate parts could be combined as one at the receiving end and the process would be completely transparent to the recipient.

This header takes up some space, this reducing the maximum count of characters a bit more: 153 (from 160) for GSM-7 messages and 67 (from 70) for UCS-2 message.

CharactersIf you use at least one character not from GSM7 alphabet, whole message will be accounted as unicode (UCS-2).
Automatic message splittingThe actual number of SMS messages (parts), that the text you provided was split into (and sent to the recipient), can be retrieved from the X-VertexSMS-Amount-Sent response header.
GSM-7 encodingSome GSM-7-encoded characters will take 14 bits, which means such character will be counted as 2 separate characters. These characters include (but are not limited to): []~€ You can find full GSM-7 Alphabet here.

Delivery Reports (DLRS)

After an attempt to send your submitted message(s), Vertex server will perform a POST request to your dlrUrl with POST body containing JSON object with delivery receipt.

Example request (when dlrUrl is set as http://yourserver.com/your_script.php):

CALLBACK EXAMPLEPOST
POST /your_script.php HTTP/1.1 Host: yourserver.com Content-Type: application/json { "id": "1281532560", "status": "1", "error": 0, "mcc": "246", "mnc": "021" }

DLR fields explanation

FieldTypeDescription
idstringUnique message identifier, which was returned after submitting a message for sending.
statusintegerPossible values:
  • 1 - message was delivered.
  • 2 - message was not delivered. ErrorCode field will indicate the reason.
  • 16 - message was sent, but delivery period has expired.
errorintegerYou can find all VertexSMS API error codes here.
mccstringIf available you will get mobile country code, more info here.
mncstringIf available you will get mobile country code, more info here.
Your server responseYour script, which will handle message delivery reports coming to dlrUrl MUST respond with HTTP status code 200 OK and response body OK. Otherwise, the callback will be considered failed and will be repeated until it succeeds.

Scheduled Sendings

GEThttps://api.vertexsms.com/sms?scheduled

Request example:

REQUEST EXAMPLEGET
GET /sms?scheduled HTTP/1.1 Host: api.vertexsms.com Accept: application/json X-VertexSMS-Token: eB52vNTPL9fO3rDrx8pYmVnj6nqceHNhnqceHNh

Response example:

RESPONSE · 200 OK
HTTP/1.1 200 OK Content-Type: application/json [{id: "1695684253",scheduled: "2016-03-16 18:00:00",from: "Test",to: "37069559295",message: "Hello!",dlrUrl: "http://vertexsms.com"},{id: "1695684559",scheduled: "2016-03-16 18:00:00",from: "Test",to: "37069559295",message: "Hello!",dlrUrl: "http://vertexsms.com"}]

Scheduled sendings fields explanation

FieldTypeDescription
idintegerUnique sms identifier, which was returned after submitting an sms was submitted.
scheduledintegerDate and time in UTC timezone.
fromintegerSource address (originator).
tostringDestination address (recipient).
messagestringMessage body. If optional parameter udh is not used - length is not limited: messages will be split automatically. Otherwise, max. text length depends on characters used - see here for more info.
dlrUrlstringWhere to transfer delivery report of each submitted message. Delivery report will contain the same message ID, which is returned after submitting the message for sending.