Skip to main content
GET
Search Plivo Numbers
Read only Searches Plivo’s inventory of phone numbers that are available for purchase. This is the discovery step before buying: find a number in the country and pattern you want, then pass it to Buy Phone Number.

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.
If you bring your own number instead of buying one, skip this endpoint and use Link SIP Trunk.

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

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

country_iso
string
required

ISO country code (e.g., IN, US, GB)

Example:

"IN"

type
string
default:tollfree

Number type: local, tollfree, or mobile. Defaults to tollfree.

Example:

"tollfree"

region
string

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).

Example:

"Mumbai"

Response

Available Plivo numbers returned successfully.

success
enum<boolean>
required
Available options:
true
error
enum<boolean>
required
Available options:
false
statusCode
integer
required
Example:

200

message
string
required
Example:

"Success"

data
object
required

Plivo's search response, passed through unchanged. Plivo can include fields beyond those listed here.

timestamp
string<date-time>
required