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

# List phone numbers

`GET /v1/messaging/phone-numbers`

## Request

- Base URL: `https://apihub.co.il`
- URL: `https://apihub.co.il/v1/messaging/phone-numbers`
- Auth: HTTP bearer

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.


**Billing:** Read (free unless it says otherwise) · **Rate limit:** 120/min

## Query parameters

- `status` 'provisioning' | 'verifying' | 'pending_payment' | 'pending_regulatory' | 'regulatory_declined' | 'active' | 'suspended' | 'releasing' | 'released': Filter by status (by default excludes released numbers). NOTE: `status=pending_regulatory` returns the "provisioning" view: numbers still in review PLUS recently-declined (last 30 days) ones, so a failed registration surfaces (with `regulatoryDeclineReason`) instead of silently disappearing. Declined numbers can be re-submitted via POST /v1/phone-numbers/{id}/remediate. `verifying` is the short-lived state after the number is provisioned on our side while WhatsApp confirms the activation code; the number is not billed until it reaches `active`.

## Headers

- `Idempotency-Key` string
- `X-Tag` string

## Response `200`

Completed

- object
  - `id` string: Execution id — stable across internal retries; use it with GET /v1/executions/{id}
  - `status` 'pending' | 'processing' | 'completed' | 'partial' | 'failed' | 'cancelled' | 'timeout'
  - `operation` string
  - `tag` string, nullable: Your X-Tag, if sent
  - `created_at` string, date-time
  - `completed_at` string, date-time, nullable
  - `output` object: Operation result (see each operation). While a Studio render is processing: `stage` (queued · transcribing · downloading · preparing · cleaning_voice · mixing_audio · rendering · finishing), `phase` (the engine's: download · prepare · voice · audio · encode · qa · upload, or null), `progress` (a percent, 0–100) and `progress_fraction` (0–1), `eta_seconds` (seconds left, never below 0) and `estimate_seconds`
    - `numbers` object[]
      - `_id` string
      - `status` 'pending_payment' | 'pending_regulatory' | 'regulatory_declined' | 'provisioning' | 'verifying' | 'active' | 'suspended' | 'releasing' | 'released'
      - `country` string
      - `features` object
        - `calls` boolean
        - `whatsapp` boolean
        - `smsPending` boolean
      - `createdAt` string, date-time
      - `forwardTo` string: WhatsApp calling forward destination.
      - `ivrPrompt` string
      - `profileId` union: The profile the number belongs to: `{ _id, name }` when the profile exists, otherwise its id.
        - object
          - `_id` string
          - `name` string, nullable
        - string
      - `updatedAt` string, date-time
      - `verifyUrl` string, nullable: Stable redirect to the live Onfido session. Prefer it over `onfidoVerificationUrl`, since it always resolves to a fresh session.
      - `ivrEnabled` boolean
      - `ivrOptions` object[]
        - `digit` string
        - `label` string
        - `forwardTo` string
      - `mmsCapable` boolean: Whether the number can send MMS. Absent while unknown.
      - `numberType` string: For example local, mobile, national or toll_free.
      - `releasedAt` string, date-time
      - `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.
      - `smsCapable` boolean: Whether the number can send SMS. Absent while unknown.
      - `activatedAt` string, date-time
      - `connectedAt` string, date-time
      - `phoneNumber` string
      - `signupError` string: Meta's Embedded Signup error from the last failed connect attempt (raw text, often localized).
      - `suspendedAt` string, date-time
      - `domesticOnly` boolean: True when the number can only text numbers in its own country. Absent while unknown.
      - `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.
      - `onfidoOpened` boolean: True once the verify link has been opened at least once.
      - `smsBrandName` string, nullable: Brand of the 10DLC registration covering the number.
      - `smsRequested` boolean
      - `businessHours` object[]
        - `day` integer
        - `open` string
        - `close` string
      - `provisionedAt` string, date-time
      - `pstnForwardTo` string
      - `signupErrorAt` string, date-time
      - `telnyxOrderId` string, nullable: Present once the number order has been placed (i.e. the requirement group was approved). Absent while still in identity review.
      - `blockedCallers` string[]
      - `callingEnabled` boolean: Whether WhatsApp Business Calling is enabled on this number (manage via /v1/whatsapp/phone-numbers/{id}/calling).
      - `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.
      - `metaVerifiedAt` string, date-time
      - `ownerAccountId` string, nullable: The telephony account that owns Calls and SMS on the number.
      - `registrantName` string, nullable: For regulated numbers, who it's registered for (company or person), set from the submitted KYC.
      - `endUserLastName` string, nullable
      - `forwardCallerId` 'business' | 'caller'
      - `signupErrorStep` string
      - `sipAuthUsername` string: SIP digest username for a sip: forward destination. The password is never returned.
      - `smsSendApproved` boolean: True when outbound SMS is unlocked: an approved 10DLC covers the number, or the number is outside the US.
      - `socialAccountId` string, nullable: The WhatsApp account the number is linked to; null when WhatsApp is not connected.
      - `endUserFirstName` string, nullable
      - `pstnVoiceEnabled` boolean: Whether Calls (PSTN voice) is on.
      - `recordingEnabled` boolean
      - `voicemailEnabled` boolean
      - `callIconCountries` string[]
      - `metaPreverifiedId` string
      - `voicemailGreeting` string
      - `whatsAppRequested` boolean: False for a standalone phone bought for Calls or SMS only.
      - `callerIdVerifiedAt` string, date-time
      - `businessHoursEnabled` boolean
      - `regulatoryInfoStatus` string: `action_required` when the reviewer is waiting on you.
      - `transcriptionEnabled` boolean
      - `businessHoursTimezone` string
      - `metaPoolAddRejectedAt` string, date-time: Set when WhatsApp reported the number as registered to another WhatsApp account while connecting it. The number keeps working for Calls and SMS; remove it from the other account and connect again, or replace it with POST /v1/whatsapp/phone-numbers/{id}/replace. Absent once WhatsApp accepts the number.
      - `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.
      - `telnyxAdvancedOrderId` string: Present on a pre-order: the carrier request placed for a number with no stock yet.
      - `transcriptionLanguage` 'auto' | 'en' | 'es'
      - `maxCallDurationSeconds` integer
      - `metaVerificationStatus` 'pending' | 'code_requested' | 'verified' | 'expired'
      - `smsRegistrationPending` boolean: True while a 10DLC registration covering this number is in review.
      - `regulatoryDeclineReason` string, nullable: Reviewer rejection reason when status is regulatory_declined.
      - `regulatoryReviewComment` string: The latest reviewer comment on a regulated number still in review.
      - `metaVerificationExpiresAt` 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.
      - `template` object
        - `name` string
        - `language` string
      - `accountId` string, nullable
      - `isSandbox` boolean
      - `phoneNumber` string
    - `imessage` object[]: 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'
      - `handle` string, nullable: The sender handle once activation assigns it
      - `region` 'US' | 'GB' | 'null', nullable
      - `status` 'ordering' | 'awaiting_payment' | 'activating' | 'active' | 'suspended' | 'canceled' | 'failed': `awaiting_payment`: the first-month charge is still being confirmed by the card; the number is ordered automatically once it is paid (usually under 5 minutes), or the order fails with `failureReason` when the card declines or nothing confirms within 30 minutes.
      - `provider` string
      - `accountId` string, nullable: The messaging account created at activation
      - `createdAt` string, date-time
      - `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.
      - `profileId` string
      - `priceCents` integer: Monthly price billed while the sender is active
      - `displayName` string, nullable
      - `failureReason` string, nullable
    - `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
      - `profileId` string, nullable
      - `connectedAt` string, date-time, nullable
      - `displayName` string, nullable
      - `phoneNumber` string, nullable
      - `callingEnabled` boolean: Whether WhatsApp Business Calling is enabled on this number.
  - `error` string, nullable
  - `usage` object
    - `credits_charged` number, nullable
    - `credits_reserved` number
    - `estimated_credits` number
    - `cost_source` 'provider_reported' | 'calculated' | 'estimated' | 'null', nullable
    - `provider_usage` object, nullable: Normalised consumption, e.g. { VIDEO_SECOND: 22.4 }
  - `balance` object
    - `available` number
    - `reserved` number

## Other responses

- `400`: Invalid input
- `402`: Insufficient credits / project budget
- `404`: Resource not found (or not yours)
- `429`: Rate limited
- `503`: Service temporarily paused

---

[API](https://skmtc.dev/apihub/apis/apihub-one-api-for-chat-image-video-ai.md) · [All operations](https://skmtc.dev/apihub/apis/apihub-one-api-for-chat-image-video-ai/llms.txt) · [OpenAPI document](https://skmtc.dev/apihub/apis/apihub-one-api-for-chat-image-video-ai/revisions/a8caa42835ce?raw)