<Intro>

<EndpointHeader />

<Description>

Returns phone numbers available for purchase in a country, newest first. Narrow the search with `number_type`, `capabilities`, and `prefix`. Inventory numbers are returned first and support pagination. The final page can include a live snapshot of numbers available from suppliers.

</Description>

</Intro>

<Parameters in="query">

<Parameter name="country_code" type="string">

<Description>

ISO 3166-1 alpha-2 country code to search in.

</Description>

</Parameter>

<Parameter name="number_type" type="string">

<Description>

Return only numbers of this physical type after applying the country and prefix filters.

</Description>

<Description>

Possible values (may grow over time): `mobile`, `local`, `national`, `short_code`, `short_code_fteu`, `toll_free`

</Description>

</Parameter>

<Parameter name="prefix" type="string">

<Description>

Return only numbers that start with these digits, matched right after the country dial code: with `country_code=US`, `prefix=212` matches +1 212 area-code numbers and `prefix=833` matches 833 toll-free numbers. Digits only. Leave out the country dial code and any national dialing prefix such as a leading 0. Short codes never match a prefix search.

</Description>

</Parameter>

<Parameter name="capabilities" type="array">

<Description>

Filter by channel capability. Repeat the parameter to require several at once: `capabilities=sms&capabilities=voice` returns only numbers that support both.

</Description>

</Parameter>

<Parameter name="limit" type="integer">

<Description>

Maximum number of items to return per page.

</Description>

</Parameter>

<Parameter name="starting_after" type="string">

<Description>

Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order.

</Description>

</Parameter>

<Parameter name="ending_before" type="string">

<Description>

Cursor from the `prev_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order.

</Description>

</Parameter>

</Parameters>

<Payload kind="response">

<Field name="data" type="array of object" required>

<FieldChildren kind="response">

<Field name="number" type="string" prefix="data." required>

<Description>

Phone number in E.164 format.

</Description>

</Field>

<Field name="country_code" type="string" prefix="data." required>

<Description>

ISO 3166-1 alpha-2 country code.

</Description>

</Field>

<Field name="number_type" type="string" prefix="data." required>

<Description>

Physical type of this phone number.

</Description>

</Field>

<Field name="capabilities" type="array of string" prefix="data." required>

<Description>

Channel capabilities supported by this number.

</Description>

</Field>

</FieldChildren>

</Field>

<Field name="next_cursor" type="nullable string" required>

<Description>

Cursor for the next page. Pass back as `starting_after` to advance forward. `null` when no next page exists.

</Description>

</Field>

<Field name="prev_cursor" type="nullable string" required>

<Description>

Cursor for the previous page. Pass back as `ending_before` to step backward. `null` when no previous page exists.

</Description>

</Field>

<Field name="refresh_cursor" type="nullable string" required>

<Description>

Refresh anchor. Pass back as `ending_before` later to fetch items that have appeared since this response. Non-`null` whenever `data` is non-empty; `null` only on an empty page. Distinct from `prev_cursor`.

</Description>

</Field>

</Payload>