Validate a list of phone numbers with Python

The phone product checks a number against its country's numbering plan and returns the number in E.164, national and international formats, the country, the number type the plan assigns, and for North American numbers the area code and its region. It never contacts a carrier, so it cannot say whether a number is switched on, ported or reachable.

E.164 is the ITU-T recommendation titled "The international public telecommunication numbering plan" ², and it is the form to store: one unambiguous string per number. A number the plan rejects comes back as found: false with the reason, and costs nothing.

The API reads punctuation and a trailing extension on its own, so normalisation here is about hygiene: strip the characters that cause stray rejections, collapse whitespace, and drop duplicates so you do not pay twice for the same number. Letters in the number body are refused by the API, so keep letters out of the cleaned string except for an extension marker.

• Replace non-breaking spaces and runs of whitespace with a single space.
• Remove brackets, dots and dashes between digits.
• Remove spaces between digits, so two spellings of one number become the same string.
• Keep a leading plus sign: it tells the parser the country code is already there.
• Pass a two-letter country hint such as US for numbers written without a country code. Without it the check assumes US.

With requests, passing a dict to the json argument encodes the body and sets the content type for you ¹. The docs also advise setting timeout on nearly every production request, since without it a call can hang indefinitely ¹. Check status_code yourself, because a 4xx or 5xx response is returned rather than raised unless you call raise_for_status() ¹.

1import os
2import re
3import time
4​
5import requests
6​
7API = "https://YOUR_API_HOST"
8​
9​
10def normalise(raw):
11    text = raw.replace("\u00a0", " ")
12    text = re.sub(r"[().-]", "", text)
13    text = re.sub(r"(?<=\d)\s+(?=\d)", "", text)
14    return re.sub(r"\s+", " ", text).strip()
15​
16​
17def lookup(session, phone, country=None):
18    payload = {"phone": phone}
19    if country:
20        payload["country"] = country
21    for attempt in range(3):
22        r = session.post(API + "/v1/phone", json=payload, timeout=10)
23        if r.status_code == 429 and attempt < 2:
24            time.sleep(int(r.headers.get("Retry-After", "1")))
25            continue
26        if r.status_code >= 400:
27            err = r.json().get("error", {})
28            raise RuntimeError(f"{err.get('code')}: {err.get('message')}")
29        return r.json()
30​
31​
32def validate(numbers, country="US"):
33    session = requests.Session()
34    session.headers["Authorization"] = "Bearer " + os.environ["LOOKVALID_API_KEY"]
35    seen, results, spent = set(), {}, 0
36    for raw in numbers:
37        phone = normalise(raw)
38        if not phone or phone.lower() in seen:
39            continue
40        seen.add(phone.lower())
41        body = lookup(session, phone, country)
42        spent += body["credits_charged"]
43        results[phone] = body["data"]["e164"] if body["found"] else body["reason"]
44    return results, spent
45​
46​
47print(validate(["+1 (202) 555-0143", "+1 202.555.0143"]))

A found number is billed at 1 credit per the catalog, and the loop above skips the second spelling of the same number before it reaches the API.

Errors arrive as an error object with a code such as invalid_input or insufficient_credits; the error reference lists them all. Stop the run on insufficient_credits rather than retrying.

Test one number with curl before you run a list.

1curl -X POST https://YOUR_API_HOST/v1/phone \
2  -H "Authorization: Bearer $LOOKVALID_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{"phone":"+12025550143"}'

Read the phone product page for every field, try the phone number validator in the browser, or begin with the quickstart.