Retrieve your Contact Lists and the contacts within’ them.
Add new Contacts into a new or existing list.
Retrieve your Contact Lists or the Contacts within’ the list.
/contacts
There are no required
properties for this API, only optional
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
}
]
}
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 or update Contact Lists
To create a new Contact List, specify a List name that is unique and does not already exist.
/contacts
Attribute | Type | Description |
---|---|---|
name | string | The name of your Contact List. |
contacts | object | A Contacts object that shows a number and dynamic data. |
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
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 a Contact List by changing the List name or adding new Contacts to the list.
/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
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."
}
}
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 |
/contacts/:contact_list_id
Delete a Contact List by providing the ID of the list.
/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"
}
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"
}
}