Listar e consultar linhas telefônicas
Liste todas as linhas telefônicas do seu workspace ou obtenha uma peloid. As duas rotas retornam o mesmo objeto linha.
Exige uma chave com escopo de tenant. Com um token OAuth / MCP, o usuário precisa ser Proprietário ou Administrador (
phone_lines:read) — caso contrário, 403 PERMISSION_DENIED.GET /v1/phone-lines — Listar suas linhas
Retorna as linhas do workspace da chave, da compra mais recente para a mais antiga. Por padrão, só as linhas que você ainda mantém (ACTIVE, PAYMENT_PENDING, SUSPENDED); adicione includeClosed=true para incluir as encerradas (RETURNED, CANCELED).
boolean
padrão:"false"
true ou 1 inclui as linhas encerradas; false, 0 ou ausente as deixa de fora. Qualquer outro valor (a comparação diferencia maiúsculas: TRUE é recusado) → 400 INVALID_QUERY.Obter uma linha
GET /v1/phone-lines/{id} retorna { "line": { … } } para uma linha do seu workspace, incluindo as encerradas.
{id} é o id da linha (da lista, ou lineId no resultado da compra) — não o número de telefone. Uma linha de outro workspace responde 404 LINE_NOT_FOUND, exatamente como uma linha que não existe.
Campos do objeto linha
string
O id da linha. Use-o em todo caminho
/v1/phone-lines/{id}.string
Dígitos E.164 sem o
+, por exemplo 551148637200.string
O número formatado para leitura humana:
(11) 4863-7200.string
O DDD, com dois dígitos.
string
ACTIVE, PAYMENT_PENDING, SUSPENDED, RETURNED ou CANCELED. Veja o ciclo de vida da linha.number
Preço mensal desta linha, congelado na compra (por exemplo,
33.9). Toda renovação da linha cobra esse valor.string
BRL ou USD — a moeda em que o price é cobrado.string
ISO 8601 — quando a linha foi comprada. As renovações contam a partir desta data: no mesmo dia de cada mês, ou no último dia do mês quando esse dia não existe — e esse dia mais curto passa a valer daí em diante.
string
ISO 8601 — fim do período pago. A próxima renovação é tentada na primeira execução horária do faturamento depois dele. Para uma linha cancelada no fim do período, é quando ela passa a
CANCELED.boolean
true depois de um DELETE em uma linha ACTIVE: ela não será renovada e passa a CANCELED em currentPeriodEnd.string | null
ISO 8601 — quando a cobrança da renovação falhou. A linha é suspensa 2 dias depois disso. Volta a ser
null quando uma renovação é bem-sucedida.string | null
ISO 8601 — quando a linha foi suspensa. Ela é devolvida 1 dia depois disso. Volta a ser
null quando uma renovação é bem-sucedida.string | null
ISO 8601 — quando o número foi devolvido à operadora (
RETURNED).string | null
ISO 8601 — quando uma linha cancelada no fim do período passou a
CANCELED.integer
Quantos pedidos de código foram abertos nesta linha até agora. Um
POST …/activations que respondeu 503 não é contado.status é o campo em que a sua lógica deve se basear. Os campos de data explicam como a linha chegou até ali; currentPeriodEnd não muda enquanto uma renovação está em atraso, então, em uma linha PAYMENT_PENDING ou SUSPENDED, ele já está no passado. returnedAt e canceledAt podem aparecer um instante antes de o status mudar, enquanto a operadora confirma a devolução ou o cancelamento.