Phone Number Lookup API

Phone Number Lookup API is an Apify Actor for RevOps, trust-and-safety, and agent workflows that already have exact phone numbers. Each input number becomes one dataset record with validation, E.164 formatting, country, numbering-plan line type, optional carrier enrichment, optional fraud/name fields, sources, warnings, and lookedUpAt. Carrier and line-type enrichment come from IPQualityScore when that key still has credits, otherwise Veriphone.io static verify (1 credit). RapidAPI Veriphone is an optional fallback only after a missing key or HTTP 401, never after HTTP 402. Fraud score and owner name are filled only when IPQS returns them. The phone-looked-up event is charged only when that enrichment lands.

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.
• Continue with a listing or CRM export Actor when you first need to collect public phone fields, then pass those values into phoneNumbers.

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

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. 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; carrier and lineType (when Veriphone or IPQS filled them) separate mobile from landline; fraudScore is used only when IPQS actually returned it. Format-only rows still give usable numbering-plan data and are not billed as enriched lookups.

Quick start input

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

phoneNumbers is exact-match lookup, not a search box. maxCostUsd stops billed enrichment events; format-only rows stay outside that cap.

Input reference

Field	Type	What it controls
phoneNumbers	array of strings	Exact numbers to look up (required, max 10,000). Prefer E.164.
defaultCountry	string	ISO 3166-1 alpha-2 fallback for local formats. Default US.
maxConcurrency	integer	Parallel lookups, 1–100. Default 20.
includeReverseLookupUrls	boolean	Pre-built manual investigation URLs. Default true. No extra event charge.
includeWhatsAppCheck	boolean	Experimental wa.me format check, not registration. Default false.
includeTelegramCheck	boolean	Public Telegram profile via t.me only. Default true.
enableUnofficialSources	boolean	Reserved no-op flag. Default false.
maxCostUsd	integer	Run-level cap on billed phone-looked-up events. 0 means no cap.

What data you receive

One dataset item represents one input phone number. Useful fields: valid, e164, countryCode, lineType, carrier, fraudScore, name, sources, warnings, lookedUpAt. carrier is filled by IPQS or Veriphone when those providers respond. fraudScore and name stay null when IPQS has no credits. WhatsApp stays off unless you enable the experimental format check.

{
  "inputNumber": "+14155550100",
  "valid": true,
  "formatted": "+1 415 555 0100",
  "e164": "+14155550100",
  "international": "+1 415 555 0100",
  "national": "(415) 555-0100",
  "countryCode": "US",
  "countryCallingCode": "+1",
  "countryName": "United States",
  "region": "CA",
  "city": "San Francisco",
  "lineType": "mobile",
  "carrier": "Example Wireless",
  "fraudScore": null,
  "name": null,
  "whatsApp": null,
  "telegram": {
    "registered": false,
    "publicName": null,
    "publicPhotoUrl": null
  },
  "sources": [
    "libphonenumber",
    "veriphone",
    "telegram",
    "reverse_lookup_urls"
  ],
  "warnings": [
    "IPQS failed (insufficient credits) — trying Veriphone.io",
    "Used Veriphone.io static verify for carrier/line-type after IPQS was unavailable or empty"
  ]
}

city for US/CA can come from a NANPA 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, persisted counts, 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, fraudScore, sources, and warnings. Keep WhatsApp off. Then read the dataset and the OUTPUT outcome. If carrier is null, treat the row as format-only and treat carrier as optional numbering-plan data rather than live HLR, CNAM, or WhatsApp registration.

Starting information: an array of exact phone numbers and an optional defaultCountry. The Actor is read-only against public numbering-plan and provider APIs; it does not place calls. Expected output is one dataset record per number plus OUTPUT/RUN_SUMMARY. Provenance is in sources and lookedUpAt. Cost unit is phone-looked-up only when enrichment lands; cap with maxCostUsd. Configure the hosted MCP connector at https://mcp.apify.com.

Connect the workflow

When you already collected public listing phones, start with Practo Doctor Scraper or Naver Map Scraper — Korean Places, Phone & Menus, then pass the phone field into this Actor as phoneNumbers.

Pricing

This Actor uses Pay per event plus Apify platform usage. Open the live Pricing tab on the Actor page for current event details.

• phone-looked-up is $0.025 per enriched lookup (IPQS or Veriphone landed carrier or line-type).
• Format-only libphonenumber rows are persisted without that event.
• Actor start and Apify platform usage still apply.

Veriphone.io static verify costs the owner 1 credit per successful lookup. HTTP 402 (empty credits) skips Veriphone for the rest of the run; remaining rows stay format-only and unbilled for phone-looked-up. RapidAPI Basic is an optional owner-side fallback after 401 or a missing direct key, not after 402.

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.
• Read sources and warnings before treating carrier or fraudScore as present.

Builder's note

I learned while testing live runs that format-only libphonenumber rows were being billed whenever IPQS had no credits. The Actor now charges the event only when IPQS or Veriphone actually land carrier or line-type, and it records that in sources and warnings.

FAQ

Does every field fill on every number? No. Validation and E.164 come from libphonenumber. Carrier/line-type come from IPQS or Veriphone.io static verify when those providers respond. Fraud score, owner name, active, and CNAM-style name stay null when IPQS has no credits.

Is this live HLR or CNAM? Not unless IPQS returns those fields on the live key. Veriphone.io static mode returns original numbering-plan carrier and line type (1 credit), not a live HLR snapshot and not Current Carrier Lookup.

What does WhatsApp check actually do? An experimental unauthenticated wa.me format check, default off. It is not WhatsApp registration status.

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

Why was a valid number not charged? Format-only rows are useful and free of the phone-looked-up event. Check sources for ipqualityscore or veriphone, and confirm carrier or lineType actually landed from those providers.

Responsible use

This Actor returns public numbering-plan data plus carrier/line-type from the configured providers. It is not a substitute for consent, TCPA, or other legal advice. Do not use it for harassment, unlawful outreach, or to infer sensitive personal data. Respect applicable privacy, telecom, and consumer-protection rules in your jurisdiction.