GreatNumber
Home Search FAQ Porting Guide More ▾
Carrier Lookup Number Valuation Agency Partners Number Energy Area Code Info Referral Program Carriers Guide Developer API
About Contact
Sign In Sign Up
DEVELOPER API

GreatNumber Developer API

Query our premium phone number inventory programmatically via RESTful endpoints. Search, retrieve details, and access stats.

CA Registered Business US Registered SSL Encrypted Checkout
API Overview

API Overview

Authenticate with a Bearer Token and start querying our number database instantly.

🔑

Authentication

Include Authorization: Bearer YOUR_API_KEY in the request header to authenticate all API requests.

🌐

Base URL

https://www.greatnumber.com/api/v1
⚡

Rate Limiting

Default 100 requests per minute, configurable per API key. Returns 429 status when exceeded.

API Endpoints

API Endpoints

All available endpoints with parameter documentation.

GET /api/v1/numbers

Search Numbers

Search available premium numbers with filters for area code, state, type, price range, and more.

Parameters
Parameter Type Required Description
area_codestringNoFilter by area code (e.g. 888, 310)
statestringNoFilter by US state (e.g. CA, NY)
typestringNoNumber type: local, tollfree
price_minnumberNoMinimum price in USD
price_maxnumberNoMaximum price in USD
searchstringNoFree-text search (digits or patterns)
sortstringNoprice_asc, price_desc, newest
per_pageintegerNoResults per page, max 100 (default 25)
Example Response
JSON Response
{
  "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 }
}
GET /api/v1/numbers/{number}

Number Detail

Retrieve full details for a single number, wrapped in a data object.

Path Parameter
Parameter Type Required Description
numberstringYes10-digit phone number (e.g. 8889998888)
Example Response
JSON Response
{
  "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 /api/v1/stats

Inventory Stats

Get aggregated inventory statistics including totals, counts by type/pattern, and price range distribution. Cached for 5 minutes.

Example Response
JSON Response
{
  "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"
  }
}
Code Examples

Code Examples

Sample API calls in popular programming languages.

cURL
# 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"
PHP (Guzzle)
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";
}
Python (requests)
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']}")
JavaScript (fetch)
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}`);
Error Responses

Error Responses

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
Error Response Format
// 401 Unauthorized
{
  "message": "Unauthenticated."
}

// 429 Rate Limited
{
  "message": "Too Many Requests",
  "retry_after": 30
}

// 404 Not Found
{
  "message": "Number not found."
}

Ready to Integrate?

Contact us to get your API key and start building today.

Instagram Instagram
WhatsApp WhatsApp
WeChat WeChat
Xiaohongshu Xiaohongshu
Numi · Number Concierge
Your number & porting assistant
Redirecting to third-party platform
Visit Page →
Add Us on WeChat
Scan the QR code below to add us
Scan to add GreatNumber on WeChat
WeChat ID: GreatNumber2