Phone intelligence

Where each fact comes from

Every response names the datasets it consulted, with the version or sync date each one carried, so an answer can be checked against the data that produced it.

What the lookup deliberately does not claim: it does not know who serves a ported number; it does not split US mobiles from landlines beyond what the block holder proves; a valid number is assignable, not necessarily in service; and there is no caller name, no reverse lookup and no do-not-call scrub, because those sit on regulated personal data that open sources do not carry.

Test numbers

Seven fixed numbers in the Washington 555-01XX fiction block always answer the same result, cost no credits and leave no repeat marker, on every endpoint including batch, bulk and the browser endpoint. National notation works with country US.

Risk score

The score is arithmetic over the flags in the same response, capped at 100. Recompute it, or ignore it and branch on the booleans. It measures how unlikely a number is to reach a person’s own handset, not fraud, and an invalid number has no score at all.

Worked examples, as the API answers them:

risk_signals spells the sum out so nobody re-implements it. For the wholesaler example above it reads:

"risk_signals": [
  { "signal": "virtual", "weight": 40, "dataset": "nanpa-co-codes" }
],
"risk_score": 40,
"risk_level": "medium"

Reasons

An invalid number always says why, in one of ten values, each with its own reference page. Every one of them is free.

Batch and bulk

POST /api/v1/phone/batch looks up as many as 1,000 numbers in one call, in input order, under the single-lookup billing rules. Each item is a string or an object with its own country; a list-level country applies to the items that name none. If the balance runs out mid-list, the paid partial results come back with meta.stopped_reason: "insufficient_credits"; only a batch whose first lookup is refused answers the typed 402. A batch counts as one request against the rate limit.

$ curl https://spaw.co/api/v1/phone/batch \
    -H "Authorization: Bearer sk_live_…" \
    -H "Content-Type: application/json" \
    -d '{"phones": ["+1 415 555 0142", {"phone": "020 7946 0018", "country": "GB"}], "country": "US"}'

For a CRM export, a bulk run queues up to 100,000 numbers with POST /api/v1/phone/bulk or from the phone validation page in the dashboard, where an uploaded file keeps every column and a country column gives each row its own region. Poll GET /api/v1/phone/bulk/{jobId} for progress and the running valid, invalid, low, medium and high counts, then download the CSV from GET /api/v1/phone/bulk/{jobId}/results, whole or as one variant (valid, invalid, low, medium, high): the input columns first, then these:

phone, valid, reason, e164, national, international, rfc3966, country, country_name, calling_code, continent, is_eu, currency, line_type, line_type_source, carrier, carrier_source, block_status, region, is_geographic, timezones, extension, is_fictional, is_virtual, is_disposable, disposable_seen_at, risk_score, risk_level, risk_signals, hlr_checked, reachable, ported, current_carrier, roaming, sources, credits_used, suppressed

Cancelling stops a queued job on the spot and a running one at its next checkpoint; rows already answered stay billed and downloadable. With a webhook_url, the finish is POSTed there as bulk_phone_job.finished, signed in X-Spaw-Signature with the HMAC-SHA256 of the raw body keyed with the secret creation returns once. An Idempotency-Key header makes creation safe to retry. Phone endpoints have their own rate limit of 50 requests per second per key, like the IP endpoints.

Batch, bulk and monitor runs honour your phone suppression list: a number in a block the regulator lists as unassigned lands there on its own, and so does a number your own SMS reports called undelivered twice or abused; such numbers answer free, marked meta.suppressed: true per item and in the CSV's trailing suppressed column, while a single lookup always re-checks. Both endpoints take hlr: true to run the live carrier-network check on every item where the service has it enabled: the balance is gated for the premium up front, it is charged only where the network answered, and a bulk job records the choice as live_check.

A monitored list ( POST /api/v1/phone/monitors, or the Monitors tab of the dashboard page) keeps up to 500 numbers under a weekly or monthly re-check against the same tables, your suppression list and, when switched on, the live check. The first run sets the baseline; from the next run on, numbers that stop being valid or reachable count as decayed and arrive by email, and each run bills every number like a single lookup.

Browser lookups

The form helper that checks email fields checks phone fields too. Mark an input with data-spaw-phone and it is validated on blur through the publishable-key endpoint; the country comes from data-spaw-country on the input, else from the form field named by data-spaw-country-field, else it is left out and international notation is expected. Valid numbers show their international format, flagged ones a note, invalid ones the reason in plain words. The helper never blocks a submit, and every result is dispatched as a spaw:result event whose detail carries type: "phone" and the answer.

<script src="https://spaw.co/spaw-form.js" data-key="pk_live_…"></script>

<select name="country">…</select>
<input type="tel" name="phone" data-spaw-phone data-spaw-country-field="country">

Or call POST /api/v1/phone/public yourself with the publishable key, the number and an optional country. Create the key on the API keys page and list the domains it may run from; the endpoint checks the browser’s Origin header against that list, bills the key’s owner, and answers without a meta block so visitors never see the balance.

const response = await fetch('https://spaw.co/api/v1/phone/public', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ key: 'pk_live_…', phone: form.phone.value, country: form.country.value }),
});
const { data } = await response.json();

if (!data.valid) showHint(data.reason);
if (data.is_disposable || data.is_fictional) askForAnotherNumber();
if (data.e164) form.phone.value = data.e164;

Because the key sits in page source, give it a daily credit cap; once spent, the endpoint answers 429 KEY_SPEND_CAP_REACHED until the next day, and free answers never count toward it. A key that carries a Cloudflare Turnstile pair requires a confirmed turnstile_token with every lookup. The endpoint is throttled at 20 requests a minute per visitor and never runs the live check.