Skip to main content
POST
Reserve a line
  • Credential: an API key, on any account. The call checks no payment method. See Reservations.
  • Line-scoped keys: a line-scoped key gets 403 forbidden unless the line is in its list.
  • Test keys: a reservation sent with an isnap_test_ account key reserves a real line: see Test keys.
  • Idempotency-Key: not honored. Reserving a line that you have already reserved returns 409 conflict and does not extend the reservation.
  • Payment: no operation that an API key can call activates the reserved line of a direct account or pays for it. A payment started in the iSnap dashboard moves expires_at to 24 hours after its start: see A line paid in the dashboard.
  • Events: none. See Events.

Errors

Treat any 409 as “choose another line”, except after a request whose response you did not receive: read GET /v1/lines/my first, since a line that you have already reserved also returns 409 conflict. This operation never returns 404. The errors that every operation shares are in Errors.

Authorizations

Authorization
string
header
required

An API key created in the iSnap dashboard, or a trial key, sent as Authorization: Bearer <key>. An API key starts with isnap_live_ or isnap_test_; both act on the same account, lines and billing. A trial key acts on its trial only.

Path Parameters

id
string
required

Id of a line: line_ followed by 25 letters or digits.

Pattern: ^line_[0-9A-Za-z]{25}$

Response

The reserved line, with its full phone number and expires_at.

success
enum<boolean>
required

Always true on a success response.

Available options:
true
data
object
required

A line. billing_tier, byod, shared, test_line and inbound_only tell the kinds of line apart: a rented line (two-way or inbound-only), a BYOD line, a shared line, a test line.

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.