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. Phone facts by country lists every numbering region with its calling code, its number formats and, where there is one, the table below that covers it. Phone data sources gives each publisher a page: its files and their format, the terms as it states them, and what the copy installed here holds.

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. The complaint counts are not one either: they are what consumers told the FTC about the numbers that called them, not the Do Not Call Registry, and they say nothing about whether you may call or text a number. Nor are they proof of wrongdoing: the FTC verifies none of it and caller ID is often spoofed, so an innocent number can collect complaints, which is why the weight is small.

Test numbers

Eight 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"

disposable_range is for the neighbours of listed numbers. SMS-receiving websites rent numbers in runs and the public lists lag the sites, so every daily sync counts, per 1,000-number range (the number without its last three digits, a run of digits rather than a regulator’s block), the listings that still score disposable: numbers the lists carry and dated within the last year, and numbers they dropped that were seen within the last 90 days. A number that is not listed itself, in a range holding ten or more of them, scores 30: medium on its own, never high. A listed number scores its own listing instead, so the two never add up. GET /api/v1/phone/block/{country}/{prefix} reports the same count under disposable: the fresh listings under the prefix, the newest date among them, and how many of the ranges it overlaps the signal flags. Spaw measures the signal weekly against the list itself: how many listed numbers it would catch if the list missed them, and how many of the week’s new listings already sat in a flagged range.

The SMS policy

Every answer ends with a decision, so an OTP or signup flow branches on one boolean instead of re-implementing the weights table. ok_to_send and blocked_by come from your account’s SMS policy, seven rules with published defaults.

The rules apply in a fixed order, and blocked_by names the one that decided: invalid for a number that is not valid — blocked whatever the policy says — then opted_out, country, line_type, the first blocked signal in the weights’ order, risk_score, and last unreachable or unconfirmed; a batch, bulk or monitored run answers suppressed for a number served from your suppression list. Null means sending is fine. Under the defaults the docs example +1 415 555 0142 answers blocked_by: "fictional", and so does the fictional test number +1 202 555 0105.

ok_to_send is a fraud and deliverability decision computed from the answer and your rules. It is not consent to message anyone and not a do-not-call scrub: neither is part of the answer, and both stay your obligation. A country allow-list is the first control against SMS pumping to destinations you never serve; it is a business choice about where you send, not a verdict that a country’s numbers are fraudulent. The live-check rule needs a lookup made with hlr: true; while the live check is not enabled on the service, every lookup answers unconfirmed under it.

The opt-out rule reads your own suppression list: an opted_out report, or your SMS provider’s opt-out code, puts the number there. It is on by default, so a number that replied STOP is not sent your next message by mistake. An OTP or transactional sender may want it off: an opt-out from marketing does not always forbid a verification code, and the person typing the number into your form may be its owner asking for a code again. Either way the rule is not a consent record, and honouring an opt-out stays your obligation. Batch, bulk and monitored runs serve an opted-out number from the list as suppressed whichever way the rule is set, and the test numbers never read the list.

The policy is account configuration, not money: any member may change it. GET /api/v1/phone/policy reads it, PUT changes any subset of the seven keys (signals come back in the weights’ order, countries upper-case and sorted; an empty allow-list and a body naming none of the keys are a 422), DELETE restores the defaults, and the dashboard has an “SMS policy” tab. All three are free and unlogged, and every lookup — single, batch, bulk rows, monitors, the browser endpoint, the test numbers — applies the stored policy at once. The score is not the decision: the policy, not the weights, answers “may I send”.

The glossary defines the SMS policy in one page, and the guide to gating SMS verification codes with it walks through a signup flow.

Your own traffic

Three fields and two signals come from nothing but your own account’s recent phone lookups. They are counted for single lookups (the API, the dashboard, the MCP verify-phone tool, the consistency check) and for browser lookups with a publishable key, and for nothing else: batch, bulk and monitor runs hold lists, and a list naturally holds neighbouring numbers, so they are never counted and answer these fields null. Neither are the test numbers or the guest demo. An invalid answer counts only toward its destination below. No other account’s lookups are ever read.

range_seen_by_you and range_burst. The distinct numbers your account looked up in the same 1,000-number range in the last 60 minutes, this one included, so a first lookup answers {"distinct_numbers": 1, "window_minutes": 60}. The range is the E.164 number without its last three digits (+14152010142 sits in +14152010xxx). From five distinct numbers the answer carries range_burst, +40 from the dataset account-velocity. SMS pumping walks consecutive numbers in a range where someone earns a share of every message sent there, and each of those numbers looks clean on its own. The range is a heuristic, since not every regulator allocates in thousands, and in North America, where pumping is rare, a burst more likely means someone is testing numbers against your form or opening accounts in bulk.

client_velocity and numbers_per_client. Send client_ip, the address of the person behind the lookup (your visitor, not your server), and the answer counts the distinct numbers tried from that address on your account in the last 60 minutes, this one included; an IPv6 address counts by its /64. A browser lookup counts the visitor’s own address without being asked. From five distinct numbers the answer carries numbers_per_client, +30 from account-velocity, unless Spaw’s own IP data places the address on a mobile carrier or a corporate proxy, where many people share one address, or the address is private or reserved, which makes it your proxy rather than your visitor; those still answer the count. The address is never looked up and never billed. The signal catches one script cycling numbers from one source, not an attack rotated through residential proxies. Without a client address the field is null.

destination_new_for_you. True when your account has not looked up a valid number in the number’s country in the last 30 days, false when it has. It is null until a week of the account’s own lookups has been counted, when there is no baseline yet, and on invalid answers, and it carries no weight: read it beside the score.

A browser lookup always answers the three fields null, because the answer reaches your visitor’s browser and would tell anyone which countries you serve and how busy your form is. The two signals still score there, and range_burst on a browser answer counts only the browser lookups, so it cannot reveal what your backend looked up; your own single lookups count both.

Three emails go to the account owner, all worked out from these counts:

The destination alerts are checked every five minutes. A list checked one number at a time trips them too; send lists to POST /api/v1/phone/batch, which is never counted. The Usage page shows the last seven days of the destination counts: lookups per country per day, and how many were invalid.

What is kept: each number as a truncated keyed hash under your account’s own key, filed under a keyed hash of its range and of the client address, for the 60-minute window; and per country and hour, how many lookups there were and how many were invalid, as counts, for 30 days. Erasing a number takes it out of every range count.

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 key with a daily credit cap stops the list the same way once the cap is spent, reporting meta.stopped_reason: "key_spend_cap", so one large batch can never spend past the cap; a call that starts with the cap already spent answers 429 KEY_SPEND_CAP_REACHED and runs nothing. 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, deduped, mobile, ok, blocked): 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, carrier_code, carrier_brand, block_pooled, block_assigned_at, region_level, local_time, utc_offsets, did_you_mean, complaints_90d, complaints_last_at, ok_to_send, blocked_by, sources, credits_used, suppressed, is_duplicate, duplicate_of_row

local_time and utc_offsets are the clock when the row was processed. Four fields of the single answer are not columns: a run is not counted in your own traffic, so range_seen_by_you, client_velocity and destination_new_for_you would always be empty, and it takes no call window, so neither would in_call_window.

A row that repeats a number an earlier row already held, in any spelling, is looked up once and is free; it says so in is_duplicate, and duplicate_of_row names the earlier row's position in your list (1 for the first row under the header). The deduped variant keeps the valid rows that are the first to hold their number; mobile keeps the valid rows whose line type is mobile — most North American numbers answer fixed_line_or_mobile, because mobiles and landlines share blocks there, and are not in it; ok and blocked split the rows by your phone policy's ok_to_send, with blocked_by saying why. Once a run has settled, the job also carries a summary added up from the same cells: rows, repeats, verdicts and reasons, the risk split, valid rows per line type and what settled it, the ten commonest countries and carriers, rows per risk signal, fictional, virtual and disposable counts, rows your suppression list answered, what the live check found when the run asked for it, and the rows your policy held back, by reason. The completion webhook does not carry it.

Cancelling stops a queued job on the spot and a running one at its next checkpoint; rows already answered stay billed and downloadable. A run that failed part-way keeps the rows it had already written, and they stay downloadable too. With a webhook_url, the finish is POSTed there as bulk_phone_job.finished, signed with the secret creation returns once: X-Spaw-Signature-V2 carries t={unix seconds},v2={hex}, the HMAC-SHA256 of v2:{t}:{raw body}, and a receiver refuses a t more than five minutes from its own clock so a captured delivery cannot be replayed later. The original X-Spaw-Signature, over the body alone, is sent beside it until 1 March 2027. 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.

A run that stopped because your credits ran out is resumed rather than uploaded again: top up, then press Resume on the run or call POST /api/v1/phone/bulk/{jobId}/resume. The whole list runs again from the top, and the rows it already answered are repeats inside the seven-day window, so only the rows it never reached are charged. On a run with the live check, a number whose network answer is more than a day old is asked again and charged the premium, even inside the seven days, so resume within a day to keep those rows free. The job keeps its id, its webhook and its cumulative credits_used, while processed and the verdict counts restart at zero and are rebuilt as the rows come back. A run that stopped for any other reason, or that is already going again, answers 409 JOB_NOT_RESUMABLE; one whose list has passed out of the 30-day retention window answers 409 JOB_INPUT_EXPIRED, and an empty balance answers 402 INSUFFICIENT_CREDITS rather than queueing a run that would stop again at once.

If a delivery fails — your endpoint was down for the half-minute the three attempts cover — ask for it again rather than falling back to polling: press Send webhook again on the run in the dashboard, or call POST /api/v1/phone/bulk/{jobId}/webhook/redeliver. The body is byte-for-byte the body the first delivery carried, rebuilt from the run's own frozen row, so the two reconcile. The signature is new, and has to be: a receiver refuses anything whose t is more than five minutes from its own clock, so verify a redelivery exactly as you verify any other delivery. Nothing deduplicates it for you — a receiver that gets both the original and the redelivery sees bulk_phone_job.finished twice, and job.id is the key to deduplicate on. A run created without a webhook_url answers 409 WEBHOOK_NOT_CONFIGURED and one that has not settled answers 409 JOB_NOT_FINISHED; a run whose last delivery succeeded is not refused, because a receiver can lose a message it has already acknowledged. The delivery is queued rather than made while you wait — one attempt takes half a minute against an endpoint that is down, which is the endpoint you are asking about — so the call answers 202 and the run reads webhook_status: "pending" until a worker has an answer, then delivered or failed with what your endpoint said in webhook_detail. The dashboard shows the same three states beside the run. It is free and capped at ten a minute counted per signed-in user: neither per key nor per account, so two keys held by one person share the one budget while two teammates have one each.

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, failed for good once, abused, or opted out; such numbers answer free, marked meta.suppressed: true per item and in the CSV's trailing suppressed column, while a single lookup always looks the number up afresh. A valid answer — from any lookup, the public widget included — removes only an entry an unassigned block put there: one your own failure reports added leaves when you report a delivery or a verified outcome (the recipient entered the code), and an abuse report, an opt-out or one you imported only when you remove it, so nobody typing a number into your form can take it off your list. An abuse or opt-out entry you removed comes back only with a new abuse report or opt-out, never from one you had already made. Imports, abuse reports and opt-outs never go stale: batch, bulk and monitor runs serve them for as long as they are listed. An entry a lookup or your own failure reports added is looked up afresh in those runs once it is untouched for 90 days: one an unassigned block put there leaves if the fresh answer is valid, and one your failure reports added stays listed, renewed by a new failure report. Importing a number that is already listed makes it one you imported, keeping its reason, so it stops going stale; importing it again is harmless and never needed. An import that kept the stored answer of a block nobody held serves that answer for 90 days after the entry was last renewed, then drops it with the unassigned_block reason and answers suppressed, because nothing looks an import up again. An abuse report or opt-out about a number you imported is recorded on that entry, which stays an import. Only failures about the number count toward it: a failure your SMS provider's error code (or your own report's failure_class) calls sender-side or not SMS-capable is kept in your feedback summary and never scored. An opted_out report, or a provider's opt-out code such as Twilio 21610, is never scored either: it suppresses the number with reason opted_out and never goes stale. A single lookup still answers and scores the number in full with meta.opted_out: true, and under the default SMS policy it answers ok_to_send: false with blocked_by: "opted_out"; switch block_opted_out off to decide it like any other number. Honouring an opt-out stays your obligation; the list is your own record, not a consent system. 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.

Manage the list from the Suppressions tab or with GET, POST and DELETE /api/v1/phone/suppressions. The list endpoint takes value — with a country for a number written without a calling code — plus source, reason, since, until and per_page, and a searched number is read to E.164 before it is matched, so any notation of a suppressed number finds it. The DELETE on the collection removes up to 1,000 numbers named in values and answers which were on the list and which were not, so nothing has to be paged for an id.

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. A number you took out yourself (an import, your own failure or abuse reports, an opt-out) answers suppressed and is never decay. Numbers are saved in E.164, read against the monitor's country where they have no calling code, so two spellings of one number are one entry and the 500 counts distinct numbers; an entry that does not parse is saved as typed and answers invalid.

A number that still answers valid but changed since the last valid answer is flagged, counted in the summary's newly_flagged and sent in a second email: became_disposable (an SMS-receiving website started listing it), reported_abuse_widely (three or more accounts reported abuse), risk_high (its risk rose from low or medium to high) and line_type_changed — a North American number going from fixed_line_or_mobile to mobile or landline is a sharper answer, not a change, and a type now read from another block holder, or from a holder where the plan decided it before (as when NANPA’s thousands-block report first names the holder of a pooled number’s own block), sets a new baseline instead, because neither says the number changed. With the live check on, ported and carrier_changed say the network reports a port or that another network serves the number; that is not SIM-swap detection, because the check sees the network, not the SIM in the handset. Each flag needs the earlier value to have been known, so a first sighting only records it. GET /api/v1/phone/monitors/{id} answers flags beside results, per number. There is deliberately no daily option: most regulator tables refresh weekly (NANPA’s and the SMS-receiving lists daily), a weekly run already catches a number that stopped being valid or started being listed within days, and with the live check a daily run would pay for the network check seven times a week.

A monitor can post its runs as well as email about them. Set webhook_url (https) when you create it, or later with a PATCH, and the signing secret comes back once in that response and is never readable again. webhook_events decides which runs are posted: changes, the default, posts only when the run found something new — a number that has stopped being valid or reachable, or a newly flagged one — or stopped early, and every_run posts after every run, which also tells you the monitor is still running. The body is { "event": "phone_monitor.run", "monitor": {…}, "summary": {…}, "changes": [ … ], "flags": {…} }, where changes names the numbers the alert emails name and flags maps each newly flagged one to what it raised, and X-Spaw-Signature-V2 carries t={unix seconds},v2={hex}, where the hex is the HMAC-SHA256 of v2:{t}:{raw body} keyed with the secret. Refuse anything whose t is more than five minutes from your own clock: that window is what stops a captured delivery being replayed at you later. The original X-Spaw-Signature, the HMAC of the body alone, is sent beside it until 1 March 2027 and still verifies. Connection errors and 5xx answers are retried twice, three attempts in all; webhook_status and webhook_detail on the monitor say how the last delivery went. A URL that resolves onto a private network is refused at delivery, every time, because DNS can be repointed after a URL is saved.

A monitor is changed rather than replaced: PATCH /api/v1/phone/monitors/{id} takes name, numbers, cadence, country, live_check and the webhook fields, and applies only the ones you send. That matters because what the last run recorded per entry is the baseline every alert is compared against: deleting a monitor and creating it again throws that away, and the first run of the new one only sets a baseline — a full cycle of silence, which is the one thing a monitor is bought to prevent. Replacing the list keeps what was recorded about the numbers that stayed, deletes what was recorded about the ones you removed, and gives a new entry no baseline. Changing the cadence neither skips a run nor starts a second one: a run already scheduled sooner than the new interval still happens, and a longer interval applies from the one after it. A body naming no field it could change answers 422.

A monitor that stops being run is deleted, and the identifiers and results it stored go with it. prunes_after_days on every monitor payload says how long that takes. A monitor in active use is never pruned: each run advances last_run_at, so the window only closes on a list that has genuinely stopped being re-checked — at which point holding the details somebody gave you serves no purpose. Deleting a monitor yourself removes everything it held at once.

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.