NAV Navbar
cURL PHP Ruby

Introduction

Welcome to the VoodooSMS API. Our API allows you to integrate your website or your application to our platform giving you the ability to use our features such as our Send SMS API.

We use a RESTful endpoint with an API Key which is used to authorize the API.

Responses are returned as JSON.

Getting Started

To begin using the API you must first register an account with VoodooSMS. You can do that here.

Once registered, you must create an API Key. Click here to get further details on how to get this.

Authentication

Authentication using Bearer Authorization header

curl https://api.voodoosms.com/balance \
  -H 'Authorization: Bearer {key}'

Authentication is done via an API Key. You can obtain your Key here

Each API call sent through us will need to be authenticated using the Bearer authentication mode in the request headers of your application.

Unicode 👀

You are able to use Unicode characters (including Emojis 😎) when sending SMS via the API.

The following characters if used will be sent as plain text 7-bit encoding which allows you to send an SMS up to 160 characters before it is segmented.

@ Δ SP 0 ¡ P ¿ p
£ _ ! 1 A Q a q
$ Φ 2 B R b r
¥ Γ # 3 C S c s
è Λ ¤ 4 D T d t
é Ω % 5 E U e u
ù Π & 6 F V f v
ì Ψ 7 G W g w
ò Σ ( 8 H X h x
Ç Θ ) 9 I Y i y
LF Ξ * : J Z j z
Ø + ; K Ä k ä
ø Æ , < L Ö l ö
æ - = M Ñ m ñ
Å ß . > N Ü n ü
å É / ? O § o à

There are some specific characters that when used will actually take up 2 characters on your message.

| , ^ , , { , } , [ , ] , ~ , \

This table will give you a visual idea of how your messages will be segmeneted.

Length Segments
1 - 160 1
161 - 304 2
305 - 456 3
457 - 608 4
609 - 760 5

Unicode messages are sent in a multi-part 7-bit encoded message and has a maximum character limit of 152.

When Unicode characters are detected, your character count will be reduced to 70 characters.

This table shows how your messages will be segmented using these characters.

Length Segments
1 - 70 1
71 - 132 2
133 - 198 3
199 - 264 4
265 - 330 5

Click here for a guide on how to use Emojis from your computer

Endpoint

https://api.voodoosms.com/

ChangeLog

All notable changes to the API will be documented here.

27/03/2019

Added support for using Unicode and Emojis 🥳

11/03/2019

Added PHP and Ruby code examples

Sandbox

The sandbox parameter allows you to use our Send SMS API without any actions been taken.

Example Code

curl -X POST https://api.voodoosms.com/sendsms \
  -H "Authorization: Bearer {key}" \
  -d '{
    "to": 447000123890,
    "from": "VoodooSMS",
    "msg": "Testing The API"
    "schedule": "3 weeks",
    "external_reference": "Testing VoodooSMS",
    "sandbox": true
  }'
<?php
api_key = 'API KEY';

msg = json_encode(
    [
        'to' => 447857754521,
        'from' => "VoodooSMS",
        'msg' => "This is another test message",
        'schedule' => "3 weeks",
        'external_reference' => "Testing VoodooSMS",
        'sandbox' => true
    ]
);

ch = curl_init('https://api.voodoosms.com/sendsms');

curl_setopt(ch, CURLOPT_POST, true);
curl_setopt(ch, CURLOPT_HTTPHEADER, [
    'Authorization: ' . api_key
]);
curl_setopt(ch, CURLOPT_POSTFIELDS, msg);
curl_setopt(ch, CURLOPT_RETURNTRANSFER, true);

response = curl_exec(ch);

curl_close(ch);
require 'rest-client'

url = "https://api.voodoosms.com/sendsms"
api_key = "INSERT API KEY"

payload = '{
    "to": "447000123890",
    "from": "VoodooSMS",
    "msg": "Testing The API",
    "schedule": "3 weeks",
    "external_reference": "Testing VoodooSMS",
    "sandbox": true
}'

headers = {
    :content_type => :json,
    :Authorization => 'Bearer ' + api_key
}

response = RestClient.post(
    url,
    payload,
    headers
)

puts response

Example Response

{
  "count": 1,
  "originator": "VoodooSMS",
  "body": "Hello this is a test",
  "scheduledDateTime": null,
  "credits": 1,
  "balance": 2365,
  "messages": [
    {
      "id": null,
      "recipient": 447800000000,
      "reference": null,
      "status": "SANDBOX"
    }
  ]
}

How To Use

Add the sandbox parameter alongside your other parameters and mark it as true

When using this API with the sandbox parameter, you will receive a response back as normal, but the actual SMS will not be sent.

Sending SMS

Sending Overview

The Send SMS API allows you to send SMS to single or multiple recipients, or a contact list of numbers.

SMS can be sent straight away or scheduled for a date in the future.

OPTIONAL PROPERTIES

Attribute Type Description Default
country_code int The country code for your destination number
schedule datetime,string A date or time in the future to schedule SMS to be sent at.

Formats:

UNIX: A UNIX timestamp (e.g. 1537525884)
ISO 8601: A string format including the time and timezone (e.g. 2018-02-22T09:03:00+00:00)
Human Readable: A human readable way to write the date or time you want to sent the message at (e.g. 25th December 2019 21:00, 2 weeks, august 20, may 11 2019, last friday of march 2019, next saturday)
timezone string Match your timezone you're sending from. Note: Will only work in conjunction with the schedule parameter. UTC
truncate int Select whether you want to truncate the from attribute. Value must be 1. 0
quiet int Quiet times are set-up in the Portal here. Set-up your desired times and then you can enable this feature. Value must be 1
validity int The amount of minutes the message is valid for 2880
external_reference string Your own reference for the SMS (e.g. An order number)

Single SMS

Send a single SMS to a single recipient.

REQUEST

Code Example

curl -X POST https://api.voodoosms.com/sendsms \
  -H "Authorization: Bearer {key}" \
  -d '{
    "to": 447000123890,
    "from": "VoodooSMS",
    "msg": "Testing The API"
    "schedule": "3 weeks",
    "external_reference": "Testing VoodooSMS"
  }'
<?php
$api_key = 'API KEY';

$msg = json_encode(
    [
        'to' => 447857754521,
        'from' => "VoodooSMS",
        'msg' => "This is another test message",
        'schedule' => "3 weeks",
        'external_reference' => "Testing VoodooSMS"
    ]
);

$ch = curl_init('https://api.voodoosms.com/sendsms');

curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: ' . $api_key
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, $msg);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);

curl_close($ch);
require 'rest-client'

url = "https://api.voodoosms.com/sendsms"
api_key = "API KEY"

payload = '{
    "to": "447000123890",
    "from": "VoodooSMS",
    "msg": "Testing The API",
    "schedule": "3 weeks",
    "external_reference": "Testing VoodooSMS"
}'

headers = {
    :content_type => :json,
    :Authorization => 'Bearer ' + api_key
}

response = RestClient::Request.execute(
    :method => :post,
    :url => url,
    :headers => headers,
    :payload => payload
)

puts response

Response

{
  "count": 1,
  "originator": "VoodooSMS",
  "body": "Hello this is your SMS body",
  "scheduledDateTime": 1537525949,
  "credits": 1,
  "balance": 2365,
  "messages": [
    {
      "id": "97709216074987x3NFD16GgkChK2E67441209181vapi",
      "recipient": 447800000000,
      "reference": null,
      "status": "PENDING_SENT"
    }
  ]
}

Error Response

{
  "error": {
    "code": 5,
    "message": "A required parameter is missing"
  }
}

PROPERTIES

Attribute Type Description
to string The recipient of the SMS
from string Who the message is from. Can be a number or alphanumeric string
msg string The message you want to send

ERRORS

These errors are specific to this API call. More sendSMS errors are here

Code Message Meaning
7 Multiple destinations attempted You can only send to one number per call. If you want to send bulk SMS, use the Bulk SMS API call.
8 Attempted to send to a contact list To send to a Contact List of numbers, you must use the Send SMS to Contact List API.

Bulk SMS

Send a message to multiple contacts in one go.

Similar to sending to a single contact but just provide a commar-seperated list of numbers.

REQUEST

Code Example

curl -X POST https://api.voodoosms.com/bulksms \
  -H "Authorization: Bearer {key}" \
  -d '{
    "to": "447000000123,447800000345",
    "from": "VoodooSMS",
    "msg": "Hello this is a test to multiple numbers"
  }'
<?php
$api_key = 'API KEY';

$msg = json_encode(
    [
        'to' => "447700900123,447700900321",
        'from' => "VoodooSMS",
        'msg' => "This is a test message for multiple users",
        'schedule' => "3 weeks",
        'external_reference' => "Testing VoodooSMS"
    ]
);

$ch = curl_init('https://api.voodoosms.com/bulksms');

curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: ' . $api_key
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, $msg);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);

curl_close($ch);
require 'rest-client'

url = "https://api.voodoosms.com/bulksms"
api_key = "API KEY"

payload = '{
    "to": "447700900123,447700900321",
    "from": "VoodooSMS",
    "msg": "This is a test message for multiple users",
    "schedule": "3 weeks",
    "external_reference": "Testing VoodooSMS"
}'

headers = {
    :content_type => :json,
    :Authorization => 'Bearer ' + api_key
}

response = RestClient::Request.execute(
    :method => :post,
    :url => url,
    :headers => headers,
    :payload => payload
)

puts response

Response

{
  "count": 2,
  "originator": "VoodooSMS",
  "body": "Hello this is your SMS body to multiple contacts",
  "scheduledDateTime": null,
  "credits": 2,
  "balance": 2363,
  "messages": [
    {
      "id": "96889234412987x3NFD16GgkChK4R57441409423vapi",
      "recipient": 447000000123,
      "reference": null,
      "status": "PENDING_SENT"
    },
    {
      "id": "96899216074955x3NFD14GgkChK2E61267209599vapi",
      "recipient": 447800000345,
      "reference": null,
      "status": "PENDING_SENT"
    }
  ]
}

Error Response

{
  "error": {
    "code": 9,
    "message": "Attempted to send to a single destination"
  }
}

PROPERTIES

Attribute Type Description
to array The recipients of the SMS
from string Who the message is from. Can be a number or alphanumeric string
msg string The message you want to send

ERRORS

These errors are specific to this API call. More bulkSMS errors are here

Code Message Meaning
9 Attempted to send to a single destination You must send to > 1 destination. If you want to send a single SMS, use the Bulk SMS API call.
8 Attempted to send to a contact list To send to a Contact List of numbers, you must use the Send SMS to Contact List API.

Send SMS to Contact List

You can send SMS to recipients off a Contact List.

You need to create a Contact List on the VoodooSMS Portal and import your numbers. Then using just the ID you can send SMS to that list of numbers.

You can find the Contact List ID by going here and clicking the drop-down on your list.

REQUEST

Code Example

curl -X POST https://api.voodoosms.com/sendtocontacts \
  -H "Authorization: Bearer {key}" \
  -d '{
    "to": "c4767",
    "from": "VoodooSMS",
    "msg": "Hello I am sending from a Contact List"
  }'
<?php
$api_key = 'API KEY';

$msg = json_encode(
    [
        'to' => "c51396",
        'from' => "VoodooSMS",
        'msg' => "This is a test message to contact list",
        'schedule' => "3 weeks",
        'external_reference' => "Testing VoodooSMS"
    ]
);

$ch = curl_init('https://api.voodoosms.com/sendtocontacts');

curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: ' . $api_key
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, $msg);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);

curl_close($ch);
require 'rest-client'

url = "https://api.voodoosms.com/sendtocontacts"
api_key = "API KEY"

payload = '{
    "to": "c51396",
    "from": "VoodooSMS",
    "msg": "This is a test message to contact list",
    "schedule": "3 weeks",
    "external_reference": "Testing VoodooSMS"
}'

headers = {
    :content_type => :json,
    :Authorization => 'Bearer ' + api_key
}

response = RestClient::Request.execute(
    :method => :post,
    :url => url,
    :headers => headers,
    :payload => payload
)

puts response

Response

{
  "count": 25,
  "originator": "VoodooSMS",
  "body": "Hello I am sending SMS from a list of Contacts",
  "scheduledDateTime": 1537525949,
  "credits": 2,
  "balance": 2363,
  "messages": [
    {
      "id": "96889234412987x3NFD16GgkChK4R57441409423vapi",
      "recipient": 447000000123,
      "reference": null,
      "status": "PENDING_SENT"
    },
    {
      "id": "96899216074955x3NFD14GgkChK2E61267209599vapi",
      "recipient": 447800000345,
      "reference": null,
      "status": "PENDING_SENT"
    }
  ]
}

PROPERTIES

Attribute Type Description
to string A Contact List ID using the prefix of c
from string Who the message is from. Can be a number or alphanumeric string
msg string The message you want to send

ERRORS

These errors are specific to this API call. More sendToContacts errors are here

Code Message Meaning
11 Attempted to send to a specific destination You cannot send to single or bulk numbers on this API call.
12 Invalid destination You must prefix your Contact List ID with a c followed by the ID of your list.
13 Invalid contact list ID The contact list ID you specified is not valid or does not belong to your account.

Error Response

{
  "error": {
    "code": 13,
    "message": "Invalid contact list ID"
  }
}

Schedule SMS

If you want to schedule your SMS to go out at a date in the future, add the schedule parameter with a value of the date/time you want the SMS to go out. You can do this by using the Send SMS API. Dates can be a UNIX timestamp or in the ISO 8601 format. See the SMS Overview for more details.

Retrieve

Retrieve your scheduled SMS

REQUEST

Code Example

curl https://api.voodoosms.com/schedule \
  -H "Authorization: Bearer {key}"
<?php
$api_key = 'API KEY';

$ch = curl_init('https://api.voodoosms.com/schedule');

curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: ' . $api_key
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);

curl_close($ch);
require 'rest-client'

url = "https://api.voodoosms.com/schedule"
api_key = "API KEY"

headers = {
    :content_type => :json,
    :Authorization => 'Bearer ' + api_key
}

response = RestClient::Request.execute(
    :method => :get,
    :url => url,
    :headers => headers
)

puts response

Response

{
  "count": 25,
  "schedules": [
    {
      "id": 45678,
      "originator": "VoodooSMS",
      "body": "This is an SMS",
      "scheduledDateTime": 15676789,
      "status": "scheduled"
    }
  ]
}

Cancel

Cancel the SMS you have scheduled

REQUEST

Code Example

curl -X DELETE https://api.voodoosms.com/schedule/45678 \
  -H "Authorization: Bearer {key}"
<?php
$api_key = 'API KEY';

$ch = curl_init('https://api.voodoosms.com/schedule/45678');

curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: ' . $api_key
]);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "DELETE");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);

curl_close($ch);
require 'rest-client'

url = "https://api.voodoosms.com/schedule/45678"
api_key = "API KEY"

headers = {
    :content_type => :json,
    :Authorization => 'Bearer ' + api_key
}

response = RestClient::Request.execute(
    :method => :delete,
    :url => url,
    :headers => headers
)

puts response

Response

{
  "status": "SUCCESS",
  "msg": "Scheduled SMS ($id) has been cancelled"
}

Error Response

{
  "error": {
    "code": 23,
    "message": "Invalid ID"
  }
}

International

You are able to send SMS to International destinations, but each country has different prices and most countries have rules and regulations around sending SMS.

Please contact your account manager, or speak to us on Live Chat to discuss your International requirements.

HOW TO USE

You must add the country_code parameter to your API call with the country code of the country you wish to send to. Then add the number to the to parameter and your messages will send successfully.

ERRORS

Error Code Error Msg Meaning
14 Cannot send to this country You are trying to send to a country that you do not have enabled.

Response Errors

These errors are universal to all Sending SMS API calls.

Error Code Error Msg Meaning
5 A required parameter is missing One of the required parameters needed is missing.
15 Validity is > 2880 A message can only be valid for a maximum of 48 hours
16 No country code given. Add country code (eg. 44) to beginning of number, or add the country_code param (eg. country_code=44) Your default country code is not set or you have not prefixed the country code to your destination number.
17 No destination number given to field was left blank
18 Invalid characters detected Your message contains invalid characters that are not allowed.
19 Your account has been locked out You may be locked out of your VoodooSMS account for reasons. You cannot use the API while your account is locked. Please contact your Account Manager to discuss your account.
20 This number - 447111111111 - is currently on a blacklist. A number you're trying to send to is on your blacklist.
21 You have no credits You have run out of credits and cannot send any more SMS until you top-up.
22 You do not have enough credits You don't have enogh credits to send to the amount of recipients you've specified. e.g. you have 10 credits and are trying to send to 25 recipients.
23 Invalid ID The scheduled SMS campaign ID is invalid. This is used in conjunction with Scheduling SMS
24 Scheduled date provided is in the past The scheduled SMS date/time you have given is in the past. Times and dates can only be in the future.
25 Message length has exceeded 918 characters The message body cannot exceed 918 characters
26 Invalid Sender ID The Sender ID must be > 3 and <= 11 alphanumeric characters.
27 You have no scheduled messages to be sent You haven't scheduled any SMS to be sent out.
28 Parsed data is invalid The human readable format you chose cannot be parsed correctly.
29 This message has already been sent and cannot be cancelled If a message has already been sent then it can no longer be cancelled.

Retrieving SMS

Inbox

The Retrieve SMS API allows you to get all messages that have been sent to any of your Virtual Mobile Numbers.

REQUEST

Example Code

curl https://api.voodoosms.com/inbox \
  -H "Authorization: Bearer {key}"
<?php
$api_key = 'API KEY';

$ch = curl_init('https://api.voodoosms.com/inbox');

curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: ' . $api_key
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);

curl_close($ch);
require 'rest-client'

url = "https://api.voodoosms.com/inbox"
api_key = "API KEY"

headers = {
    :content_type => :json,
    :Authorization => 'Bearer ' + api_key
}

response = RestClient::Request.execute(
    :method => :get,
    :url => url,
    :headers => headers
)

puts response

Response

{
  "count": 2,
  "unread": 1,
  "message": [
    {
      "id": 46123,
      "from": 447860123858,
      "to": 447857475646,
      "nickname": "Pizza Guy",
      "msg": "Hi, yes I'd like a large pepperoni, please",
      "recievedDateTime": 1538611200,
      "external_reference": "Pizza Order: 333",
      "reply_id": "CL6Rt0ZwDcH5vMU"
    },
    {
      "id": 46134,
      "from": 447860126789,
      "to": 447857475646,
      "nickname": null,
      "msg": "Hi, yes I'd like a small BBQ chicken, please",
      "recievedDateTime": "2018-11-09T12:11:00+00:00",
      "external_reference": "Pizza Order: 688",
      "reply_id": "CL6Rt0ZwDcH5vMU"
    }
  ]
}

Error Response

{
  "error": {
    "code": 30,
    "message": "You have no messages in your inbox"
  }
}

OPTIONAL PROPERTIES

There are no required properties for this API, only optional

Attribute Type Description Default
keyword string Search by keyword used. This would be the first word in the body of the message.
start datetime, string The oldest date of the messages you want to retrieve.

Formats:

UNIX: A UNIX timestamp (e.g. 1537525884)
ISO 8601: A string format including the time and timezone (e.g. 2018-02-22T09:03:00+00:00)
Human Readable: A human readable way to write the date or time you want to sent the message at (e.g. 25th December 2019 21:00, 2 weeks, august 20, may 11 2019, last friday of march 2019, next saturday)
NOW()
end datetime, string The newest date of the messages you want to retrieve.

Formats:

UNIX: A UNIX timestamp (e.g. 1537525884)
ISO 8601: A string format including the time and timezone (e.g. 2018-02-22T09:03:00+00:00)
Human Readable: A human readable way to write the date or time you want to sent the message at (e.g. 25th December 2019 21:00, 2 weeks, august 20, may 11 2019, last friday of march 2019, next saturday)
from int The number the message was sent from
to int The number the message was sent to.
reference string If you used the external_reference parameter in the Send SMS API, then this will show in reference to that message
sort string Sort the response by ID in ASC or DESC order. DESC
skip int Where to start the returned results 0
limit int Where to end the returned results. Limit: 1000 25

ERRORS

Code Message Meaning
30 You have no messages in your inbox Your Inbox is empty

Delete Messages

Delete messages in your Inbox

REQUEST

Example Code

curl -X DELETE https://api.voodoosms.com/inbox/46134 \
  -H "Authorization: Bearer {key}"
<?php
$api_key = 'API KEY';

$ch = curl_init('https://api.voodoosms.com/inbox/46134');

curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: ' . $api_key
]);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "DELETE");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);

curl_close($ch);
require 'rest-client'

url = "https://api.voodoosms.com/inbox/46134"
api_key = "API KEY"

headers = {
    :content_type => :json,
    :Authorization => 'Bearer ' + api_key
}

response = RestClient::Request.execute(
    :method => :delete,
    :url => url,
    :headers => headers
)

puts response

Response

{
  "status": "SUCCESS",
  "msg": "Inbox message ($id) has been removed"
}

Error Response

{
  "error": {
    "code": 36,
    "message": "Invalid ID"
  }
}

Numbers

Retrieve a list of your purchased Virtual Mobile Numbers. If you do not have a VMN, you can purchase one here.

REQUEST

Example Code

curl https://api.voodoosms.com/numbers \
  -H "Authorization: Bearer {key}"
<?php
$api_key = 'API KEY';

$ch = curl_init('https://api.voodoosms.com/numbers');

curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: ' . $api_key
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);

curl_close($ch);
require 'rest-client'

url = "https://api.voodoosms.com/numbers"
api_key = "API KEY"

headers = {
    :content_type => :json,
    :Authorization => 'Bearer ' + api_key
}

response = RestClient::Request.execute(
    :method => :get,
    :url => url,
    :headers => headers
)

puts response

Response

{
  "count": 2,
  "number": [
    {
      "id": 454,
      "number": 447860064555,
      "purchased": 1541603582,
      "nickname": "Homer Simpson",
      "next_payment": 1542813252
    },
    {
      "id": 455,
      "number": 447860064768,
      "purchased": 1541603582,
      "nickname": "Bart Simpson",
      "next_payment": 1493696723
    }
  ]
]

Error Response

{
  "error": {
    "code": 31,
    "message": "You do not own any Virtual Mobile Numbers"
  }
}

 PROPERTIES

There are no required or optional properties for this API.

ERRORS

Code Message Meaning
31 You do not own any Virtual Mobile Numbers You have no VMN's attached to your account.

Keywords

Retrieve a list and manage your Keywords.

Retrieve Keywords

Retrieve a list of keywords assigned to your VMN's.

REQUEST

Example Code

curl https://api.voodoosms.com/keywords \
  -H "Authorization: Bearer {key}"
<?php
$api_key = 'API KEY';

$ch = curl_init('https://api.voodoosms.com/keywords');

curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: ' . $api_key
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);

curl_close($ch);
require 'rest-client'

url = "https://api.voodoosms.com/keywords"
api_key = "API KEY"

headers = {
    :content_type => :json,
    :Authorization => 'Bearer ' + api_key
}

response = RestClient::Request.execute(
    :method => :get,
    :url => url,
    :headers => headers
)

puts response

Response

{
  "count": 1,
  "keywords": [
    {
      "id": 43,
      "keyword": "COLA",
      "assigned_to": 447860064345,
      "description": "The cola campaign to see who likes Cola",
      "created_at": 1523877180,
      "updated_at": 1526481843
    }
  ]
}

Error Response

{
  "error": {
    "code": 32,
    "msg": "You have no Keywords"
  }
}

OPTIONAL PROPERTIES

There are no required properties for this API, only optional

Attribute Type Description
keyword string The keyword you want to search for
assigned_to int A VMN where a keyword is assigned

ERRORS

Code Message Meaning
32 You have no keywords You have no keywords assigned to any of your numbers.
33 Invalid number You do not have access to this chosen number.

Add New Keyword

Create a new keyword and assign it to a number.

REQUEST

Example Code

curl -X POST https://api.voodoosms.com/keywords \
  -H "Authorization: Bearer {key}" \
  -d '{
    "keyword": "BOOK1",
    "assign_to": 447860064596
  }'
<?php
$api_key = 'API KEY';

$msg = json_encode(
    [
        'keyword' => 'BOOK1',
        'assign_to' => 447860064596
    ]
);

$ch = curl_init('https://api.voodoosms.com/keywords');

curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: ' . $api_key
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, $msg);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);

curl_close($ch);
require 'rest-client'

url = "https://api.voodoosms.com/keywords"
api_key = "API KEY"

payload = '{
    "keyword": "BOOK1",
    "assign_to": "447860064596"
}'

headers = {
    :content_type => :json,
    :Authorization => 'Bearer ' + api_key
}

response = RestClient::Request.execute(
    :method => :post,
    :url => url,
    :headers => headers,
    :payload => payload
)

puts response

Response

{
  "id": 47,
  "status": "SUCCESS",
  "keyword": "BOOK1",
  "assigned_to": 447860064596
  }
}

Error Response

{
  "error": {
    "code": 34,
    "msg": "Keyword already assigned to this number"
  }
}

PROPERTIES

Attribute Type Description
keyword string The keyword you want to assign
assign_to int The number you want to assign the keyword to

ERRORS

Code Message Meaning
34 Keyword already assigned to this number The keyword has already been assigned to the VMN.
35 Number not found The VMN chosen is not associated with your account.

Delete Keyword

Delete a keyword from your account

REQUEST

Example Code

curl -X DELETE https://api.voodoosms.com/keywords/47 \
  -H "Authorization: Bearer {key}"
<?php
$api_key = 'API KEY';

$ch = curl_init('https://api.voodoosms.com/keywords/47');

curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: ' . $api_key
]);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "DELETE");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);

curl_close($ch);
require 'rest-client'

url = "https://api.voodoosms.com/keywords/47"
api_key = "API KEY"

headers = {
    :content_type => :json,
    :Authorization => 'Bearer ' + api_key
}

response = RestClient::Request.execute(
    :method => :delete,
    :url => url,
    :headers => headers
)

puts response

Response

{
  "status": "SUCCESS",
  "message": "Keyword "keyword.name" has been deleted"
}

Error Response

{
  "error": {
    "code": 23,
    "msg": "Invalid ID"
  }
}

ERRORS

Code Message Meaning
23 Invalid ID The ID does not match any of your keywords

Delivery Reports

Get the status' of your messages that you have sent out.

OPTIONAL PROPERTIES

Attribute Type Description Default
message_id string The messages.id attribute in the response given after using the Sending SMS API
to int The number you have sent messages to
sent_at datetime,string A date of when a message was sent.

Formats:

UNIX: A UNIX timestamp (e.g. 1537525884)
ISO 8601: A string format including the time and timezone (e.g. 2018-02-22T09:03:00+00:00)
Human Readable: A human readable way to write the date or time you want to sent the message at (e.g. 25th December 2019 21:00, 2 weeks, august 20, may 11 2019, last friday of march 2019, next saturday)
delivered_at datetime,string A date of when a message was delivered.

Formats:

UNIX: A UNIX timestamp (e.g. 1537525884)
ISO 8601: A string format including the time and timezone (e.g. 2018-02-22T09:03:00+00:00)
Human Readable: A human readable way to write the date or time you want to sent the message at (e.g. 25th December 2019 21:00, 2 weeks, august 20, may 11 2019, last friday of march 2019, next saturday)
status string The status of your messages.

Available options:
  • Delivered
  • Sent - Awaiting Delivery
  • Not Delivered
  • Expired
Delivered
limit int Return the number of delivery reports 25

REQUEST

Example Code

curl https://api.voodoosms.com/report \
  -H "Authorization: Bearer {key}"
<?php
$api_key = 'API KEY';

$ch = curl_init('https://api.voodoosms.com/report');

curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: ' . $api_key
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);

curl_close($ch);
require 'rest-client'

url = "https://api.voodoosms.com/report"
api_key = "API KEY"

headers = {
    :content_type => :json,
    :Authorization => 'Bearer ' + api_key
}

response = RestClient::Request.execute(
    :method => :get,
    :url => url,
    :headers => headers
)

puts response

Response

{
  "limit": 25,
  "report" [
    {
      "message_id": "97709216074987x3NFD16GgkChK2E67441209181vapi",
      "to": 447000000000,
      "sent_at": 1542120829,
      "delivered_at": 1542120852,
      "price": 2.9,
      "status": "DELIVERED"
    }
  ]
}

Error Response

{
  "error": {
    "code": 23,
    "msg": "Invalid ID"
  }
}

ERRORS

Code Message Meaning
23 Invalid ID The ID used is invalid or not related to your account

Credits

Get Credits

Retrieve the amount of credits you have on your account.

Example Code

curl https://api.voodoosms.com/credits \
  -H "Authorization: Bearer {key}"
<?php
$api_key = 'API KEY';

$ch = curl_init('https://api.voodoosms.com/credits');

curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: ' . $api_key
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);

curl_close($ch);
require 'rest-client'

url = "https://api.voodoosms.com/credits"
api_key = "INSERT API KEY"

headers = {
    :content_type => :json,
    :Authorization => 'Bearer ' + api_key
}

response = RestClient::Request.execute(
    :method => :get,
    :url => url,
    :headers => headers
)

puts response

Response

{
  "amount": 256
}

Error Response

{
  "error": {
    "code": 21,
    "msg": "You have no credits"
  }
}

Transfer

Transfer credits from your account to one of your sub-accounts.

PROPERTIES

Attribute Type Description
to int The ID of the sub-account. Sub-account must be owned by parent ID
amount int The amount of credits you want to give to the sub-account

REQUEST

Example Code

curl -X POST https://api.voodoosms.com/credits \
  -H "Authorization: Bearer {key}" \
  -d '{
    "to": 59000,
    "amount": 55
  }'
<?php
$api_key = 'API KEY';

$msg = json_encode(
    [
        'to' => 59000,
        'amount' => 55
    ]
);

$ch = curl_init('https://api.voodoosms.com/credits');

curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: ' . $api_key
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, $msg);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);

curl_close($ch);
require 'rest-client'

url = "https://api.voodoosms.com/credits"
api_key = "API KEY"

payload = '{
    "to": "59000",
    "amount": "55"
}'

headers = {
    :content_type => :json,
    :Authorization => 'Bearer ' + api_key
}

response = RestClient::Request.execute(
    :method => :post,
    :url => url,
    :headers => headers,
    :payload => payload
)

puts response

Response

{
  "to": 59000,
  "amount": 55,
  "status": "SUCCESS"
}

Error Response

{
  "error": {
    "code": 38,
    "msg": "The ID you gave does not belong to your account"
  }
}

ERRORS

Code Message Meaning
38 The ID you gave does not belong to your account The ID provided is not listed under your parent account
39 Cannot transfer due to insufficient credit You don't have enough credits in your account to transfer to the sub-account
40 You must provide an amount > 0 You can only transfer an amount of credit that is greater than zero

Contacts

Retrieve your Contact Lists and the contacts within' them.

Add new Contacts into a new or existing list.

Retrieve Contacts

Retrieve your Contact Lists or the Contacts within' the list.

REQUEST

Code Example

curl https://api.voodoosms.com/contacts \
  -H "Authorization: Bearer {key}"
<?php
$api_key = 'API KEY';

$ch = curl_init('https://api.voodoosms.com/contacts');

curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: ' . $api_key
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);

curl_close($ch);
require 'rest-client'

url = "https://api.voodoosms.com/contacts"
api_key = "API KEY"

headers = {
    :content_type => :json,
    :Authorization => 'Bearer ' + api_key
}

response = RestClient::Request.execute(
    :method => :get,
    :url => url,
    :headers => headers
)

puts response

Response

{
  "count": 2,
  "contact_list": [
    {
      "id": 44757,
      "name": "People who like Game of Thrones",
      "status": "ACTIVE",
      "size": 25,
      "created_at": 1545391963,
      "updated_at": 1546784532
    }
  ]
}

Response w/ Contact List ID

{
  "count": 2,
  "contact_list": [
    {
      "id": 44757,
      "name": "People who like Game of Thrones",
      "status": "ACTIVE",
      "size": 25,
      "contacts": [
        {
          "id": 74589987,
          "number": 447000000123,
          "status": "ACTIVE",
          "dynamic_data": [
            {
              "FIRST NAME": "Jon",
              "SURNAME": "Snow",
              "HOUSE": "Stark"
            }
          ],
          "created_at": 1539337532
        },
        {
          "id": 74589988,
          "number": 447000000578,
          "status": "DISABLED",
          "dynamic_data": [
            {
              "FIRST NAME": "Jamie",
              "SURNAME": "Lannister",
              "HOUSE": "Lannister"
            }
          ],
          "created_at": 1535062375
        }
      ],
      "created_at": 1545391963,
      "updated_at": 1546784532
    }
  ]
}

Error Response

{
  "error": {
    "code": 41,
    "msg": "You have no Contact Lists"
  }
}

There are no required properties for this API, only optional

OPTIONAL PARAMETERS

Attribute Type Description Default
contact_list_id int The ID from the contact_list.id response
skip int Where to start the returned results 0
limit int Where to end the returned results. Limit: 5000 1000

ERRORS

Code Message Meaning
23 Invalid ID ID of Contact List does not belong to your account
41 You have no Contact Lists There are no Contact Lists attached to your account
43 Limit is greater than 5000 The limit cannot be greater than 5000

Add Contacts

Create or update Contact Lists

To create a new Contact List, specify a List name that is unique and does not already exist.

REQUEST

Example of a Contacts Object

{
  "contacts": [
    {
      "number": 447897878909,
      "dynamic_data": [
        {
          "First Name": "Homer",
          "Surname": "Simpson"
        }
      ]
    }
  ]
}

Code Example

curl -X POST https://api.voodoosms.com/contacts \
  -H "Authorization: Bearer {key}" \
  -d '{
    "name": "My Contact List",
    "contacts": [
      {
        "number": 447897878909,
        "dynamic_data": [
          {
            "First Name": "Homer",
            "Surname": "Simpson"
          }
        ]
      }
    ]
  }'
<?php
$api_key = 'API KEY';

$msg = json_encode(
  [
    "name" => "My Contact List",
    "contacts" => [
      [
        "number" => 447897878909,
        "dynamic_data" => [
          [
            "First Name" => "Homer",
            "Surname" => "Simpson",
          ],
        ],
      ],
    ],
  ]
);

$ch = curl_init('https://api.voodoosms.com/contacts');

curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: ' . $api_key
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, $msg);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);

curl_close($ch);
require 'rest-client'

url = "https://api.voodoosms.com/contacts"
api_key = "API KEY"

payload = '{
    "name": "MyContactList",
    "contacts": [{
      "number": 447897878909,
      "dynamic_data": [{
        "FirstName": "Homer",
        "Surname": "Simpson"
      }]
    }]
}'

headers = {
    :content_type => :json,
    :Authorization => 'Bearer ' + api_key
}

response = RestClient::Request.execute(
    :method => :post,
    :url => url,
    :headers => headers,
    :payload => payload
)

puts response

Response

{
  "status": "SUCCESS",
  "id": 44758,
  "name": "People who like Rick and Morty",
  "contacts": [
    {
      "count": 2,
      "contact": [
        {
          "id": 1587986,
          "number": 07000000478,
          "dynamic_data": [
            {
              "FIRST NAME": "Rick",
              "SURNAME": "Sanchez"
            }
          ]
        },
        {
          "id": 1897890,
          "number": 07000000567,
          "dynamic_data": [
            {
              "FIRST NAME": "Morty",
              "SURNAME": "Smith"
            }
          ]
        }
      ]
    }
  ],
  "created_at": 1536669912
}

Error Response

{
  "error": {
    "code": 5,
    "msg": "A required parameter is missing"
  }
}

There are both required and optional properties for this API

PROPERTIES

Attribute Type Description
name string The name of your Contact List.
contacts object A Contacts object that shows a number and dynamic data.
See an example on the right

OPTIONAL PROPERTIES

Attribute Type Description Default
description string A description of your Contact List
country int A default country code. If your list will only consist of international numbers, you can specify the country code here 44
dynamic_data json A JSON string of dynamic data you wish to add to the contact.
Notes: Maximum of 7 dynamic fields.

ERRORS

Code Message Meaning
36 Dynamic Data field limit reached You are limited to using upto 7 dynamic fields
37 Invalid Dynamic Data There was a problem processing your dyanmic data
44 Contact List name is too long. Contact List name is too long.
Limit: 32 characters
45 Invalid Country Code The country code you have supplied is invalid

Update Contact List

Update a Contact List by changing the List name or adding new Contacts to the list.

REQUEST

Code Example

curl -X PUT https://api.voodoosms.com/contacts/44758 \
  -H "Authorization: Beader {key}" \
  -d '{
    "contacts": [
      {
        "number": 447897878909,
        "dynamic_data": [
          {
            "First Name": "Marty",
            "Surname": "McFly"
          }
        ]
      }
    ]
  }'
<?php
$api_key = 'API KEY';

$msg = json_encode(
  [
    'contacts' => [
      'number' => 447897878909,
      'dynamic_data' => [
          'First Name' => 'Marty',
          'Surname' => 'McFly'
      ]
    ]
  ]
);

$ch = curl_init('https://api.voodoosms.com/contacts/44758');

curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: ' . $api_key
]);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PUT");
curl_setopt($ch, CURLOPT_POSTFIELDS, $msg);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);

curl_close($ch);
require 'rest-client'

url = "https://api.voodoosms.com/contacts/44758"
api_key = "API KEY"

headers = {
    :content_type => :json,
    :Authorization => 'Bearer ' + api_key
}

payload = '{
    "contacts": [
      {
        "number": 447897878909
        "dynamic_data": [
          {
            "First Name": "Marty",
            "Surname": "McFly"
          }
        ]
      }
    ]
}'

response = RestClient::Request.execute(
    :method => :put,
    :url => url,
    :headers => headers,
    :payload => payload
)

puts response

Response

{
  "status": "SUCCESS",
  "total": 177,
  "summary": {
    "valid": {
      "count": 123,
      "numbers": [447000000123, 447000000432]
    },
    "rejected": {
      "count": 54,
      "numbers": [447000000567, 447000000654]
    }
  }
}

Error Response

{
  "error": {
    "code": 44,
    "msg": "Contact List name is too long."
  }
}

There are no required properties for this API, only optional

OPTIONAL PROPERTIES

Attribute Type Description
name string The name of your Contact List.
Limit: 32 characters
contacts object A Contacts object that shows a number and dynamic data.
Example

ERRORS

Code Message Meaning
23 Invalid ID Contact List ID is invalid. Does not belong to your account
44 Contact List name is too long. Contact List name is too long.
Limit: 32 characters
48 Contact List is not dynamic Your Contact List was not created as Dynamic and you cannot update a non-Dynamic list with Dynamic Data

Delete Contacts

Example Code

curl -X DELETE https://api.voodoosms.com/contacts \
  -H "Authorization: Beader {key}"
<?php
$api_key = 'API KEY';

$ch = curl_init('https://api.voodoosms.com/contacts/44757');

curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: ' . $api_key
]);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "DELETE");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);

curl_close($ch);
require 'rest-client'

url = "https://api.voodoosms.com/contacts/44757"
api_key = "API KEY"

headers = {
    :content_type => :json,
    :Authorization => 'Bearer ' + api_key
}

response = RestClient::Request.execute(
    :method => :delete,
    :url => url,
    :headers => headers
)

puts response

Response

{
  "status": "SUCCESS",
  "message": "Contact list has been removed"
}

Error Response

{
  "error": {
    "code": 23,
    "msg": "Invalid ID"
  }
}

Delete a Contact List by providing the ID of the list.

Delete a specific Contact from within a specified Contact List

ERRORS

Code Message Meaning
23 Invalid ID The ID does not match any either a Contact List or a Contact ID

Blacklists

Retrieve Blacklist

Retrieve a list of contacts that are Blacklisted

REQUEST

Example Code

curl https://api.voodoosms.com/blacklist \
  -H "Authorization: Bearer {key}"
<?php
$api_key = 'API KEY';

$query = http_build_query([
  "number" => 447800000987
]);

$ch = curl_init('https://api.voodoosms.com/blacklist?' . $query);

curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: ' . $api_key
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);

curl_close($ch);
require 'rest-client'
require 'uri'

query = URI.encode_www_form({
  number: 447800000987
})

url = "https://api.voodoosms.com/blacklist?" + query
api_key = "API KEY"

headers = {
    :content_type => :json,
    :Authorization => 'Bearer ' + api_key
}

response = RestClient::Request.execute(
    :method => :get,
    :url => url,
    :headers => headers
)

puts response

Response

{
  "count": 567,
  "blacklist": {
    "id": 2624,
    "blacklisted_numbers": {
      "id": 467787,
      "number": 447000000678,
      "created_at": 1542811725
    }
  }
}

Error Response

{
  "error": {
    "code": 33,
    "msg": "Invalid number"
  }
}

There are no required properties for this API, only optional

OPTIONAL PROPERTIES

Attribute Type Description Default
number int Fetch a single blacklisted number
start datetime, string The oldest date of the blacklisted numbers added you want to retrieve.

Formats:

UNIX: A UNIX timestamp (e.g. 1537525884)
ISO 8601: A string format including the time and timezone (e.g. 2018-02-22T09:03:00+00:00)
Human Readable: A human readable way to write the date or time you want to sent the message at (e.g. 25th December 2019 21:00, 2 weeks, august 20, may 11 2019, last friday of march 2019, next saturday)
NOW()
end datetime, string The newest date of the blacklisted numbers added you want to retrieve.

Formats:

UNIX: A UNIX timestamp (e.g. 1537525884)
ISO 8601: A string format including the time and timezone (e.g. 2018-02-22T09:03:00+00:00)
Human Readable: A human readable way to write the date or time you want to sent the message at (e.g. 25th December 2019 21:00, 2 weeks, august 20, may 11 2019, last friday of march 2019, next saturday)
sort string Sort the response by ID in ASC or DESC order. DESC
skip int Where to start the returned results 0
limit int Where to end the returned results. Limit: 1000 25

ERRORS

Code Message Meaning
33 Invalid number This number is not in your blacklist
51 Blacklist is empty Your Blacklist contains no contacts

Add to Blacklist

Add a contact to your Blacklist

REQUEST

Example Code

curl -X POST https://api.voodoosms.com/blacklist \
  -H "Authorization: Bearer {key}" \
  -d '{
    "number": 447800000987
  }'
<?php
$api_key = 'API KEY';

$msg = json_encode(
  [
    "number" => 447800000987
  ]
);

$ch = curl_init('https://api.voodoosms.com/blacklist');

curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: ' . $api_key
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, $msg);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);

curl_close($ch);
require 'rest-client'

url = "https://api.voodoosms.com/blacklist"
api_key = "API KEY"

payload = '{
  "number": "447800000987"
}'

headers = {
    :content_type => :json,
    :Authorization => 'Bearer ' + api_key
}

response = RestClient::Request.execute(
    :method => :post,
    :url => url,
    :headers => headers,
    :payload => payload
)

puts response

Response

{
  "id": 467787,
  "number": 447800000987,
  "status": "SUCCESS",
  "created_at": 1542811725
}

Error Response

{
  "error": {
    "code": 33,
    "msg": "Invalid number"
  }
}

There are no optional properties for this API, only required

PROPERTIES

Attribute Type Description
number int The number you want to Blacklist

ERRORS

Code Message Meaning
33 Invalid number This must be a number
53 Number already in Blacklist Number is already present in the Blacklist

Edit Blacklist

Edit a contact from the Blacklist

REQUEST

Code Examples

curl -X PUT https://api.voodoosms.com/blacklist \
  -H "Authorization: Bearer {key}"
  -d '{
    "old_number": 447000000547,
    "new_number": 447000000367
  }'
<?php
$api_key = 'API KEY';

$msg = json_encode(
  [
    'old_number' => 447000000547,
    'new_number' => 447000000367
  ]
);

$ch = curl_init('https://api.voodoosms.com/blacklist');

curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: ' . $api_key
]);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PUT");
curl_setopt($ch, CURLOPT_POSTFIELDS, $msg);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);

curl_close($ch);
require 'rest-client'

url = "https://api.voodoosms.com/blacklist"
api_key = "API KEY"

headers = {
    :content_type => :json,
    :Authorization => 'Bearer ' + api_key
}

payload = '{
  "old_number": "447000000547",
  "new_number": "447000000367"
}'

response = RestClient::Request.execute(
    :method => :put,
    :url => url,
    :headers => headers,
    :payload => payload
)

puts response

Response

{
  "status": "SUCCESS",
  "old_number": 447800000987,
  "new_number": 447000000547
}

Error Response

{
  "error": {
    "code": 33,
    "msg": "Invalid number"
  }
}

There are no optional properties for this API, only required

PROPERTIES

Attribute Type Description
old_number int The number you're changing
new_number int The number you're amending it to

ERRORS

Code Message Meaning
33 Invalid number This must be a number

Delete from Blacklist

Delete a contact from the Blacklist

Example Code

curl -X DELETE https://api.voodoosms.com/blacklist/467787 \
  -H "Authorization: Beader {key}"
<?php
$api_key = 'API KEY';

$ch = curl_init('https://api.voodoosms.com/blacklist/467787');

curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: ' . $api_key
]);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "DELETE");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);

curl_close($ch);
require 'rest-client'

url = "https://api.voodoosms.com/blacklist/467787"
api_key = "API KEY"

headers = {
    :content_type => :json,
    :Authorization => 'Bearer ' + api_key
}

response = RestClient::Request.execute(
    :method => :delete,
    :url => url,
    :headers => headers
)

puts response

Response

{
  "status": "SUCCESS",
  "message": "Number has been removed from the Blacklist"
}

Error Response

{
  "error": {
    "code": 23,
    "msg": "Invalid ID"
  }
}

ERRORS

Code Message Meaning
23 Invalid ID The ID does not belong to a contact in your Blacklist

Short URL

Retrieve Short URL

Retrieve all the Short URL's you have created.

REQUEST

Code Example

curl https://api.voodoosms.com/shorturl \
  -H "Authorization: Bearer {key}"
<?php
$api_key = 'API KEY';

$ch = curl_init('https://api.voodoosms.com/shorturl');

curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: ' . $api_key
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);

curl_close($ch);
require 'rest-client'

url = "https://api.voodoosms.com/shorturl"
api_key = "API KEY"

headers = {
    :content_type => :json,
    :Authorization => 'Bearer ' + api_key
}

response = RestClient::Request.execute(
    :method => :get,
    :url => url,
    :headers => headers
)

puts response

Response

{
  "count": 1,
  "url": {
    "id": 5123,
    "name": "Pizza Shop",
    "link": "http://vsms.co/5hG",
    "destination": "https://website.pizza",
    "method": "simple",
    "websms_name": "My SMS Campaign",
    "clicks" {
      "total": 23,
      "last_click": 1546378474,
      "last_used": 1546378474
    },
    "created_at": 1547587700,
    "updated_at": 1534865678
  }
}

Error Response

{
  "error": {
    "code": 56,
    "msg": "No Short URL's created"
  }
}

There are no required properties for this API, only optional

OPTIONAL PROPERTIES

Attribute Type Description Default
method string The type of Short URL created. Must be either simple or tracked both
start datetime, string The oldest date of Short URL's created that you want to retrieve.

Formats:

UNIX: A UNIX timestamp (e.g. 1537525884)
ISO 8601: A string format including the time and timezone (e.g. 2018-02-22T09:03:00+00:00)
Human Readable: A human readable way to write the date or time you want to sent the message at (e.g. 25th December 2019 21:00, 2 weeks, august 20, may 11 2019, last friday of march 2019, next saturday)
NOW()
end datetime, string The newest date of Short URL's created that you want to retrieve.

Formats:

UNIX: A UNIX timestamp (e.g. 1537525884)
ISO 8601: A string format including the time and timezone (e.g. 2018-02-22T09:03:00+00:00)
Human Readable: A human readable way to write the date or time you want to sent the message at (e.g. 25th December 2019 21:00, 2 weeks, august 20, may 11 2019, last friday of march 2019, next saturday)
sort string Sort the response by ID in ASC or DESC order. DESC
skip int Where to start the returned results 0
limit int Where to end the returned results. Limit: 1000 25

ERRORS

Code Message Meaning
56 No Short URL's created You have no Short URL's attached to your account
57 Invalid method Method invalid. Allowed methods: simple, tracked

Create Short URL

Create a new Short URL

REQUEST

Code Example

curl -X POST https://api.voodoosms.com/shorturl \
  -H "Authorization: Bearer {key}" \
  -d '{
    "name": "Pizza Shop",
    "url": "https://pizzashop.com",
    "method": "tracked"
  }'
<?php
$api_key = 'API KEY';

$msg = json_encode(
  [
    "name" => "Pizza Shop",
    "url" => "https://pizzashop.com",
    "method" => "tracked"
  ]
);

$ch = curl_init('https://api.voodoosms.com/shorturl');

curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: ' . $api_key
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, $msg);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);

curl_close($ch);
require 'rest-client'

url = "https://api.voodoosms.com/shorturl"
api_key = "API KEY"

payload = '{
    "name": "Pizza Shop",
    "url": "https://pizzashop.com",
    "method": "tracked"
}'

headers = {
    :content_type => :json,
    :Authorization => 'Bearer ' + api_key
}

response = RestClient::Request.execute(
    :method => :post,
    :url => url,
    :headers => headers,
    :payload => payload
)

puts response

Response

{
  "id": 2354,
  "status": "SUCCESS",
  "data": {
    "name": "Pizza Shop",
    "url": "https://pizzashop.com",
    "method": "tracked",
    "short_url": "http://vsms.co/5hG"
  },
  "created_at": 1547683200
}

Error Response

{
  "error": {
    "code": 59,
    "msg": "Invalid URL"
  }
}

There are no optional properties for this API, only required

PROPERTIES

Attribute Type Description Default
name string A name to recognise the Short URL
url string The URL you want to redirect to
method string The type of Short URL. Accepted values: simple or tracked

ERRORS

Code Message Meaning
57 Invalid method The method chosen is invalid. Accepted values: simple, tracked
58 Invalid name The name must only be alphanumeric and not exceed 32 characters
59 Invalid URL Not a valid URL. Must start with http or https or the URL check failed.
61 Short URL creation has failed Creating the Short URL has failed. Contact your account manager

Update a Short URL

Update Short URL's name or URL.

REQUEST

Code Example

curl -X PUT https://api.voodoosms.com/shorturl/2354 \
  -H "Authorization: Bearer {key}"
  -d '{
    "name": "Burger Shop",
    "url": "https://burger-shop.com"
  }'
<?php
$api_key = 'API KEY';

$msg = json_encode(
  [
    'name' => 'Burger Shop',
    'url' => 'https://burger-shop.com'
  ]
);

$ch = curl_init('https://api.voodoosms.com/shorturl/2354');

curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: ' . $api_key
]);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PUT");
curl_setopt($ch, CURLOPT_POSTFIELDS, $msg);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);

curl_close($ch);
require 'rest-client'

url = "https://api.voodoosms.com/shorturl/2354"
api_key = "API KEY"

headers = {
    :content_type => :json,
    :Authorization => 'Bearer ' + api_key
}

payload = '{
    "name": "Burger Shop",
    "url": "https://burger-shop.com"
}'

response = RestClient::Request.execute(
    :method => :put,
    :url => url,
    :headers => headers,
    :payload => payload
)

puts response

Response

{
  "status": "SUCCESS",
  "name": "Burger Shop",
  "url": "https://burger-shop.com",
  "short_url": "http://vsms.co/5hG"
}

Error Response

{
  "error": {
    "code": 58,
    "msg": "Invalid name"
  }
}

There are no optional properties for this API, only required

PROPERTIES

Attribute Type Description
name string The name of the Short URL
url string The URL the Short URL redirects to. Must start with http or https

ERRORS

Code Message Meaning
23 Invalid ID This Short URL does not belong to your account
58 Invalid name The name must only be alphanumeric
59 Invalid URL Not a valid URL. Must start with http or https or the URL check failed.

Delete Short URL

Delete a Short URL

Code Example

curl -X DELETE https://api.voodoosms.com/shorturl/2354 \
  -H "Authorization: Beader {key}"
<?php
$api_key = 'API KEY';

$ch = curl_init('https://api.voodoosms.com/shorturl/2354');

curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: ' . $api_key
]);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "DELETE");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);

curl_close($ch);
require 'rest-client'

url = "https://api.voodoosms.com/shorturl/2354"
api_key = "API KEY"

headers = {
    :content_type => :json,
    :Authorization => 'Bearer ' + api_key
}

response = RestClient::Request.execute(
    :method => :delete,
    :url => url,
    :headers => headers
)

puts response

Response

{
  "status": "SUCCESS",
  "message": "Short URL has been deleted"
}

Error Response

{
  "error": {
    "code": 23,
    "msg": "Invalid ID"
  }
}

ERRORS

Code Message Meaning
23 Invalid ID The ID does not match to any of your Short URL

Sub-Accounts

Manage your Sub-Accounts.

Retrieve Sub-Accounts

Retrieve the Sub-Accounts attached to your account.

REQUEST

Code Example

curl https://api.voodoosms.com/subaccounts \
  -H "Authorization: Bearer {key}"
<?php
$api_key = 'API KEY';

$ch = curl_init('https://api.voodoosms.com/subaccounts');

curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: ' . $api_key
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);

curl_close($ch);
require 'rest-client'

url = "https://api.voodoosms.com/subaccounts"
api_key = "API KEY"

headers = {
    :content_type => :json,
    :Authorization => 'Bearer ' + api_key
}

response = RestClient::Request.execute(
    :method => :get,
    :url => url,
    :headers => headers
)

puts response

Response

{
  "count": 1,
  "subaccounts": {
    {
      "account": [
        "id": 90546,
        "username": "my_sub_account",
        "email": "jon.snow@acme.com",
        "name": "Jon Snow",
        "company": "Acme Ltd",
        "balance": 2001,
        "status": "Active",
        "children": [
          {
            "id": 929767,
            "username": "my_sub-sub_account",
            "email": "jamie.lannister@acme.com",
            "name": "Jamie Lannister",
            "company": "Some Company Ltd",
            "balance": 1324,
            "status": "Active",
            "children": [],
            "created_at": 1548113852
          }
        ],
        "created_at": 1548115200
      ]
    }
  }
}

Error Response

{
  "error": {
    "code": 67,
    "msg": "Invalid status"
  }
}

There are no required properties for this API, only optional

OPTIONAL PROPERTIES

Attribute Type Description Default
status string The status of the sub-account. Available options:
Active, Locked, Closed
skip int Where to start the returned results 0
limit int Where to end the returned results. Limit: 1000 25

ERRORS

Code Message Meaning
10 Limit is greater than 1000 The limit property cannot be greater than 1000
59 Cannot find any sub-accounts There are no sub-accounts attached to your account
60 Invalid status The status you have added is not valid. Available options:
Active, Locked, Closed

Create Sub-Account

Create a new Sub-Account

REQUEST

Code Example

curl -X POST https://api.voodoosms.com/subaccounts \
  -H "Authorization: Bearer {key}" \
  -d '{
    "username": "MySubAccount",
    "firstname": "Jon",
    "surname": "Snow",
    "number": "447890000000",
    "email": "jon.snow@gameofthrones.net",
    "company": "Acme Ltd",
    "give_credits": 255,
    "reference": "GOT Fan Club Member"
  }'
<?php
$api_key = 'API KEY';

$msg = json_encode(
  [
     "username" => "MySubAccount",
     "firstname" => "Jon",
     "surname" => "Snow",
     "number" => "447890000000",
     "email" => "jon.snow@gameofthrones.net",
     "company" => "Acme Ltd",
     "give_credits" => 255,
     "reference" => "GOT Fan Club Member",
  ]
);

$ch = curl_init('https://api.voodoosms.com/subaccounts');

curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: ' . $api_key
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, $msg);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);

curl_close($ch);
require 'rest-client'

url = "https://api.voodoosms.com/subaccounts"
api_key = "API KEY"

payload = '{
    "username": "MySubAccount",
    "firstname": "Jon",
    "surname": "Snow",
    "number": "447890000000",
    "email": "jon.snow@gameofthrones.net",
    "company": "Acme Ltd",
    "give_credits": 255,
    "reference": "GOT Fan Club Member"
}'

headers = {
    :content_type => :json,
    :Authorization => 'Bearer ' + api_key
}

response = RestClient::Request.execute(
    :method => :post,
    :url => url,
    :headers => headers,
    :payload => payload
)

puts response

Response

{
  "id": 59444,
  "status": "SUCCESS",
  "data": {
    "username": "MySubAccount",
    "firstname": "Jon",
    "surname": "Snow",
    "number", "447890000000",
    "email": "jon.snow@gameofthrones.net",
    "give_credits": 255,
    "reference": "GOT Fan Club Member"
  },
  "created_at": 1547683200
}

Error Response

{
  "error": {
    "code": 70,
    "msg": "Username in use"
  }
}

There are both required and optional properties for this API

PROPERTIES

Attribute Type Description Default
username string The username of the account
firstname string The users First Name
surname string The users Surname
number int A valid mobile number
email string A valid email address
company string The company of the sub-account
give_credits int The amount of credits to give from your credit pool

OPTIONAL PROPERTIES

Attribute Type Description Default
reference string A reference related to the user you're creating

ERRORS

Code Message Meaning
33 Invalid number The given mobile number is not valid
69 Invalid email The given email address is invalid
70 Username in use The chosen username is already taken
71 Not enough credits You do not have enough credits to allocate the amount specified
72 You must have Reseller permissions to use this method You must have Reseller permissions. Contact your account manager

Delete Sub-Account

Delete a Sub-Account

REQUEST

Code Example

curl -X DELETE https://api.voodoosms.com/subaccounts/90546 \
  -H "Authorization: Beader {key}"
<?php
$api_key = 'API KEY';

$ch = curl_init('https://api.voodoosms.com/subaccounts/90546');

curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: ' . $api_key
]);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "DELETE");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);

curl_close($ch);
require 'rest-client'

url = "https://api.voodoosms.com/subaccounts/90546"
api_key = "API KEY"

headers = {
    :content_type => :json,
    :Authorization => 'Bearer ' + api_key
}

response = RestClient::Request.execute(
    :method => :delete,
    :url => url,
    :headers => headers
)

puts response

Response

{
  "status": "SUCCESS",
  "message": "Sub-Account has been deleted"
}

Error Response

{
  "error": {
    "code": 23,
    "msg": "Invalid ID"
  }
}

ERRORS

Code Message Meaning
23 Invalid ID The ID does not match to any of your Sub-Accounts
42 Sub-Account is already deleted Sub-Account does not exist

Manage

Manage your sub-accounts.

Suspend Sub-Account

Suspend a Sub-Account, preventing the user from accessing the account.

REQUEST

Code Example

curl -X DELETE https://api.voodoosms.com/subaccounts/suspend/90546 \
  -H "Authorization: Beader {key}"
<?php
$api_key = 'API KEY';

$ch = curl_init('https://api.voodoosms.com/subaccounts/suspend/90546');

curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: ' . $api_key
]);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "DELETE");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);

curl_close($ch);
require 'rest-client'

url = "https://api.voodoosms.com/subaccounts/suspend/90546"
api_key = "API KEY"

headers = {
    :content_type => :json,
    :Authorization => 'Bearer ' + api_key
}

response = RestClient::Request.execute(
    :method => :delete,
    :url => url,
    :headers => headers
)

puts response

Response

{
  "status": "SUCCESS",
  "message": "Sub-Account has been suspended"
}

Error Response

{
  "error": {
    "code": 73,
    "msg": "Sub-Account is already suspended"
  }
}

ERRORS

Code Message Meaning
73 Sub-Account is already suspended The Sub-Account is already suspended and cannot be re-suspended

Unsuspend Sub-Account

Unsuspend a Sub-Account, allowing a user back into the account.

REQUEST

Code Example

curl -X DELETE https://api.voodoosms.com/subaccounts/unsuspend/90546 \
  -H "Authorization: Beader {key}"
<?php
$api_key = 'API KEY';

$ch = curl_init('https://api.voodoosms.com/subaccounts/unsuspend/90546');

curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: ' . $api_key
]);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "DELETE");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);

curl_close($ch);
require 'rest-client'

url = "https://api.voodoosms.com/subaccounts/unsuspend/90546"
api_key = "API KEY"

headers = {
    :content_type => :json,
    :Authorization => 'Bearer ' + api_key
}

response = RestClient::Request.execute(
    :method => :delete,
    :url => url,
    :headers => headers
)

puts response

Response

{
  "status": "SUCCESS",
  "message": "Sub-Account has been unsuspended"
}

Error Response

{
  "error": {
    "code": 46,
    "msg": "Sub-Account is not suspended"
  }
}

ERRORS

Code Message Meaning
46 Sub-Account is not suspended The Sub-Account not suspended so cannot be un-suspended

GDPR

These API's allow you to use the features that we built to allow us to comply with the GDPR regulations.

Forget

We offer an API that can be used to forget your data on our platform. You can also track the status of your requests.

Forget Request

When you request for your data to be forgotten it will be instantly added to your Blacklist. This means no further SMS will be sent to the destination numbers provided.

Within' 24 hours off the request been submitted our system will go through your Contact Lists, Sent SMS, Received SMS, Blacklist and remove this data. Any numbers or an SMS body printed will be masked so it does not show the full number or message.

Once the process has completed the destination numbers will no longer be stored on our system.

REQUEST

curl -X POST https://api.voodoosms.com/gdpr/forget \
  -H "Authorization: Bearer {key}" \
  -d '{
    "number": 447000000123
  }'
<?php
$api_key = 'API KEY';

$msg = json_encode(
  [
     "number" => 447000000123
  ]
);

$ch = curl_init('https://api.voodoosms.com/gdpr/forget');

curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: ' . $api_key
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, $msg);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);

curl_close($ch);
require 'rest-client'

url = "https://api.voodoosms.com/gdpr/forget"
api_key = "API KEY"

payload = '{
    "number": 447000000123
}'

headers = {
    :content_type => :json,
    :Authorization => 'Bearer ' + api_key
}

response = RestClient::Request.execute(
    :method => :post,
    :url => url,
    :headers => headers,
    :payload => payload
)

puts response

Response

{
  "status": "SUCCESS",
  "msg": "Your request has been accepted",
  "reference": "BWwmkoxO3YTfpEt",
  "created_at": 1548892800
}

Error Response

{
  "error": {
    "code": 76,
    "msg": "Cannot use this number"
  }
}

There are both required and optional properties for this API

REQUIRED PARAMETERS

Attribute Type Description Default
number int The number you want to be forgotten. The format of the number must begin with 44

OPTIONAL PARAMETERS

Attribute Type Description Default
blacklist boolean Specify if you want to keep or remove a number in the Blacklist
  • true - Number is removed from the Blacklist
  • false - Number is left in the Blacklist

ERRORS

Code Message Meaning
76 Cannot use this number You have no affiliation with this number

Request Status

If you have requested your data to be removed, you can check the status of your request as it can take up to 24 hours from making the original request

REQUEST

Code Example

curl -X POST https://api.voodoosms.com/gdpr/status \
  -H "Authorization: Bearer {key}" \
  -d '{
    "date": "yesterday"
  }'
<?php
$api_key = 'API KEY';

$msg = json_encode(
  [
     "date" => "yesterday"
  ]
);

$ch = curl_init('https://api.voodoosms.com/gdpr/status');

curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: ' . $api_key
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, $msg);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);

curl_close($ch);
require 'rest-client'

url = "https://api.voodoosms.com/gdpr/status"
api_key = "API KEY"

payload = '{
    "date": "yesterday"
}'

headers = {
    :content_type => :json,
    :Authorization => 'Bearer ' + api_key
}

response = RestClient::Request.execute(
    :method => :post,
    :url => url,
    :headers => headers,
    :payload => payload
)

puts response

Response

{
  "status": "SUCCESS",
  "msg": "Your request has been accepted and is pending removal",
  "reference": "BWwmkoxO3YTfpEt",
  "created_at": 1548892800
}

// or

{
  "status": "SUCCESS",
  "msg": "The number has been removed",
  "reference": "BWwmkoxO3YTfpEt",
  "created_at": 1548892800
}

Error Response

{
  "error": {
    "code": 77,
    "msg": "No records found"
  }
}

There are both required and optional properties for this API

REQUIRED PARAMETERS

Attribute Type Description Default
date datetime, string The date you submitted your removal request.

Formats:

UNIX: A UNIX timestamp (e.g. 1537525884)
ISO 8601: A string format including the time and timezone (e.g. 2018-02-22T09:03:00+00:00)
Human Readable: A human readable way to write the date or time you want to sent the message at (e.g. 25th December 2019 21:00, 2 weeks, august 20, may 11 2019, last friday of march 2019, next saturday)

OPTIONAL PARAMETERS

Attribute Type Description Default
reference string The reference given to you when you made your request

ERRORS

Code Message Meaning
77 No records found No requests have been made.
78 Request failed The request failed. Please contact your Account Manager

Error Codes

These are universal errors that can be seen throughout the API.

Code Error Msg Meaning
1 No API Key provided, or Key is invalid The API key does not exist or has an error in it
2 This API Key has been removed or disabled The API has been removed or disabled from the account
3 You cannot use this method with your permissions Trying to run a POST method, but permissions are not set to Read-write
4 Wrong request method used You have used the wrong request method. e.g. Used GET but expected POST
5 A required parameter is missing One of the required parameters needed is missing.
6 Request method does not exist The requested URL method does not exist