Skip to navigation
REST ClientPhone Numbers

search

View as MarkdownOpen in Claude

Search for available phone numbers that can be purchased.

Query parameters

areacodestringOptional
An areacode to search within.
number_typestringOptional
Search for local or toll-free numbers: `local`, `tollfree`, or `toll-free`. Defaults to `local`. Any other value returns a `400` with no body.
starts_withstringOptional
3 to 7 digits the number must start with, not counting the `+1` country code. When `areacode` is also set, the match starts right after the area code. To find a vanity number, search by its keypad digits, for example `3569377` for `FLOWERS`. Cannot be used in combination with `contains` or `ends_with`.
containsstringOptional
3 to 7 digits that must appear somewhere in the number, after the area code when `areacode` is also set. On Spaces limited to 10 toll-free results, a toll-free `contains` search matches only the end of the number. To find a vanity number, search by its keypad digits. Cannot be used in combination with `starts_with` or `ends_with`.
ends_withstringOptional
3 to 7 digits the number must end with. To find a vanity number, search by its keypad digits. Cannot be used in combination with `starts_with` or `contains`.
max_resultsintegerOptional>=1
The maximum number of matches to return. Defaults to 50. Toll-free searches accept up to 100; some Spaces are limited to 10 toll-free results, with a default of 5. Local searches have no fixed upper limit, but a very large value can make the search return no numbers or fail with an error; narrow the search with `areacode`, `region`, `city`, or `starts_with` rather than raising `max_results` that far.
regionstringOptional
A region or state to search within. Must be an ISO 3166-2 alpha-2 code, i.e. TX for Texas. Only supported for local searches; not supported when `number_type` is toll-free.
citystringOptional
A specific City to search within. Must be used in combination with region. Only supported for local searches; not supported when `number_type` is toll-free.

Response

filtersobjectRequired
The search filters that were applied, keyed by query parameter name. Always includes `max_results`; other filters appear only when you set them.
ignored_parameterslist of stringsRequired
The names of any query parameters in the request that this operation doesn't recognize and ignored.
datalist of objectsOptional
List of available phone numbers.

Response Example

Response
{
  "links": {},
  "filters": {
    "areacode": "918",
    "max_results": 1
  },
  "ignored_parameters": [],
  "data": [
    {
      "e164": "+15551234567",
      "national_number_formatted": "(555) 123-4567",
      "international_number_formatted": "+1 555-123-4567",
      "rate_center": "LOS ANGELES",
      "region": "CA",
      "country_code": "US",
      "capabilities": [
        "voice",
        "fax",
        "sms",
        "mms"
      ]
    }
  ]
}

Example

from signalwire.rest import RestClient
client = RestClient(
    project="your-project-id",
    token="your-api-token",
    host="your-space.signalwire.com",
)
available = client.phone_numbers.search(areacode="503", max_results=5)
for number in available.get("data", []):
    print(number["e164"], number.get("region"))