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.
The FreeSpy API gives your software the same answer a person gets on a number page: whether a US or Canadian number can exist, where it was issued, what kind of line it is, what people and the FTC have reported, and a 0–100 risk score with every factor listed. This guide covers keys, requests, response fields, errors, caching and the rules for using the data responsibly.
Key takeaways
- It’s a JSON REST API at
https://freespy.app/wp-json/freespy/v1. Send your key in theX-API-Keyheader. - Keys start with
fs_. Request one through the contact page. Limits depend on your plan; see pricing. - Always check
validandscore.level, not just the number. An impossible number returns 200 withvalid: false. - Cache results on your side and use live carrier checks only when you need the current carrier.
- The data is for screening calls and numbers, never for tracking down or profiling people.
What the API returns
A lookup runs the same pipeline as the website, described on the How it works page. One call to /lookup/{number} returns:
- Validation:
valid, plusreasonandreason_labelwhen a number breaks numbering-plan rules or sits in a special range. - Formatting:
number(10 digits),formatted,e164andvariants. - Number type:
typeis one ofgeographic,tollfree,premium,caribbean,territory,personal,nongeoorgovernment, withcountry. - Location:
locationhas the area code, city, state or province, covered cities, coordinates, time zone,local_time(with acallableflag for the 8 a.m.–9 p.m. window), overlay codes and rate center. - Exchange:
exchangeholds the original block holder and rate center from numbering data. - Carrier:
carrierhasname,line_type,ported,source,fetched_atandestimated. Whenestimatedis true, the carrier is the original block holder and the line type is a guess. - Evidence:
community(totals, last 7 and 30 days, top category, a 90-day timeline, atrendingflag) andftc(complaints, robocalls, first and last seen, subjects), which isnullwhen there are no FTC complaints. - Verdict:
scorewithscore,level,label,advice,confidenceand afactorsarray of{label, impact, detail}. - Extras: the newest
reports,block_activity(other reported numbers in the same exchange block),verifiedandremoved.
Line types are mobile, landline, fixed_voip, nonfixed_voip, voip, tollfree, premium or unknown. Levels are unknown (no reports yet), safe, caution, suspicious and danger, matching the verdict bands 0–24, 25–49, 50–74 and 75–100.
Getting a key
Use the “Get an API key” button above, which opens the contact form with the API topic selected. Tell us what you’re building and roughly how many lookups you expect. Keys look like fs_ followed by 37 lowercase hex characters. Treat yours like a password: keep it on your server, out of browser code and public repositories.

Authentication
Send the key in a header. Three forms are accepted, in this order of preference:
X-API-Key: fs_your_key
Authorization: Bearer fs_your_key
?api_key=fs_your_key (query string; avoid, since URLs end up in logs)
A malformed, unknown or revoked key returns 401. A request with no key at all may be refused or held to a small anonymous allowance, so production code should always send one.
Endpoints and example requests
All examples use the fictional number (202) 555-0147 with demo data. On the live API, numbers from 555-0100 to 555-0199 come back flagged as fictional, so test with a real number from your own records.
Look up one number
GET /lookup/{number} accepts any common format: 2025550147, +12025550147 or (202) 555-0147 URL-encoded. Optional parameters: reports (0–50 recent reports to include, default 10) and live=1 for a fresh carrier check, which counts against your live-check allowance.
curl -H "X-API-Key: fs_your_key" \
"https://freespy.app/wp-json/freespy/v1/lookup/2025550147?reports=0"
{
"number": "2025550147",
"formatted": "(202) 555-0147",
"e164": "+12025550147",
"valid": true,
"type": "geographic",
"country": "US",
"location": { "npa": "202", "city": "Washington", "state": "DC",
"tz": "America/New_York",
"local_time": { "time": "3:42 pm", "callable": true } },
"carrier": { "name": "ExampleTel VoIP", "line_type": "nonfixed_voip",
"ported": true, "estimated": false, "source": "twilio" },
"community": { "total": 3, "negative": 3, "last_7d": 3,
"top_category": "bank", "trending": true },
"ftc": { "complaints": 3, "robocalls": 3, "last_seen": "2026-10-07" },
"score": { "score": 85, "level": "danger", "label": "Likely scam",
"confidence": "medium",
"factors": [
{ "label": "Community spam reports", "impact": 28,
"detail": "3 of 3 reports are negative (recent reports count more)." },
{ "label": "FTC Do-Not-Call complaints", "impact": 18,
"detail": "3 complaints filed with the FTC." }
] }
}
The response above is trimmed for space. Fields you don’t need can be ignored safely, and new fields may be added over time, so parse by name rather than position.
Check a list
POST /bulk takes up to 50 numbers per call and returns one flat row per number, built from cached data. It’s the same engine as the bulk lookup page.
curl -X POST -H "X-API-Key: fs_your_key" \
-H "Content-Type: application/json" \
-d '{"numbers": ["(202) 555-0147", "312-555-0199", "123-456"]}' \
"https://freespy.app/wp-json/freespy/v1/bulk"
[
{ "input": "(202) 555-0147", "number": "2025550147", "valid": true,
"type": "Geographic", "location": "Washington, DC",
"line_type": "Non-fixed VoIP", "carrier": "ExampleTel VoIP",
"reports": 3, "ftc": 3, "score": 85, "level": "danger",
"verdict": "Likely scam", "url": "https://freespy.app/phone/2025550147/" },
{ "input": "123-456", "valid": false,
"reason": "Not a valid 10-digit US/Canada number." }
]
Reports, feeds and reference data
GET /reports?number=2025550147&page=1&per_page=10&sort=newreturns paginated community reports (items,total,pages). Usesort=helpfulfor the most-upvoted first, andcategoryto filter.GET /recent?limit=20&category=&npa=returns the newest reports across the site, the same data as the recent reports feed.GET /trending?days=7&limit=10&npa=returns the most-reported numbers in a window of 1 to 365 days, with report counts, top category, score and a 14-day sparkline.GET /heatmap?days=30returns unwanted-report counts per area code with coordinates.GET /areacodes?q=texassearches the area-code database.GET /areacodes/212returns one code with its local time, overlays and recent spam.
Report objects include the category, call type, rating (−1 unwanted, 0 unsure, 1 safe), the caller name the reporter heard, the comment and a general reporter location. They never include IP addresses or the reporter’s phone number.
Errors and rate limits
Errors come back as JSON with a machine-readable code, a human message and the HTTP status in data.status:
{ "code": "nt_quota",
"message": "Daily API quota exceeded for this key.",
"data": { "status": 429 } }

Input that can’t be read as a 10-digit number returns 400 with code nt_invalid on lookups, and 422 when you submit a report. An unknown area code on /areacodes/{npa} returns 404.
Limits depend on your plan; see pricing. Usage is counted per key per day, and live carrier checks have a separate, smaller allowance. On a 429, back off and retry later instead of retrying in a tight loop. If a lookup with live=1 hits the limit, repeat it without live to get cached data.
Watch out: a well-formed but impossible number, such as one with an area code starting with 1, is not an HTTP error. It returns 200 with valid: false, a reason, and a score of 88. Branch on valid, not just on the status code.
Caching advice
Lookup responses are sent with Cache-Control: no-store so you always get current data from us. That doesn’t mean you need to ask every time. Sensible defaults:
- Numbering facts (validity, type, location, time zone) almost never change. Cache them for weeks.
- Carrier and line type change when a number is ported. Cache for days to weeks, and use
live=1only when the answer feeds a decision, such as blocking a sign-up. - Score and reports move as new reports arrive. Hours to a day is reasonable for screening. For a call ringing right now, look it up fresh.
- Trending and heatmap data is meant for dashboards. Polling every few minutes is plenty.
Store the generated_at timestamp with each cached result so you know how old your data is.
Common use cases
Call-center screening. Look up inbound caller IDs before routing. Send danger calls to an automated verification step, flag suspicious ones for the agent, and let the rest through. Remember that caller ID can be spoofed, so a clean score doesn’t confirm who is calling.
CRM cleanup. Run stored phone fields through /bulk to catch impossible numbers, fictional numbers typed into forms, and wrong country assumptions. The local_time and callable fields help sales teams avoid calling outside permitted hours.
Fraud checks at sign-up. When a new account enters a phone number, check valid, type and carrier.line_type. Premium-rate and Caribbean numbers deserve a second look before you send them an SMS code, since they’re used in SMS-pumping fraud. A non-fixed VoIP number isn’t proof of fraud, but combined with other signals it can justify extra verification.

Responsible use
FreeSpy data describes phone numbers. It must not be turned into a tool for finding, watching or pressuring people. By using the API you agree to these rules:
- Don’t use the API to harass, threaten or contact anyone because of what a report says.
- Don’t combine FreeSpy data with other sources to build profiles of individuals or to identify who owns a number.
- Don’t use scores as the only basis for decisions about credit, employment, housing or insurance.
- Don’t republish reports in bulk or present them as verified facts. They are individual accounts.
- Respect removals: if a number’s
removedflag is true, drop any reports you cached for it. - Follow the telemarketing and privacy laws that apply to you. In the US that includes the TCPA and the Do Not Call rules; in Canada, the CRTC’s rules and the National DNCL. This guide isn’t legal advice, so check with a lawyer for your case.
Keys used against these rules are revoked. If you’re unsure whether your use fits, ask through the contact page before you build.

Frequently asked questions
Is there a free tier?
Yes, light use is free. Higher volumes and more live carrier checks are on paid plans. The current limits are on the pricing page.
Can I call the API straight from a browser or mobile app?
Don’t. Anyone can read a key shipped inside an app or web page. Call FreeSpy from your own server and pass only the fields you need to the client.
Can I submit reports through the API?
Yes, with POST /reports and the fields number, rating, category, call_type, caller_name and comment. Reports go through the same limits and moderation as the website form. An invalid number returns 422.
Why does a number show “No reports yet” with a low score?
The level unknown means there were no reports and no FTC complaints to judge by. Treat it as unknown, not as safe.