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

SMS API introduction

VertexSMS API is based on REST principles. To use REST API, you will need VertexSMS account and API access token. You can generate them inside your VertexSMS account. You must supply a Content-type header: `Content-type: application/json` for all PUT or POST requests.

HTTP headers and codes

REST API takes full advantage of all HTTP headers. Every header is important and has its own purpose, from status code to content type and request method. Bellow is list of http codes used by VertexSMS API.

General error when fulfilling the request would cause an invalid state. Domain validation errors, missing data, etc.
Similar to 403 Forbidden, but specifically for use when authentication is possible but has failed or not yet been provided.
The server understood the request, but is refusing to fulfil it. Authorisation will not help and the request SHOULD NOT be repeated.
The server has not found anything matching the Request-URI. No indication is given if the condition is temporary or permanent.
The method specified in the Request-Line is not allowed for the resource identified by the Request-URI.
The request could not be completed due to a conflict with the current state of the resource.
Server error, please try again.
Server error, please try again.
The server is currently unable to handle the request due to a temporary overloading or maintenance of the server. Please try again.

Handling errors

If our API rejects your request to send a message, an error will be returned in the form of 4xx (or 500, if our systems fail) HTTP status code and a JSON-encoded string with error description.

Here’s an example of a bad request:

Request example:

POST /sms HTTP/1.1
Host: api.vertexsms.com
Content-Type: application/json
Accept: application/json
X-VertexSMS-Token: eB52vNTPL9fO3rDrx8pYmVnj6nqceHNhnqceHNh

{ “to”: “37069912345”, “from”: “invalid sender ID”, “message”: “Test SMS 001” }

Response example:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{“message”: “Invalid value for field ‘from’. Sender ID must either be a valid MSISDN or an alpha-numeric string (max. length: 11 characters), which may consist only of upper+lower-case latin letters, digits, spaces and dots.”}


To ensure privacy we recommend you to use HTTPS for all VertexSMS API requests. All callbacks from our servers made only from those ip’s: and