The manual

Everything List
Viper does.

A working manual for a tool that cleans, carrier-filters and de-duplicates telephone lead files — on your own machine, with the paid step kept for last.

2,020,680

Prefixes, free

32,131,610

Largest file tested

22.3%

Struck for $0 on it

107,550

Lookups per second

Installing

List Viper is a Windows application. It installs for you alone — no administrator rights, no service, no driver, nothing written outside your own user folder.

Download the installer from listviper.com/download.
Run it. Accept the default location unless you have a reason not to.
It opens in its own window when finished.

⚠

Windows may warn you the first time. The installer is signed as Pinkviper LLC, but a new signing certificate has no reputation with SmartScreen yet, so the blue “Windows protected your PC” box can still appear. Click More info — the publisher must read Pinkviper LLC. If it says anything else, it is not our file. The SHA‑256 of every release is published on the download page so you can check it yourself.

First run

On a fresh install List Viper offers to fetch the carrier block table. Say yes. It is about two megabytes from NANPA, takes a few seconds, and it is the thing that strips landline and VoIP numbers out of a file for nothing. Without it the free filtering layer is missing and you would be paying a validation service to tell you things the public numbering plan already knows.

The second step offers to store an IPQualityScore API key. That one is optional and only matters when you want paid validation. The key is tested with a single live lookup before it is accepted; if the test fails the key is saved but left switched off, so nothing can run against a broken key by accident.

What it reads

Files	CSV, TXT, or any delimited text. No size limit — files are read straight from disk rather than loaded into memory, so a 20 GB list starts immediately instead of being copied first.
Delimiters	Comma, tab, pipe or semicolon, detected automatically.
Encodings	UTF‑8, UTF‑8 with BOM, Windows‑1252, Latin‑1.
Headers	Detected if present, and matched to roles by name. Where the header disagrees with the data, the data wins — a column headed `firstname` that is full of email addresses is treated as email.
Phone column	Found by the shape of the numbers, not the header text, so unlabelled columns still work.

The four-step method

Everything in List Viper is arranged around one idea: the step that costs money runs last, and only on what survived the free ones. Carrier resolution goes through four layers, cheapest first, and each is tried before the one below it.

The verified cache

Every answer you have ever paid for, kept forever. Lead files overlap heavily month to month, so the same numbers keep coming back. Look one up once and never buy that answer again.

already paid for

The NPA-NXX block table

Which carrier was originally assigned each thousand-number block. Published by NANPA rather than sold, so it costs nothing to run — and looking up 27 million numbers is 27 million array reads with no network and no per-row cost.

free forever

The vendor's own carrier column

If the file came with one, it is used — but never trusted blindly. Run Vendor accuracy to find out how often that column is actually right before relying on it.

free, if present

The paid lookup

Runs last, on distinct numbers only, and only on what survived every free filter above. The bill tracks deliverable leads rather than file size.

costs credits

💰

Why the order matters. On a real 32,131,610-row file the free layers struck 7,151,542 rows — landline, VoIP and duplicates — before a single credit was spent. At $0.022 a lookup that is roughly $157,000 of validation not bought.

⚠

Block data is reliable for line type, approximate for brand. Number portability means a number assigned to one carrier may now be carried by another. Use it to strike landline and VoIP with confidence; do not present it to a client as a verified brand. Every output carries a carrier_source column so you can always see which layer answered.

Carrier groups

Rather than picking carriers one at a time, filter by group. Every spelling of a carrier maps to one name first, so ticking AT&T also catches AT&T Mobility, SBC, Cingular and New Cingular Wireless.

Group	What it holds
Major wireless	AT&T, Verizon, T-Mobile
Regional wireless	Smaller networks operating their own spectrum
MVNO / prepaid	Resellers riding a host network — Cricket maps to AT&T, and so on
Landline	Fixed lines
VoIP	Internet-carried numbers
Unrecognized / blank	No answer from any layer — decide deliberately whether to keep these

ⓘ

“Top three carriers” is ambiguous. Brands only, or the networks including the MVNOs riding them? It is roughly a two-fold difference in volume. Decide which your client means before quoting them a count.

Columns and detection

After a file is added, the Columns panel shows what each column was detected as. Change anything that looks wrong — the detection is good but a vendor can always surprise it.

Fields List Viper understands natively include phone, carrier, line type, first and last name, full name, address, city, state, ZIP, email, date, date of birth, gender and IP. Anything else you care about can be kept as a custom field: give it a name, point it at a column, and it travels through to the output.

ⓘ

Keep extra columns is on by default, so columns List Viper does not recognise are passed through untouched rather than dropped.

The tools

Clean & filter free

Carriers, states, duplicates, tags

The main tool. Point it at one or more files, choose what to keep, and it streams through in a single pass writing a clean output file.

It handles carrier and line-type filtering, area code and state and time-zone filtering, exact de-duplication by phone number, suppression against your master lists, placeholder scrubbing, email cleaning, lead-age limits and do-not-call columns.

Rejects file. Turn on “Also write a rejects file” and everything struck is written out separately with the reason. This is how you check a filter did what you expected before trusting a 30-million-row run.

Quick clean free

Paste numbers or emails, get them back

For the times you have forty numbers in an email and want them tidied now. Everything happens in memory, the result comes straight back, and nothing is written unless you ask to export it.

Sample maker free

Pull a test batch out of a big list

Three ways to take a sample, and which you want depends on why you are sampling:

Every Nth — spread evenly across the file, so the sample inherits whatever ordering the file has, by area code or by vendor batch.
Random — for statistical work, like measuring vendor accuracy.
First N — fastest, for a quick look at the shape of a file.

ⓘ

Use this before a paid run. A sample of a few thousand tells you what the file is worth without spending on all of it.

List counter free changes nothing

See what a file holds, change nothing

The tool for the question “what did I just buy?” How many numbers are valid, how many are duplicates, which carriers dominate — and the one that catches people out, how much of each column is actually filled in rather than merely present.

Data health free changes nothing

What is wrong, and which setting fixes it

Scans a file and lists what is wrong with it: what the problem is, how many rows it touches, how serious it is, and which setting on Clean & filter fixes it.

Nineteen checks, ranked by severity — unreadable rows and do-not-call flags at the top, then unusable and missing phone numbers, duplicates, dead area codes, toll-free and non-geographic numbers, placeholder junk, stale leads, landline and VoIP counts, international numbers, unknown carriers, state columns that disagree with the area code, bad emails, and rows re-aligned after a stray delimiter.

It never edits anything. “Fix” means turning those settings on and running Clean & filter — because a tool that can quietly rewrite a vendor's file is a tool that can quietly destroy the only copy of it.

ⓘ

Run it on the raw file, not the cleaned one. On a file you have already cleaned it will report zeros, which only confirms the clean worked. On the vendor's original it tells you what you actually bought — and the state-mismatch check is a good tell for a list stitched together from several sources and resold.

Append fields free

Fill a stripped file back out from a master

Clicker exports arrive with most columns gone — a phone number, maybe a timestamp, nothing else. The data still exists in the master file the leads came from, so this matches one against the other and puts the missing fields back.

The join indexes by the smaller file's keys and holds only matched rows, so memory tracks the small side. A 400,000-row clicker file against a 10-million-row master is comfortable.

IPQS clean spends credits

Validate, filter and enrich with IPQS

A validation service knows far more about a number than which carrier holds it: whether the line is live, whether it is prepaid, whether it sits on the do-not-call registry, whether it has been seen in recent abuse, and a fraud score. All of that comes back from the same lookup, so a run that already paid for the carrier gets the rest for free.

💰

This is the tool that spends IPQS credits. Run the free filters first. Every number it resolves is written to the cache, so you never pay for the same answer twice.

Carrier verify free first

Confirm the real carrier, cheapest source first

Resolves who actually carries each number, walking the four-step method in order. Only the last step costs anything, and it is skipped entirely unless you ask for it.

Output carries a carrier_source column so a verified answer is never confused with a block-table guess.

Vendor accuracy may spend credits

Is their carrier column any good?

Takes a random sample, resolves each number properly, and compares that against what the vendor claimed. The output is one number per vendor: how often their carrier column agrees with the truth, and where it goes wrong.

Worth running once on every new supplier. A vendor whose carrier column is 60% right is a vendor whose file you must re-resolve yourself — which changes what their data is worth to you.

Litigator & validation spends credits

Paid lookups, kept on a budget

Runs a paid service over a file within a budget. It never simply “runs on the file”: it collects the distinct numbers first, stops at a cap you set, and tells you the cost before and after.

Two services, and you choose which. The default is the Blacklist Alliance litigator scrub, which checks numbers against Blacklist Alliance’s register of known TCPA litigators and serial filers. The alternative is phone validation via IPQualityScore. They are separate vendors with separate accounts and separate billing — a Blacklist Alliance scrub spends no IPQS credits, and vice versa.

Numbers the service flags are written to a suppression file, which Clean & filter can then strike on every future run. So one paid scrub keeps paying off.

Distinct matters — a lead file repeats numbers constantly, and paying twice for the same answer is pure waste.

Setup panels

Data prospects

A small CRM for people who want data from you: how they got in touch (Telegram, Signal, Messenger, Teams and so on), what they asked for, what you quoted, and any notes. It tracks stages, deal value and what needs attention — overdue, due today, quiet, adrift, undated, unpriced.

Carrier data

Where the block table and the verified cache live. Import or refresh the NANPA file here, and see how many prefixes and cached answers you hold. NANPA republish on a roughly quarterly cycle; re-importing is a few seconds and worth doing when you remember.

Master lists

Suppression lists that persist between runs — one for phone numbers, one for email addresses. They are a stored object rather than files you re-attach each time, so the count is always visible. A suppression step that silently does nothing because the list is empty is worse than no suppression step at all.

Automated rules

Settings applied to every run, so the things you always want are not one forgotten checkbox away from being skipped.

Services

API keys for the two paid services, which are separate accounts with separate billing:

IPQualityScore — phone validation, line status, prepaid, do-not-call, abuse history and fraud score. Used by IPQS clean, by Carrier verify when it reaches the paid step, and by Litigator & validation if you switch it to Phone validation.
Blacklist Alliance — the litigator scrub, for known TCPA litigators and serial filers. Used by Litigator & validation, and it is what that tool does by default.

Both are inert without a key, and neither can spend the other's balance. A key that fails its test is saved but left switched off rather than reported as working — a service that claims to be configured while failing every lookup is worse than one that is plainly not set up.

Trial and licensing

The trial runs 7 days with the full product and a cap of 250,000 rows per run. No card, no account.

ⓘ

Why a row cap and not just a clock. The value here is concentrated rather than continuous — somebody with a thirty-million-row backlog could clean the lot inside a week and never come back. A row cap makes the trial “proof it works on your own data” rather than “the whole product free for a week”. It is generous enough to run a real file and see real results.

Buying gives you a licence key. Paste it into Licence and the cap lifts immediately.

The licence is perpetual. It never expires and the software never stops working.
Updates are included for 12 months. After that the version you have carries on exactly as it is; newer versions are optional at $197 a year.
Bound to a machine on first use. The key is not machine-specific when issued, so it can be sent to you without anyone knowing anything about your hardware. The first machine to activate it claims it. Moving to a new PC is a deliberate act — Release — rather than a support ticket.

Updates

List Viper checks for a newer version and tells you if one exists. Nothing installs itself silently — software that replaces itself while you are twenty minutes into a twenty-million-row run is not being helpful.

Every update is signed. The signature covers the version, the download URL and the SHA‑256 of the installer, and the hash is checked before anything runs. A tampered manifest fails the signature; a swapped installer fails the hash. Neither ever reaches the point of being executed.

What leaves your machine

Your lists are read off your disk and written back to it. No upload, no account, no cloud bucket, no telemetry. Two things do leave, and it is worth being exact:

A phone number, when you ask to buy a lookup for it. That is the lookup.
Once a day, a licensed copy reports its licence ID, an anonymous machine fingerprint and the version number, so a key that was refunded or passed around can be switched off. No names, no lists, no rows.

If that report never gets through, nothing stops working. The licence is verified offline by signature and the check-in is only ever advisory.

Troubleshooting

“Windows protected your PC”

Click More info and check the publisher reads Pinkviper LLC. The installer is correctly signed; a new certificate simply has not accumulated SmartScreen reputation yet. Compare the SHA‑256 against the one published on the download page if you want certainty.

The window opens but says it cannot reach the page

Fixed in 1.0.3. If you are on an older build, close it and reopen; upgrading is the real fix.

A run says KEPT 0

Almost always a filter that excluded everything. The usual cause is filtering to a carrier group that the file does not contain — check the rejects file, which names the reason each row was struck. If it says carrier not selected for everything, widen the groups or check whether the block table is imported.

Reading the file layout is slow to start

On a very large file the first pass has to sniff the delimiter, encoding and headers before it can report progress. It is working. Do not click Run again — you will queue a second job over the top of the first.

A column came through as the wrong thing

Open the Columns panel and set it by hand. Where a header and the data disagree, the data wins, which is usually right — but a column of numeric IDs that looks like ZIP codes is exactly the case to correct manually.

Carrier verify is taking hours

Make sure the block table is imported under Carrier data. Without it, every number falls through to the slowest layer.

Common jobs

Pre-scrub a file before spending on validation

Data health on the raw file — see what you bought.
Clean & filter: untick Landline, VoIP and Unrecognized, leave de-duplication on.
Only then IPQS clean on the survivors.

The credits you spend now track deliverable leads rather than file size.

Check a new supplier before buying again

Sample maker — random, a few thousand rows.
Vendor accuracy on the sample.
If their carrier column is poor, price their next file as raw data rather than carrier-resolved data.

Never call the same lead twice

Add delivered numbers to a Master list.
Switch suppression on in Automated rules so it applies to every run.

Rebuild a stripped clicker export

Append fields, clicker file as the input, original master as the source.
Match on phone number; the missing columns come back.