Caller ID API - Reverse America Developer Tools

« Back to the developer index

The Caller ID API

For PABX systems we suggest using simple lookups along with a spam threshold to remove unwanted callers. Extended lookups include full address details and age of the record.

The request to our API is a standard HTTP GET request as follows:

http://api.reverseamerica.co/cidlookup.php?format=FORMAT&key=APIKEY&q=PHONE

Parameters

format (required)

valid options are json, xml, text


key (required)

32 characters long, provided when you join the developer program


q (required)

valid America phone number


extended (optional)

valid options are 1 or 0. Provides extended details about a record


spamthreshold (optional)

an integer between 1 and 100 representing a spam score percentage. If the spam score of the number is above this the name of the caller will be changed to SPAM and the age property will represent the time of the last complaint. For more information on how the spam score is calculated, take a look at our Spam API


spamscore (optional)

valid options are 1 or 0. This option is not compatible with spamthreshold. When you use it, you will get back a spam score along with the name. If a number has no name but has a spam score it will 'Not found' as the name


notfound (optional)

if you need the API to return back a different value other than 'Not found' for compatibility, you can specify a string of up to 10 characters here. This is especially useful for PBX systems that expect a blank response


normalize (optional)

valid options are 1 or 0. Takes the resulting names, removes any non-alphanumeric character, and upper cases the result, for example 'Smith, J' would become 'SMITH J'


timestamp (optional)

valid options are 1 or 0. Adds a timestamp to the results, which reflects the last time the record was verified


Test Number

For testing purposes, searching for 0262195555 will allow an unlimited amount of searches past your limit. Searches to the test number will still count towards your limits however.



Suggested implementation for PBX systems

If a person has chosen to opt-out of our service, we will still provide their name in our simple lookup exclusively for the purpose of caller identification. No address information will be available an extended lookup will fail. We recommend including a spam threshold in your requests to minimize unnecessary requests to our spam API.

http://api.reverseamerica.co/cidlookup.php?format=json&key=EXAMPLE&q=0262195555&spamthreshold=40
result
{"name":"Australian Communications Authority (aca)"}

Example in PHP

<?php
  define
('APIKEY''xxxxxxxxxxx');
  
$phone '0262195555';
  
$result = (array)json_decode(file_get_contents("http://{$API_URL}/cidlookup.php?format=json&key=" APIKEY "&q=$phone&spamthreshold=40"));
  if (isset(
$result['error'])) {
      if (
$result['error'] == 'Not found') {
          
//record not found
      
} else {
          die(
"Error: {$result['error']}");
      }
  } else {
      echo 
"Record: {$result['name']}";
  }
?>

Example Query Results

Text

http://api.reverseamerica.co/cidlookup.php?format=text&key=EXAMPLE&q=0262195555&extended=1
result (tab separated)
Australian Communications Authority (aca) \t College St, ACT 2611, Australia \t (02) 6219 5555 \t 1130832000

JSON

http://api.reverseamerica.co/cidlookup.php?format=json&key=EXAMPLE&q=0262195555&extended=1
result
{"address":"College St, ACT 2611, Australia","age":1130832000,"names":["Australian Communications Authority (aca)"],"phone":"(02) 6219 5555"}

XML

http://api.reverseamerica.co/cidlookup.php?format=xml&key=EXAMPLE&q=0262195555&extended=1
result
<?xml version="1.0" encoding="iso-8859-1"?><record><address>College St, ACT 2611, Australia</address><age>1130832000</age><names><name>Australian Communications Authority (aca)</name></names><phone>(02) 6219 5555</phone></record>


API Support

Please contact support@reverseamerica.co if you are having trouble implementing our API