Spring Offer

50% Free

* Terms & conditions apply

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

GET /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: is 1000. 25
Example Code

cURL

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

PHP

<?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);
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-to-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-to-id": "CL6Rt0ZwDcH5vMU"
    }
  ]
}

Errors

Code Message Meaning
30 You have no messages in your inbox Your Inbox is empty.
Error Response
{
  "error": {
    "code": 30,
    "msg": "You have no messages in your inbox"
  }
}

Delete Messages

Allows you to delete messages in your Inbox by using unique ID.

Request

DELETE /inbox/:id
Example Code

cURL

curl -X DELETE https://api.voodoosms.com/inbox/46134 \
  -H "Authorization: Bearer {key}"

PHP

<?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);
Response
{
  "status": "SUCCESS",
  "msg": "Inbox message ($id) has been removed"
}
Error Response
{
  "error": {
    "code": 36,
    "msg": "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

GET /numbers
Example Code

cURL

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

PHP

<?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);
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
    }
  ]
]

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.
Error Response
{
  "error": {
    "code": 31,
    "msg": "You do not own any Virtual Mobile Numbers"
  }
}

Keywords

Our API allows you to create, retrieve and manage your Keywords.

Retrieve Keywords

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

Request

GET /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.
Example Code

cURL

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

PHP

<?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);
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"
  }
}

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

POST /keywords

Properties

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

cURL

curl -X POST https://api.voodoosms.com/keywords \
  -H "Authorization: Bearer {key}" \
  -d '{
    "keyword": "BOOK1",
    "assign_to": 447860064596
  }'

PHP

<?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);
Response
{
  "id": 47,
  "status": "SUCCESS",
  "keyword": "BOOK1",
  "assigned_to": 447860064596
  }
}

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.
Error Response
{
  "error": {
    "code": 34,
    "msg": "Keyword already assigned to this number"
  }
}

Delete Keyword

Delete a keyword from your account by using unique ID.

Request

DELETE /keywords/:id
Example Code

cURL

curl -X DELETE https://api.voodoosms.com/keywords/47 \
  -H "Authorization: Bearer {key}"

PHP

<?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);
Response
{
  "status": "SUCCESS",
  "message": "Keyword "keyword.name" has been deleted"
}

Errors

Code Message Meaning
23 Invalid ID The ID does not match any of your keywords.
Error Response
{
  "error": {
    "code": 23,
    "msg": "Invalid ID"
  }
}