> For the complete documentation index, see [llms.txt](https://docs.stopbot.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stopbot.net/v2/api-v2-documentation/phone-number-identify.md).

# Phone Number Identify

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:

```
+16595290000
```

Numbers without `+` are normalized by adding `+` before parsing.

### Example Request

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

### Valid Number Response

```json
{
  "isValid": true,
  "info": {
    "phonenumber": "+1 659-529-0000",
    "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`.

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

Example response:

```json
{
  "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`.

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

Example response:

```json
{
  "status": "error",
  "errorMessage": "Please enter a valid number. (ex: +11231231234)",
  "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                                           |