Phone Spam Check

Open in ChatGPT Open in Claude

Reported-caller complaints for a phone number from public FTC Do Not Call and FCC consumer complaint data: how many reports, when, and what kind of calls were reported. Complaints are unverified consumer reports, not a verdict about the caller.

POST https://YOUR_API_HOST/v1/phone-spam

Credits and caching

Success billing. 1 credit per number with complaints on record. You are charged only when the lookup finds something; a not-found result is free.
Results are cached per account for 7 days. Repeating the same lookup in that window is free and returns cache_hit: true.
Invalid input, rate limits and errors are never charged.
Read the billing rules for the full picture.

Request

Send a JSON body with Authorization: Bearer <key>. The body can be up to 64 KB.

Field	Type	Required	Notes
`phone`	string	yes	Up to 64 characters.

Example request

Terminal

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

1const response = await fetch("https://YOUR_API_HOST/v1/phone-spam", {
2  method: "POST",
3  headers: {
4    Authorization: `Bearer ${process.env.LOOKVALID_API_KEY}`,
5    "Content-Type": "application/json",
6  },
7  body: JSON.stringify({
8    "phone": "+12025550143"
9  }),
10});
11
12const result = await response.json();
13if (!response.ok) throw new Error(`${result.error.code}: ${result.error.fix}`);
14console.log(result.found, result.data, result.credits_charged);

1import os
2import requests
3
4response = requests.post(
5    "https://YOUR_API_HOST/v1/phone-spam",
6    headers={"Authorization": f"Bearer {os.environ['LOOKVALID_API_KEY']}"},
7    json={
8        "phone": "+12025550143",
9    },
10    timeout=30,
11)
12result = response.json()
13if not response.ok:
14    raise RuntimeError(f"{result['error']['code']}: {result['error']['fix']}")
15print(result["found"], result["data"], result["credits_charged"])

Response

The status is 200 whether or not anything was found. Check found. Every response also carries the X-Request-Id, X-Credits-Charged, X-Credits-Remaining and X-RateLimit-* headers.

Envelope

Field	Type	Notes
`request_id`	string	-
`product`	"phone-spam"	-
`found`	boolean	False means the lookup ran and found nothing; it is free.
`reason`	string or null	Why nothing was found; null when found.
`sources`	array of string	Where the data came from, including any attribution the licence requires.
`credits_charged`	integer	0 for a cache hit, a not-found result or an error.
`credits_remaining`	integer	-
`cache_hit`	boolean	True when the account already paid for this lookup within the cache window.
`cache`	object	-

The `data` object

Present when found is true, otherwise null.

Field	Type	Notes
`phone_e164`	string	-
`complaints_total`	integer	Minimum 0.
`first_reported`	string or null	-
`last_reported`	string or null	-
`issue_types`	array of string	Distinct issue types reported, most serious first
`sources_used`	array of object	-
`sources_used[].id`	string	One of `fcc`, `ftc`.
`sources_used[].name`	string	-
`sources_used[].complaints`	integer	Minimum 0.
`sources_used[].dataset_built_at`	string	-
`spam_score`	integer	Computed as of cache.cached_at; a cached answer keeps its score, so the recency part can be up to the cache lifetime out of date Minimum 0. Maximum 100.
`risk_level`	string	One of `none`, `low`, `medium`, `high`.
`score_basis`	object	-
`score_basis.components`	object	-
`score_basis.components.volume`	number	-
`score_basis.components.recency`	number	-
`score_basis.components.issue_type`	number	-
`score_basis.formula`	string	-
`disclaimer`	string	-

Captured example (2026-10-18)

A real run of this lookup on 2026-10-18, using the request above, which is a public input. The envelope fields are left out.

1{
2  "product": "phone-spam",
3  "found": true,
4  "data": {
5    "phone_e164": "+12025550143",
6    "complaints_total": 2,
7    "first_reported": "2017-03-23",
8    "last_reported": "2017-03-23",
9    "issue_types": [
10      "prerecorded voice",
11      "unwanted calls"
12    ],
13    "sources_used": [
14      {
15        "id": "fcc",
16        "name": "FCC Consumer Complaints (opendata.fcc.gov, public domain)",
17        "complaints": 2,
18        "dataset_built_at": "2026-10-17T20:41:34.966Z"
19      }
20    ],
21    "spam_score": 32,
22    "risk_level": "medium",
23    "score_basis": {
24      "components": {
25        "volume": 11.9,
26        "recency": 0,
27        "issue_type": 20
28      },
29      "formula": "spam_score = round(volume + recency + issue_type). volume = 50 * min(1, log10(1 + complaints) / log10(101)). recency = 30 * 0.5^(age_days / 90) where age_days is the age of the newest complaint. issue_type = 20 * weight of the most serious reported issue (1.0 scam, fraud, robocall, prerecorded, spoofing or impersonation; 0.6 telemarketing, sales or other unwanted contact; 0.3 anything else)."
30    },
31    "disclaimer": "Complaints are unverified consumer reports and phone numbers can be spoofed, so a score describes how often a number was reported, not who is calling."
32  },
33  "sources": [
34    "FCC consumer complaints, public domain (opendata.fcc.gov)"
35  ]
36}

Errors

400 invalid_input: The request input is invalid.
401 unauthorized: The API key is missing, malformed, revoked or unknown.
402 insufficient_credits: The account does not have enough credits for this lookup. Error code: insufficient_credits. During a trial whose allowance is used up the code is trial_allowance_exhausted: nothing is charged and the customer starts the plan from the billing page.
405 method_not_allowed: This endpoint does not accept that HTTP method.
413 payload_too_large: The request body is too large.
429 rate_limited: Too many requests for this API key.
500 internal_error: An unexpected error occurred.
503 provider_unavailable: The data source for this product is unavailable right now.