Query our premium phone number inventory programmatically via RESTful endpoints. Search, retrieve details, and access stats.
Authenticate with a Bearer Token and start querying our number database instantly.
Include Authorization: Bearer YOUR_API_KEY in the request header to authenticate all API requests.
Default 100 requests per minute, configurable per API key. Returns 429 status when exceeded.
All available endpoints with parameter documentation.
Search available premium numbers with filters for area code, state, type, price range, and more.
| Parameter | Type | Required | Description |
|---|---|---|---|
| area_code | string | No | Filter by area code (e.g. 888, 310) |
| state | string | No | Filter by US state (e.g. CA, NY) |
| type | string | No | Number type: local, tollfree |
| price_min | number | No | Minimum price in USD |
| price_max | number | No | Maximum price in USD |
| search | string | No | Free-text search (digits or patterns) |
| sort | string | No | price_asc, price_desc, newest |
| per_page | integer | No | Results per page, max 100 (default 25) |
{
"data": [
{
"number": "8889998888",
"formatted": "(888) 999-8888",
"area_code": "888",
"state": null,
"city": null,
"type": "tollfree",
"line_type": "voip",
"pattern_type": "repeating",
"price": 4999.00,
"original_price": 5999.00,
"status": "available",
"is_featured": true,
"label": "Repeating",
"url": "https://www.greatnumber.com/en/number/8889998888"
}
],
"links": { "first": "...", "last": "...", "prev": null, "next": "..." },
"meta": { "current_page": 1, "last_page": 10, "per_page": 25, "total": 245 }
}
Retrieve full details for a single number, wrapped in a data object.
| Parameter | Type | Required | Description |
|---|---|---|---|
| number | string | Yes | 10-digit phone number (e.g. 8889998888) |
{
"data": {
"number": "8889998888",
"formatted": "(888) 999-8888",
"area_code": "888",
"state": null,
"city": null,
"type": "tollfree",
"line_type": "voip",
"pattern_type": "repeating",
"price": 4999.00,
"original_price": 5999.00,
"status": "available",
"is_featured": true,
"label": "Repeating",
"url": "https://www.greatnumber.com/en/number/8889998888"
}
}
Get aggregated inventory statistics including totals, counts by type/pattern, and price range distribution. Cached for 5 minutes.
{
"data": {
"total": 80245312,
"by_type": {
"local": 72180000,
"tollfree": 8065312
},
"by_pattern": {
"repeating": 12450,
"sequential": 8320,
"double_repeating": 45200,
"ending_0000": 3210
},
"price_ranges": {
"under_100": 68000000,
"100_to_500": 9800000,
"500_to_2000": 1900000,
"2000_to_10000": 420000,
"over_10000": 125312
},
"cached_at": "2026-06-01T12:00:00Z"
}
}
Sample API calls in popular programming languages.
# Search toll-free numbers under $5000 curl -X GET "https://www.greatnumber.com/api/v1/numbers?type=tollfree&price_max=5000&sort=price_desc" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Accept: application/json" # Get details for a specific number curl -X GET "https://www.greatnumber.com/api/v1/numbers/8889998888" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Accept: application/json" # Get inventory stats curl -X GET "https://www.greatnumber.com/api/v1/stats" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Accept: application/json"
use GuzzleHttp\Client; $client = new Client([ 'base_uri' => 'https://www.greatnumber.com/api/v1/', 'headers' => [ 'Authorization' => 'Bearer YOUR_API_KEY', 'Accept' => 'application/json', ], ]); // Search numbers $response = $client->get('numbers', [ 'query' => [ 'type' => 'tollfree', 'price_max' => 5000, 'sort' => 'price_desc', 'per_page' => 25, ], ]); $data = json_decode($response->getBody(), true); foreach ($data['data'] as $number) { echo $number['formatted'] . ' — $' . $number['price'] . "\n"; }
import requests API_KEY = "YOUR_API_KEY" BASE_URL = "https://www.greatnumber.com/api/v1" headers = { "Authorization": f"Bearer {API_KEY}", "Accept": "application/json", } # Search numbers resp = requests.get(f"{BASE_URL}/numbers", headers=headers, params={ "type": "tollfree", "price_max": 5000, "sort": "price_desc", }) data = resp.json() for number in data["data"]: print(f"{number['formatted']} — ${number['price']}")
const API_KEY = 'YOUR_API_KEY'; const BASE_URL = 'https://www.greatnumber.com/api/v1'; // Search numbers const params = new URLSearchParams({ type: 'tollfree', price_max: 5000, sort: 'price_desc', }); const response = await fetch(`${BASE_URL}/numbers?${params}`, { headers: { 'Authorization': `Bearer ${API_KEY}`, 'Accept': 'application/json', }, }); const { data, meta } = await response.json(); data.forEach(number => { console.log(`${number.formatted} — $${number.price}`); }); console.log(`Page ${meta.current_page} of ${meta.last_page}`);
The API uses standard HTTP status codes for error reporting.
| Status | Code | Description |
|---|---|---|
| 401 | Unauthorized | Unauthorized — missing, invalid, or expired API key |
| 404 | Not Found | Not Found — the requested resource does not exist |
| 429 | Too Many Requests | Rate Limited — too many requests, retry after retry_after seconds |
// 401 Unauthorized { "message": "Unauthenticated." } // 429 Rate Limited { "message": "Too Many Requests", "retry_after": 30 } // 404 Not Found { "message": "Number not found." }
Contact us to get your API key and start building today.