Running a large list through a lookup safely

A bulk job is the simplest route. You upload a CSV in the dashboard, pick a live product and the column that holds the value, and the platform runs one lookup per row in the background through the same engine as a single API call. The bulk jobs guide walks through the screens. If you would rather keep control of ordering and storage, loop over POST /v1/<product> from your own code, which is shown below.

The limits for a bulk job are read from the code that enforces them:

A larger list is split into files of at most 10,000 rows, one job per file.

CSV looks trivial, but the format has rules. RFC 4180 says each line should hold the same number of fields, that a field containing commas, double quotes or line breaks should be enclosed in double quotes, and that a quote inside a quoted field is written twice ¹.

Our reader follows that and is forgiving where spreadsheets are sloppy: it drops a leading byte order mark, accepts LF, CRLF or CR line ends, skips blank lines and pads a short row with empty cells. It is strict where a wrong guess would change your data. A quote that never closes, a row with more cells than the header, an empty or repeated column name, and control characters other than tab, carriage return and line feed are all refused with a message that names the line.

The result file is written defensively too. A cell that starts with =, +, - or @ gets a leading single quote, so opening the file in a spreadsheet never runs an input as a formula.

Cost control comes from three rules that apply to every lookup. First, success billing on most products: a row that finds nothing, fails or is refused costs nothing, while a per-call product (Link Safety Check) charges every completed row. A phone lookup is 1 credit per valid number, so the invalid rows in a messy list are free. Second, a bulk job holds its worst case on your balance before it starts, refuses the upload if you cannot cover it, and releases whatever is not spent. Third, results are cached per account for 7 days.

The cache is what makes re-runs safe. If a job crashes or a row is claimed twice, the second attempt finds the first attempt's cache entry and answers free, so a row is never charged twice inside the window. Your own script gets the same protection: a repeated input returns cache_hit: true and credits_charged: 0. Inputs are normalized before caching, so (415) 555-2671 and +14155552671 are one lookup.

• Do not retry a found: false answer. It repeats for free until the cache expires.
• Check credits_remaining on each response and stop the loop before the balance runs out.
• Save every answer as you go, so a restart skips the rows you already have.

A request that exceeds the key's limit gets HTTP 429, which RFC 6585 defines as the user having sent too many requests in a given amount of time, and the response may carry a Retry-After header ². Our rate limits page lists the numbers. The loop below honors that header, writes one JSON line per row as it goes and skips rows it already holds.

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":"+14155552671"}'

1import csv, json, os, time
2import requests
3​
4URL = "https://YOUR_API_HOST/v1/phone"
5HEADERS = {"Authorization": "Bearer " + os.environ["LOOKVALID_API_KEY"]}
6​
7done = set()
8if os.path.exists("results.jsonl"):
9    with open("results.jsonl") as f:
10        done = {json.loads(line)["input"] for line in f}
11​
12with open("numbers.csv", newline="") as src, open("results.jsonl", "a") as out:
13    for row in csv.DictReader(src):
14        number = row["phone"]
15        if number in done:
16            continue
17        for attempt in range(5):
18            r = requests.post(URL, headers=HEADERS, json={"phone": number}, timeout=30)
19            if r.status_code != 429:
20                break
21            time.sleep(float(r.headers.get("Retry-After", 1)))
22        body = r.json()
23        out.write(json.dumps({"input": number, "status": r.status_code, "body": body}) + "\n")
24        out.flush()
25        if r.status_code == 402:
26            break

A 402 means the balance is too low, so the loop stops instead of burning requests. Anything else, such as a 400 for a malformed number, is recorded and the loop moves on.

Run the first twenty rows before the full file, read the found and cache_hit fields, and check the credits spent against your expectation. Then upload the whole list. The Phone Number Validation product page lists what each answer contains, and the quickstart gets you a key in a few minutes.