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.
get
https://blocklist.plumvoice.com
/api/numbers
List of Numbers
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
$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);
$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);
post
https://blocklist.plumvoice.com
/api/upload
Upload Numbers to Blocklist
​Sample CSV File​
Return Structure
Upload Details
Number Details
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
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
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
$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);
$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);
$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);
get
https://blocklist.plumvoice.com
/api/history
Account History
Return Structure
History Details
Event Details
Subevent Details
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
Name
Data Type
Value
total
int
Total number of events
events
array of objects
Contains the events with specific details listed below
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
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
$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);
$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);

Plum DEV APIs - Previous

Application API

Last modified 5mo ago

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

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

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