Skip to main content
GET
List available lines
  • Credential: none. The operation ignores any credential, and phone numbers are masked for every caller. See The marketplace.
  • Events: none.
  • What is listed: only lines that can be acquired now. A line can leave the list and come back, so read the list again before each reservation.
  • Pagination: by page number, with page and limit. This list does not use the cursors of the other list operations.
  • Metadata: each line carries its metadata, which can hold keys that an earlier owner left. The query parameter metadata.<key>=<value> keeps the lines whose metadata holds exactly that string under that key. Anyone can use this filter, without a credential: never put personal data or secrets in line metadata. See Metadata at acquisition.

Errors

The errors that every operation shares are in Errors.

Query Parameters

billing_tier
enum<string>

Keep the lines of one kind: rental_iphone, rental_android, byod_imessage or byod_android. shared_pool and shared_imessage are accepted and always return an empty list: shared lines, test lines and dedicated pool lines are never listed.

Available options:
rental_iphone,
rental_android,
byod_imessage,
byod_android,
shared_pool,
shared_imessage
area_code
string

Keep the lines whose area_code is exactly this value, a 3-digit North American area code.

Maximum string length: 10
country_code
string

Keep the lines of one country: ISO 3166-1 alpha-2 code, case-insensitive.

Required string length: 2
state
string

Keep the lines of one US state: its 2-letter code or its name, case-insensitive. An unknown state returns an empty list.

Required string length: 2 - 40
Example:

"California"

country
string

Keep the lines of one country: its ISO 3166-1 alpha-2 code or its name, case-insensitive. An unknown country returns an empty list.

Required string length: 2 - 60
Example:

"United States"

status
string

Accepts available, or an empty value: any other value returns 400 validation_failed. The list holds available lines whether or not this parameter is sent.

Example:

"available"

page
integer
default:1

Page number, starting at 1.

Required range: x >= 1
limit
integer
default:20

Number of lines per page, from 1 to 100.

Required range: 1 <= x <= 100

Response

One page of available lines, with the number of lines that match the filters.

success
enum<boolean>
required

Always true on a success response.

Available options:
true
data
object
required

One page of the marketplace.

trace_id
string
required

Trace id of the request that produced this response: 32 lowercase hexadecimal characters. Quote it when you report a problem to iSnap.

request_id
string
required

Id of the request that produced this response: req_ followed by 25 letters or digits.