Bulk Phone Number Lookup API — High-Throughput Batch Validation
Validate millions of numbers in a single job. LRN, carrier, CNAM, and messaging provider data returned in hours — not days. Pay only for what you query. No subscriptions, no caps, no contracts.
Phone Data Degrades Fast. Bulk Validation Fixes That.
Phone numbers port between carriers, get reassigned, and go dead every month. By the time you launch a campaign or dial a contact center list that's six months old, a meaningful portion of it is stale. The cost of acting on bad data compounds: failed deliveries, wasted agent time, TCPA exposure from dialing reassigned numbers, and suppression lists that are themselves out of date.
Validating numbers one-at-a-time through a synchronous API is impractical at any real scale. VRI's bulk phone number lookup API is built for the volume that matters: submit your full list as a single batch job, get structured results back, and continue — without managing rate limits, retry logic, or connection pooling yourself.
What the Bulk API Returns
Each number in your batch can return any combination of the following data types. Select only what your workflow needs — you're billed only for the lookups you request.
| Data Type | What It Tells You | Price per Number |
|---|---|---|
| LRN (Local Routing Number) | Current porting status and routing destination | Under $0.01 — see pricing |
| Carrier / OCN | Carrier of record — the network that owns the number | Under $0.01 — see pricing |
| Messaging Provider | The network actually delivering SMS (Bandwidth, Twilio, Syniverse, etc.) | Under $0.01 — see pricing |
| CNAM | Caller ID name registered to the number | Under $0.01 — see pricing |
| Line Type | Mobile, landline, VoIP, or toll-free classification | Included with carrier lookup |
Pricing: Pay Only for the Data You Request
Most bulk validation workflows don't need every data type on every number. Request only what your pipeline needs — LRN for current routing and porting, carrier + messaging provider for routing, CNAM for caller ID enrichment. Your cost scales with what you query.
| Lookup Configuration | Price per Number | Best For |
|---|---|---|
| LRN only | Under $0.01 — see pricing | Porting verification, flagging numbers to recheck after a carrier change |
| Carrier + messaging provider | Under $0.01 — see pricing | SMS routing optimization, campaign eligibility |
| CNAM only | Under $0.01 — see pricing | Caller ID enrichment, fraud scoring |
| LRN + carrier + messaging provider | Under $0.01 — see pricing | Full list hygiene before campaign or dialing launch |
No minimums. No monthly caps. No contracts. Run a batch today and another one in six months — you're billed only when you use the API. Free sandbox — no credit card required.
Built for the Workflows That Demand Scale
Pre-Campaign List Cleaning
Sending to stale lists drives up costs, tanks deliverability, and creates TCPA liability. Run your contact list through VRI's bulk API 24–48 hours before launch:
- Filter numbers that return no routing data with LRN validation
- Separate mobile from landline and VoIP before segmentation
- Identify which numbers route through which messaging provider to optimize per-gateway throughput
- Remove numbers that have ported since your last suppression update
Each number costs less than a penny to check, whether you run LRN validation alone or add carrier and messaging provider data. That's a fraction of the cost of a failed send, and a fraction of one FCC complaint. Exact rates are on the pricing page.
Contact Center Data Refresh
Contact center databases degrade over time. Schedule a quarterly or monthly bulk refresh against your full contact database:
- Detect numbers that have ported to a different carrier since last contact
- Flag routing changes since last contact, so you know which numbers to recheck
- Update CNAM records for caller ID accuracy and answer rates
- Identify mobile-to-VoIP transitions that may call for a different outreach strategy
A monthly LRN plus carrier refresh costs less than a penny a record, so even a 1M-record contact database is cheap to keep current. You can start with a $5 balance and see exact rates on the pricing page.
Data Enrichment Pipelines
Data platforms, CRMs, and CDPs often need phone intelligence appended to records at ingest or on a refresh schedule. Submit a nightly or weekly export to VRI's batch endpoint. Results return as structured JSON or CSV, ready to re-ingest into your data warehouse, CRM, or enrichment layer. The API is stateless — no sessions to manage, no persistent connection to keep alive. Submit, poll or receive a webhook, ingest results.
How the Bulk API Works
The bulk API uses an asynchronous job model. You submit a batch, receive a job ID, and retrieve results when the job completes — via polling or a webhook callback.
Async Batch Job Flow
# Step 1: Submit a batch job
POST /v1/bulk/jobs
Authorization: Bearer {api_key}
Content-Type: application/json
{
"numbers": ["12125551234", "13105559876", "..."],
"lookups": ["lrn", "carrier", "messaging_provider"]
}
Response:
{
"jobId": "job_4f8a2c1d",
"status": "queued",
"count": 1000000
}
# Step 2: Poll status
GET /v1/bulk/jobs/job_4f8a2c1d
Authorization: Bearer {api_key}
# Step 3: Retrieve results (status === "complete")
GET /v1/bulk/jobs/job_4f8a2c1d/results
Authorization: Bearer {api_key}
Each result:
{
"number": "12125551234",
"lrn": "12125550000",
"carrier": "T-Mobile",
"messagingProvider": "bandwidth",
"lineType": "mobile",
"ported": true
}Throughput and Processing Times
VRI's batch processing is designed for scale. You submit the job; VRI manages rate coordination against upstream carriers and SS7 networks.
| Batch Size | Estimated Processing Time |
|---|---|
| Up to 10,000 numbers | Under 10 minutes |
| 10,000–100,000 numbers | 15–60 minutes |
| 100,000–1,000,000 numbers | 1–4 hours |
| 1,000,000–10,000,000 numbers | 4–24 hours |
Run multiple batch jobs concurrently. Contact us for limits and enterprise-tier concurrency options if your pipeline needs parallel high-volume jobs running simultaneously.
VRI Bulk PAYG vs. Subscription-Based Lookup Services
Subscription-based phone lookup services were designed for low-volume, recurring use. Monthly caps, overage penalties, and annual contracts make sense if you're running 50K lookups a month like clockwork. They don't make sense if you need to clean 3 million numbers before Q4 and nothing again until spring.
| Feature | VRI Bulk PAYG | Typical Subscription Service |
|---|---|---|
| Pricing model | Per-lookup, billed on use | Monthly flat fee or tiered plan |
| Monthly lookup cap | None | 100K–500K typical; upgrade required for more |
| Overage handling | No overage — same rate at any volume | Higher per-lookup rates or plan upgrade required |
| Contract required | No | Often monthly or annual commitment |
| Messaging provider data | Yes, for less than a penny a lookup | Rarely available as a distinct field |
| Minimum monthly spend | None | $200–$2,000/month depending on tier |
| Async batch job support | Yes — up to millions per job | Often limited or synchronous-only |
If your lookups happen in large irregular bursts — a campaign prep flush, a database acquisition cleanup, an annual hygiene audit — PAYG bulk is almost always the lower-cost model. You pay for the lookup, not for the month.
Frequently Asked Questions
What is a bulk phone number lookup API?
A bulk phone number lookup API lets you query carrier, routing, and identity data for large lists of phone numbers in a single asynchronous batch job rather than one call at a time. You submit the list, the API processes it in the background, and returns structured results when complete. VRI's bulk API supports batches of millions of numbers — far beyond what a synchronous API can handle in a practical workflow.
What data does the bulk lookup return?
Each number can return: LRN (Local Routing Number) for porting and routing status, current carrier/OCN, messaging provider (the actual network delivering SMS — a field most competitors don't surface), CNAM (Caller ID name), and line type (mobile, landline, VoIP, toll-free). You select which data types to include per job and pay only for what you request.
How does VRI's bulk pricing compare to subscription services?
VRI charges per lookup with no monthly minimums, caps, or contracts. Subscription services typically charge a flat monthly fee for a fixed lookup volume and then charge more per lookup when you exceed that cap. Every VRI lookup costs less than a penny, and exact rates are on the pricing page. There's no monthly floor and no annual commitment.
What file formats does the bulk API accept?
Numbers can be submitted as a JSON array in a POST request body, or as a CSV or TXT file upload with one number per line. Numbers are accepted in E.164 format (+1XXXXXXXXXX) or 10-digit NANP format. The API normalizes and deduplicates records before processing begins — you don't need to pre-clean the list.
Is there a minimum batch size for bulk lookups?
No minimum. The async batch endpoint handles jobs from a few hundred numbers up to millions in a single job. For smaller batches under a few hundred numbers, VRI's synchronous single-lookup API is often faster and simpler. Contact us if your volume requirements exceed standard batch limits for a single job.
What is messaging provider lookup, and why does it matter for SMS?
Messaging provider lookup identifies the network gateway — Bandwidth, Twilio, Syniverse, and others — that actually routes SMS to a number. This is distinct from carrier of record. Carrier data tells you who owns the number; messaging provider data tells you where to route the message. For SMS aggregators, CPaaS platforms, and high-volume SMS marketers, that distinction directly affects deliverability, routing cost, and throughput decisions. At less than a penny a lookup, the same price as carrier data, it's one of VRI's clearest differentiators against services that only return carrier-of-record.
There are no minimums or monthly fees, and the sandbox is free with no credit card required. Live lookups cost less than a penny a number, and you can start with a $5 balance.
Get started →Need high-volume access, concurrent jobs, or custom SLAs? Our enterprise plans include dedicated support and competitive rates for large-scale pipelines.
Contact Sales →