Search phone numbers
Searches SignalWire’s available inventory for local or toll-free phone numbers. Search results are candidates, not numbers your project owns; pass a selected result to Purchase phone number. Use List phone numbers for owned numbers, or Compatibility Available Phone Numbers for form-encoded requests.
Search results aren’t paginated. Each request returns up to max_results numbers, links is always empty, and paging parameters such as page_number are ignored. To see more of the inventory, raise max_results or run narrower searches, for example with starts_with set to an area code and exchange.
Permissions
The API token used to authenticate must have the following scope(s) enabled to make a successful request: Numbers.
Authentication
SignalWire Basic Authentication using Project ID and API Token.
The client sends HTTP requests with the Authorization header containing the word Basic followed by a space and a base64-encoded string of project_id:token. The project ID will be used as the username and the API token as the password.
Example:
Authorization: Basic base64(project_id:token)
Query parameters
Search for local or toll-free numbers: local, tollfree, or toll-free. Defaults to local. Any other value returns a 400 with no body.
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.
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.
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.
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.
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.
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
Always an empty object. Search results aren’t paginated, so there are no next or prev links.
The search filters that were applied, keyed by query parameter name. Always includes max_results; other filters appear only when you set them.