---
title: "List phone numbers"
method: GET
path: "/v1/whatsapp/phone-numbers"
tags: ["WhatsApp Phone Numbers"]
deprecated: true
---

# List phone numbers

`GET /v1/whatsapp/phone-numbers`

> **Deprecated.**

Deprecated alias of `/v1/phone-numbers`; same contract. New
integrations should use that path.

List all WhatsApp phone numbers purchased by the authenticated user.
By default, released numbers are excluded. Connected (bring-your-own)
numbers are returned in the separate `connected` array. They are not
billed and have no provisioning lifecycle.

## Query parameters

- `status` 'provisioning' | 'verifying' | 'pending_payment' | 'pending_regulatory' | 'regulatory_declined' | 'active' | 'suspended' | 'releasing' | 'released'
- `profileId` string

## Response `200`

Phone numbers retrieved successfully

- object
  - `numbers` object[]
    - `_id` string
    - `phoneNumber` string
    - `country` string
    - `status` 'pending_payment' | 'pending_regulatory' | 'regulatory_declined' | 'provisioning' | 'verifying' | 'active' | 'suspended' | 'releasing' | 'released'
    - `registrantName` string, nullable — For regulated numbers, who it's registered for (company or person), set from the submitted KYC.
    - `telnyxOrderId` string, nullable — Present once the number order has been placed (i.e. the requirement group was approved). Absent while still in identity review.
    - `monthlyCents` integer — What this number bills each month, in cents. Stamped when the number was bought, so an existing number keeps its price when the rate card changes.
    - `hostedByZernio` boolean — False for numbers you brought yourself (connected via Meta embedded signup). They live on your own carrier, so SMS/Calls can't be enabled on them.
    - `sipTrunkId` string, nullable — SIP trunk the number is attached to; null when not trunked. While attached, enabling Calls or WhatsApp calling, requesting WhatsApp verification, and releasing the number all return 409.
    - `profileId` object
    - `provisionedAt` string, date-time
    - `metaPreverifiedId` string
    - `metaVerificationStatus` string
    - `onfidoVerificationUrl` string, nullable — For regulated (Tier 3/4) numbers with an Onfido ID-verification step: the link to forward to the end user. Set once the order is placed; null otherwise. Poll this field after submitting KYC.
    - `endUserFirstName` string, nullable
    - `endUserLastName` string, nullable
    - `regulatoryDeclineReason` string, nullable — Reviewer rejection reason when status is regulatory_declined.
    - `callingEnabled` boolean — Whether WhatsApp Business Calling is enabled on this number (manage via /v1/whatsapp/phone-numbers/{id}/calling).
    - `createdAt` string, date-time
  - `connected` object[] — Connected (bring-your-own) WhatsApp numbers: your own WABA numbers linked via Embedded Signup. Not provisioned or billed by Zernio, so they are not in `numbers`; `accountId` is the social-account id used by the messaging and inbox endpoints. Included only on the default and `status=active` views.
    - `accountId` string
    - `phoneNumber` string, nullable
    - `displayName` string, nullable
    - `profileId` string, nullable
    - `connectedAt` string, date-time, nullable
    - `callingEnabled` boolean — Whether WhatsApp Business Calling is enabled on this number.
  - `imessage` ImessageSenderLifecycle[] — iMessage phone senders (see /v1/imessage/senders/order). Hosted by the iMessage provider, not on your Telnyx numbers: SMS and Calls can never be enabled on them, and they bill as iMessage senders. `handle` is null until the carrier assigns the number at activation. Included only on the default and `status=active` views.
    - `id` string
    - `kind` 'phone' | 'email'
    - `region` 'US' | 'GB' | 'null', nullable
    - `handle` string, nullable — The sender handle once activation assigns it
    - `optInLink` string, nullable — imessage:// deep link that opens Messages on this sender with a prefilled text. Share it so contacts message you first (Apple only lets a sender reach contacts who wrote to it first); null until the handle is assigned.
    - `status` 'ordering' | 'activating' | 'active' | 'suspended' | 'canceled' | 'failed'
    - `priceCents` integer — Monthly price billed while the sender is active
    - `provider` string
    - `profileId` string
    - `displayName` string, nullable
    - `failureReason` string, nullable
    - `accountId` string, nullable — The messaging account created at activation
    - `createdAt` string, date-time
  - `sandbox` object, nullable — The shared WhatsApp sandbox (one Zernio-owned number, all users test against it). Present when the sandbox is configured; null otherwise. The `accountId` lets you address the sandbox in compose endpoints. `template` is the only template a sandbox send is allowed to use.
    - `phoneNumber` string
    - `accountId` string, nullable
    - `template` object
      - `name` string
      - `language` string
    - `isSandbox` boolean

## Other responses

- `400` — Invalid request
- `401` — Unauthorized

## Changes

- **2026-09-21** `339f59df69dd` — 1 info
  - added the optional property `imessage` to the response with the `200` status
- **2026-09-16** `3e6ddf2a99ea` — 1 info
  - added the optional property `details/budgetScope` to the response with the `400` status
- **2026-09-15** `0dba7d004d75` — 2 info
  - added the optional property `details/quotaExhausted` to the response with the `400` status
  - added the optional property `details/quotaScope` to the response with the `400` status
- **2026-08-24** `1307bc21beec` — 1 info
  - added the optional property `numbers/items/sipTrunkId` to the response with the `200` status
- **2026-08-21** `15e893e69e8c` — 2 info
  - added the optional property `connected/items/callingEnabled` to the response with the `200` status
  - added the optional property `numbers/items/callingEnabled` to the response with the `200` status

[Change history](https://skmtc.dev/zernio/apis/zernio-api/changes/v1/whatsapp/phone-numbers/get.md)

---

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