Search Number Groups

Search for available number groups — catalogs of phone numbers you can purchase. This is the main search endpoint for finding numbers.

Endpoint

GET https://api.p.2chat.io/open/numbers/groups

Authentication

Include your API key in the X-User-API-Key header. Learn more about authentication.

Parameters

These are query-string parameters.

Field	Type	Required	Description
country	string	Yes	ISO country code (e.g. US, BR, DE)
region_id	string	No	Filter by region (from the Get Regions endpoint)
city_id	string	No	Filter by city (from the Get Cities endpoint)
city_name_or_prefix	string	No	Search by city name or number prefix
did_type	string	No	Filter by DID type: local, mobile, tollfree, national, global, sharedcost, or all

Invocation

cURL

curl --location --request GET 'https://api.p.2chat.io/open/numbers/groups?country=US&did_type=local' \
--header 'X-User-API-Key: your_api_key_here'

Python

import requests

url = "https://api.p.2chat.io/open/numbers/groups"
headers = {
    "X-User-API-Key": "your_api_key_here"
}
params = {
    "country": "US",
    "did_type": "local"
}

response = requests.get(url, headers=headers, params=params)
print(response.json())

JavaScript

const axios = require('axios');

const response = await axios.get('https://api.p.2chat.io/open/numbers/groups', {
    params: { country: 'US', did_type: 'local' },
    headers: {
        'X-User-API-Key': 'your_api_key_here'
    }
});

console.log(response.data);

PHP

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.p.2chat.io/open/numbers/groups?country=US&did_type=local',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'X-User-API-Key: your_api_key_here'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Response

Success

{
    "success": true,
    "data": {
        "groups": [
            {
                "id": "abc-123",
                "prefix": "+1 (213)",
                "location": "Los Angeles",
                "price": {
                    "setup_price": "0.00",
                    "monthly_price": "3.50"
                },
                "type": "local",
                "requirements": [],
                "allow_number_selection": true,
                "is_eligible_for_free_number": false,
                "features": ["voice", "sms_in", "sms_out", "whatsapp_business"]
            }
        ]
    }
}

Field	Description
groups[].id	Group ID to use with the Available Numbers and Reserve Number endpoints
groups[].prefix	Phone number prefix for numbers in this group
groups[].location	City or location name
groups[].price.setup_price	One-time setup fee
groups[].price.monthly_price	Recurring monthly fee
groups[].type	DID type (e.g. local, mobile, tollfree)
groups[].requirements	Regulatory requirements for this group (empty if none)
groups[].allow_number_selection	Whether you can pick a specific number from this group
groups[].is_eligible_for_free_number	Whether this group qualifies for a free number
groups[].features	Supported features for numbers in this group

Features

• voice — Always included for all number types
• sms_in / sms_out — Included for non-US countries
• whatsapp — Added for mobile numbers
• whatsapp_business — Added for all number types

Error

{
    "success": false,
    "error": true,
    "error_message": "Description of what went wrong"
}