Search Plivo Numbers
Search available phone numbers from Plivo.
When to use this
- Provisioning a new line: find an available number in the destination country before purchasing it for inbound or outbound calling.
- Self-serve number pickers: let users of your own product browse available numbers before you buy one on their behalf.
Result
The response is Plivo’s own search result, passed through unchanged:api_id, meta and the candidate numbers in objects. Plivo lists each number as digits without a plus sign; pass it to Buy Phone Number exactly as returned. Plivo can include fields beyond those in the schema on this page. When Plivo has no numbers for your filters, the response is still 200, with an empty objects list, meta.total_count of 0, and Plivo’s explanation in error (for example We are currently unable to offer your requested numbers); try another region, type or pattern. Availability is live inventory and can change between searching and buying, so purchase promptly after picking a number. See API errors for the standard error format.
Query parameters
Related endpoints
- Buy Phone Number: purchase a number found here.
- List Phone Numbers: the numbers your workspace already owns.
- Link SIP Trunk: bring your own number instead.
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Query Parameters
ISO country code (e.g., IN, US, GB)
"IN"
Number type: local, tollfree, or mobile. Defaults to tollfree.
"tollfree"
City or state filter. For IN it is sent to Plivo as city (for example Mumbai, Bengaluru, Chennai). For Mumbai and Bengaluru (or Bangalore) only, a city search that returns no numbers is retried with the city's STD code as a number pattern. For other countries it is sent as region (for example California, Texas).
"Mumbai"
Response
Available Plivo numbers returned successfully.
true false 200
"Success"
Plivo's search response, passed through unchanged. Plivo can include fields beyond those listed here.