Retailer magic: SMS strategies for Winter | On Demand Sign up for our webinar
API call which allows you to create or retrieve existing Contact List(s), as well add new contacts to an existing one.
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"
}
}
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"
}
}