# WhoseNo Phone Number Generator API

Endpoint: `POST /tools/phone-number-generator/api.php`

This endpoint generates synthetic, structurally valid phone numbers based on country metadata and optional line-type filters.

## Authentication

No API key is required for same-origin usage.

## Request Limits

- `60 requests / minute / IP`
- `count` must be between `1` and `100`

## Content Types

You can send either:

- `application/x-www-form-urlencoded`
- `application/json`

## Request Parameters

- `country_iso2` (string, optional): ISO-3166 alpha-2 country code. Default: `US`
- `number_type` (string, optional): `ANY`, `MOBILE`, `FIXED_LINE`, `VOIP`, `TOLL_FREE`, `PREMIUM_RATE`. Default: `ANY`
- `count` (integer, optional): `1..100`. Default: `10`
- `output_format` (string, optional): `all`, `e164`, `international`, `national`, `rfc3966`. Default: `all`

## cURL Example

```bash
curl -X POST 'https://www.whoseno.com/tools/phone-number-generator/api.php' \
  -H 'Referer: https://www.whoseno.com/tools/phone-number-generator/' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'country_iso2=US&number_type=MOBILE&count=5&output_format=e164'
```

## Success Response

```json
{
  "success": true,
  "generated_at": "2026-05-21T03:40:00+00:00",
  "country": {
    "iso2": "US",
    "name": "United States",
    "calling_code": "1",
    "flag_emoji": "🇺🇸"
  },
  "number_type": "MOBILE",
  "number_type_label": "Mobile",
  "output_format": "e164",
  "count": 5,
  "numbers": [
    {
      "type": "MOBILE",
      "type_label": "Mobile Phone",
      "national_number": "4155552671",
      "selected_format": "e164",
      "selected_value": "+14155552671",
      "formats": {
        "e164": "+14155552671",
        "international": "+1 (415) 555-2671",
        "national": "(415) 555-2671",
        "rfc3966": "tel:+14155552671"
      }
    }
  ],
  "usage_notice": "Generated numbers are synthetic and structurally valid for formatting/testing workflows. They may still overlap real assigned subscriber numbers."
}
```

## Error Responses

### 400 `INVALID_COUNTRY`

```json
{
  "success": false,
  "error": "INVALID_COUNTRY",
  "message": "country_iso2 must be a valid two-letter ISO country code."
}
```

### 400 `INVALID_COUNT`

```json
{
  "success": false,
  "error": "INVALID_COUNT",
  "message": "count must be between 1 and 100."
}
```

### 400 `TYPE_NOT_SUPPORTED`

```json
{
  "success": false,
  "error": "TYPE_NOT_SUPPORTED",
  "message": "The selected number type is not currently supported for this country. Try \"Any type\" for broader generation."
}
```

### 403 `FORBIDDEN_ORIGIN`

```json
{
  "success": false,
  "error": "FORBIDDEN_ORIGIN",
  "message": "Cross-origin requests are not allowed."
}
```

### 429 `RATE_LIMITED`

```json
{
  "success": false,
  "error": "RATE_LIMITED",
  "message": "Too many requests. Please slow down and try again in a minute."
}
```

### 500 `INTERNAL`

```json
{
  "success": false,
  "error": "INTERNAL",
  "message": "Could not process the request. Please try again."
}
```

## Notes

- Generated numbers are synthetic but can still overlap real assignments.
- For public media assets, prefer regulator-designated fiction/drama ranges.
- For real user onboarding, use OTP verification after structural validation.