Winter Offer

50% Free

* Terms & conditions apply

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

GET /contacts

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
Code Example

cURL

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

PHP

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

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
Error Response
{
  "error": {
    "code": 41,
    "msg": "You have no Contact Lists"
  }
}

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

POST /contacts

Properties

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

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.
Example of a Contacts Object
{
  "contacts": [
    {
      "number": 447897878909,
      "dynamic_data": [
        {
          "First Name": "Homer",
          "Surname": "Simpson"
        }
      ]
    }
  ]
}
Code Example

cURL

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

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

There are both required and optional properties for this API

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
Error Response
{
  "error": {
    "code": 5,
    "msg": "A required parameter is missing"
  }
}

Update Contact List

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

Request

PUT /contacts/:contact_list_id
Code Example

cURL

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

<?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);
Response
{
  "status": "SUCCESS",
  "total": 177,
  "summary": {
    "valid": {
      "count": 123,
      "numbers": [447000000123, 447000000432]
    },
    "rejected": {
      "count": 54,
      "numbers": [447000000567, 447000000654]
    }
  }
}

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.
Error Response
{
  "error": {
    "code": 44,
    "msg": "Contact List name is too long."
  }
}

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

DELETE /contacts/:contact_list_id

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

DELETE /contacts/:contact_list_id/:contact_id

Delete a specific Contact from within a specified Contact List

Example Code

cURL

curl -X DELETE https://api.voodoosms.com/contacts \
  -H "Authorization: Beader {key}"

PHP

<?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);
Response
{
  "status": "SUCCESS",
  "message": "Contact list has been removed"
}

Errors

Code Message Meaning
23 Invalid ID The ID does not match any either a Contact List or a Contact ID
Error Response
{
  "error": {
    "code": 23,
    "msg": "Invalid ID"
  }
}