Blocklist API

- NEW! - Interactive API docs, now live!

Visit api-docs.plumvoice.com to read Plum API documentation, build and test requests in our interactive API sandbox, review the responses, and share it all with your team.

Overview

The Blocklist API provides programmatic access to the following functionality:

Method	Service	Description
GET	api/numbers	Pull the list of IVR phone numbers.
POST	api/upload	Block ANIs for a set of IVR phone numbers
GET	api/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.

List of Numbers

GET https://blocklist.plumvoice.com/api/numbers

This allows you to pull the list of numbers that already exist in your Blocklist profile.

Query Parameters

Name	Type	Description
details	boolean	Return the specific details for each number pulled.

Headers

Name	Type	Description
Accept	string	application/json
Content-Type	string	application/json

200

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

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

$url = 'https://blocklist.plumvoice.com/api/numbers';
$username = '[email protected]';
$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 = '[email protected]';
$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);

Upload Numbers to Blocklist

POST https://blocklist.plumvoice.com/api/upload

This method enables you to upload additional numbers to your Blocklist account.

Query Parameters

Name	Type	Description
csv	object	The CSV file containing the ANI to add or delete. See Sample CSV file.
numbers	string	Either the string "All" or a JSON-encoded string containing an array of numbers.

Headers

Name	Type	Description
Accept	string	application/json
Content-Type	string	multipart/form-data

200

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

{
    "success": false,
    "error": "Missing required JSON parameter: numbers"
}

Sample CSV File

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

$url = 'https://blocklist.plumvoice.com/api/history';
$username = '[email protected]';
$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 = '[email protected]';
$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 = '[email protected]';
$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);

Account History

GET https://blocklist.plumvoice.com/api/history

This method allows you to pull a detailed history of the changes made to your Blocklist account.

Query Parameters

Name	Type	Description
details	boolean	Return the specific details for each event pulled.
limit	integer	Return a limited number of entries. This is only required if offset is provided. (Note: 0 will pull all entries.)
offset	integer	Return entries after skipping a certain amount. This is only required if limit is provided.

Headers

Name	Type	Description
Accept	string	application/json
Content-Type	string	application/json

200

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

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

$url = 'https://blocklist.plumvoice.com/api/history';
$username = '[email protected]';
$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 = '[email protected]';
$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);