---
title: "Listar números"
method: GET
path: "/v1/organizations/me/numbers"
tags: ["Números"]
---

# Listar números

`GET /v1/organizations/me/numbers`

## Request

- Base URL: `https://api.ararahq.com`
- URL: `https://api.ararahq.com/v1/organizations/me/numbers`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/ararahq/apis/ararahq-api/docs/v1/organizations/me/numbers/get.ts> (a function with typed inputs; its response is checked against the schema)

Números ativos da organização, com qualidade, limite diário (tier) e uso do plano. Permissão: `READ`.

## Response `200`

Números e slot do plano

- NumbersResponse
  - `numbers` NumberCard[], required
    - `id` string, required
    - `name` string, required
    - `alias` string, nullable
    - `description` string, nullable
    - `phoneNumber` string, required
    - `type` 'SHARED' | 'DEDICATED', required
    - `isDefault` boolean, required
    - `status` 'ACTIVE' | 'PENDING_REVIEW' | 'SUSPENDED' | 'DISABLED', required
    - `qualityScore` 'HIGH' | 'MEDIUM' | 'LOW' | 'FLAGGED' | 'UNKNOWN', required: Qualidade do número segundo a Meta.
    - `messagingTier` 'TIER_50' | 'TIER_250' | 'TIER_1K' | 'TIER_2K' | 'TIER_10K' | 'TIER_100K' | 'UNLIMITED' | 'UNKNOWN', required: Tier informado pela Meta (conversas iniciadas pelo número por dia): `TIER_50` (50), `TIER_250` (250), `TIER_1K` (1.000), `TIER_2K` (2.000), `TIER_10K` (10.000), `TIER_100K` (100.000) e `UNLIMITED` (sem limite); `UNKNOWN` é tier ainda não sincronizado. O teto diário que a Arara aplica no envio é o do tier, exceto `TIER_2K` e `UNKNOWN`, tratados como 1.000.
    - `verifiedAt` string, date-time, nullable
    - `lastHealthCheckAt` string, date-time, nullable
    - `provider` string, required
    - `createdAt` string, date-time, nullable
    - `messagesLast7d` integer
    - `messagesLast30d` integer
    - `deliveredLast30d` integer
    - `provisionedByArara` boolean
    - `wabaId` string, nullable
    - `isCoexistence` boolean, nullable
  - `slot` object, required
    - `used` integer, required
    - `max` integer, required
    - `planLabel` string, required
    - `atCap` boolean, required
    - `noEntitlement` boolean, required
    - `monthlyPriceCents` integer, required
    - `monthlyTotalCents` integer, required

## Other responses

- `401`: Chave inexistente, revogada, expirada, com prefixo errado (`ara_` sem `ara_live_`) ou vinda de IP fora da allowlist. O corpo é o JSON padrão do Spring, sem `error.code`.
- `403`: Dois casos, com corpos diferentes: - Autenticação: header `Authorization` ausente, Bearer que não começa com `ara_`, chave sem a permissão da rota ou rota que não aceita chave de API. Corpo no formato padrão do Spring, sem `error.code`. - Regra de negócio, no formato `{ "error": { ... } }`: `PLAN_FEATURE_LOCKED`, `PLAN_LIMIT_REACHED`, `ACCOUNT_NOT_ACTIVATED`, `NO_DEDICATED_NUMBER`, `ORGANIZATION_SUSPENDED`, `NUMBER_BLOCKED`, `FRAUD_SUSPECTED`, `RESOURCE_FORBIDDEN`, `VIEWER_READ_ONLY`.
- `429`: `RATE_LIMIT_EXCEEDED`: limite geral da API (1.200 leituras ou 3.000 escritas por minuto, por usuário da chave).

## Changes

- **2026-10-12** `d576cd28afc0`: 3 info
  - api tag `Números` added
  - api tag `numbers` removed
  - added the non-success response with the status `429`
- **2026-09-15** `372d8c2e735d`: 4 breaking, 8 warning, 11 info
  - the response property `error` became optional for the status `401`
  - the `error` response's property type changed from `object` to `string` for status `401`
  - removed the required property `error/code` from the response with the `401` status
  - removed the required property `error/message` from the response with the `401` status
  - …19 more
- **2026-05-25** `4e426b85f784`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/ararahq/apis/ararahq-api/changes/v1/organizations/me/numbers/get.md)

---

[API](https://skmtc.dev/ararahq/apis/ararahq-api.md) - [All operations](https://skmtc.dev/ararahq/apis/ararahq-api/llms.txt) - [OpenAPI document](https://skmtc.dev/ararahq/apis/ararahq-api/revisions/d576cd28afc0?raw)