Skip to content
Phone

Phone Spam Check

Spam, robocall and fraud risk score for a number, with the reasons behind it.

POST/v1/phone-spam-check
from 1 creditBulk supportedUS & Canada
Request
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"}'
Response
{
  "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>required

Your 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>required

Phone number. Example: +15125550142

freshboolean

Skip the 7-day cache and run a new lookup. Charged as a normal lookup.

referencestring

Your 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.

successboolean

true when the lookup ran.

data.risk_scorenumber

A number from 0 to 100. Higher means more complaint activity and more risk signals tied to the number.

data.risk_levelstring

low, medium or high. A banded version of the score for simple allow and block rules.

data.complaints.ftc_reports_12mnumber

Complaints consumers filed with the FTC about this number in the last 12 months.

data.complaints.fcc_reports_12mnumber

Complaints naming the number in FCC consumer complaint data over the same period.

data.complaints.last_reportedstring

Date of the newest complaint, which separates an old problem from a current one.

data.top_categoriesarray

What callers were reported for, such as robocall, debt or impersonation, ordered by volume.

data.line_typestring

mobile, landline, voip or toll_free, given as context for reading the score.

data.reasonsarray

The factors that moved the score, as short machine-readable codes.

meta.credits_usednumber

Credits charged for this call.

meta.credits_remainingnumber

Your balance after the call.

meta.cachedboolean

true when the result came from the 7-day cache.

meta.request_idstring

Quote 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.

HTTPCodeMeaning
401unauthorizedThe key is missing, malformed or revoked.
402insufficient_creditsYour credits are used up and pay as you go is off or at its limit.
422invalid_inputA field is missing or malformed. The field property names it.
429rate_limitedToo many requests for this key. Wait for the Retry-After interval.
500internal_errorSomething failed on our side. Safe to retry.
503source_unavailableAn 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