Phone Number Identify

Use Phone Number Identify to validate and identify phone numbers, including formatted international number, number type, carrier, location, and country code.

Phone Number Identify checks whether a submitted number can be parsed and validated as a real phone number. It does not send SMS, call the number, or verify ownership.

Endpoint

GET https://api.stopbot.net/services/phonenumber

Parameters

Parameter	Required	Description
apikey	Yes	Your STOPBOT API key
number	Yes	Phone number to validate and identify

Parameter Rules

Parameter	Rule
number	Must contain a plus sign or digit as the first character, followed by 6-32 digits

Recommended format:

+{country_code}{number}

Example:

[phone]

Numbers without + are normalized by adding + before parsing.

Example Request

curl "https://api.stopbot.net/services/phonenumber?apikey={API_KEY}&number=%2B16595290000"

Valid Number Response

{
  "isValid": true,
  "info": {
    "phonenumber": "[phone]",
    "type": "FIXED_LINE_OR_MOBILE",
    "carrier": "FRACTEL",
    "location": "BESSEMER, AL",
    "countryCode": "US"
  },
  "status": "success",
  "executionTime": "53.28ms",
  "timeResponse": "2026-07-07 12:00:00"
}

Invalid Number Response

If the number format is accepted but the number cannot be validated, STOPBOT returns status: success with isValid: false.

curl "https://api.stopbot.net/services/phonenumber?apikey={API_KEY}&number=1234567"

Example response:

{
  "isValid": false,
  "status": "success",
  "executionTime": "1.59ms",
  "timeResponse": "2026-07-07 12:00:00"
}

Invalid Format Response

If the number parameter does not match the accepted format, Phone Number Identify returns 400 Bad Request.

curl "https://api.stopbot.net/services/phonenumber?apikey={API_KEY}&number=abc"

Example response:

{
  "status": "error",
  "errorMessage": "Please enter a valid number. (ex: [phone])",
  "executionTime": "1.53ms",
  "timeResponse": "2026-07-07 12:00:00"
}

Response Fields

Field	Description
isValid	true when the number can be parsed and validated; otherwise false
info	Phone number detail object. This field is returned only when isValid is true
status	API result status. Valid and possible-format invalid numbers both return success
executionTime	Server-side execution time for the request
timeResponse	Response timestamp in YYYY-MM-DD HH:mm:ss format

Info Fields

Field	Description
phonenumber	Formatted international phone number
type	Phone number type
carrier	Carrier name in uppercase. If no carrier is detected, STOPBOT returns UNDETECT
location	Geocoded number location in uppercase when available
countryCode	ISO country code for the phone number region

Number Types

The type field can include:

Value	Meaning
FIXED_LINE	Fixed-line number
MOBILE	Mobile number
FIXED_LINE_OR_MOBILE	Number can be fixed-line or mobile
TOLL_FREE	Toll-free number
PREMIUM_RATE	Premium-rate number
SHARED_COST	Shared-cost number
VOIP	VoIP number
PERSONAL_NUMBER	Personal number
PAGER	Pager number
UAN	Universal access number
UNKNOWN	Number type is not mapped by STOPBOT

Error Response Fields

Failed Phone Number Identify responses may include:

Field	Description
errorMessage	Human-readable error message
status	Invalid format returns error; authentication, quota, or service errors may return failed
executionTime	Server-side execution time for the request
timeResponse	Response timestamp in YYYY-MM-DD HH:mm:ss format