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.

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.

Authentication

AuthorizationBearer

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

Query parameters

areaCodestring or nullOptional

3-digit area code, e.g. “415”. The most broadly supported filter.

citystring or nullOptional

City name. Pair with state. Support varies by account.

statestring or nullOptional

2-letter state code, e.g. “CA”. Pair with city for consistent results; standalone support varies by account.

zipstring or nullOptional

5-digit ZIP. Support varies by account.

countrystringOptionalDefaults to US

“US”, “CA”, or “UK” (“GB” is accepted as an alias). United Kingdom availability varies by account.

limitintegerOptional1-30Defaults to 10

Max results, 1-30.

Response

Successful Response

datalist of objects

widenedbooleanOptionalDefaults to false

Errors

422

Unprocessable Entity Error