There's no easy way to stop spam and scam phone calls. We looked at building a mobile application that'd rely on user data to build a reliable and open freely-available database but the process required garnishing millions of local users... but this process was just unreasonable and outside our areas of focus. The fact that a reliable real-time database of phone numbers likely associated with scams isn't made freely available by the Australian Government through the AMCA is just unacceptable when it'll potentially protect the thousands of Australians that lose hundreds of millions every year as a result of fraud. As part of our everyday phone usage we can generally rely on popular diallers made available from the likes of Google and Samsung to block shonky calls, but this isn't of any use to those of us that build applications that should include a measure of protection against (mainly offshore) malicious scammers.
Gaining access to a database that'll protect our customers is hard. Until then, our Phone API is more of a 'Resolution API' than the intended Abuse API... and quite frankly, we're unlikely to pursue the latter anytime soon.
Phone Number API
Until our API reliably returns scam caller information, the primary purpose of the API to verify a phone number exists, return an approximate location, and convert the number to various formats. While the API is limited in terms of functionality, it still may be useful to those of our clients that build internal applications. In terms of our usage, each incoming phone number (associated with leads of enquires) is passed through the API, and we use it to force formatting of phone numbers in forms based on a resolved location.
The Country Code (Advanced): The country code of each user is required if used in a form. This value (for those building plugins on top of our own) can be referenced by a session variable. The timezone array is only generally accurate to the country code and offset level, and the returned timezone text string (in a format suitable for Microsoft) is generally used only for calendar date availability. The session variables we've recorded for you are ' (, )' - note that the offset and country code are likely accurate.
Number Regex (Advanced): If using on your website, call the bmpnf($id, $t, $cc) function with the field id, country code, and phone number to correct number formatting in real-time. The same function can be called on submit to return true or false for validity (include a fourth argument as true).
API Endpoint
The API endpoint is shown below. As noted above, if making the request via your website you should generally access the country from the session variable rather than have the user waste their time with a dropdown.
api.beliefmedia.com/tel/tel.json?tel={tel}&country_code={cc}&apikey={key}The API key used if your primary API Key. No usage limits apply.
Example Response
We'll first query the Bunnings Hardware store at Sydney's Leppington, about 10 minutes southwest of Liverpool.
The is_scam value is derived from limited scammer databases and by checking the number against known reputable numbers. However, any number can be spoofed so no method of scan detection can be relied upon. One of the important values from a marketing perspective is the resolved_location key (Liverpool) which we can use to map out a heat signature of activity.
If an international enquiry is made you can refer to the e164 value to determine the correct number to call.
Querying the AFCA's relay mobile number 
returns the following:
Mobile numbers can't be resolved to any single location so they should be considered 'National' (as reflected by the all-inclusive timezone array). The carrier might be useful for statistical purposes.
Invalid phone numbers, and those that can't be resolved, will serve a code of 404 with a relevant message.
More Information
Our clients generally steer clear of building their own apps and instead focus on what puts their kids through school, but if you require more information it's expected that we'll include the full documentation in our FAQ module, although you're welcome to contact us in the meantime to see if the features of the API might be useful.
