import { CommuneClient } from 'commune-ai';
const commune = new CommuneClient({ apiKey: process.env.COMMUNE_API_KEY });
const results = await commune.phoneNumbers.search({
country: 'US',
type: 'TollFree',
capabilities: { sms: true },
});
console.log(results[0].phoneNumber); // +18005550001
from commune import CommuneClient
client = CommuneClient()
results = client.phone_numbers.search(
country="US",
type="TollFree",
capabilities={"sms": True},
)
print(results[0].phone_number) # +18005550001
search_available_phone_numbers(
country="US",
type="TollFree",
sms_enabled=True
)
curl -G https://api.commune.email/v1/phone-numbers/available \
-H "Authorization: Bearer comm_..." \
-d "country=US" \
-d "type=TollFree" \
-d "sms_enabled=true"
commune phone-numbers search --country US --type TollFree
{
"data": [
{
"phoneNumber": "+18005550001",
"friendlyName": "(800) 555-0001",
"region": null,
"isoCountry": "US",
"capabilities": {
"sms": true,
"mms": true,
"voice": true
},
"beta": false
},
{
"phoneNumber": "+18335550002",
"friendlyName": "(833) 555-0002",
"region": null,
"isoCountry": "US",
"capabilities": {
"sms": true,
"mms": false,
"voice": true
},
"beta": false
}
]
}
{
"error": "plan_upgrade_required",
"feature": "smsMessaging"
}
Phone Numbers
Search Available Numbers
Search for available phone numbers to purchase. Filter by country, type, area code, and capabilities.
GET
/
v1
/
phone-numbers
/
available
import { CommuneClient } from 'commune-ai';
const commune = new CommuneClient({ apiKey: process.env.COMMUNE_API_KEY });
const results = await commune.phoneNumbers.search({
country: 'US',
type: 'TollFree',
capabilities: { sms: true },
});
console.log(results[0].phoneNumber); // +18005550001
from commune import CommuneClient
client = CommuneClient()
results = client.phone_numbers.search(
country="US",
type="TollFree",
capabilities={"sms": True},
)
print(results[0].phone_number) # +18005550001
search_available_phone_numbers(
country="US",
type="TollFree",
sms_enabled=True
)
curl -G https://api.commune.email/v1/phone-numbers/available \
-H "Authorization: Bearer comm_..." \
-d "country=US" \
-d "type=TollFree" \
-d "sms_enabled=true"
commune phone-numbers search --country US --type TollFree
{
"data": [
{
"phoneNumber": "+18005550001",
"friendlyName": "(800) 555-0001",
"region": null,
"isoCountry": "US",
"capabilities": {
"sms": true,
"mms": true,
"voice": true
},
"beta": false
},
{
"phoneNumber": "+18335550002",
"friendlyName": "(833) 555-0002",
"region": null,
"isoCountry": "US",
"capabilities": {
"sms": true,
"mms": false,
"voice": true
},
"beta": false
}
]
}
{
"error": "plan_upgrade_required",
"feature": "smsMessaging"
}
import { CommuneClient } from 'commune-ai';
const commune = new CommuneClient({ apiKey: process.env.COMMUNE_API_KEY });
const results = await commune.phoneNumbers.search({
country: 'US',
type: 'TollFree',
capabilities: { sms: true },
});
console.log(results[0].phoneNumber); // +18005550001
from commune import CommuneClient
client = CommuneClient()
results = client.phone_numbers.search(
country="US",
type="TollFree",
capabilities={"sms": True},
)
print(results[0].phone_number) # +18005550001
search_available_phone_numbers(
country="US",
type="TollFree",
sms_enabled=True
)
curl -G https://api.commune.email/v1/phone-numbers/available \
-H "Authorization: Bearer comm_..." \
-d "country=US" \
-d "type=TollFree" \
-d "sms_enabled=true"
commune phone-numbers search --country US --type TollFree
{
"data": [
{
"phoneNumber": "+18005550001",
"friendlyName": "(800) 555-0001",
"region": null,
"isoCountry": "US",
"capabilities": {
"sms": true,
"mms": true,
"voice": true
},
"beta": false
},
{
"phoneNumber": "+18335550002",
"friendlyName": "(833) 555-0002",
"region": null,
"isoCountry": "US",
"capabilities": {
"sms": true,
"mms": false,
"voice": true
},
"beta": false
}
]
}
{
"error": "plan_upgrade_required",
"feature": "smsMessaging"
}
Query Parameters
string
default:"US"
ISO-3166 alpha-2 country code. Examples:
US, CA, GB.string
default:"TollFree"
Number type. One of:
Local, TollFree. Toll-free numbers do not require A2P 10DLC registration for US sending.string
Filter local numbers by area code (e.g.,
415). Only applies when type=Local.boolean
default:"true"
Only return numbers with SMS capability.
boolean
Only return numbers with MMS capability. MMS is supported on US and CA numbers only.
string
Filter numbers containing a specific digit pattern (e.g.,
555).string
Filter by state/region code (e.g.,
CA for California). Only applies to local numbers.number
default:"20"
Maximum number of results to return. Maximum: 20.
Response
AvailableNumber[]
Array of available phone numbers matching your criteria.
Hide AvailableNumber properties
Hide AvailableNumber properties
string
The phone number in E.164 format (e.g.,
+18005550001).string
Human-readable number format (e.g.,
(800) 555-0001).string | null
State or region code for local numbers.
null for toll-free.string
ISO-3166 country code of the number.
object
boolean
Whether the number is in beta with Twilio. Beta numbers may have limited availability.
SMS messaging requires the Agent Pro plan or higher. The free plan includes
smsMessaging access with 200 included credits per month.Last modified on March 19, 2026
Was this page helpful?

