> ## 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. # Buscar números disponíveis > Lista os números fixos que podem ser comprados agora em um DDD brasileiro. É o primeiro passo de uma compra: o `number` de cada resultado é exatamente o que `POST /v1/phone-lines` recebe. - **Buscar não é reservar.** Um número listado pode ser comprado por outra pessoa antes que a sua compra chegue a ele; nesse caso, ele volta nos resultados da compra como `NUMBER_UNAVAILABLE`. - **Toda busca chega à nossa operadora** e consome uma cota de requisições compartilhada por toda a plataforma. Busque uma vez, mostre a lista e reutilize-a — não consulte este endpoint periodicamente. Quando a cota se esgota, o endpoint responde `503 SUPPLIER_UNAVAILABLE`. - A verificação do titular **não** é necessária para buscar — só para comprar. Permissões: com um token OAuth / MCP, só o **Proprietário** do workspace pode buscar (`phone_lines:purchase`, a mesma permissão da compra) — caso contrário, `403 PERMISSION_DENIED`. Uma chave `ps_` clássica de tenant não tem usuário nem papel: a autoridade dela é o escopo. 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/available 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/available: get: tags: - Phone Lines summary: Buscar números disponíveis description: >- Lista os números fixos que podem ser comprados agora em um DDD brasileiro. É o primeiro passo de uma compra: o `number` de cada resultado é exatamente o que `POST /v1/phone-lines` recebe. - **Buscar não é reservar.** Um número listado pode ser comprado por outra pessoa antes que a sua compra chegue a ele; nesse caso, ele volta nos resultados da compra como `NUMBER_UNAVAILABLE`. - **Toda busca chega à nossa operadora** e consome uma cota de requisições compartilhada por toda a plataforma. Busque uma vez, mostre a lista e reutilize-a — não consulte este endpoint periodicamente. Quando a cota se esgota, o endpoint responde `503 SUPPLIER_UNAVAILABLE`. - A verificação do titular **não** é necessária para buscar — só para comprar. Permissões: com um token OAuth / MCP, só o **Proprietário** do workspace pode buscar (`phone_lines:purchase`, a mesma permissão da compra) — caso contrário, `403 PERMISSION_DENIED`. Uma chave `ps_` clássica de tenant não tem usuário nem papel: a autoridade dela é o escopo. 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_available parameters: - name: ddd in: query required: true description: >- O DDD com dois dígitos, sendo o primeiro de 1 a 9 (ex.: `11`, `21`, `31`). Ausente ou malformado → **400 `INVALID_AREA_CODE`**, e nenhuma chamada é feita à operadora. schema: type: string pattern: ^[1-9][0-9]$ example: '11' responses: '200': description: Números disponíveis no DDD content: application/json: schema: type: object properties: ddd: type: string description: O DDD que você buscou, repetido na resposta. example: '11' totalAvailable: type: integer description: >- Quantos números a operadora informa como disponíveis neste DDD. Não presuma que é igual ao tamanho de `numbers`. example: 2 numbers: type: array description: Os números retornados por esta busca. Sem paginação. items: type: object properties: number: type: string description: >- Dígitos E.164 **sem** o `+`: `55` + DDD + 8 dígitos, ex.: `551148637200`. Envie este valor para `POST /v1/phone-lines`. example: '551148637200' display: type: string description: >- O mesmo número formatado para leitura humana: `(11) 4863-7200`. example: (11) 4863-7200 price: type: number example: 33.9 description: >- Preço mensal de UMA linha nova para este workspace, mostrado antes da compra. Respeita o preço de linha próprio do workspace definido pela equipe da Pilot Status; é o mesmo valor que o `POST /v1/phone-lines` cobra. currency: type: string enum: - BRL - USD example: BRL description: A moeda do workspace — a moeda de `price` e da compra. example: ddd: '11' totalAvailable: 2 numbers: - number: '551148637200' display: (11) 4863-7200 - number: '551148637201' display: (11) 4863-7201 price: 33.9 currency: BRL '400': description: >- `ddd` ausente, ou sem dois dígitos começando por 1–9 (`INVALID_AREA_CODE`) content: application/json: schema: type: object properties: error: type: string code: type: string example: error: Invalid area code. | DDD inválido. code: INVALID_AREA_CODE '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 é o Proprietário do workspace (`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 é o Proprietário value: error: >- Your workspace role does not allow this action (phone_lines:purchase). 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: >- Foi enviado um header `x-whatsapp-number-id` que não indica nenhum número de WhatsApp da sua conta (`NUMBER_NOT_FOUND`). Este endpoint não precisa desse header — remova-o. content: application/json: schema: type: object properties: error: type: string code: type: string example: 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 '503': description: >- A operadora não respondeu, ou a cota de requisições compartilhada por toda a plataforma se esgotou (`SUPPLIER_UNAVAILABLE`). Tente de novo em alguns minutos. content: application/json: schema: type: object properties: error: type: string code: type: string example: error: >- Phone lines are temporarily unavailable. Try again in a few minutes. | As linhas estão temporariamente indisponíveis. Tente de novo em alguns minutos. code: SUPPLIER_UNAVAILABLE 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.