A single bad phone number can quietly drain your budget: wasted SMS sends, failed OTP deliveries, and lead lists full of dead digits you keep paying to dial. The fix is one API call that tells you whether a number is real, what kind of line it is, who carries it, and whether it smells like fraud. In the next five minutes you'll learn how to validate phone numbers with API requests using 1Lookup, from your first curl command to production-ready Node.js and Python code.

What You'll Build

By the end of this phone validation API tutorial you'll have a working integration that takes any phone number and returns:

• Validity — is this a real, dialable number in E.164 format?
• Line type — mobile, landline, VoIP, or toll-free
• Carrier — the current network operator serving the number
• Risk signals — a fraud score plus VoIP and prepaid flags
• Compliance flags — whether the number sits on a DNC or DNO list

That's everything you need to clean a lead form, gate a signup, or screen a number before you dial.

Prerequisites

You only need three things:

1. A 1Lookup account and API key — create a free account and grab your key from the dashboard in under a minute.
2. A terminal with curl (already installed on macOS and most Linux distros).
3. Node.js 18+ or Python 3.8+ if you want to run the code examples. Both are optional for the curl steps.

Keep your API key out of source control. Store it in an environment variable like LOOKUP_API_KEY and reference it from there. We'll do exactly that below.

Step 1 — Make Your First Request

The phone validation endpoint lives at https://api.1lookup.io/v1/validate/phone. You authenticate with a bearer token and send a JSON body containing the number and its country. Open a terminal and run:

curl -X POST https://api.1lookup.io/v1/validate/phone \
  -H "Authorization: Bearer $LOOKUP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone":"+14155552671","country":"US"}'

Three things matter here:

• The method is POST. Phone data goes in the request body, never the URL.
• The Authorization header carries your bearer token. Replace the variable with Bearer YOUR_API_KEY directly only when testing — never hardcode keys in committed files.
• country is an ISO country code. It helps the API parse numbers that aren't already in full E.164 format. Pass "US" for North American numbers; the API still normalizes everything to E.164 in the response.

If your key is valid, you'll get a JSON payload back in well under a second. That's the entire happy path. Now let's read it.

Step 2 — Read the Response

A successful call returns a structured JSON object. Here's a realistic example for a valid US mobile number:

{
  "number": "+14155552671",
  "valid": true,
  "line_type": "mobile",
  "carrier": "T-Mobile USA",
  "location": {
    "state": "California",
    "city": "San Francisco",
    "timezone": "America/Los_Angeles"
  },
  "risk": {
    "fraud_score": 12,
    "risk_level": "low",
    "is_voip": false,
    "is_prepaid": false
  },
  "compliance": {
    "dnc_listed": false,
    "dno_listed": false
  }
}

Every field earns its place. Here's how to use them:

• valid is your first gate. If it's false, stop — the number isn't dialable and nothing else matters.
• line_type tells you how to reach the number. mobile numbers can receive SMS; landline numbers can't, so route them to voice. voip and toll-free deserve extra scrutiny. (For a deep dive on every classification, see our phone number validation API complete guide.)
• carrier is the live network operator, pulled from network data rather than guessed from the area code. This is the same intelligence that powers a dedicated carrier lookup, and it stays accurate even after a number is ported.
• risk packages the fraud signals. A fraud_score near 0 is clean; scores climbing toward 100 warrant friction or a manual review. The is_voip and is_prepaid flags are strong fraud correlates on signup forms.
• compliance surfaces dnc_listed (Do Not Call) and dno_listed (Do Not Originate) status so you can avoid dialing numbers you're legally barred from contacting.

This single object replaces what used to take three or four separate services to assemble.

Step 3 — Call It From Your Code

Curl is great for testing, but you'll want this in your application. Here are two drop-in implementations.

Node.js (fetch)

Node 18+ ships fetch natively, so there are no dependencies to install:

const API_KEY = process.env.LOOKUP_API_KEY;

async function validatePhone(phone, country = "US") {
  const res = await fetch("https://api.1lookup.io/v1/validate/phone", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ phone, country }),
  });

  if (!res.ok) {
    throw new Error(`Validation failed: ${res.status}`);
  }

  return res.json();
}

const result = await validatePhone("+14155552671", "US");

if (result.valid && result.line_type === "mobile" && result.risk.fraud_score < 50) {
  console.log(`${result.number} is a clean mobile on ${result.carrier}`);
} else {
  console.log(`Flagging ${result.number} for review`);
}

Python (requests)

The Python version uses the ubiquitous requests library (pip install requests):

import os
import requests

API_KEY = os.environ["LOOKUP_API_KEY"]

def validate_phone(phone, country="US"):
    response = requests.post(
        "https://api.1lookup.io/v1/validate/phone",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        json={"phone": phone, "country": country},
        timeout=10,
    )
    response.raise_for_status()
    return response.json()

result = validate_phone("+14155552671", "US")

if result["valid"] and result["line_type"] == "mobile" and result["risk"]["fraud_score"] < 50:
    print(f"{result['number']} is a clean mobile on {result['carrier']}")
else:
    print(f"Flagging {result['number']} for review")

Both examples do the same thing: validate, then apply a simple business rule. Notice the timeout on the Python call — always set one so a slow upstream never hangs your request thread.

Handling Errors and Rate Limits

Production code has to handle the unhappy paths. A few rules will keep your integration resilient:

• Check the HTTP status, not just the body. A 401 means a bad or missing API key. A 400 means a malformed body — usually a missing phone field or invalid JSON. A 429 means you've hit your rate limit.
• Back off on 429. When you see a rate-limit response, wait and retry with exponential backoff (e.g. 1s, then 2s, then 4s) rather than hammering the endpoint. Honor any Retry-After header if present.
• Validate input before you spend a call. Strip whitespace and reject obviously empty strings client-side so you don't waste API quota on garbage.
• Fail open or closed deliberately. If the API is unreachable during a signup, decide in advance whether to let the user through (fail open) or block them (fail closed). For fraud-sensitive flows, failing closed is usually safer.

Here's the pattern in practice — a quick checklist for every call you make:

• API key loaded from an environment variable, never hardcoded
• Content-Type: application/json header set on the POST
• Non-2xx responses handled explicitly
• A timeout set on the HTTP client
• Retry-with-backoff logic for 429 responses

Validating Phone Numbers in Bulk

Validating one number at a time is fine for real-time forms, but if you're cleaning an existing list of thousands of numbers, loop the single endpoint with controlled concurrency rather than blasting requests in parallel. Cap yourself at a handful of simultaneous requests, collect the results, and respect 429 responses with backoff.

import os
import time
import requests

API_KEY = os.environ["LOOKUP_API_KEY"]
URL = "https://api.1lookup.io/v1/validate/phone"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

def validate_list(numbers, country="US"):
    results = []
    for phone in numbers:
        resp = requests.post(URL, headers=HEADERS,
                             json={"phone": phone, "country": country}, timeout=10)
        if resp.status_code == 429:
            time.sleep(2)          # simple backoff, then retry once
            resp = requests.post(URL, headers=HEADERS,
                                 json={"phone": phone, "country": country}, timeout=10)
        results.append(resp.json())
    return results

clean = [r for r in validate_list(["+14155552671", "+12025550181"]) if r["valid"]]
print(f"{len(clean)} valid numbers")

For large recurring jobs, this same loop scales comfortably with a worker pool. If you want a full walkthrough of batching strategy, dedup, and cost control, our carrier lookup API guide covers the patterns in depth.

Common Use Cases

Now that you can validate phone numbers with API calls, here's where teams actually plug this in.

Cleaning Lead and Signup Forms

Validate the number the moment a user submits. Reject anything where valid is false, and use line_type to decide your follow-up channel — text the mobiles, call the landlines. This alone strips fake and fat-fingered numbers out of your CRM before they cost you anything. Pairing validation with our phone validation endpoint at the form level is the single highest-ROI place to start.

Screening for Fraud

The risk block does the heavy lifting. A signup with is_voip: true, is_prepaid: true, and a high fraud_score is a classic burner-number pattern. Add friction or block outright. To go deeper on the disposable and burner-number tactics fraudsters use, read our fake phone number detection guide, and screen suspicious traffic before it ever reaches a human with a phone spam check.

Staying TCPA and DNC Compliant

Before you place an outbound call or text, check the compliance block. If dnc_listed is true, don't dial — the penalties for ignoring the Do Not Call registry run into thousands of dollars per violation. Treating dnc_listed and dno_listed as hard stops keeps your dialing campaigns on the right side of the law without a separate compliance vendor.

Next Steps

You just went from zero to a working phone validation integration: a curl test, production Node.js and Python clients, error handling, a bulk loop, and three real use cases — all on a single endpoint that returns validity, line type, carrier, risk, and compliance data in one call.

From here, you can:

• Wire validation into your signup or checkout form as a real-time gate
• Add the fraud_score and VoIP flags to your risk-scoring model
• Schedule a recurring bulk job to keep your existing contact lists clean

Ready to put it to work? Create your free 1Lookup account and start validating numbers in minutes, or compare plans on our pricing page to size the right tier for your volume. Your first clean lead list is one API call away.