Call Control Protect API

The Call Control Protect API informs the call path of a blocking decision. Using a RESTful POST request providing the caller ID of the phone number and the number being called the Protect API makes the block or allow decision based on the user call control preferences and community blacklist. Simple.

Request

The Protect API request is a RESTful HTTPS GET in the following format:

Request parameters

URI Part Descriptions Example
API Version (uri) Specifies the version of the REST API to ensure no breaking changes. 2015-11-01 (latest)
Caller Phone Number (uri) Phone number of originating caller in E164 format 18008472911
Customer Phone Number (uri) (optional) Phone number of customer/user being called 12066194123
api_key API Key is specified as a URI parameter. Send us email here to acquire an API Key. demo

Response

The response will indicate the action to take: Allow the call, Drop the call (disconnect no response) or Voice mail

Field Type Description
Action string Represents the reported type of call.

  • allow
  • block
  • voiceMail

Example Response

"block"

HTTP Codes

HTTP Code Error Name Description
200 OK Success
500 Error Input request error, invalid phone number format
401 Unauthorized Missing or invalid API key: Contact us for a free key
429 Request Rate Exceeded The number of requests for the api key have been exceeded

Call Control Protect User Management API

The Protect User Management API enables the retrieval and setting of user preferences including call blocking behavior, whitelist, blacklist, quiet hours and breakthrough rules. Details can be provided on request.

Call Control Identify API

The Call Control Identify API provides detailed informatio on the spam activity and behavior of a phone number. Using a RESTful GET request providing the phone number with your API key, you’ll receive a response that includes whether the phone number is spam and a confidence indicator, the type of call (e.g. fraud, robocall, telemarketing), the date and time of the most recient complaint and a set of tags that were generated from natural language processing of the all of the reported complaints.

Request

The Call Control Identify API request is a RESTful HTTPS GET in the following format:

Request parameters

URI Part Descriptions Example
API Version (uri) Specifies the version of the REST API to ensure no breaking changes. 2015-11-01 (latest)
Phone Number (uri) Phone number to look up as displayed on caller ID 18008472911 or 1(800)847-2911
api_key API Key is specified as a URI parameter. Send us email here to acquire an API Key. demo

Response

The response of the Identify API is an aggregation accross a variety of data sources, normalized into a common format.

Field Type Description
CallType string Represents the reported type of call.

  • Business
  • Callback
  • Collection_Agency
  • Fax_Machine
  • Fund_Raiser
  • Junk_Fax
  • NotSpam
  • Other_Commercial
  • VOIP
  • Political
  • Prank_Call
  • Reminder_Notification_Call
  • RoboCall
  • Scam
  • Spam_Text
  • Surveyor
  • Telemarketing
  • Unknown
Confidence int 0 .. 10 where 0 is low and 10 is high
IsSpam bool true | false
LastComplaintDate string (datetime) DateTime UTC of the last time a complaint was registered for the phone number
Tags string array A list of string tags describing the test

Example Response

{
  "CallType": "Telemarketing",
  "Confidence": 10,
  "IsSpam": true,
  "LastComplaintDate": "2016-01-29T17:49:56.577",
  "ReportedCallerName": "Visa",
  "Tags": [
    "Heather",
    "Credit Card Services",
    "Jennifer",
    "CardMember Services",
    "Customer Care Center of Visa",
    "Credit Cards",
    "MasterCard Customer Assistance Center",
    "Visa Customer Services Center",
    "Charles Larson",
    "Jim Michaels",
    "Stanley Rivers",
    "Christopher Williams",
  ]
}

HTTP Codes

HTTP Code Error Name Description
200 OK Success
500 Error Input request error, invalid phone number format
401 Unauthorized Missing or invalid API key: Contact us for a free key
429 Request Rate Exceeded The number of requests for the api key have been exceeded