Why choose HLR Lookup API over traditional phone validation methods?

Unlike basic validation services, our HLR lookup API connects directly to carrier networks, providing: 99.9% accurate carrier validation through direct network queries, real-time phone validation API without outdated databases, significant cost savings by preventing failed message delivery, instant network-level verification for business numbers, and enterprise-grade reliability with carrier-direct connections. This translates to immediate ROI through reduced communication costs and improved delivery rates.

How does our Phone Lookup API reduce business communication costs?

Our comprehensive phone lookup service delivers measurable cost benefits: eliminate messaging costs to invalid business numbers, reduce carrier fees through smart routing optimization, prevent revenue loss from fraudulent activities, optimize communication pathways using carrier data, and improve delivery rates with pre-validated numbers. Clients typically see 30-40% reduction in communication infrastructure costs.

What makes our Spam Number Lookup superior for enterprise fraud prevention?

Our enterprise-grade spam detection system provides unmatched protection: real-time spam status verification across carrier networks, business-focused fraud pattern detection, community-driven spam reporting system, automated risk scoring for all numbers, and integration with major telecom security systems. Enterprise clients report up to 95% reduction in fraudulent communication attempts.

How does Reverse Phone Lookup API enhance business verification?

Our phone lookup capabilities improve business trustworthiness: instant business name verification through carrier data, telecom fraud prevention, phone number spoofing detection, cross-reference with business registries, and real-time business status monitoring. This enables secure, verified B2B communications at scale.

How does our KYC API speeds up onboarding?

Our KYC API accelerates client verification while maintaining compliance: automated client identity verification, instant carrier-level client validation, multiple data points for verification, reduced onboarding time by up to 80%, and full audit trail for compliance. This typically reduces onboarding costs while improving security.

What ROI can businesses expect from our Carrier Lookup API?

Our carrier lookup API delivers measurable business impact: 50% reduction in failed message costs, 30% improvement in delivery rates, reduced telecom fraud losses, and enhanced business communication reliability. Most enterprises see positive ROI within the first month of implementation.

How does Branded Caller ID improve connection rates?

Our branded caller ID solution significantly impacts business metrics: up to 3x increase in call answer rates, verified business identity display, enhanced customer trust through verification, reduced spam flagging of legitimate calls, and improved customer engagement metrics. Clients report 60-80% improvement in first-call connection rates.

Can I resell CallerAPI services?

Yes! With our industry-lowest rate of $0.0039 per lookup (compared to competitors charging $0.009 or more), you can simply purchase our API and resell it at whatever price point you choose. The significant price difference lets you set competitive rates while maintaining healthy margins.

Caller ID API | Documentation

Authentication

To use the CallerAPI, include your API key in the header of each request:

X-Auth: YOUR_API_KEY

Replace YOUR_API_KEY with the actual API key provided in your CallerAPI dashboard.

API Key

••••••••••••••••••••••••••••••

Get User Information

Retrieve information about the authenticated user.

GET https://callerapi.com/api/me

Response

{
    "status": "success",
    "email": "[email protected]",
    "credits_spent": 23498,
    "credits_monthly": 250000,
    "credits_left": 226502
}

Code Examples

curl -H 'X-Auth: YOUR_API_KEY' 'https://callerapi.com/api/me'

import requests

url = "https://callerapi.com/api/me"
headers = {
    "X-Auth": "YOUR_API_KEY"
}

response = requests.get(url, headers=headers)
print(response.json())

fetch('https://callerapi.com/api/me', {
    headers: {
        'X-Auth': 'YOUR_API_KEY'
    }
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));

$phone_number = "18006927753";
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://callerapi.com/api/phone/info/$phone_number");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('X-Auth: YOUR_API_KEY'));
$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true);
print_r($data);

Get Phone Number Information

Retrieve detailed information about a specific phone number.

GET https://callerapi.com/api/lookup/{phone}?hlr=true

Replace {phone} with the phone number you want to look up. The phone number should be in E.164 format (e.g., +16502530000). Add the optional hlr=true parameter to include HLR (Home Location Register) data in the response. HLR lookup adds 1-3 seconds to the response time but incurs no additional cost.

Response

{
    "status": "success",
    "data": {
        "phone": "+16502530000",
        "entity_type": "BUSINESS",
        "reputation": "SPAM",
        "total_complaints": 50,
        "is_spam": true,
        "spam_score": 100,
        "business_info": {
            "business_name": "Google, Inc.",
            "category": "services",
            "city": "Mountain View",
            "industry": "Internet Products & Services",
            "state": "CA",
            "verified": false
        },
        "carrier_info": {
            "country": {
                "code": "1",
                "iso": "US",
                "name": "United States"
            },
            "network": {
                "carrier": "Level 3/1",
                "ocn": "152550",
                "type": "LANDLINE",
                "spid": "152550",
                "original": {
                    "carrier": "MCImetro Former Worldcom/1",
                    "ocn": "152202",
                    "spid": "152202"
                }
            },
            "number": {
                "msisdn": "16502530000",
                "local_format": "(650) 253-0000",
                "type": "LANDLINE",
                "landline": true,
                "mobile": false,
                "lrn": "4159686199",
                "valid": "undetermined",
                "reachable": "undetermined",
                "ported": true,
                "timezone": "America/Los_Angeles"
            }
        },
        "complaints": [
            {
                "CreatedDate": "2025-03-17T09:18:11Z",
                "ViolationDate": "2025-03-06T12:00:00Z",
                "ConsumerState": "Georgia",
                "Subject": "Reducing your debt (credit cards, mortgage, student loans)",
                "RecordedMessageOrRobocall": "Y"
            }
            // ... more complaints ...
        ]
    }
}

Field Descriptions

Main Fields

entity_type: Type of entity (BUSINESS, PERSONAL, UNKNOWN)
reputation: Overall reputation (SPAM, VERIFIED, UNKNOWN)
total_complaints: Total number of FTC complaints
is_spam: Whether the number is marked as spam
spam_score: Spam likelihood score (0-100)

Business Information

business_name: Name of the business
category: Business category
industry: Industry classification
city: Business city location
state: Business state/province
verified: Whether the business is verified

Carrier Information (HLR)

country: Country information (code, ISO, name)
network: Network details:

carrier: Current carrier name
ocn: Operating Company Number
spid: Service Provider ID
type: Network type (LANDLINE, MOBILE, VOIP, TOLLFREE)
original: Original carrier information

number: Number details:

msisdn: Full phone number
local_format: Local number format
type: Line type (LANDLINE, MOBILE, VOIP, TOLLFREE)
landline: Whether it's a landline
mobile: Whether it's a mobile number
lrn: Location Routing Number
valid: Number validity status
reachable: Number reachability status
ported: Whether number is ported
timezone: Number timezone

Complaints

CreatedDate: When the complaint was filed
ViolationDate: When the violation occurred
ConsumerState: State where complaint originated
Subject: Type of complaint
RecordedMessageOrRobocall: Whether it was a robocall (Y/N)

Code Examples

curl -H 'X-Auth: YOUR_API_KEY' 'https://callerapi.com/api/lookup/+16502530000?hlr=true'

import requests

phone = "+16502530000"
url = f"https://callerapi.com/api/lookup/{phone}"
headers = {
    "X-Auth": "YOUR_API_KEY"
}
params = {
    "hlr": "true"
}

response = requests.get(url, headers=headers, params=params)
print(response.json())

const phone = '+16502530000';
fetch(`https://callerapi.com/api/lookup/${phone}?hlr=true`, {
    headers: {
        'X-Auth': 'YOUR_API_KEY'
    }
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));

$phone = "+16502530000";
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://callerapi.com/api/lookup/$phone?hlr=true");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('X-Auth: YOUR_API_KEY'));

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
print_r($data);

KYC API

These endpoints provide advanced phone number intelligence. Each endpoint requires authentication with your API key.

Pricing

Network Intelligence

Ported Date €0.008
Porting History €0.02
Port Fraud Risk €0.02

Advanced Verification

Online Presence €0.15
KYC Match €0.30

Note: 1 credit = $0.0039. Credits will be deducted based on the equivalent cost of each request.

Get Porting Information

Check if a number has been ported and get the most recent porting date.

GET https://callerapi.com/api/ported/{phone}

Response

{
    "ported": true,
    "ported_date": "2016-12-30 15:15:19",
    "ported_date_type": "exact",
    "status": 0,
    "status_message": "Success"
}

Field Descriptions

Porting Information Fields

ported: Boolean indicating if the number has been ported from its original network
ported_date: Timestamp of the most recent porting event in "YYYY-MM-DD HH:MM:SS" format
ported_date_type: Indicates the reliability of the porting date:

"exact": Precise porting date and time from network records
"estimate": Approximate date based on available data
"unknown": Porting occurred but exact date cannot be determined

current_network: Information about the current network operator:

mcc: Mobile Country Code
mnc: Mobile Network Code
name: Operator name
spid: Service Provider ID
lrn: Location Routing Number (if applicable)

origin_network: Information about the original network operator that issued the number (same fields as current_network)
present: Indicates if the number is currently active in the network ("yes", "no", or "n/a")
status: Response status code (0 = Success)
status_message: Human-readable status message

Code Examples

curl -H 'X-Auth: YOUR_API_KEY' \
'https://callerapi.com/api/ported/40721987086'

import requests

phone = "40721987086"
url = f"https://callerapi.com/api/ported/{phone}"
headers = {
    "X-Auth": "YOUR_API_KEY"
}

response = requests.get(url, headers=headers)
print(response.json())

const phone = '40721987086';
fetch(`https://callerapi.com/api/ported/${phone}`, {
    headers: {
        'X-Auth': 'YOUR_API_KEY'
    }
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));

$phone = "40721987086";
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://callerapi.com/api/ported/$phone");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('X-Auth: YOUR_API_KEY'));

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
print_r($data);

Get Porting History

Retrieve the complete history of porting events for a number.

GET https://callerapi.com/api/porting-history/{phone}

Response

{
    "porting_history": [
        {
            "action": "D",
            "tmtnetwork": 4018720,
            "i_type": "m",
            "ts": "2022-01-31T00:00:00"
        },
        {
            "action": "A",
            "tmtnetwork": 4018740,
            "i_type": "m",
            "ts": "2021-03-18T00:00:00"
        }
    ],
    "status": 0,
    "status_message": "Success"
}

Field Descriptions

Porting History Fields

porting_history: Array of porting events since logging began for the country, ordered from most recent to oldest
Each porting event contains:

action: Type of porting action:

"A": Addition - number added to network
"D": Deletion - number removed from network
"C": Change - network details changed
"P": Port - number ported between networks
"R": Return - number returned to original network

tmtnetwork: Unique identifier for the network operator involved in the event
i_type: Network type identifier:

"m": Mobile network operator
"f": Fixed/landline network
"v": VoIP provider
"o": Other network type

ts: Timestamp of the event in ISO 8601 format

current_network: Information about the current network operator:

mcc: Mobile Country Code
mnc: Mobile Network Code
name: Operator name
spid: Service Provider ID
lrn: Location Routing Number (if applicable)

ported: Boolean indicating if the number is currently ported
status: Response status code (0 = Success)
status_message: Human-readable status message

Code Examples

curl -H 'X-Auth: YOUR_API_KEY' \
'https://callerapi.com/api/porting-history/40739521819'

import requests

phone = "40739521819"
url = f"https://callerapi.com/api/porting-history/{phone}"
headers = {
    "X-Auth": "YOUR_API_KEY"
}

response = requests.get(url, headers=headers)
print(response.json())

const phone = '40739521819';
fetch(`https://callerapi.com/api/porting-history/${phone}`, {
    headers: {
        'X-Auth': 'YOUR_API_KEY'
    }
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));

$phone = "40739521819";
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://callerapi.com/api/porting-history/$phone");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('X-Auth: YOUR_API_KEY'));

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
print_r($data);

Get Port Fraud Risk

Assess the risk of port-out fraud for a number based on recent porting activity.

GET https://callerapi.com/api/port-fraud/{phone}

Response

{
    "port_fraud_risk": "low",
    "status": 0,
    "status_message": "Success"
}

Field Descriptions

Port Fraud Risk Fields

port_fraud_risk: Assessment of the risk level for potential port-out fraud:

"none": No risk detected - no recent porting activity or suspicious patterns
"low": Minimal risk - normal porting activity within expected patterns
"medium": Moderate risk - some unusual porting patterns detected
"high": Significant risk - multiple suspicious porting events or patterns
"critical": Very high risk - clear indicators of potential port-out fraud

risk_factors: Array of detected risk factors (if any):

"recent_port": Recent porting activity within last 30 days
"multiple_ports": Multiple porting events in short timeframe
"suspicious_pattern": Unusual porting pattern detected
"known_fraud": Previous fraud activity associated with number
"cross_border": International porting activity

last_port: Information about the most recent porting event (if any):

date: Date of the last porting event
from: Source network operator
to: Destination network operator

status: Response status code (0 = Success)
status_message: Human-readable status message

Note: Port fraud risk assessment combines historical porting data with real-time network signaling checks to evaluate the likelihood of fraudulent porting activity.

Code Examples

curl -H 'X-Auth: YOUR_API_KEY' \
'https://callerapi.com/api/port-fraud/40721987086'

import requests

phone = "40721987086"
url = f"https://callerapi.com/api/port-fraud/{phone}"
headers = {
    "X-Auth": "YOUR_API_KEY"
}

response = requests.get(url, headers=headers)
print(response.json())

const phone = '40721987086';
fetch(`https://callerapi.com/api/port-fraud/${phone}`, {
    headers: {
        'X-Auth': 'YOUR_API_KEY'
    }
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));

$phone = "40721987086";
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://callerapi.com/api/port-fraud/$phone");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('X-Auth: YOUR_API_KEY'));

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
print_r($data);

Get Online Presence

Check if a number is linked to various online platforms and services.

GET https://callerapi.com/api/online-presence/{phone}

Response

{
    "online_presence": {
        "whatsapp": 1,
        "telegram": 0,
        "amazon": 1,
        "google": 1,
        "office365": 1,
        "instagram": 1,
        "linkedin": -1,
        "twitter": 1,
        "skype": 0,
        "viber": 0
    },
    "status": 0,
    "status_message": "Success"
}

Field Descriptions

Online Presence Fields

online_presence: Object containing presence status for various platforms
Status values for each platform:

1: Active - phone number is linked to an active account
0: Inactive - phone number is not linked to an account
-1: Unknown - platform status could not be determined
-2: Error - error occurred while checking platform

Supported platforms:

whatsapp: WhatsApp messaging service
telegram: Telegram messaging service
amazon: Amazon shopping platform
google: Google account services
office365: Microsoft Office 365
instagram: Instagram social media
linkedin: LinkedIn professional network
twitter: Twitter/X social media
skype: Skype calling service
viber: Viber messaging app
facebook: Facebook social network
flipkart: Flipkart shopping platform (India)
bukalapak: Bukalapak shopping platform (Indonesia)

Error response fields (when status = 4):

error: Error code
error_description: Human-readable error message

status: Response status code:

0: Success - all platforms checked successfully
4: Partial Reply - some platform checks failed

status_message: Human-readable status message

Note: Platform availability may vary by country. Some platforms are only available in specific regions.

Values: 1 = active, 0 = not active, -1 = unknown

Code Examples

curl -H 'X-Auth: YOUR_API_KEY' \
'https://callerapi.com/api/online-presence/40721987086'

import requests

phone = "40721987086"
url = f"https://callerapi.com/api/online-presence/{phone}"
headers = {
    "X-Auth": "YOUR_API_KEY"
}

response = requests.get(url, headers=headers)
print(response.json())

const phone = '40721987086';
fetch(`https://callerapi.com/api/online-presence/${phone}`, {
    headers: {
        'X-Auth': 'YOUR_API_KEY'
    }
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));

$phone = "40721987086";
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://callerapi.com/api/online-presence/$phone");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('X-Auth: YOUR_API_KEY'));

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
print_r($data);

KYC Match

Verify identity information against mobile network operator records.

POST https://callerapi.com/api/kyc/{phone}

Request Body

{
    "name": {
        "first_name": "John",
        "middle_name": "Robert",
        "last_name": "Smith"
    },
    "dob": {
        "day": "2",
        "month": "11",
        "year": "1985"
    },
    "address": {
        "street": "Omnia",
        "street_no": "23",
        "unit_no": "11A",
        "city": "Toronto",
        "state": "Ontario",
        "postcode": "M4B1B3",
        "country": "CA"
    },
    "email": "[email protected]"
}

Response

{
    "kyc_results": {
        "first_name_score": 100,
        "last_name_score": 100,
        "middle_name_score": -1,
        "address_score": 78,
        "dob": 50,
        "email_score": 100
    },
    "status": 0,
    "status_message": "Success"
}

Field Descriptions

Request Fields

name: Object containing name components to verify

first_name: First/given name
middle_name: Middle name (optional)
last_name: Last/family name

dob: Object containing date of birth components

day: Day of birth (1-31)
month: Month of birth (1-12)
year: Year of birth (4-digit format)

address: Object containing address components

street: Street name
street_no: Street number
unit_no: Apartment/unit number (optional)
city: City/town name
state: State/province/region
postcode: Postal/ZIP code
country: Country code (ISO 2-letter)

email: Email address to verify

Response Fields

kyc_results: Object containing match scores for each verified field

Name component scores:

first_name_score: Match score for first name
middle_name_score: Match score for middle name
last_name_score: Match score for last name

Address component scores:

address_score: Overall match score for the entire address
street_name_score: Match score for street name
street_no_score: Match score for street number
unit_no_score: Match score for unit number
city_score: Match score for city
province_score: Match score for state/province
postcode_score: Match score for postal code
country_score: Match score for country

dob: Match score for date of birth
email_score: Match score for email address

status: Response status code (0 = Success)
status_message: Human-readable status message

Score Values

100: Perfect match - exact match with carrier records
75-99: Strong match - high confidence in data accuracy
50-74: Partial match - some matching elements found
1-49: Weak match - low confidence in data accuracy
0: No match - data exists but does not match
-1: Unknown - carrier has no data for comparison

Note: Different carriers may use different matching algorithms. Some use percentage-based scoring while others use simple match/no-match (converted to 100/0). All responses are normalized to the -1 to 100 scale.

Code Examples

curl -X POST -H 'X-Auth: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
    "name": {
        "first_name": "John",
        "middle_name": "Robert",
        "last_name": "Smith"
    },
    "dob": {
        "day": "2",
        "month": "11",
        "year": "1985"
    },
    "address": {
        "street": "Omnia",
        "street_no": "23",
        "unit_no": "11A",
        "city": "Toronto",
        "state": "Ontario",
        "postcode": "M4B1B3",
        "country": "CA"
    },
    "email": "[email protected]"
}' \
'https://callerapi.com/api/kyc/40721987086'

import requests

phone = "40721987086"
url = f"https://callerapi.com/api/kyc/{phone}"
headers = {
    "X-Auth": "YOUR_API_KEY",
    "Content-Type": "application/json"
}
data = {
    "name": {
        "first_name": "John",
        "middle_name": "Robert",
        "last_name": "Smith"
    },
    "dob": {
        "day": "2",
        "month": "11",
        "year": "1985"
    },
    "address": {
        "street": "Omnia",
        "street_no": "23",
        "unit_no": "11A",
        "city": "Toronto",
        "state": "Ontario",
        "postcode": "M4B1B3",
        "country": "CA"
    },
    "email": "[email protected]"
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

const phone = '40721987086';
const data = {
    name: {
        first_name: "John",
        middle_name: "Robert",
        last_name: "Smith"
    },
    dob: {
        day: "2",
        month: "11",
        year: "1985"
    },
    address: {
        street: "Omnia",
        street_no: "23",
        unit_no: "11A",
        city: "Toronto",
        state: "Ontario",
        postcode: "M4B1B3",
        country: "CA"
    },
    email: "[email protected]"
};

fetch(`https://callerapi.com/api/kyc/${phone}`, {
    method: 'POST',
    headers: {
        'X-Auth': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));

$phone = "40721987086";
$data = array(
    'name' => array(
        'first_name' => "John",
        'middle_name' => "Robert",
        'last_name' => "Smith"
    ),
    'dob' => array(
        'day' => "2",
        'month' => "11",
        'year' => "1985"
    ),
    'address' => array(
        'street' => "Omnia",
        'street_no' => "23",
        'unit_no' => "11A",
        'city' => "Toronto",
        'state' => "Ontario",
        'postcode' => "M4B1B3",
        'country' => "CA"
    ),
    'email' => "[email protected]"
);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://callerapi.com/api/kyc/$phone");
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'X-Auth: YOUR_API_KEY',
    'Content-Type: application/json'
));

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
print_r($result);

API Reference

Authentication

API Key

Get User Information

Response

Code Examples

Get Phone Number Information

Response

Field Descriptions

Main Fields

Business Information

Carrier Information (HLR)

Complaints

Code Examples

KYC API

Pricing

Network Intelligence

Advanced Verification

Get Porting Information

Response

Field Descriptions

Porting Information Fields

Code Examples

Get Porting History

Response

Field Descriptions

Porting History Fields

Code Examples

Get Port Fraud Risk

Response

Field Descriptions

Port Fraud Risk Fields

Code Examples

Get Online Presence

Response

Field Descriptions

Online Presence Fields

Code Examples

KYC Match

Request Body

Response

Field Descriptions

Request Fields

Response Fields

Score Values

Code Examples