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:

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

NameTypeDescription

details

boolean

Return the specific details for each number pulled.

Headers

NameTypeDescription

Accept

string

application/json

Content-Type

string

application/json

{
    "success": true,
    "data": [
        "6177123000",
        "6177123001",
        "6177123002",
        "6177123003",
        "6177123004"
    ]
}

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.

$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);

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

NameTypeDescription

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

NameTypeDescription

Accept

string

application/json

Content-Type

string

multipart/form-data

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

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

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:

$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);

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

NameTypeDescription

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

NameTypeDescription

Accept

string

application/json

Content-Type

string

application/json

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

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

Sample Code

This sample PHP code makes a request to this method:

$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);

Last updated