List Available Numbers

Search purchasable phone numbers before buying one.

Pick a number here, then buy it by passing the same phoneNumber to POST /v1/numbers. Searching with no criteria returns a page of whatever is currently in stock.

Results are not reserved. This is live inventory, so a number can be bought by someone else between your search and your purchase. When that happens the purchase returns 409 with fresh alternatives in this same shape; pick another and retry rather than treating it as fatal.

Criteria support varies by account, and there is no single rule that holds everywhere:

• areaCode is the most broadly supported filter.
• city, state and zip work on some accounts and not others. Where they aren’t supported they are ignored rather than rejected, so check what comes back instead of assuming the filter applied.
• state on its own is honored on some accounts and rejected with 400 on others. Pair it with city for consistent behavior.

Returns 404 when number search isn’t available on your account at all, and 422 when it isn’t configured yet. If you need location search and aren’t getting it, contact support.

Giving a Canadian area code searches Canada even though country defaults to US.

country=UK (or GB) returns United Kingdom mobile numbers on accounts where they’re available. UK numbers are SMS-only and have no area codes, so location filters are rejected for UK searches.

If widened is true, your exact criteria were out of stock and these are nearby alternatives instead.