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 PartDescriptionsExample
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 format18008472911
Customer Phone Number (uri)(optional) Phone number of customer/user being called12066194123
api_keyAPI 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

FieldTypeDescription
ActionstringRepresents the reported type of call.

  • allow
  • block
  • voiceMail

Example Response

"block"

HTTP Codes

HTTP CodeError NameDescription
200OKSuccess
500ErrorInput request error, invalid phone number format
401UnauthorizedMissing or invalid API key: Contact us for a free key
429Request Rate ExceededThe 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 PartDescriptionsExample
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 ID18008472911 or 8008472911 or 1(800)847-2911
api_keyAPI 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.

FieldTypeDescription
CallTypestringRepresents 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
Confidenceint0 .. 10 where 0 is low and 10 is high
IsSpambooltrue | false
LastComplaintDatestring (datetime)DateTime UTC of the last time a complaint was registered for the phone number
Tagsstring arrayA 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 CodeError NameDescription
200OKSuccess
500ErrorInput request error, invalid phone number format
401UnauthorizedMissing or invalid API key: Contact us for a free key
429Request Rate ExceededThe number of requests for the api key have been exceeded