Logo
Search
Docs

Available phone numbers

GET https://app.sulus.ai/api/phone-numbers/available

Search purchasable phone number inventory

Authentication

Send a bearer token created on your dashboard's Developer page:

Authorization: Bearer <YOUR_API_KEY>

Query parameters

country string Optional Nullable

Country name; mapped to a 2-letter country_code when provided.

Validation: nullable|string|in:United States,Canada,Australia,United Kingdom
country_code string Optional Nullable Default: US

ISO country code used when country is omitted.

Validation: nullable|string|max:2
area_code string Optional Nullable
Validation: nullable|string|max:3 (exactly 3 digits when set; only US, CA, AU, GB)
limit integer Optional Nullable Default: 10
Validation: nullable|integer|min:1|max:50

Errors

StatusMeaningBody
422 Area code not supported or not 3 digits {"success":false,"message":"Area code must be exactly 3 digits."}
500 Inventory search failed {"success":false,"message":"Failed to load available phone numbers."}
401 Missing or invalid bearer token
403 Feature phone_numbers not enabled for the account

Notes

  • Use a returned phone_number as the body of POST /phone-numbers.
  • This path must be registered before /phone-numbers/{id}.
curl --request GET \
  --url https://app.sulus.ai/api/phone-numbers/available \
  --header 'Authorization: Bearer <YOUR_API_KEY>'
import requests

url = "https://app.sulus.ai/api/phone-numbers/available"
headers = {"Authorization": "Bearer <YOUR_API_KEY>"}

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

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://app.sulus.ai/api/phone-numbers/available"
	req, _ := http.NewRequest("GET", url, nil)
	req.Header.Add("Authorization", "Bearer <YOUR_API_KEY>")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}
Response 200 
{
    "success": true,
    "data": [
        {
            "phone_number": "+14155551234",
            "locality": "San Francisco",
            "region": "CA"
        }
    ]
}