Search phone numbers

GET

https://{your_space_name}.signalwire.com/api/relay/rest/phone_numbers/search

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.

Permissions

The API token used to authenticate must have the following scope(s) enabled to make a successful request: Numbers.

Learn more about API scopes.

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](/docs/apis/rest/phone-numbers/purchase-phone-number). Use [List phone numbers](/docs/apis/rest/phone-numbers/list-phone-numbers) for owned numbers, or Compatibility [Available Phone Numbers](/docs/compatibility-api/rest/available-phone-numbers/search-local-available-phone-numbers) for form-encoded requests. #### Permissions The API token used to authenticate must have the following scope(s) enabled to make a successful request: _Numbers_. [Learn more about API scopes](/docs/platform/your-signalwire-api-space).

Authentication

AuthorizationBasic

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)

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

areacodestringOptional

An areacode to search within.

number_typestringOptional

Search for either local or toll-free numbers. Defaults to local.

starts_withstringOptional

A string of 3 to 7 digits that should be used as the start of a number. Cannot be used in combination with contains or ends_with.

containsstringOptional

A string of 3 to 7 digits that should appear somewhere in the number. Cannot be used in combination with starts_with or ends_with.

ends_withstringOptional

A string of 3 to 7 digits that should be used as the end of a number. Cannot be used in combination with starts_with or contains.

max_resultsintegerOptional

The maximum number of matches to return. Upper limit of 100. Defaults to 50.

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

The request has succeeded.

linksobjectOptional

Pagination links.

datalist of objectsOptional

List of available phone numbers.

Errors

401

Unauthorized Error

500

Internal Server Error