POST /v1/fraud · Check a number - Support

Send a phone number and get back what it is: who it belongs to, what kind of line it is, where it's from, and how risky it looks. Use it to screen a number before you answer or call back, or to tell a conversation who's really calling.

This is the same endpoint that scores phone conversations. Send only a number and it's a number check. Add text, utterances, start or id and it's a conversation instead.

New to the API? Start with Getting started with the Spoofey API.

Price

Each number check costs a flat number of credits, shown at the top of this page, and the response says what it charged in credits_charged. If the lookup can't run, you get a 503 and nothing is charged.

text

POST https://api.spoofey.com/v1/fraud

Body

Field	Required	Type	Notes
`number`	Yes	string	The number to check, with its country code, like `+14155550142`. `phone` works too.

Example

bash

curl https://api.spoofey.com/v1/fraud \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"number": "+14155550142"}'

Response

200:

json

{
  "object": "number_check",
  "id": "3c8e2f4a-9b1d-4c7e-a2f6-5d0b8e1c7a93",
  "number": "+14155550142",
  "valid": true,
  "country": "US",
  "line_type": "Fixed line",
  "place": "San Francisco, CA",
  "risk_score": 6,
  "reported": false,
  "community": { "legitimate": 0, "inconclusive": 0, "fraudulent": 0 },
  "classification": "business",
  "category": "retailer",
  "name": "Mission Street Hardware",
  "website": "https://example.com",
  "address": "2100 Mission St, San Francisco, CA",
  "city": "San Francisco",
  "sources": ["https://example.com/contact"],
  "credits_charged": 0.012,
  "balance": 41.988
}

Field	Notes
`object`	Always `number_check`.
`id`	This check's id. Pass it as `classification` when you start a conversation to use the result without paying again.
`number`	The number in international format.
`valid`	Whether it's a number that can exist.
`country`	Two-letter country code, or `null`.
`line_type`	`Mobile`, `Fixed line`, `Toll-free`, `VoIP` and so on, or `Unknown`.
`place`	Where the number is from, when that's known.
`risk_score`	The number's own risk score, 0 to 100. Higher is riskier.
`reported`	`true` when the number has been reported for spoofing or scams.
`community`	Community votes on the number, or `null`.
`classification`	What the number is: `emergency`, `financial`, `carrier`, `business`, or `ordinary` when it isn't tied to any organization (most personal numbers).
`category`	A finer category, like `bank`, `hospital` or `retailer`. `null` when `ordinary`.
`name`, `website`, `address`, `city`	Who it belongs to, when that's known. `null` when `ordinary`.
`sources`	Links the answer came from, when there are any.
`credits_charged`	What this check cost.
`balance`	Your balance afterwards.

Reading it

A number that claims to be a bank, a government office or a carrier but comes back ordinary is the classic sign of a spoofed or scam call.
reported: true or a high risk_score means others have flagged the number. Treat the call with suspicion.
A matching classification and name isn't proof. Caller ID can be faked, so a scammer can show a real bank's number. Pair the check with conversation scoring, which looks at what's actually said.

Using it with a conversation

A conversation that knows what the number is scores more sharply. Either:

start the conversation with classify: true, which runs a number check on its number for you, at this price; or
run the check first, then pass its id (or the whole response) as classification, at no extra charge.

How a classification moves the score is in the guide, under Using number classification.

Errors

Errors come back as {"error":{"message":"...","code":"..."}}. See API errors and rate limits for every status code and the rate limit.

Status	Code	When
`400`	`missing_input`	There's no `number` in the request.
`400`	`invalid_number`	It isn't a phone number that can be read. Include the country code.
`402`	`insufficient_credits`	Your balance doesn't cover the price. Nothing is charged.
`429`	`rate_limited`	Over 120 requests a minute, the limit number checks share with the rest of the API.
`503`	`lookup_unavailable`	The lookup couldn't run just now. You're refunded; try again in a minute.