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

import { RestClient } from "@signalwire/sdk";
const client = new RestClient({
  project: "your-project-id",
  token: "your-api-token",
  host: "your-space.signalwire.com"
});
const available = await client.phoneNumbers.search({ areacode: "503", max_results: 5 });
for (const number of available.data ?? []) {
    console.log(number.e164, number.region);
}