Search Available Numbers

Search the inventory of phone numbers available to rent.

GEThttps://api.identitycall.ai/api/v1/public/virtual_numbers/available

Queries our phone-number provider for numbers available to purchase in the requested country and number type.

Requires read permission

Scopes

API key scope	Behavior
Account-wide	Allowed.
Project-scoped	Allowed. The search is provider-side and not constrained by project.

Query Parameters

Parameters

Name	Type	Required	Default	Description
`country`	string	No	`US`	ISO 3166-1 alpha-2 country code (case-insensitive)
`number_type`	string	No	`mobile`	Number type: mobile, local, toll-free, or national

Request

cURL


curl -X GET "https://api.identitycall.ai/api/v1/public/virtual_numbers/available?country=US&number_type=local" \
  -H "Authorization: Bearer $IDENTITYCALL_API_KEY"

Python


import requests
import os
 
API_KEY = os.environ.get("IDENTITYCALL_API_KEY")
 
response = requests.get(
    "https://api.identitycall.ai/api/v1/public/virtual_numbers/available",
    headers={"Authorization": f"Bearer {API_KEY}"},
    params={"country": "US", "number_type": "local"}
)
 
for option in response.json()["data"]:
    print(f"{option['phone_number']} - upfront: {option.get('upfront_cost')}, monthly: {option.get('monthly_cost')}")

Node.js


const API_KEY = process.env.IDENTITYCALL_API_KEY;
 
const url = new URL('https://api.identitycall.ai/api/v1/public/virtual_numbers/available');
url.searchParams.set('country', 'US');
url.searchParams.set('number_type', 'local');
 
const response = await fetch(url, {
  headers: { 'Authorization': `Bearer ${API_KEY}` }
});
 
const { data } = await response.json();
data.forEach(opt => console.log(`${opt.phone_number} (${opt.country_code})`));

Response

The shape of each entry is passed through from our phone-number provider. The fields below are typical but provider-dependent.

Response200 OK

{
"data": [
  {
    "phone_number": "+15551234567",
    "country_code": "US",
    "number_type": "local",
    "upfront_cost": "1.00",
    "monthly_cost": "1.00",
    "features": ["sms", "voice", "mms"],
    "region_information": [
      { "region_type": "state", "region_name": "CA" }
    ]
  },
  {
    "phone_number": "+15551234568",
    "country_code": "US",
    "number_type": "local",
    "upfront_cost": "1.00",
    "monthly_cost": "1.00",
    "features": ["voice"],
    "region_information": [
      { "region_type": "state", "region_name": "NY" }
    ]
  }
]
}

Response Fields

Field	Type	Description
`phone_number`	string	E.164-formatted candidate number
`country_code`	string	ISO 3166-1 alpha-2 country code
`number_type`	string	Number category (mobile, local, toll-free, national)
`upfront_cost`	string	One-time purchase cost (decimal as string)
`monthly_cost`	string	Recurring monthly cost (decimal as string)
`features`	array	Capabilities supported by the number
`region_information`	array	Provider-supplied region metadata

Errors

Status	Error	Description
422	Provider error	The upstream provider rejected the search (invalid country, etc.)

Try It

API Key

Parameters

country

number_type

Search Available Numbers

Scopes

Query Parameters

Parameters

Request

cURL

Python

Node.js

Response

Response Fields

Errors

See Also

Try It

Try It