Summer Offer

50% Free

* Terms & conditions apply

Contacts

API call which allows you to create or retrieve existing Contact List(s), as well add new contacts to an existing one.

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"
  }
}

Create Contact List

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"
  }
}