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:
Parameters
format (required)
valid options are json, xml, text
key (required)
32 characters long, provided when you join the developer program
q (required)
valid Planet 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.
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
JSON
XML
API Support
Please contact support@reverseplanet.com if you are having trouble implementing our API