Phone Number Lookup API avatar

Phone Number Lookup API

Pricing

from $10.00 / 1,000 phone number looked ups

Go to Apify Store
Phone Number Lookup API

Phone Number Lookup API

Validate phone numbers in bulk, or straight from another Apify run's results. Get format, country, carrier, line type and a can-receive-texts flag. Not a WhatsApp or owner lookup. Rows without carrier data are free.

Pricing

from $10.00 / 1,000 phone number looked ups

Rating

1.0

(3)

Developer

Khadin Akbar

Khadin Akbar

Maintained by Community

Actor stats

1

Bookmarked

966

Total users

28

Monthly active users

4 days ago

Last modified

Features

Limited permissionsMulti-tenantServer interface

Share

What is Phone Number Lookup API?

Phone Number Lookup API cleans and enriches phone lists: validation, original carrier and line type. Type numbers, paste or upload a CSV from your CRM or spreadsheet, or pick the results of another Apify run (for example a Google Maps or contact scraper). It returns one dataset record per number with:

  • Text eligibility estimate: smsEligibilityEstimate likely / unlikely / unknown from line type (plus the older canReceiveTexts yes / no / not sure). An estimate, not proof of delivery or consent
  • Validity and formats: valid, E.164, national, international and RFC 3966 formats
  • Location: country, region, and timezones (plus city for many US/CA area codes)
  • Line type: mobile, landline, VoIP, toll-free or premium-rate, with lineTypeSource saying whether it came from the carrier database or a free numbering-plan guess
  • Original carrier: the network the number range was first allocated to (carrierKind: "original_allocation"). If the number was ported to another network, the current carrier can differ
  • Honest status: providerOutcome tells you if carrier data was found, was empty, or the lookup was unavailable, and checkedAt stamps every row
  • Telegram public profile check (optional): public name and photo only when the profile is public
  • Reverse-lookup links: ready-made search URLs so you can research a number by hand

Every row carries a lookupStatus (enriched, format_only, invalid or error) and a charged flag, so you can see which rows were billed.

After each run you also get ready-made download lists (all valid, mobile, landline, unknown type, bad numbers) and a one-line summary such as: "Checked 1,000 numbers: 820 good, 140 bad, 40 repeats (not charged again). 70% mobile, 25% landline, 5% VoIP; 574 can receive texts. Top countries: United States (600), United Kingdom (200)."

Check the phones from another Apify run (3 steps)

Already scraped businesses or contacts on Apify? You don't need to copy the numbers out.

  1. Run your scraper as usual, for example Google Maps Scraper — Emails, Phones & B2B Leads or Contact Details Scraper.
  2. Open this Actor, go to Use results from another Apify run, and pick that run's results.
  3. Click Start.

The Actor finds the phone column for you (for example phone or phones), checks every number, and keeps each row's name, address, website and other simple fields next to the phone info. Open the With your original data view to see them side by side. If the phone column is not found, type its name in Phone column name.

Want this to happen automatically? In your scraper's Integrations tab, add this Actor to run after the scraper finishes, with the input {"datasetId": "{{resource.defaultDatasetId}}"}.

Clean a CSV or spreadsheet export

  1. Paste CSV text into Or: paste a CSV, or upload a .csv file (up to 5 MB, header row required, comma, semicolon or tab separated).
  2. The phone column is found for you (for example Phone, Mobile, Telephone). If not, type its name in Phone column name.
  3. Click Start. Every other column (name, email, address) stays next to the phone result in the dataset and in the download lists.
  4. Want to clean first for free? Tick Check format only (free): you get valid / bad lists, E.164 and a basic line-type guess with no carrier lookup and no charge per number. Run again with it off when you want carrier data.

Download lists are spreadsheet-safe: a cell that would run as a formula in Excel or Sheets starts with an apostrophe.

Download lists and run summary

Open the Output tab after a run:

  • All valid numbers (CSV): every valid, de-duplicated number with your original columns
  • Mobile numbers (CSV): only valid mobile numbers, ready for a text-message list
  • Unknown-type numbers (CSV): valid numbers that are not clearly mobile or landline (VoIP, toll-free, no data). Check these before texting or calling
  • Landline numbers (CSV): only valid landlines
  • Bad numbers (CSV): numbers to remove from your list
  • Run summary (OUTPUT): the one-line summary above, plus counts by line type and the top countries

When numbers came from another run, each list also has the original row's columns (name, address and so on).

Why it is cheaper on real lists

  • You pay only for numbers with carrier data. Invalid and format-only numbers are saved free. Many tools charge for every row.
  • Duplicates are charged once. If the same number appears twice in your list (even written differently, like +1 415 555 0100 and (415) 555-0100), it is looked up and charged once.
  • Volume discounts. Higher Apify plans pay a lower price per number. See the Pricing tab.
  • Spending cap. Set maxCostUsd and the run stops before it spends more.

What this Actor does not do

  • No WhatsApp lookup. It does not tell you whether a number uses WhatsApp and returns no WhatsApp profile, name or photo.
  • No owner name. It does not identify who owns a number. It is not a people-search or caller-ID tool.
  • No fraud or spam score. It does not rate how risky a number is.
  • Not live HLR and not the current carrier. The carrier is the network the number range was originally allocated to. It is not a live network-status or portability check, so a ported number can show its old carrier.
  • No proof of consent or delivery. Text eligibility is an estimate from line type.

If you need carrier, line type and clean formatting for a list of numbers, this Actor fits. If you need to know who is behind a number, it does not.

Price: the phone-looked-up event is charged only for enriched rows (carrier or line type landed). Format-only, invalid and error rows are saved free. Apify platform usage is included. See the Pricing tab for the current event price.

Best fit for this Actor

  • Start with a list of exact phone numbers when you need validation, E.164, country, and carrier/line type in one record per number.
  • Use defaultCountry when local-format numbers need an ISO country fallback.
  • Turn on requireCarrier when a batch is only useful with carrier data, so a carrier outage stops the run with a clear message instead of returning format-only rows.
  • Already have results from another Apify scraper? Pick them in Use results from another Apify run instead of copying numbers by hand.

This Actor is designed as a focused standalone workflow: you already have phone numbers and want structured lookup rather than a people-search query.

What it costs: examples

Prices are per distinct number with carrier data found. See the Pricing tab for your plan. Start fee is tiny and per run.

Your listBilled numbersFree / Bronze ($0.025)Silver ($0.015)Gold and above ($0.010)
100 numbers, 10 repeats, 5 invalid, 85 with carrier data85$2.13$1.28$0.85
1,000 numbers, 100 repeats, 60 invalid, 800 with carrier data800$20.00$12.00$8.00
Same 1,000 list with Check format only0$0$0$0

Invalid, repeated and no-data numbers are never charged.

What's new

  • CSV and spreadsheet input: paste or upload a CSV, keep your columns, get clean lists back.
  • Honest labels: every row says it is the original carrier, where the carrier and line type came from, and when it was checked.
  • Honest status: if carrier lookup is unavailable the run says so (partial or failed) instead of looking complete. Those rows are free.
  • New download lists: all valid numbers and unknown-type numbers. Spreadsheet-safe.
  • Check format only: free cleaning with no carrier lookup.
  • Spending limit accepts cents (for example 0.50).
  • Big-list guidance: a memory table for lists of 10,000 numbers or more (see Best results).
  • Fewer wasted lookups: numbers with an impossible length are rejected locally and never sent to the carrier lookup.

Workflow: from a messy CRM phone column to a routing decision

A RevOps operator starts with a CRM column of mixed E.164 and US local numbers, with some numbers repeated. They submit the array with defaultCountry: "US", keep WhatsApp off, and read one dataset row per number. valid and e164 decide whether the row can enter a dialer; lineType and carrier separate mobile from landline; lookupStatus tells them which rows have carrier data. Format-only rows still give usable numbering-plan data and are not billed, and repeated numbers are looked up once.

Quick start input

{
"phoneNumbers": [
"+14155550100",
"(415) 555-0101"
],
"defaultCountry": "US",
"maxConcurrency": 10,
"includeReverseLookupUrls": true,
"includeTelegramCheck": true,
"includeWhatsAppCheck": false,
"requireCarrier": false,
"maxCostUsd": 5
}

phoneNumbers is exact-match lookup, not a search box. maxCostUsd (cents allowed, for example 0.50) stops billed phone-looked-up events; free rows stay outside that cap.

Input reference

FieldTypeWhat it controls
phoneNumbersarray of stringsNumbers to look up (up to 10,000; free Apify plan: first 25 different numbers per run). Prefer E.164. Ignored when datasetId, csvText or csvFile is set.
csvTextstringPasted CSV with a header row. Optional.
csvFilestringUploaded CSV file (up to 5 MB). Optional; pasted text is used first.
validateOnlybooleanFree format, country and offline line-type check only. No carrier lookup, no charge. Default false.
datasetIdstringResults (dataset) of another Apify run to take phone numbers from. Optional.
phoneFieldstringPhone column in those results. Optional; found automatically when empty.
defaultCountrystringISO 3166-1 alpha-2 fallback for local formats. Default US.
maxConcurrencyintegerParallel lookups, 1–100. Default 20.
includeReverseLookupUrlsbooleanPre-built manual investigation URLs. Default true. No extra event charge.
includeTelegramCheckbooleanPublic Telegram profile via t.me only. Default true.
includeWhatsAppCheckbooleanExperimental wa.me format check, not registration. Default false.
maxCostUsdnumberRun-level spending limit in USD on billed phone-looked-up events, counted at the highest listed price. Decimals work. 0 means no limit.
requireCarrierbooleanStop with a clear status when carrier lookup is unavailable. Default false.

Row status and billing

lookupStatusMeaningcharged
enrichedCarrier or line type landed from the carrier lookuptrue (one phone-looked-up event)
format_onlyValid number, but no carrier data for itfalse
invalidNumber failed libphonenumber validationfalse
errorThe lookup failed for this numberfalse

providerOutcome explains why: ok (carrier data found, billed), no_data (lookup worked, nothing returned, free), unavailable (lookup failed or out of service, free, retry later), not_attempted (impossible number), skipped_by_request (Check format only). If every valid number comes back unavailable the run ends UPSTREAM_FAILED; if only some do, it ends PARTIAL.

What data you receive

One dataset item represents one input phone number. Useful fields: valid, e164, countryCode, countryName, region, timezones, lineType, lineTypeSource, isMobile, carrier, carrierKind, carrierSource, canReceiveTexts, smsEligibilityEstimate, lookupStatus, providerOutcome, charged, isRepeat, sources, warnings, checkedAt, lookedUpAt. When numbers came from another run, sourceRow holds the original row's simple fields and sourceRowIndex its position. Example (a subset of a real enriched row from October 2026):

{
"inputNumber": "+919876543210",
"valid": true,
"e164": "+919876543210",
"national": "098765 43210",
"countryCode": "IN",
"countryName": "India",
"lineType": "mobile",
"isMobile": true,
"carrier": "Airtel",
"carrierKind": "original_allocation",
"carrierSource": "carrier_database",
"lineTypeSource": "carrier_database",
"canReceiveTexts": true,
"smsEligibilityEstimate": "likely",
"providerOutcome": "ok",
"checkedAt": "2026-10-19T20:12:01.168Z",
"telegram": {
"registered": false,
"publicName": null,
"publicPhotoUrl": null
},
"lookupStatus": "enriched",
"charged": true,
"sources": [
"libphonenumber",
"carrier_lookup_primary",
"telegram",
"reverse_lookup_urls"
],
"lookedUpAt": "2026-10-19T20:12:01.168Z"
}

sources lists what contributed to the row: libphonenumber (validation and formatting), carrier_lookup_primary or carrier_lookup_secondary (carrier and line type), telegram, whatsapp and reverse_lookup_urls. city for US/CA can come from an area-code map even on format-only rows. That is not live HLR.

Use through the API

Replace <APIFY_TOKEN> with your Apify API token. Never paste the token into Actor input.

curl -X POST "https://api.apify.com/v2/acts/khadinakbar~phone-number-lookup-api/runs?waitForFinish=120" \
-H "Authorization: Bearer <APIFY_TOKEN>" \
-H "Content-Type: application/json" \
-d '{"phoneNumbers":["+14155550100"],"defaultCountry":"US","includeWhatsAppCheck":false}'

Read the dataset once the Actor has finished:

curl "https://api.apify.com/v2/datasets/<DATASET_ID>/items" \
-H "Authorization: Bearer <APIFY_TOKEN>"

JavaScript client using the same Actor identity:

import { ApifyClient } from "apify-client";
const client = new ApifyClient({
token: process.env.APIFY_TOKEN
});
const run = await client.actor("khadinakbar/phone-number-lookup-api").call({
phoneNumbers: ["+14155550100"],
defaultCountry: "US",
includeWhatsAppCheck: false
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);

Inspect OUTPUT and RUN_SUMMARY in the default key-value store for outcome, enriched and format-only counts, skipped duplicates (duplicateCount), and charged events.

Use with AI agents through Apify MCP

Look up these exact phone numbers with khadinakbar/phone-number-lookup-api: ["+14155550100"]. Return e164, valid, countryCode, carrier, lineType, lookupStatus, charged and warnings. Keep WhatsApp off. Then read the dataset and the OUTPUT outcome. Treat rows with lookupStatus "format_only" as numbering-plan data without carrier, not as live HLR, CNAM or WhatsApp registration.

Starting information: an array of exact phone numbers (or datasetId with the results of another Apify run) and an optional defaultCountry. The Actor is read-only; it does not place calls or send messages. Expected output is one dataset record per number plus OUTPUT (with an agentSummary sentence) and RUN_SUMMARY. Treat carrier as the original carrier, and smsEligibilityEstimate as an estimate. Provenance is in sources and lookedUpAt. Cost unit is phone-looked-up, only on enriched rows; cap with maxCostUsd. Configure the hosted MCP connector at https://mcp.apify.com.

Connect the workflow

Related Actors from the same author: Email Address Validator (clean the email column of the same CRM export), Bulk Website Contact Extractor and Google Maps Scraper — Emails, Phones & B2B Leads (collect phones and contacts first).

Collect phones first with Google Maps Scraper — Emails, Phones & B2B Leads, Contact Details Scraper, Practo Doctor Scraper or Naver Map Scraper — Korean Places, Phone & Menus, then pick that run's results in this Actor (datasetId).

Pricing

This Actor uses Pay per event with Apify platform usage included. Open the Pricing tab on the Actor page for current event prices.

  • phone-looked-up is charged once per enriched row (carrier or line type landed).
  • format_only, invalid and error rows are saved without that event.
  • A small apify-actor-start event applies to each run.

Worked example: a list of 1,000 numbers with 100 repeats has 900 distinct numbers. If 720 of those come back enriched and 180 format_only, you pay for 720 phone-looked-up events.

Volume discounts: the per-number price is lower on higher Apify plans. Open the Pricing tab to see the price for your plan.

Free Apify plan

Runs started from an Apify free plan process the first 25 distinct phone numbers per run. Every supported mode and output field remains available with the same lookup quality. Extra inputs are not sent to lookup services and are not charged. The dataset contains the completed rows, and the status message plus OUTPUT and RUN_SUMMARY explain when this limit is reached.

Paid Apify plans keep the existing 10,000-number input limit, concurrency options, spending controls, and event prices. This is a per-run allowance, not a monthly allowance. Format-only, invalid, and error rows still have no phone-looked-up event; the existing startup event applies.

Call over HTTP

For a short lookup, open Endpoints and copy this Actor's server URL. Send POST /lookup with the same JSON input fields used by a normal run and your Apify API token in Authorization: Bearer. Read GET /openapi.json for the endpoint schema. GET / checks readiness without a lookup or lookup event.

# Set ACTOR_STANDBY_URL to the server URL shown in Endpoints.
curl --request POST "$ACTOR_STANDBY_URL/lookup" \
--header "Authorization: Bearer $APIFY_TOKEN" \
--header "Content-Type: application/json" \
--data '{"phoneNumbers":["+447911123456"],"includeTelegramCheck":false}'

The response contains outcome, message (a plain-English summary), results and summary. Every result has the same fields as a batch row, including lookupStatus, charged and canReceiveTexts. Repeated numbers in one request (same number in any format) are looked up and charged once and returned once; summary.duplicateCount says how many. Picking another run's results and the download lists are for normal batch runs. Free Apify callers receive up to 25 non-empty inputs per HTTP request; extra inputs are excluded before lookup. Paid callers retain the existing 10,000-input maximum and options. There is a 1 MiB HTTP body limit, at most 256 characters per input, and a four-minute processing window. Large requests may return PARTIAL; use normal batch runs for long jobs, persistent Datasets and exports. Existing batch inputs and normal saved tasks continue to work.

HTTP results use the existing phone-looked-up price per enriched result, with platform usage included. Format-only, invalid and error rows have no lookup event. maxCostUsd (decimals allowed) limits the enriched event total for that request, counted at the highest listed price, so Silver and Gold callers are charged less than the estimate shown in summary.estimatedChargedUsd (estimatedChargedUsdIsMaximum: true). If carrier lookup is unavailable for every valid number the call returns 502 UPSTREAM_FAILED with no charge. The existing startup event remains part of normal run pricing; it is not added as a new manual HTTP-request charge. Billing is attributed to the authenticated caller before the response. If billing cannot be confirmed, the API returns BILLING_UNCONFIRMED without results: do not automatically retry it, because a timed-out charge can be ambiguous.

Responses are returned directly to the caller. The service does not save callers' phone numbers or results in a shared Dataset or key-value record. Save your response if you need an export or history. Busy responses use HTTP 503 with Retry-After; input errors return 400/413/415, missing authentication returns 401, and required upstream or billing failures return 502. A per-request allowance does not impose a monthly quota or prevent repeated requests.

Best results

  • Provide E.164 numbers when you have them; set defaultCountry only for local formats.
  • Keep maxConcurrency at the default 20 unless you have a reason to go lower.
  • Leave includeWhatsAppCheck false unless you explicitly want an experimental format flag.
  • Set maxCostUsd on bulk runs so billed enrichment stays within your budget.
  • Clean first with Check format only (free), then run the carrier lookup on the good numbers.
  • Filter on lookupStatus before treating carrier as present.

Big lists: pick the run memory

The Actor starts with 1024 MB, which suits lists up to a few thousand numbers. For very large lists you can choose more memory in the run options; the total cost stays about the same because the run finishes sooner. Measured on 10,000 numbers (format-only run): 256 MB took 586 s, 512 MB 239 s, 1024 MB 95 s, 2048 MB 48 s. At 2048 MB the start fee is charged twice (one start fee per GB), which is a fraction of a cent.

Builder's note

I learned while testing live runs that format-only rows were being billed whenever the carrier lookup had no data. The Actor now charges the event only when carrier or line type actually lands, and each row says so in lookupStatus and charged.

FAQ

Does every field fill on every number? No. Validation, E.164 and timezones come from libphonenumber. Carrier and line type come from the carrier lookup when it responds; when it has no data the row is format_only and free. Every row tells you the source.

What happens to duplicate numbers? Each distinct number is looked up and charged once per run. Typed repeats (same number, any format) are skipped and counted in RUN_SUMMARY.duplicateCount. When numbers come from another run, every original row still gets its own result row, but repeats are marked isRepeat: true and are not charged again.

Which numbers can receive texts? Use smsEligibilityEstimate (or canReceiveTexts): likely for mobile numbers, unlikely for landlines, toll-free and bad numbers, unknown when it is not clear (for example VoIP). It is based on line type only, not a live delivery test, and it is not consent.

Can it tell me who owns a number, or whether it is on WhatsApp? No. This Actor does not return owner names, WhatsApp registration or WhatsApp profiles. It returns validation, formats, location, line type and carrier.

Is this the current carrier? Is it live HLR or CNAM? No. The carrier is the network the number range was originally allocated to. If the number was ported, the current carrier can differ. Line type is numbering-plan data, not a live HLR snapshot.

Why was a valid number not charged? Its lookupStatus is format_only: the number is valid but no carrier data landed, so the row is free. Check warnings on that row for the reason.

What happens when carrier lookup is unavailable? The Actor saves free format_only rows with providerOutcome: "unavailable" and says so: the run ends PARTIAL (some numbers) or UPSTREAM_FAILED (all valid numbers). With requireCarrier: true it stops early. Nothing is charged for those rows. Retry later, or use Check format only if you only need cleaning.

Can I upload a CSV? Yes. Paste CSV text or upload a .csv file (up to 5 MB). The phone column is found automatically; your other columns stay next to each result.

What does the WhatsApp check actually do? An experimental format check, default off. It cannot tell whether a number uses WhatsApp and returns no WhatsApp profile.

What does the Telegram check actually do? Public-profile detection via t.me. Private Telegram accounts correctly return registered: false.

Responsible use

This Actor returns public numbering-plan data plus carrier and line type. It is not a substitute for consent, TCPA, or other legal advice. Use it only for lawful purposes, and keep it away from harassment, unlawful outreach, or inferring sensitive personal data. Respect applicable privacy, telecom, and consumer-protection rules in your jurisdiction.