Phone Spam Check
Spam, robocall and fraud risk score for a number, with the reasons behind it.
curl -X POST https://api.1lookup.dev/v1/phone-spam-check \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"phone_number":"+15125550142"}'{
"success": true,
"data": {
"phone_number": "+15125550142",
"risk_score": 82,
"risk_level": "high",
"complaints": {
"ftc_reports_12m": 37,
"fcc_reports_12m": 9,
"last_reported": "2026-10-28"
},
"top_categories": [
{
"category": "robocall",
"reports": 21
},
{
"category": "debt",
"reports": 11
},
{
"category": "impersonation",
"reports": 8
}
],
"line_type": "voip",
"reasons": [
"high_complaint_volume_12m",
"reported_in_last_30_days",
"voip_line"
]
},
"meta": {
"credits_used": 1,
"credits_remaining": 999,
"cached": false,
"request_id": "req_8f3a2c1e9b7d"
}
}Authorization
Authorizationstring<bearer>requiredYour API key as a Bearer token. Live keys start with 1lk_live_. Test keys start with 1lk_test_ and return this endpoint's sample response without spending credits. See authentication.
Body
Send the fields as a JSON object with Content-Type: application/json.
phone_numberstring<E.164>requiredPhone number. Example: +15125550142
freshbooleanSkip the 7-day cache and run a new lookup. Charged as a normal lookup.
referencestringYour own identifier, echoed back in meta and shown in lookup history.
Response
A 200 response carries the result in data and the cost of the call in meta. These are the fields most integrations read.
successbooleantrue when the lookup ran.
data.risk_scorenumberA number from 0 to 100. Higher means more complaint activity and more risk signals tied to the number.
data.risk_levelstringlow, medium or high. A banded version of the score for simple allow and block rules.
data.complaints.ftc_reports_12mnumberComplaints consumers filed with the FTC about this number in the last 12 months.
data.complaints.fcc_reports_12mnumberComplaints naming the number in FCC consumer complaint data over the same period.
data.complaints.last_reportedstringDate of the newest complaint, which separates an old problem from a current one.
data.top_categoriesarrayWhat callers were reported for, such as robocall, debt or impersonation, ordered by volume.
data.line_typestringmobile, landline, voip or toll_free, given as context for reading the score.
data.reasonsarrayThe factors that moved the score, as short machine-readable codes.
meta.credits_usednumberCredits charged for this call.
meta.credits_remainingnumberYour balance after the call.
meta.cachedbooleantrue when the result came from the 7-day cache.
meta.request_idstringQuote this when you contact support.
Errors
A failed request returns success: false with an error object, and is never charged. The full list is on the errors page.
| HTTP | Code | Meaning |
|---|---|---|
| 401 | unauthorized | The key is missing, malformed or revoked. |
| 402 | insufficient_credits | Your credits are used up and pay as you go is off or at its limit. |
| 422 | invalid_input | A field is missing or malformed. The field property names it. |
| 429 | rate_limited | Too many requests for this key. Wait for the Retry-After interval. |
| 500 | internal_error | Something failed on our side. Safe to retry. |
| 503 | source_unavailable | An upstream source did not answer in time. Safe to retry. |
Billing
From 1 credit. Charged when the lookup runs and returns a result. Errors are never charged, and repeating the same input within 7 days is served from cache at no charge.
Product overview and use cases