> ## Documentation Index > Fetch the complete documentation index at: https://docs.pilotstatus.com.br/llms.txt > Use this file to discover all available pages before exploring further. # Obter linha > 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. Permissões: com um token OAuth / MCP, o usuário precisa ser **Proprietário ou Administrador** (`phone_lines:read`) — caso contrário, `403 PERMISSION_DENIED`. Todo endpoint `/v1/phone-lines` aceita só uma chave **com escopo de tenant**: a linha pertence ao workspace, não a um número de WhatsApp, então uma chave com escopo de número (ou uma concessão OAuth por número) recebe `403 NUMBER_SCOPE_NOT_ALLOWED` antes de qualquer verificação de papel. Um `403 PERMISSION_DENIED` / `WORKSPACE_MEMBERSHIP_REQUIRED` é enviado com `Cache-Control: no-store`. **Requer uma chave com escopo de tenant.** ## OpenAPI ````yaml openapi.pt.json GET /v1/phone-lines/{id} openapi: 3.1.0 info: title: API Pilot Status version: 1.0.0 license: name: Pilot Status Terms of Service url: https://pilotstatus.com.br/terms description: >- API REST pública do Pilot Status. Autentique com o header `x-api-key: ps_...` (ou `x-api-key-id`). Base URL: https://pilotstatus.com.br servers: - url: https://pilotstatus.com.br security: - apiKey: [] - apiKeyId: [] paths: /v1/phone-lines/{id}: get: tags: - Phone Lines summary: Obter uma linha telefônica description: >- 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. Permissões: com um token OAuth / MCP, o usuário precisa ser **Proprietário ou Administrador** (`phone_lines:read`) — caso contrário, `403 PERMISSION_DENIED`. Todo endpoint `/v1/phone-lines` aceita só uma chave **com escopo de tenant**: a linha pertence ao workspace, não a um número de WhatsApp, então uma chave com escopo de número (ou uma concessão OAuth por número) recebe `403 NUMBER_SCOPE_NOT_ALLOWED` antes de qualquer verificação de papel. Um `403 PERMISSION_DENIED` / `WORKSPACE_MEMBERSHIP_REQUIRED` é enviado com `Cache-Control: no-store`. **Requer uma chave com escopo de tenant.** operationId: get_phone_lines_id parameters: - name: id in: path required: true schema: type: string example: cmg5k2l1n0001pl8example9x description: >- O `id` da linha (de `GET /v1/phone-lines`, ou `lineId` no resultado da compra) — não o número de telefone. responses: '200': description: A linha content: application/json: schema: type: object properties: line: type: object properties: id: type: string description: >- O id da linha. Use-o em todo caminho `/v1/phone-lines/{id}`. example: cmg5k2l1n0001pl8example9x name: type: string description: >- O nome que sua equipe deu à linha no painel, com até 60 caracteres. **Nunca vem vazio:** uma linha sem nome retorna o número formatado, igual a `display` — e toda linha é comprada sem nome. Não pode ser definido nem alterado pela API. É um rótulo: identifique a linha pelo `id`. example: Suporte SP number: type: string description: >- Dígitos E.164 **sem** o `+`, por exemplo `551148637200`. example: '551148637200' display: type: string description: >- O número formatado para leitura humana: `(11) 4863-7200`. example: (11) 4863-7200 ddd: type: string description: O DDD, com dois dígitos. example: '11' status: type: string description: >- `ACTIVE`, `PAYMENT_PENDING`, `SUSPENDED`, `RETURNED` ou `CANCELED`. É o campo em que a sua lógica deve se basear. example: ACTIVE enum: - ACTIVE - PAYMENT_PENDING - SUSPENDED - RETURNED - CANCELED price: type: number description: >- Quanto **esta** linha custa por mês — o preço da próxima renovação (por exemplo, `33.9`): o preço de compra, ou o preço próprio da linha do workspace quando a equipe da Pilot Status definiu um (vale também para linhas compradas antes). example: 33.9 currency: type: string description: '`BRL` ou `USD` — a moeda em que o `price` é cobrado.' example: BRL enum: - BRL - USD purchasedAt: type: string description: >- ISO 8601 — quando a linha foi comprada. As renovações contam a partir desta data. example: '2026-10-01T14:03:11.000Z' format: date-time currentPeriodEnd: type: string description: >- 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`. Não muda enquanto uma renovação está em atraso. example: '2026-11-01T14:03:11.000Z' format: date-time cancelAtPeriodEnd: type: boolean description: >- `true` depois de um `DELETE` em uma linha `ACTIVE`: ela não será renovada e passa a `CANCELED` em `currentPeriodEnd`. example: false paymentPendingSince: type: - string - 'null' description: >- 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. example: null format: date-time suspendedAt: type: - string - 'null' description: >- ISO 8601 — quando a linha foi suspensa. Ela é devolvida 1 dia depois disso. Volta a ser `null` quando uma renovação é bem-sucedida. example: null format: date-time returnedAt: type: - string - 'null' description: >- ISO 8601 — quando o número foi devolvido à operadora (`RETURNED`). example: null format: date-time canceledAt: type: - string - 'null' description: >- ISO 8601 — quando uma linha cancelada no fim do período passou a `CANCELED`. example: null format: date-time activationCount: type: integer description: >- Quantos pedidos de código foram abertos nesta linha até agora. Um `POST …/activations` que respondeu `503` não é contado. example: 1 amountDue: type: - number - 'null' description: >- Numa linha `PAYMENT_PENDING` ou `SUSPENDED`, quanto pagá-la agora cobra — o valor do período em atraso, fixado na primeira cobrança daquele período. `null` em qualquer outra linha. example: null example: line: id: cmg5k2l1n0001pl8example9x name: Suporte SP number: '551148637200' display: (11) 4863-7200 ddd: '11' status: PAYMENT_PENDING price: 33.9 currency: BRL purchasedAt: '2026-10-01T14:03:11.000Z' currentPeriodEnd: '2026-11-01T14:03:11.000Z' cancelAtPeriodEnd: false paymentPendingSince: '2026-11-01T14:17:02.000Z' suspendedAt: null returnedAt: null canceledAt: null activationCount: 1 amountDue: 33.9 '401': description: >- Credencial ausente ou inválida (`x-api-key`, `x-api-key-id` ou `Authorization: Bearer`). O corpo traz só `error`, sem `code`. content: application/json: schema: type: object properties: error: type: string code: type: string examples: missing: summary: Sem credencial value: error: >- Missing x-api-key, x-api-key-id or Authorization Bearer token invalid: summary: API key inválida value: error: Invalid API key '403': description: >- Chave com escopo de número (`NUMBER_SCOPE_NOT_ALLOWED`), token OAuth/MCP de um usuário que não é Proprietário nem Administrador (`PERMISSION_DENIED`) ou que não é mais membro ativo (`WORKSPACE_MEMBERSHIP_REQUIRED`), ou workspace arquivado (`WORKSPACE_ARCHIVED`). `TENANT_REQUIRED`: credencial sem workspace content: application/json: schema: type: object properties: error: type: string code: type: string examples: numberScope: summary: Chave com escopo de número value: error: This endpoint requires a tenant-scoped API key code: NUMBER_SCOPE_NOT_ALLOWED permissionDenied: summary: Usuário OAuth/MCP que não é Proprietário nem Administrador value: error: >- Your workspace role does not allow this action (phone_lines:read). code: PERMISSION_DENIED notMember: summary: Usuário OAuth/MCP que não é mais membro value: error: >- The user behind this token is not an active member of this workspace. code: WORKSPACE_MEMBERSHIP_REQUIRED archived: summary: Workspace arquivado value: error: >- This workspace has been archived and its API is closed. | Este workspace foi arquivado e sua API está encerrada. code: WORKSPACE_ARCHIVED tenantRequired: summary: Credencial sem workspace value: error: This credential is not bound to a workspace. code: TENANT_REQUIRED '404': description: >- Essa linha não existe no seu workspace (`LINE_NOT_FOUND`) — uma linha de outro workspace recebe a mesma resposta content: application/json: schema: type: object properties: error: type: string code: type: string examples: lineNotFound: summary: Essa linha não existe no seu workspace value: error: Line not found. | Linha não encontrada. code: LINE_NOT_FOUND numberHeader: summary: '`x-whatsapp-number-id` não indica nenhum número' value: error: >- x-whatsapp-number-id does not name a WhatsApp number of this account | x-whatsapp-number-id não indica um número de WhatsApp desta conta code: NUMBER_NOT_FOUND '500': description: Falha inesperada (`INTERNAL_ERROR`). content: application/json: schema: type: object properties: error: type: string code: type: string example: error: Unexpected error. | Erro inesperado. code: INTERNAL_ERROR components: securitySchemes: apiKey: type: apiKey in: header name: x-api-key description: Sua chave de API ps_ apiKeyId: type: apiKey in: header name: x-api-key-id description: Id da chave de API (alternativa ao x-api-key) ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.