Blocklist API

Overview

The Blocklist API provides programmatic access to the following functionality:

  • Numbers: Pull the list of IVR phone numbers.

  • Upload: Block ANIs for a set of IVR phone numbers

  • History: Pull the history of uploads in your account

Base URL

The base url for all requests should be made to: https://blocklist.plumvoice.com/api

Authentication

All API requests are authenticated using HTTP Basic Authentication. The username value will be the email address users use to log in to their Blocklist account and the password will be their Developer Key, located within the Account interface.

Depending on the HTTP libraries available in one's chosen programming language, users may be able to use built-in HTTP Basic Authentication. If this is not available, users can build the header manually by base64 encoding their username and developer key concatenated with a colon and then prefixing it with 'Basic'. Manually built HTTP Basic Authentication in this instance should look like: "Authentication: Basic your_base64_encoded_string"

Any requests made without this header or with invalid credentials will return HTTP 401 Unauthorized.

get
List of Numbers

https://blocklist.plumvoice.com/api/numbers
This allows you to pull the list of numbers that already exist in your Blocklist profile.
Request
Response
Request
Headers
Accept
optional
string
application/json
Content-Type
optional
string
application/json
Query Parameters
details
required
boolean
Return the specific details for each number pulled.
Response
200: OK
Code Sample 1
Code Sample 2
Code Sample 1
{
"success": true,
"data": [
"6177123000",
"6177123001",
"6177123002",
"6177123003",
"6177123004"
]
}
Code Sample 2
{
"success": true,
"data": [
{
"6177123000": "31"
},
{
"6177123001": "31"
},
{
"6177123002": "2"
},
{
"6177123003": "2"
},
{
"6177123004": "31"
}
]
}
401: Unauthorized
{
"success": false,
"error": "Missing required JSON parameter: details"
}

Return Structure

Name

Data Type

Always Present

Description

success

boolean

yes

Indicates the outcome of the request

error

string

no

If the success value is false this provides a message indicating what occurred

data

JSON string

no

If the success value is true this provides a JSON-encoded array containing the numbers. If the details parameter was true, it will be objects containing the DNIS and number of blocked ANI. Otherwise, it will be strings containing the DNIS

Sample Code

Sample 1 of the following PHP code makes a request to this method without pulling the details. Sample 2 makes a request while pulling the details.

Sample 1
Sample 2
Sample 1
$url = 'https://blocklist.plumvoice.com/api/numbers';
$username = 'you@yourdomain.com';
$password = 'your_developer_key';
$post = json_encode(array('details'=>false));
$ch = curl_init();
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($ch, CURLOPT_USERPWD, $username.":".$password);
curl_setopt($ch, CURLOPT_HTTPHEADER, array("Accept: application/json", "Content-type: application/json"));
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $post);
$result = curl_exec($ch);
curl_close($ch);
var_dump($result);
Sample 2
$url = 'https://blocklist.plumvoice.com/api/numbers';
$username = 'you@yourdomain.com';
$password = 'your_developer_key';
$post = json_encode(array('details'=>true));
$ch = curl_init();
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($ch, CURLOPT_USERPWD, $username.":".$password);
curl_setopt($ch, CURLOPT_HTTPHEADER, array("Accept: application/json", "Content-type: application/json"));
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $post);
$result = curl_exec($ch);
curl_close($ch);
var_dump($result);

post
Upload Numbers to Blocklist

https://blocklist.plumvoice.com/api/upload
This method enables you to upload additional numbers to your Blocklist account.
Request
Response
Request
Headers
Accept
optional
string
application/json
Content-Type
optional
string
multipart/form-data
Query Parameters
csv
required
object
The CSV file containing the ANI to add or delete. See Sample CSV file.
numbers
required
string
Either the string "All" or a JSON-encoded string containing an array of numbers.
Response
200: OK
Sample 1
Sample 2
Sample 3
Sample 1
{
"success": true,
"data": {
"filename": "blacklist_upload.csv",
"total_rows": 1,
"rows_added": 1,
"rows_deleted": 0,
"rows_failed": 0,
"numbers": [
{
"6177123000": {
"rows_added": 1,
"rows_deleted": 0,
"total_rows": 32
},
"6177123001": {
"rows_added": 1,
"rows_deleted": 0,
"total_rows": 32
},
"6177123004": {
"rows_added": 1,
"rows_deleted": 0,
"total_rows": 32
},
}
]
}
}
Sample 2
{
"success": true,
"data": {
"filename": "blacklist_upload.csv",
"total_rows": 1,
"rows_added": 1,
"rows_deleted": 0,
"rows_failed": 0,
"numbers": [
{
"6177123000": {
"rows_added": 0,
"rows_deleted": 0,
"total_rows": 32
}
},
{
"6177123001": {
"rows_added": 0,
"rows_deleted": 0,
"total_rows": 32
}
},
{
"6177123002": {
"rows_added": 1,
"rows_deleted": 0,
"total_rows": 3
}
},
{
"6177123003": {
"rows_added": 1,
"rows_deleted": 0,
"total_rows": 3
}
},
{
"6177123004": {
"rows_added": 0,
"rows_deleted": 0,
"total_rows": 32
}
}
]
}
}
Sample 3
{
"success": true,
"data": {
"filename": "blacklist_upload.csv",
"total_rows": 1,
"rows_added": 0,
"rows_deleted": 0,
"rows_failed": 1,
"numbers": [
{
"6177123000": {
"rows_added": 0,
"rows_deleted": 0,
"total_rows": 32
}
},
{
"6177123001": {
"rows_added": 0,
"rows_deleted": 0,
"total_rows": 32
}
},
{
"6177123002": {
"rows_added": 0,
"rows_deleted": 0,
"total_rows": 3
}
},
{
"6177123003": {
"rows_added": 0,
"rows_deleted": 0,
"total_rows": 3
}
},
{
"6177123004": {
"rows_added": 0,
"rows_deleted": 0,
"total_rows": 32
}
}
],
"errors": [
"Line 2: Failed to be added - number was already blocked"
]
}
}
404: Not Found
{
"success": false,
"error": "Missing required JSON parameter: numbers"
}

Sample CSV File

Return Structure
Upload Details
Number Details
Return Structure

Name

Data Type

Always Present

Description

success

boolean

yes

Indicates the outcome of the request

error

string

no

If the success value is false this provides a message indicating what occurred

data

JSON string

no

If the success value is true this provides a JSON object containing the upload details listed below

Upload Details

Name

Data Type

Value

filename

string

The name of the CSV file uploaded

total_rows

int

Total number of rows within the CSV file

rows_added

int

Total number of rows of successfully added ANI within the CSV file

rows_deleted

int

Total number of rows of successfully deleted ANI within the CSV file

rows_failed

int

Total number of rows that had no DNIS updates

numbers

array of objects

Contains the numbers with specific details listed below

error

array of strings

Contains the error strings related to any rows_failed rows. This is only returned if rows_failed is greater than 0

Number Details

Name

Data Type

Value

rows_added

int

The number of rows added

rows_deleted

int

The number of rows deleted

total_rows

int

The total number of ANI blocked for the DNIS after adding and deleting

Sample Code

The following PHP code samples make the following requests:

  1. A subset of DNIS

  2. All DNIS

  3. All DNIS, but the ANI provided was already blocked for all DNIS:

Sample 1
Sample 2
Sample 3
Sample 1
$url = 'https://blocklist.plumvoice.com/api/history';
$username = 'you@yourdomain.com';
$password = 'your_developer_key';
if (function_exists('curl_file_create')) {
//PHP 5.5+
$csv = curl_file_create('/var/tmp/blacklist_upload.csv');
} else {
$csv = '@/var/tmp/blacklist_upload.csv';
}
$post = array('csv'=>$csv,'numbers'=>json_encode(["6177123000","6177123001","6177123004"]));
$ch = curl_init();
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($ch, CURLOPT_USERPWD, $username.":".$password);
curl_setopt($ch, CURLOPT_HTTPHEADER, array("Accept: application/json", "Content-type: multipart/form-data"));
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $post);
$result = curl_exec($ch);
curl_close($ch);
var_dump($result);
Sample 2
$url = 'https://blocklist.plumvoice.com/api/history';
$username = 'you@yourdomain.com';
$password = 'your_developer_key';
if (function_exists('curl_file_create')) {
//PHP 5.5+
$csv = curl_file_create('/var/tmp/blacklist_upload.csv');
} else {
$csv = '@/var/tmp/blacklist_upload.csv';
}
$post = array('csv'=>$csv,'numbers'=>"All");
$ch = curl_init();
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($ch, CURLOPT_USERPWD, $username.":".$password);
curl_setopt($ch, CURLOPT_HTTPHEADER, array("Accept: application/json", "Content-type: multipart/form-data"));
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $post);
$result = curl_exec($ch);
curl_close($ch);
var_dump($result);
Sample 3
$url = 'https://blocklist.plumvoice.com/api/history';
$username = 'you@yourdomain.com';
$password = 'your_developer_key';
if (function_exists('curl_file_create')) {
//PHP 5.5+
$csv = curl_file_create('/var/tmp/blacklist_upload.csv');
} else {
$csv = '@/var/tmp/blacklist_upload.csv';
}
$post = array('csv'=>$csv,'numbers'=>"All");
$ch = curl_init();
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($ch, CURLOPT_USERPWD, $username.":".$password);
curl_setopt($ch, CURLOPT_HTTPHEADER, array("Accept: application/json", "Content-type: multipart/form-data"));
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $post);
$result = curl_exec($ch);
curl_close($ch);
var_dump($result);

get
Account History

https://blocklist.plumvoice.com/api/history
This method allows you to pull a detailed history of the changes made to your Blocklist account.
Request
Response
Request
Headers
Accept
optional
string
application/json
Content-Type
optional
string
application/json
Query Parameters
details
required
boolean
Return the specific details for each event pulled.
limit
optional
integer
Return a limited number of entries. This is only required if offset is provided. (Note: 0 will pull all entries.)
offset
optional
integer
Return entries after skipping a certain amount. This is only required if limit is provided.
Response
200: OK
Sample 1
Sample 2
Sample 1
{
"success": true,
"data": {
"total": 54,
"events": [
{
"1": {
"timestamp": "1521136237",
"user": "Captain America",
"filename": "block1.csv",
"rows_added": 1,
"rows_deleted": 0
}
},
{
"2": {
"timestamp": "1521136304",
"user": "Captain America",
"filename": "block2.csv",
"rows_added": 1,
"rows_deleted": 0
}
},
{
"3": {
"timestamp": "1521136322",
"user": "Thor",
"filename": "remove_block2.csv",
"rows_added": 0,
"rows_deleted": 2
}
}
]
}
}
Sample 2
{
"success": true,
"data": {
"total": 54,
"events": [
{
"1": {
"timestamp": "1521136237",
"user": "Captain America",
"filename": "block1.csv",
"rows_added": 1,
"rows_deleted": 0,
"details": [
{
"ani": "8005557586",
"event": "added"
}
]
}
},
{
"2": {
"timestamp": "1521136304",
"user": "Captain America",
"filename": "block2.csv",
"rows_added": 1,
"rows_deleted": 0,
"details": [
{
"ani": "8005557586",
"event": "added",
"error": "Line 2: Failed to be added - number was already blocked"
},
{
"ani": "6177123000",
"event": "added"
}
]
}
},
{
"3": {
"timestamp": "1521136322",
"user": "Thor",
"filename": "remove_block2.csv",
"rows_added": 1,
"rows_deleted": 0,
"details": [
{
"ani": "8005557586",
"event": "deleted"
},
{
"ani": "6177123000",
"event": "deleted"
}
]
}
}
]
}
}
401: Unauthorized
{
"success": false,
"error": "Missing required JSON parameter: details"
}
Return Structure
History Details
Event Details
Subevent Details
Return Structure

Name

Data Type

Always Present

Description

success

boolean

yes

Indicates the outcome of the request

error

string

no

If the success value is false this provides a message indicating what occurred

data

JSON string

no

If the success value is true this provides the JSON object containing the history details listed below

History Details

Name

Data Type

Value

total

int

Total number of events

events

array of objects

Contains the events with specific details listed below

Event Details

Name

Data Type

Value

timestamp

string

The time the event was created

user

string

The user who created the event

filename

string

The name of the CSV file uploaded

rows_added

int

The number of ANI added in the CSV file

rows_deleted

int

The number of ANI deleted in the CSV file

details

array of objects

Contains the explicit actions taken parsing the CVS file. Subevent details listed below. This is only returned if details parameter was true

Subevent Details

Name

Data Type

Value

ani

string

The ANI to block

event

string

If the ANI was added or deleted

error

string

An error string detailing the error. This is only returned if an error occurred

Sample Code

This sample PHP code makes a request to this method:

Sample 1
Sample 2
Sample 1
$url = 'https://blocklist.plumvoice.com/api/history';
$username = 'you@yourdomain.com';
$password = 'your_developer_key';
$post = json_encode(array('details'=>false, 'limit'=>3, 'offset'=>0));
$ch = curl_init();
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($ch, CURLOPT_USERPWD, $username.":".$password);
curl_setopt($ch, CURLOPT_HTTPHEADER, array("Accept: application/json", "Content-type: application/json"));
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $post);
$result = curl_exec($ch);
curl_close($ch);
var_dump($result);
Sample 2
$url = 'https://blocklist.plumvoice.com/api/history';
$username = 'you@yourdomain.com';
$password = 'your_developer_key';
$post = json_encode(array('details'=>true, 'limit'=>3, 'offset'=>0));
$ch = curl_init();
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($ch, CURLOPT_USERPWD, $username.":".$password);
curl_setopt($ch, CURLOPT_HTTPHEADER, array("Accept: application/json", "Content-type: application/json"));
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $post);
$result = curl_exec($ch);
curl_close($ch);
var_dump($result);