List and inspect phone lines
List every phone line of your workspace, or fetch one by itsid. Both return the same line object.
Requires a tenant-scoped key. With an OAuth / MCP token, the user must be an Owner or Admin (
phone_lines:read) — 403 PERMISSION_DENIED otherwise.GET /v1/phone-lines — List your lines
Returns the lines of the key’s workspace, newest purchase first. By default only the lines you still hold (ACTIVE, PAYMENT_PENDING, SUSPENDED); add includeClosed=true to include the finished ones (RETURNED, CANCELED).
boolean
default:"false"
true or 1 includes finished lines; false, 0 or absent leaves them out. Any other value (case-sensitive: TRUE is refused) → 400 INVALID_QUERY.Fetch one line
GET /v1/phone-lines/{id} returns { "line": { … } } for one line of your workspace, finished lines included.
{id} is the line’s id (from the list, or lineId in the purchase result) — not the phone number. A line of another workspace answers 404 LINE_NOT_FOUND, the same as one that does not exist.
Line object fields
string
The line id. Use it in every
/v1/phone-lines/{id} path.string
E.164 digits without
+, e.g. 551148637200.string
The number formatted for people:
(11) 4863-7200.string
The two-digit area code.
string
ACTIVE, PAYMENT_PENDING, SUSPENDED, RETURNED or CANCELED. See the line lifecycle.number
Monthly price of this line, frozen at purchase (e.g.
33.9). Every renewal of the line charges this amount.string
BRL or USD — the currency price is charged in.string
ISO 8601 — when the line was bought. Renewals count from it: the same day each month, or the month’s last day when that day does not exist — and that shorter day then sticks.
string
ISO 8601 — end of the paid period. The next renewal is attempted in the first hourly billing run after it. For a line cancelled at period end, when it becomes
CANCELED.boolean
true after a DELETE on an ACTIVE line: it will not renew and becomes CANCELED at currentPeriodEnd.string | null
ISO 8601 — when the renewal charge failed. The line is suspended 2 days after this.
null once a renewal succeeds.string | null
ISO 8601 — when the line was suspended. It is returned 1 day after this.
null once a renewal succeeds.string | null
ISO 8601 — when the number was returned to the carrier (
RETURNED).string | null
ISO 8601 — when a line cancelled at period end became
CANCELED.integer
How many code requests were opened on this line so far. A
POST …/activations that answered 503 is not counted.status is the field to branch on. The timestamps explain how a line got there; currentPeriodEnd does not move while a renewal is unpaid, so on a PAYMENT_PENDING or SUSPENDED line it is already in the past. returnedAt and canceledAt can appear a moment before status changes, while the carrier confirms the return or cancellation.