Skip to content
Report

REST · JSON · Free tier

Phone intelligence API

Check, locate and score any US or Canadian number with one call. Stop fake sign-ups, SMS-pumping fraud and spam callers before they reach your team.

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 key
Base URLhttps://freespy.app/wp-json/freespy/v1
GET/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).

POST/bulk

Up to 50 numbers per call. Body: {"numbers": ["…", "…"]}

GET/reports?number={number}&page=1&sort=new|helpful

Paginated community reports for a number.

POST/reports

Submit a report: number, rating (-1|0|1), category, call_type, caller_name, comment.

GET/trending?days=7&limit=10&npa=

Most-reported numbers in a window, optional area-code filter.

GET/recent?limit=20&category=

Latest community reports (live feed).

GET/heatmap?days=30

Spam volume per area code with coordinates.

GET/areacodes?q=texas

Search the area-code database.

GET/areacodes/{npa}

Area code detail with local time, overlays, top spam.

GET/stats

Network 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"

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 the X-API-Key header.
  • Keys start with fs_. Request one through the contact page. Limits depend on your plan; see pricing.
  • Always check valid and score.level, not just the number. An impossible number returns 200 with valid: 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, plus reason and reason_label when a number breaks numbering-plan rules or sits in a special range.
  • Formatting: number (10 digits), formatted, e164 and variants.
  • Number type: type is one of geographic, tollfree, premium, caribbean, territory, personal, nongeo or government, with country.
  • Location: location has the area code, city, state or province, covered cities, coordinates, time zone, local_time (with a callable flag for the 8 a.m.–9 p.m. window), overlay codes and rate center.
  • Exchange: exchange holds the original block holder and rate center from numbering data.
  • Carrier: carrier has name, line_type, ported, source, fetched_at and estimated. When estimated is 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, a trending flag) and ftc (complaints, robocalls, first and last seen, subjects), which is null when there are no FTC complaints.
  • Verdict: score with score, level, label, advice, confidence and a factors array of {label, impact, detail}.
  • Extras: the newest reports, block_activity (other reported numbers in the same exchange block), verified and removed.

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.

Five steps to start using the FreeSpy API, from requesting a key to caching results
From key request to a working integration.

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=new returns paginated community reports (items, total, pages). Use sort=helpful for the most-upvoted first, and category to 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=30 returns unwanted-report counts per area code with coordinates.
  • GET /areacodes?q=texas searches the area-code database. GET /areacodes/212 returns 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 } }
Table of FreeSpy API HTTP status codes, error codes and what each one means
Every error body includes a code, a message and the HTTP status.

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=1 only 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.

Diagram of a sign-up screening flow using the FreeSpy API to allow, verify or block a phone number
A typical sign-up check: the decision rule stays in your code, the data comes from the API.

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 removed flag 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.

Checklist of allowed and forbidden uses of the FreeSpy API
Keys used to harass or profile people are revoked.

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.

Sources