Back to top

Veoo HTTP API

This API provides a gateway for allowing customers to send messages via HTTP(S).

Bulk Messaging

Bulk Messaging

Send a message
GET/send

This sends a bulk message through the veoo platform and onto the mobile number you specify. The response will be returned in XML by default. You may use the format parameter or set an Accept header for content type “application/json” to receive a JSON formatted output. Veoo"s response will always use a unique Veoo ID, which can be used with the Veoo Polling API to determine the status of the message. However, if you"ve provided an ID, Veoo will refer to that ID with Delivery Receipt notifications to your supplied receipt url.

Example URI

GET https://api.veoo.com/send
URI Parameters
HideShow
username
String (required) 

API Username

password
String (required) 

API Password

source
String (required) 

The msisdn (or alpha originator) that this message will appear to come from. The maximum length of a msisdn is 16 characters, where alpha originator has a max length of 11 characters. Special characters like white space and underscores are not recommended to use within originator text as we cannot guarantee delivery of these messages.

msisdn
String (required) 

Must be formatted in international format. For example a UK msisdn would have the format 4477222333444.

message
String (required) 

Message contents. It is possible to send up to 160 gsm characters in a single SMS message. If the message is larger, it will be automatically split into multiple messages, and you will be billed accordingly.

coding
Integer (optional) 

Encoding you want to use (coding: 0 (default, 7 bits), 1 (8 bits) or 2 (Unicode))

charset
String (optional) 

Charset of the message text, eg UTF-8 or UTF-16BE

id
UUID (optional) 

Your ID to be returned in delivery receipts.

format
String (optional) 

If set to json, response will be in JSON.

Request  Send Message
HideShow
Headers
Content-Type: text/xml
Response  200
HideShow
Headers
Content-Type: text/xml
Body
<?xml version=”1.0” encoding=”UTF-8” ?>
<response>
<id>7041b505-9aad-4d77-88d8-14040e47a5bf</id>
<status>0</status>
</response>
Response  500
HideShow
Headers
Content-Type: text/html
Body
Internal API Error
Response  400
HideShow
Headers
Content-Type: text/html
Body
Invalid / Missing Parameters
Request  Send Message
HideShow
Headers
Content-Type: application/json
Response  200
HideShow
Headers
Content-Type: application/json
Body
{id: "7041b505-9aad-4d77-88d8-14040e47a5bf", status: 0}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {}
}

Batch Bulk Messaging

Send bulk message to a batch of recipients
POST/batch

This sends a bulk message to the mobile numbers you specify in the body. The body may be either JSON or formdata. The response will contain the unique Veoo IDs of every message, or a failure message for any blocked numbers.

The body may also be an array of batch requests, which allows sending multiple messages to groups of recipients with a single request.

Example URI

POST https://api.veoo.com/batch
URI Parameters
HideShow
username
String (required) 

API Username

password
String (required) 

API Password

source
String (required) 

The msisdn (or alpha originator) that this message will appear to come from. The maximum length of a msisdn is 16 characters, where alpha originator has a max length of 11 characters. Special characters like white space and underscores are not recommended to use within originator text as we cannot guarantee delivery of these messages.

message
String (required) 

Message contents. It is possible to send up to 160 gsm characters in a single SMS message. If the message is larger, it will be automatically split into multiple messages, and you will be billed accordingly.

msisdn
Array[String] or Object (required) 

Must be formatted in international format. For example a UK msisdn would have the format 4477222333444. There is a limit of 2000 MSISDNs per batch request.

Request  Send Message
HideShow
Headers
Content-Type: application/json
Body
{
  "username": "bulkUsername1",
  "password": "aSecurePassword",
  "source": "88100",
  "message": "Congratulations, you won a prize!",
  "msisdn": [
    "4477222333444",
    "4477555666777",
    "4477555666888"
  ]
}
Response  200
HideShow
Body
{
  status: "partial",
  result: [
    {"msisdn": "4477222333444", "id": "42704f76-b71a-42c4-a789-a9afee5350ed"},
    {"msisdn": "4477555666777", "id": "341fc493-bab6-4832-ba66-12a9853c656b"},
    {"msisdn": "4477555666888", "id": false},
  ]
}
Request  Multi-message array
HideShow
Headers
Content-Type: application/json
Body
?username=bulkUsername1&password=aSecurePassword&source=88100

[
  {
    "message": "You are a winner",
    "msisdn": ["4477222333444"]
  },
  {
    "message": "Try again next time!",
    "msisdn": ["4477555666777", "4477555666888"]
  }
]
Response  200
HideShow
Body
{
  status: "partial",
  result: [
    {"msisdn": "4477222333444", "id": "42704f76-b71a-42c4-a789-a9afee5350ed"},
    {"msisdn": "4477555666777", "id": "341fc493-bab6-4832-ba66-12a9853c656b"},
    {"msisdn": "4477555666888", "id": false},
  ]
}
Request  Custom message IDs
HideShow
Headers
Content-Type: application/json
Body
{
  "username": "bulkUsername1",
  "password": "aSecurePassword",
  "source": "88100",
  "message": "Congratulations, you won a prize!",
  "msisdn": {
    "4477222333444": "my-custom-id",
    "4477555666777": 0
  }
}
Response  200
HideShow
Body
{
  status: "ok",
  result: [
    {"msisdn": "4477222333444", "id": "my-custom-id"},
    {"msisdn": "4477555666777", "id": "341fc493-bab6-4832-ba66-12a9853c656b"}
  ]
}
Request  Missing parameter
HideShow
Headers
Content-Type: application/json
Body
{
  "username": "bulkUsername1",
  "password": "aSecurePassword",
  "message": "Congratulations, you won a prize!",
  "msisdn": [
    "4477222333444",
    "4477555666777",
    "4477555666888"
  ]
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "status": "error",
  "error": "Invalid Parameters Passed"
}
Request  Incorrect credentials
HideShow
Headers
Content-Type: application/json
Body
{
  "username": "bulkUsername1",
  "password": "incorrectPass",
  "source": "88100",
  "message": "Congratulations, you won a prize!",
  "msisdn": [
    "4477222333444",
    "4477555666777",
    "4477555666888"
  ]
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "status": "error",
  "error": "Bulk authentication failed"
}

Message polling

Poll a message status
GET/poll

Normally delivery status notifications are via a callback url which is linked to your account which is the best way to asynchronously receive delivery status change notifications. However, should you wish to obtain the status of a message you have previously sent you can use this endpoint.

Example URI

GET https://api.veoo.com/poll
URI Parameters
HideShow
id
string (required) Example: 7041b505-9aad-4d77-88d8-14040e47a5bf

The id of the message you would like to lookup.

format
string (optional) Example: json

If present with json or Accept header is set to application/json will provide a json response, otherwise xml.

Request
HideShow
Headers
Content-Type: text/xml
Response  200
HideShow
Headers
Content-Type: text/xml
Body
<response>
<id>2c848f0b-2c38-4cf6-9a8a-9f204608dec8</id>
<client_id>2c848f0b-2c38-4cf6-9a8a-9f204608dec8</client_id>
<msisdn>35796526149</msisdn>
<created_at>Thu Feb 18 2016 07:53:18 GMT+0000 (GMT)</created_at>
<updated_at>Thu Feb 18 2016 07:53:37 GMT+0000 (GMT)</updated_at>
<state>delivered</state>
</response>
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "_id": "56c5786e66d4a73e5d1753c4",
  "veoo_id": "2c848f0b-2c38-4cf6-9a8a-9f204608dec8",
  "client_id": "2c848f0b-2c38-4cf6-9a8a-9f204608dec8",
  "state": "delivered",
  "msisdn": "35796526149",
  "created_at": "2016-02-18T07:53:18.982Z",
  "updated_at": "2016-02-18T07:53:37.105Z",
  "created_day": "2016-02-18T00:00:00.000Z",
  "transactions": [
    {
      "smsc": "bulkHttp1",
      "smsc_id": "3362756703",
      "kannel_id": "2d2b6e44-d595-48ba-871c-f3733d7bf67f",
      "date_sent": "2016-02-18 07:56:14",
      "raw_reply": "id:c86f985f-a8b0-4544-895d-c8b276d9ce31 sub:001 dlvrd:001 submit date:160218075319 done date:160218075337 stat:DELIVRD err:000 text:",
      "dlr_type": "1",
      "service": "RDBulkInt1",
      "created_at": 1455782017105
    }
  ],
  "__v": 1
}

Premium Messaging

Premium Messaging

Send a message
GET/premium

This sends a premium message through the veoo platform and onto the mobile number you specify. The response will be returned in XML by default. You may use the format parameter or set an Accept header for content type “application/json” to receive a JSON formatted output. Veoo"s response will always use a unique Veoo ID unless one is provided on the request. This ID is used to indicate the message which has been receipted with Delivery Receipt Notifications.

Example URI

GET https://api.veoo.com/premium
URI Parameters
HideShow
username
String (required) 

veoo username

passsword
String (required) 

veoo account password

source
String (required) 

The msisdn (or alpha originator) that this message will appear to come from. The maximum length of a msisdn is 16 characters, where alpha originator has a max length of 11 characters. Special characters like white space and underscores are not recommended to use within originator text as we cannot guarantee delivery of these messages.

msisdn
String (required) 

Must be formatted in international format. For example a UK msisdn would have the format 4477222333444.

message
String (required) 

Message contents. It is possible to send up to 160 gsm characters in a single SMS message. If the message is larger, it will be automatically split into multiple messages, and you will be billed accordingly.

coding
Integer (optional) 

Encoding you want to use (coding: 0 (default, 7 bits), 1 (8 bits) or 2 (Unicode))

charset
String (optional) 

set of string you send to Kannel, ie utf-8.

network
string (required) Example: 24301

Mobile network number in international format for the mobile number you wish to charge. eg.

Country Network Network ID (MCCMNC)
Belgium Belgacom (Proximus) 20601
Belgium Mobistar 20610
Belgium Base 20620
Costa Rica ICE 71201
Cyprus Cytamobile-Vodafone 28001
Cyprus MTN 28010
Greece Cosmote 20201
Greece Vodafone 20205
Greece WIND 20209
Honduras Claro 708001
Honduras Tigo 708002
Hungary Telenor 21601
Hungary T-Mobile 21630
Hungary Vodafone 21670
Indonesia Indosat 51001
Indonesia Esia/Smartfren 51009
Indonesia Telkomsel 51010
Indonesia XLCom 51011
Indonesia Hutch/3 51089
Italy TIM 22201
Italy H3G / 3 Italia 22237
Italy Vodafone Italia 22210
Italy Wind Italia 22298
Malaysia Maxis 50212
Malaysia DiGi 50216
Malaysia U Mobile 50218
Nicaragua Claro 71021
Nicaragua Movistar 71030
Paraguay Claro 74402
Paraguay Tigo 74404
Paraguay Personal 74405
Singapore SingTel 52501
Singapore M1 52503
Singapore StarHub 52505
Thailand AIS 52003
Thailand DTAC 52018
Thailand TruemoveH 52088
Ukraine MTS/Vodafone UA 25501
Ukraine Kyivstar 25503
Ukraine Life/Lifecell/Astelit 25506
United Kingdom O2 Phoenix (Legacy) 23402
United Kingdom O2 Premium 23410
United Kingdom Vodafone 23415
United Kingdom Three 23420
United Kingdom T-Mobile 23430
United Kingdom Virgin 23431
United Kingdom Orange 23433
service_id
string (required) Example: 2c848f0b-2c38-4cf6-9a8a-9f204608dec8

Service identifier from MO messagei notification or your Account Manager. Service IDs are allocated by your Account Manager and are accessible via the Veoo Portal. These are also passed with each MO message. You should always return the same Service ID on the MT message as you received for the MO opt-in which started the service. If your subscribers opt-in differently, contact your Account Manager to release the correct Service ID to use.

type
String (required) 

sets type of premium message. Following types are supported:

Type Chargeable Description
paid yes use this type in case you need to send billable Premium MT
free no use this type in case you need to send zero rate Premium MT
optin yes Opt-in confirmation - this type is used for Asian countries and networks ONLY
optout yes Opt-out confirmation - this type is used for Asian countries and networks ONLY
dupin yes Duplicate opt-in info (or just ignore messages that result in this) - this type is used for Asian countries and networks ONLY
dupout yes Duplicate opt-out info (or just ignore messages that result in this) - this type is used for Asian countries and networks ONLY
id
UUID (optional) 

Your ID to be returned in delivery receipts.

format
String (optional) 

If set to json, response will be in JSON.

Request
HideShow
Headers
Content-Type: text/xml
Response  200
HideShow
Headers
Content-Type: text/xml
Body
<?xml version=”1.0” encoding=”UTF-8” ?>
<response>
<id>7041b505-9aad-4d77-88d8-14040e47a5bf</id>
<status>0</status>
</response>
Response  502
HideShow

Bad Gateway

Headers
Content-Type: text/html
Response  503
HideShow

Temporal failure, try again later.

Headers
Content-Type: text/html
Request
HideShow
Headers
Content-Type: application/json
Response  202
HideShow
Headers
Content-Type: application/json
Body
{id: "7041b505-9aad-4d77-88d8-14040e47a5bf", status: 0}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {}
}

Message Receipt Notifications

Message receipts are forwarded to a notification url which you provide to Veoo on account setup. Example URL would be https://yourhost.com/receipt

Your URL should response with an HTTP status code of 200 on success. If the URL returns an error 4xx, 5xx or times out we will retry this receipt a number of times with exponential backoff before giving up.

Receive Receipt notifications

Receive a receipt notification
GET/receipt

Example URI

GET https://api.veoo.com/receipt
URI Parameters
HideShow
username
string (required) 

Username provided to Veoo

password
string (required) 

Password provided to Veoo

msisdn
number (required) 

Destination MSISDN, i.e., 447940123000

origin
number (required) 

Originator of message, i.e. 81888

type
string (required) 

premium or bulk where applicable

status
string (required) 

Message status

Body Description
1: delivery success Delivered to handset
2: delivery failure Message failed
4: message buffered Message in queue
8: smsc submit Submitted to SMSC
16: smsc reject Rejected by SMSC
32: (smsc intermediate notifications) Non-final statuses
statusCode
number (required) 

Numeric error code like 000 (list)

statusText
string (required) 

String error code like VEOO_DELIVERED

id
uuid (required) 

Veoo message_id or your message_id passed in the request.

Request
HideShow
Headers
Content-Type: text/html
Response  200
HideShow
Headers
Content-Type: text/html
Body
OK

MO Message notifications

Message receipts are forwarded to a notification url which you provide to Veoo on account setup. Example URL would be https://yourhost.com/mo

Your URL should response with an HTTP status code of 200 on success. If the URL returns an error 4xx, 5xx or times out we will retry this MO a number of times with exponential backoff before giving up.

Receive MO notifications

Warning: the real URL would be https://yourhost.com/mo

Receive a MO notification
GET/mo

Example URI

GET https://api.veoo.com/mo
URI Parameters
HideShow
username
string (required) 

Username provided to Veoo

password
string (required) 

Password provided to Veoo

msisdn
string (required) 

Originating MSISDN, eg. 447940123000

shortcode
number (required) 

Destination Shortcode, eg. 34001>

timestamp
string (required) 

Time received, eg. 2011-08-07T12:47:17

id
uuid (required) 

Veoo message ID in UUID format

keyword
string (required) 

Extracted keyword, the first word of the message.

network
number (required) 

Network ID of the subscriber

message
string (required) 

Full message of the MO

service_id
UUID (required) 

Service identifier. If you are running multiple services it is important to store this service_id against the subscriber so you can pass this service_id on submission.

Request
HideShow
Headers
Content-Type: text/html
Response  200
HideShow
Headers
Content-Type: text/html
Body
OK

Last updated at 14 Feb 2019 10:02