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

# List phone numbers

`GET /v1/phone-numbers`

List all phone numbers purchased by the authenticated user.
By default, released numbers are excluded. Connected (bring-your-own)
WhatsApp 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 — Per-country monthly price in cents ($2..$25).
    - `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.
    - `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.
    - `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
  - `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

- `401` — Unauthorized

---

[API](https://skmtc.net/zernio/apis/zernio-api.md) · [All operations](https://skmtc.net/zernio/apis/zernio-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/zernio/zernio-api/versions/51932b099b2f/schema)