BanishBot Documentation

cURL NodeJS PHP

Overview

BanishBot is a fast and simple API designed to help you, your teams and your organization manage opt-in, opt-out and access control lists.

							Examples of items that can be banished are:
Telephone Numbers
Email Addresses
IP Addresses
Employee IDs

Base URL

All endpoints in the documentation starts with the following URL

							https://api.banishbot.com/29-02-2018

Authentication

BanishBot authenication is done via request header, each request that you make to BanishBot must be accompanied by your API key.

Type:

HTTP Header x-api-key

Test Key:

abc-123-this-is-m7-t0ken

Please note the sample key will not return results.

							curl -XGET -H 'x-api-key: abc-123-this-is-m7-t0ken' -H "Content-type: application/json" 'https://api.banishbot.com/29-02-2018/TheDoctor/+447700900461'
							
var banishbot = require('banishbot');
var username = 'TheDoctor'; // Required
var apiKey = 'abc-123-Th1s-Is-My-K3y'; // Required
// initialize the API client with default base URL: https://api.banishbot.com/29-02-2018
$api_client = new BanishBot\ApiClient();
// authentication setting using api key/token
BanishBot\Configuration::getDefaultConfiguration()->setApiKey('x-api-key', 'abc-123-this-is-m7-t0ken');

$user = "TheDoctor";  // User

Installation

You can find the helper libraries at: github/mbmlabs/banishbot

							cURL does not require a helper library or install files.
							npm i banishbot
							composer require mbmlabs/banishbot

Banishing An Item

The fastest way to get stated with BanishBot is to think about an object you want to 'banish' or prevent access to your services from/to.
An example of this could be a telephone number that you no longer wish to receive calls from or send SMS messages to.

Using BanishBot like this you will be uploading the phone number and setting the state to true - in other words this phone number will be Banished.

							Request:
curl -XPOST -H 'x-api-key: abc-123-this-is-m7-t0ken' -H "Content-type: application/json" -d '{"notes": "These are my optional notes.","type": "PhoneNumber","banished":"true"}' 'https://api.banishbot.com/29-02-2018/TheDoctor/+447700900461'

Response:
{"statusCode":"200","body":{"Banished":true,"BanishedItem":"+447700900461","Username":"TheDoctor"}}



	banishPayload = {
	  banished: true // Required
	  type: 'email' // This is optional
	  notes: 'These are my optional notes' // This is optional
	};
	banishbot.banishNewItem(username, apiKey, 'dalek@skaro.planet', banishPayload).then(function(result) {
	  // Success Result
	  console.log(result);
	  // { success: true, username: 'TheDoctor' }
	  //{ statusCode: '409', body: { Reason: 'This item is already banished, please check the state of the item in a new request.' } }
	})
	.fail(function (error) {
	  // Error Something died, here is the response
	  console.log(error);
	});
$user = "TheDoctor";  // User
$banishObject = "dalek@skaro.planet";  // Banished object
// create AddObjectToBanishBot object
$addObjectToBanishBot = new BanishBot\Model\AddObjectToBanishBot();
$addObjectToBanishBot->setBanished(True);
$addObjectToBanishBot->setNotes("These are my optional notes.");
$addObjectToBanishBot->setType("PhoneNumber");

try {
    $user_api = new BanishBot\Api\UserAPI($api_client);
    // return BanishNewObjectResponse (model)
    $response = $user_api->banishNewObject($user, $banishObject, $addObjectToBanishBot);
    print_r($response);
} catch (BanishBot\ApiException $e) {
    echo 'Caught exception: ', $e->getMessage(), "\n";
    echo 'Resepone Header: ', print_r($e->getResponseHeaders(), true), "\n";
    echo 'Resepone Body: ', $e->getResponseBody(), "\n";
}

Check Item Banishment

You can check if an item has been banished by making a GET request containing the item in question.

							Request:
curl -XGET -H 'x-api-key: abc-123-this-is-m7-t0ken' -H "Content-type: application/json" 'https://api.banishbot.com/29-02-2018/TheDoctor/+447700900461'

Response:
{"statusCode":"200","body":{"Banished":false,"BanishedItem":"+447700900461"}}

	banishbot.checkBanishment(username, apiKey, 'dalek@skaro.planet').then(function(result) {
  // Success Result
  console.log(result);
  // {"Banished":false,"BanishedItem":"dalek@skaro.planet"}
})
.fail(function (error) {
  // Error Something died, here is the response
  console.log(error);
});


	// initialize the API client with default base URL: https://api.banishbot.com/29-02-2018
	$api_client = new BanishBot\ApiClient();
	// authentication setting using api key/token
	BanishBot\Configuration::getDefaultConfiguration()->setApiKey('x-api-key', 'abc-123-this-is-m7-t0ken');

	$user = "TheDoctor";  // User
	$banishObject = "dalek@skaro.planet";  // Banish object

	try {
	    $user_api = new BanishBot\Api\UserAPI($api_client);
	    // return CheckBanishmentResponse (model)
	    $response = $user_api->checkBanishment($user, $banishObject);
	    print_r($response);
	} catch (BanishBot\ApiException $e) {
	    echo 'Caught exception: ', $e->getMessage(), "\n";
	    echo 'Resepone Header: ', print_r($e->getResponseHeaders(), true), "\n";
	    echo 'Resepone Body: ', $e->getResponseBody(), "\n";
	}

Update a Item

If you need to update an items status or append additional notes to the object you can do so here.
When calling this resource you must always pass a banishment state, even if the state does not change.

							Request:
curl -XPUT -H 'x-api-key: abc-123-this-is-m7-t0ken' -H "Content-type: application/json" -d '{"notes": "These are my updated notes.","type": "PhoneNumber","banished":"true"}' 'https://api.banishbot.com/29-02-2018/TheDoctor/+447700900461'

Response:
{"statusCode":"200","body":{"success":true,"username":"TheDoctor"}}



	banishPayload = {
	  banished: true // Required
	  notes: 'These are my updated notes' // This is optional
	};
	banishbot.updateBanishedItem(username, apiKey, 'dalek@skaro.planet', banishPayload).then(function(result) {
	  // Success Result
	  console.log(result);
	  //{ success: true, username: 'TheDoctor' }
	})
	.fail(function (error) {
	  // Error Something died, here is the response
	  console.log(error);
	});
// initialize the API client with default base URL: https://api.banishbot.com/29-02-2018
$api_client = new BanishBot\ApiClient();
// authentication setting using api key/token
BanishBot\Configuration::getDefaultConfiguration()->setApiKey('x-api-key', 'abc-123-this-is-m7-t0ken');

$user = "TheDoctor";  // User
$banishObject = "dalek@skaro.planet";  // Banished object
// create UpdateObjectRequest object
$updateObjectRequest = new BanishBot\Model\UpdateObjectRequest();
$updateObjectRequest->setBanished(False);
$updateObjectRequest->setNotes("These are my updated notes");
$updateObjectRequests = array($updateObjectRequest);  // To update an object you need to provide a new object...

try {
    $user_api = new BanishBot\Api\UserAPI($api_client);
    // return UpdateBanishedObjectResponse (model)
    $response = $user_api->updateBanishedObject($user, $banishObject, $updateObjectRequests);
    print_r($response);
} catch (BanishBot\ApiException $e) {
    echo 'Caught exception: ', $e->getMessage(), "\n";
    echo 'Resepone Header: ', print_r($e->getResponseHeaders(), true), "\n";
    echo 'Resepone Body: ', $e->getResponseBody(), "\n";
}

Delete an Item from BanishBot

If you no longer need the object banished or a record kept on BanishBot you can delete the item from BanishBot.
Note: This immediately deletes the record from BanishBot, this cannot be undone.

							Request:
curl -XDELETE -H 'x-api-key: abc-123-this-is-m7-t0ken' -H "Content-type: application/json" 'https://api.banishbot.com/29-02-2018/TheDoctor/+447700900461'

Response:
{"statusCode":"200","body":{"Success":true,"Message":"+447700900461 has been deleted","Username":"TheDoctor"}}


	banishbot.deleteItemFromBanishBot(username, apiKey, 'dalek@skaro.planet').then(function(result) {
	  // Success Result
	  console.log(result);
	  //{"Success":true,"Message":"dalek@skaro.planet has been deleted","Username":"TheDoctor"}
	})
	.fail(function (error) {
	  // Error Something died, here is the response
	  console.log(error);
	});
// initialize the API client with default base URL: https://api.banishbot.com/29-02-2018
$api_client = new BanishBot\ApiClient();
// authentication setting using api key/token
BanishBot\Configuration::getDefaultConfiguration()->setApiKey('x-api-key', 'abc-123-this-is-m7-t0ken');

$user = "TheDoctor";  // User
$banishObject = "darlek@skaro.planet";  // Banish object

try {
    $user_api = new BanishBot\Api\UserAPI($api_client);
    // return DeleteObjectResponse (model)
    $response = $user_api->deleteObject($user, $banishObject);
    print_r($response);
} catch (BanishBot\ApiException $e) {
    echo 'Caught exception: ', $e->getMessage(), "\n";
    echo 'Resepone Header: ', print_r($e->getResponseHeaders(), true), "\n";
    echo 'Resepone Body: ', $e->getResponseBody(), "\n";
}

Errors

Attributes

statusCode:

string Code of the error

message:

string A complete message with details about the error.

200 OK - Everything worked.

400 Bad Request - The request was badly built

401 Unauthorized - Some other message

402 Request Failed - The request failed

404 Not Found - Doesn't exist

500, 502, 503, 504 Server errors