# Blocklist API

## Overview

The Blocklist API provides programmatic access to the following functionality:

* [Numbers](/blocklist/master.md#list-of-numbers): Pull the list of IVR phone numbers.
* [Upload](/blocklist/master.md#upload-numbers-to-blocklist): Block ANIs for a set of IVR phone numbers
* [History](/blocklist/master.md#account-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

<mark style="color:blue;">`GET`</mark> `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 |

{% tabs %}
{% tab title="200 " %}
{% tabs %}
{% tab title="Code Sample 1" %}

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

{% endtab %}

{% tab title="Code Sample 2" %}

```javascript
{
    "success": true,
    "data": [
        {
            "6177123000": "31"
        },
        {
            "6177123001": "31"
        },
        {
            "6177123002": "2"
        },
        {
            "6177123003": "2"
        },
        {
            "6177123004": "31"
        }
    ]
}
```

{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="401 " %}

```javascript
{
    "success": false,
    "error": "Missing required JSON parameter: details"
}
```

{% endtab %}
{% endtabs %}

**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.

{% tabs %}
{% tab title="Sample 1" %}

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

{% endtab %}

{% tab title="Sample 2" %}

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

{% endtab %}
{% endtabs %}

## Upload Numbers to Blocklist

<mark style="color:green;">`POST`</mark> `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 |

{% tabs %}
{% tab title="200 " %}
{% tabs %}
{% tab title="Sample 1" %}

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

{% endtab %}

{% tab title="Sample 2" %}

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

{% endtab %}

{% tab title="Sample 3" %}

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

{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="404 " %}

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

{% endtab %}
{% endtabs %}

[Sample CSV File](https://blacklist.plumvoice.com/assets/sample.csv)

{% tabs %}
{% tab title="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 |
| {% endtab %} |             |                |                                                                                                     |

{% tab title="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 |
| {% endtab %}  |                  |                                                                                                                      |

{% tab title="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 |
| {% endtab %}  |           |                                                                        |
| {% endtabs %} |           |                                                                        |

**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:

{% tabs %}
{% tab title="Sample 1" %}

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

{% endtab %}

{% tab title="Sample 2" %}

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

{% endtab %}

{% tab title="Sample 3" %}

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

{% endtab %}
{% endtabs %}

## Account History

<mark style="color:blue;">`GET`</mark> `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 |

{% tabs %}
{% tab title="200 " %}
{% tabs %}
{% tab title="Sample 1" %}

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

{% endtab %}

{% tab title="Sample 2" %}

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

{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="401 " %}

```javascript
{
    "success": false,
    "error": "Missing required JSON parameter: details"
}
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="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 |
| {% endtab %} |             |                |                                                                                                        |

{% tab title="History Details" %}

| Name         | Data Type        | Value                                                  |
| ------------ | ---------------- | ------------------------------------------------------ |
| total        | int              | Total number of events                                 |
| events       | array of objects | Contains the events with specific details listed below |
| {% endtab %} |                  |                                                        |

{% tab title="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 |
| {% endtab %}  |                  |                                                                                                                                              |

{% tab title="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 |
| {% endtab %}  |           |                                                                                 |
| {% endtabs %} |           |                                                                                 |

**Sample Code**

This sample PHP code makes a request to this method:

{% tabs %}
{% tab title="Sample 1" %}

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

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.plumvoice.com/blocklist/blocklist-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.