Developer API Reference
Generate mock phone numbers programmatically with our simple GET API.
HTTP Endpoint
Send HTTP GET requests to the following URL:
GEThttps://phone-number.loveyouall.qzz.io/api/generate
Try It Live
Enter parameters below and call the real API from your browser.
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
country | string | No | Country code. Supports 'US', 'CN', 'CA', 'GB', 'AU', 'DE', 'FR', 'JP', 'KR', 'IN', 'SG', 'ES', 'IT', 'BR', 'MX', 'RU', 'NL'. Defaults to 'US'. |
region | string | No | Region/State/Operator name (e.g. 'California', 'Ontario', 'China Mobile'). Case-insensitive. |
city | string | No | City name or specific prefix/area code (e.g. 'Los Angeles', '138'). Case-insensitive. Requires 'region' to be specified. |
quantity | integer | No | Number of records to generate. Range: 1 - 1000 (values above 1000 are clamped). Default: 10. |
customPrefix | string | No | Custom specific prefix digits (digits only, 0-9). Optional. |
safetyMode | string | No | Safety mode. Supports 'realistic' (realistic rules) and 'safe' (official reserved fictional test segments, e.g. 555-XXXX). Defaults to 'realistic'. |
uniqueOnly | boolean | No | Whether to return only unique numbers. Supports 'true' or 'false'. Defaults to 'true'. |
Integration Examples
Choose your language or tool to integrate the phone generator API:
curl -X GET "https://phone-number.loveyouall.qzz.io/api/generate?country=US&quantity=5&safetyMode=safe&uniqueOnly=true"Response Format
Returns a JSON array of phone record objects. Each record contains localized fields, display format, and standardized E.164 strings.
[
{
"id": "c852d129-4112-4981-8ddb",
"country": "US",
"region": "California",
"regionCode": "CA",
"city": "Los Angeles",
"areaCode": "213",
"display": "+1 (213) 932-8419",
"e164": "+12139328419"
}
]Response Fields
| Field | Type | Description |
|---|---|---|
id | string | Unique UUID v4 identifier of the record. |
country | string | Two-letter country code (e.g. US, CN). |
region | string | State / province / operator name, e.g. California or China Mobile. |
regionCode | string | Short region code when available, e.g. CA for California. |
areaCode | string | Area code or number prefix, e.g. 213 or 138. |
city | string | City name or number prefix segment, e.g. Los Angeles or 138. |
display | string | Human-readable formatted number, e.g. +1 (213) 555-1234. |
e164 | string | Standard E.164 format, e.g. +12135551234. |
Errors
The API uses standard HTTP status codes and always returns a JSON body with an "error" field on failure.
| Status | When it happens | Response body |
|---|---|---|
400 | Unsupported country code | {"error":"Unsupported country code: XX"} |
400 | Unknown region or city for the selected country | {"error":"Unknown region ... for country US"} |
400 | customPrefix contains non-digit characters | {"error":"customPrefix must contain digits only"} |
400 | city provided without region | {"error":"city requires region"} |
500 | Internal error during generation | {"error":"Internal Server Error"} |
Usage Limits
- Free & anonymous — no API key required
- Max 1,000 numbers per request (higher values are clamped)
- Defaults: country=US, quantity=10, safetyMode=realistic, uniqueOnly=true
- safetyMode=safe uses official reserved fictional test segments (e.g. 555-XXXX) that never belong to real subscribers