> ## 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.

# GET /v1/numbers — Listar e detalhar

> GET /v1/numbers — Retorna todos os números de WhatsApp conectados ao seu projeto Pilot Status, incluindo status, tipo e identificadores únicos.

# Listar e inspecionar números

Liste todos os números de WhatsApp da sua conta ou obtenha o detalhe completo de um número — incluindo a saúde e, para números Meta, dados em tempo real do Meta Graph.

<Note>
  Use uma chave de API com **escopo de tenant** para gerenciar números em toda a sua conta. Uma chave com escopo de número também pode chamar esses endpoints. Autentique-se com o cabeçalho `x-api-key: ps_...`.
</Note>

## GET /v1/numbers — Listar todos os números

Lista todas as instâncias de WhatsApp do **tenant** da chave de API como um array JSON.

* **Não** retorna credenciais de sessão.
* Cada número expõe seu `state` de conexão plano e uma flag `isFullyConnected`.
* A listagem **não** força uma atualização em massa do estado de conexão — use `GET /v1/numbers/{id}/status` por número quando precisar de uma verificação em tempo real.
* As entradas `apiKeys` de cada item incluem apenas `name`, `keyPrefix` e `keyLast4` (sem o `id` da chave de API).

```bash theme={null}
curl "https://pilotstatus.com.br/v1/numbers" \
  -H "x-api-key: ps_your_token_here"
```

## GET /v1/numbers/{id} — Detalhe completo de um número

Retorna o `state`/`isFullyConnected` plano, um bloco `health` (`qualityRating`, `messagingLimitTier`, `metaStatus`, `sendable`) e — para números **Meta** — um bloco aninhado em camelCase `meta` com informações de `phone`, `profile` e `waba` obtidas do Meta Graph. Para números não-Meta, `meta` é `null`.

<ParamField query="refresh" type="string">
  Adicione `?refresh=1` para forçar uma busca em tempo real no Meta Graph e persistir o snapshot. Por padrão, a resposta é armazenada em cache (último snapshot `meta`).
</ParamField>

Segredos (tokens de acesso, app secret, configuração do provedor) **nunca** são retornados. Retorna `404` se o id não pertencer ao tenant do chamador.

```bash theme={null}
# 1) liste para obter o id
curl "https://pilotstatus.com.br/v1/numbers" \
  -H "x-api-key: ps_your_token_here"

# 2) obtenha o detalhe completo de um número (adicione ?refresh=1 para buscar em tempo real no Meta Graph)
curl "https://pilotstatus.com.br/v1/numbers/wa_abc?refresh=1" \
  -H "x-api-key: ps_your_token_here"
```

Resposta (número Meta):

```json theme={null}
{
  "id": "wa_abc",
  "number": "5511999999999",
  "name": "My WhatsApp",
  "provider": "META",
  "state": "OPEN",
  "isFullyConnected": true,
  "createdAt": "2026-02-24T15:00:00.000Z",
  "updatedAt": "2026-06-30T09:18:33.000Z",
  "health": {
    "qualityRating": "GREEN",
    "messagingLimitTier": "TIER_2K",
    "metaStatus": "CONNECTED",
    "sendable": true
  },
  "meta": {
    "fetchedAt": "2026-06-30T09:18:33.000Z",
    "phone": {
      "displayPhoneNumber": "+55 11 99999-9999",
      "verifiedName": "Acme LTDA",
      "qualityRating": "GREEN",
      "messagingLimitTier": "TIER_2K",
      "isPinEnabled": true
    },
    "profile": {
      "about": "8h-18h",
      "email": "contato@acme.com",
      "websites": ["https://acme.com"],
      "vertical": "RETAIL"
    },
    "waba": {
      "id": "1029384756",
      "name": "Acme WABA",
      "currency": "BRL",
      "businessVerificationStatus": "verified",
      "country": "BR"
    }
  }
}
```

Para um número não-Meta (não oficial / QR), a mesma chamada retorna `"provider": "PILOT_STATUS"` e `"meta": null`.