# SearchPhone: correlating phone numbers across six data sources, with API rate limits to manage

> SearchPhone is a Python terminal tool that runs phone number lookups across Google, GitHub, Reddit, DuckDuckGo, Numverify and the Hudson Rock Cavalier infostealer database in a single session. Three of those sources require paid API credentials with monthly limits, and none of the integration libraries in requirements.txt are official SDKs.

**HackUnderway/SearchPhone** — Phone number OSINT toolkit with multi-API search (Google, GitHub, Numverify, Reddit, DuckDuckGo), Hudson Rock infostealer intelligence, and automatic report generation.

- Repository: https://github.com/HackUnderway/SearchPhone
- Website: https://hackunderway.io/
- Stars: 2,030 · Forks: 272
- Language: Python
- License: MIT
- Published: 2026-10-11 · Updated: 2026-10-11 · Language: en
- Canonical page: https://hysenlabs.com/projects/hackunderway-searchphone

## SearchPhone queries six data sources for a phone number, but three require paid API credentials

SearchPhone takes a phone number and queries six separate backends in a single terminal session, collecting everything into a JSON file and a PDF report. Three of those backends serve search purposes: SerpAPI routes Google queries, the GitHub API scans public code, and DuckDuckGo adds a second web engine. Numverify handles carrier and location. Reddit covers social mentions. Hudson Rock's Cavalier API provides the infostealer check.

The Hudson Rock source is free and needs no registration. The other three that require credentials, SerpAPI, Numverify and GitHub, are all available on free plans, but each carries its own request limit. The free tiers differ: SerpAPI gives 250 searches per month, Numverify gives 100 requests per month, and GitHub's personal access token gives 5000 requests per hour. Those caps don't compound; each limit operates independently.

For investigators who already hold these credentials and need cross-source correlation in one session, the bundling is the value. For anyone running just a handful of lookups, managing three separate API accounts adds setup cost before the first query runs.

## phonenumbers library handles local parsing; Numverify adds remote carrier data at 100 requests per free month

SearchPhone uses two separate mechanisms for phone number handling, and the README lists them under different feature headings rather than grouping them together. The phonenumbers library (version 8.13.0 or newer per requirements.txt) does all local parsing and formatting without any network call. It uses internal metadata to validate format and structure.

Numverify makes a separate remote call to return the operator name and the geographic location registered to the number. Each such call counts against the monthly quota of 100 on the free plan. The local phonenumbers validation is unlimited and runs offline; the Numverify carrier lookup is a capped network call.

The distinction matters for anyone building pipelines on top of SearchPhone. A format check on a thousand numbers costs nothing against Numverify. A carrier lookup on each of those thousand numbers would require a paid Numverify plan. The README lists both capabilities but does not call out the quota boundary between them.

## Clone the repository, install five dependencies, and configure .env with three API keys

Setup starts with cloning the repository and entering the project directory:

```bash
git clone https://github.com/HackUnderway/SearchPhone.git
cd SearchPhone
```

Then install the dependencies:

```bash
pip install -r requirements.txt
```

The requirements file lists five packages: requests, colorama, python-dotenv, phonenumbers and fpdf2. There is no SerpAPI SDK, GitHub API client or Numverify library among them; every API interaction goes through the requests library directly.

Copy the example.env file to .env and open it in an editor:

```bash
cp example.env .env
```

Replace the placeholder values with actual credentials:

```bash
NUMVERIFY_KEY=your_numverify_api_key_here
SERPAPI_KEY=your_serpapi_key_here
GITHUB_TOKEN=your_github_token_here
```

After credentials are in place, start the tool with:

```bash
python3 search_phone.py
```

Python 3.8 or newer is required. The project's compatibility matrix lists five systems, all of which are either Linux security distributions or Windows 11; see the macOS note in the final section.

## No API client SDKs in requirements.txt: every HTTP call goes through the requests library directly

Without a dedicated API client library for any of the integrated services, all HTTP calls in search_phone.py are hand-written against each provider's REST endpoint. When any of those providers changes a response field, endpoint path or authentication method, the code has to be updated manually. There is no SDK version to pin or upgrade, so each upstream change lands directly in the application.

The direct alternative for carrier and location data is querying Numverify's REST endpoint through its own API documentation. That approach uses the same credentials and the same monthly quota as SearchPhone, but the caller controls the exact request structure. SearchPhone's value is bundling that call alongside five other lookups in one session, not reducing the cost or complexity of the Numverify integration itself.

## Hudson Rock Cavalier is free and keyless; the search-by-username endpoint accepts phone numbers directly

The Hudson Rock Cavalier integration stands apart from the other API connections because it requires no registration, no API key and no paid plan. The README links to the Cavalier API endpoint directly, and the URL in that link reveals how the lookup works: it passes the phone number to the search-by-username endpoint, using the number as the value for the username parameter.

The Cavalier database holds records extracted from devices hit by information-stealing malware. A match for the target number means it appeared on a compromised host, connected to the credential set that malware collected from that device. That result has a different character than a carrier lookup or a Reddit mention; it locates the number in a specific class of security incident.

For investigators who want only this infostealer check, the Cavalier endpoint URL in the README can be called directly with any HTTP client by substituting the target number for the sample value in the username parameter. SearchPhone packages it alongside five other lookups, which is more convenient when all six backends are needed in one pass.

## SerpAPI at 250 free monthly searches and Numverify at 100 requests constrain investigation volume

Numverify's free plan gives 100 requests per month. SerpAPI's free plan gives 250 searches per month. GitHub's personal access token allows 5000 requests per hour, a much looser ceiling than the other two. The three limits are not mentioned in the README's prose; they appear only as values in the API keys table, which makes them easy to overlook on a first read.

At 100 requests per month, Numverify is the binding constraint for anyone investigating multiple numbers regularly. SerpAPI's 250 is more than twice that, which gives some room before it becomes the bottleneck. Neither limit is per-investigation; each API call across all phone numbers in a session counts against the same monthly pool.

For higher volumes, both Numverify and SerpAPI offer paid tiers, but those details fall outside what the README covers. Querying Numverify directly through its own REST API uses the same credentials and the same quota as SearchPhone does, so switching to a direct call does not reduce costs, only removes the wrapper.

## macOS is absent from the tested distributions, and bug reports go to email only

The supported distributions table covers five entries: Kali Linux 2026.2, Parrot Security OS 6.3, Windows 11, BackBox 9 and Arch Linux 2024.12.01. macOS does not appear in it. For a Python 3.8+ script with five common dependencies, macOS may work in practice, but the README makes no claim either way and offers no troubleshooting path if it does not.

Bug reports and questions go to info@hackunderway.com per the README's Support section. That is the only documented channel. The repository has a GitHub issue tracker, but the README does not point to it, so anyone debugging a failing API call has to go through email.

The last push was on 2026-08-24, and the repository has no tagged releases. The project is licensed under MIT.

## Conclusion

SearchPhone is a reasonable choice for investigators who hold SerpAPI, Numverify and GitHub credentials and want a single session correlating all of them alongside Hudson Rock infostealer data. It is the wrong choice if you plan more than a handful of lookups per month on free tiers: Numverify caps at 100 requests per month, and that ceiling arrives before SerpAPI or GitHub become constraints. macOS users need to test compatibility themselves, since the tested distributions stop at Linux variants and Windows 11. Before building it into a workflow, check whether search_phone.py's API calls still match the current endpoints for each service.

## FAQ

### What is SearchPhone?

SearchPhone is a Python terminal tool that looks up a phone number across multiple sources: Google via SerpAPI, GitHub code search, Reddit, DuckDuckGo, Numverify for carrier data, and the Hudson Rock Cavalier infostealer database. It generates JSON and PDF reports with the results.

### What API keys does SearchPhone require?

SearchPhone requires three API keys: NUMVERIFY_KEY for carrier lookups, SERPAPI_KEY for Google search results, and GITHUB_TOKEN for code repository search. Hudson Rock Cavalier is the only source that needs no key.

### What does the Hudson Rock integration in SearchPhone tell you?

The Hudson Rock Cavalier API checks whether the phone number has appeared in data collected by information-stealing malware. A result connects the number to a device compromise rather than just confirming carrier information or public web presence.

### Does SearchPhone work on macOS?

macOS does not appear in the README's supported distributions list. The list covers Kali Linux 2026.2, Parrot Security OS 6.3, Windows 11, BackBox 9 and Arch Linux 2024.12.01. The README makes no statement about macOS.

### What output formats does SearchPhone produce?

SearchPhone generates both JSON and PDF reports automatically. The PDF generation depends on the fpdf2 library, which is listed in requirements.txt at version 2.7.0 or newer.

## Sources

- [HackUnderway/SearchPhone on GitHub](https://github.com/HackUnderway/SearchPhone)
- [Issues](https://github.com/HackUnderway/SearchPhone/issues)
- [License: MIT](https://github.com/HackUnderway/SearchPhone/blob/main/LICENSE)
- [Project website](https://hackunderway.io/)
- [README](https://github.com/HackUnderway/SearchPhone/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/hackunderway-searchphone