Sign-up screening
Block disposable VoIP numbers and known spam lines when people register.
Call-center routing
Score incoming callers and send high-risk calls to verification.
SMS fraud defence
Spot the premium and Caribbean numbers used in SMS-pumping attacks.
Lead quality
Check phone fields and add line type, time zone and region.
Endpoints
Get an API keyhttps://freespy.app/wp-json/freespy/v1/lookup/{number}Full lookup: validation, location, time zone, carrier & line type, community reports, FTC complaints, risk score with factors. Add ?live=1 for a fresh carrier check (uses live quota).
/bulkUp to 50 numbers per call. Body: {"numbers": ["…", "…"]}
/reports?number={number}&page=1&sort=new|helpfulPaginated community reports for a number.
/reportsSubmit a report: number, rating (-1|0|1), category, call_type, caller_name, comment.
/trending?days=7&limit=10&npa=Most-reported numbers in a window, optional area-code filter.
/recent?limit=20&category=Latest community reports (live feed).
/heatmap?days=30Spam volume per area code with coordinates.
/areacodes?q=texasSearch the area-code database.
/areacodes/{npa}Area code detail with local time, overlays, top spam.
/statsNetwork totals, 30-day volume and category mix.
curl -H "X-API-Key: fs_your_key" \
"https://freespy.app/wp-json/freespy/v1/lookup/2025550147?live=1"const res = await fetch("https://freespy.app/wp-json/freespy/v1/lookup/2025550147", {
headers: { "X-API-Key": "fs_your_key" }
});
const { score, carrier, location } = await res.json();
console.log(score.score, score.label, carrier.line_type);import requests
r = requests.get("https://freespy.app/wp-json/freespy/v1/lookup/2025550147",
headers={"X-API-Key": "fs_your_key"}, timeout=10)
data = r.json()
print(data["score"]["score"], data["score"]["label"])$res = wp_remote_get( 'https://freespy.app/wp-json/freespy/v1/lookup/2025550147',
[ 'headers' => [ 'X-API-Key' => 'fs_your_key' ] ] );
$data = json_decode( wp_remote_retrieve_body( $res ), true );Sample response
{
"number": "2025550147",
"formatted": "(202) 555-0147",
"valid": true,
"type": "geographic",
"location": { "npa": "202", "city": "Washington", "state": "DC",
"tz": "America/New_York", "local_time": { "time": "3:42 pm", "callable": true } },
"carrier": { "name": "Bandwidth.com", "line_type": "nonfixed_voip", "source": "twilio" },
"community": { "total": 42, "negative": 39, "last_7d": 11, "top_category": "impersonation", "trending": true },
"ftc": { "complaints": 128, "robocalls": 97, "last_seen": "2026-09-29" },
"score": { "score": 91, "level": "danger", "label": "Likely scam", "confidence": "high",
"factors": [ { "label": "Community spam reports", "impact": 48 }, … ] }
}Authenticate with the X-API-Key header (or Authorization: Bearer). Errors use standard HTTP codes: 400 invalid number, 401 missing key, 429 quota exceeded.