--- 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` OwnedPhoneNumber[] - `_id` string - `phoneNumber` string - `country` string - `numberType` string — For example local, mobile, national or toll_free. - `status` 'pending_payment' | 'pending_regulatory' | 'regulatory_declined' | 'provisioning' | 'verifying' | 'active' | 'suspended' | 'releasing' | 'released' - `profileId` union — The profile the number belongs to: `{ _id, name }` when the profile exists, otherwise its id. - object - `_id` string - `name` string, nullable - string - `createdAt` string, date-time - `updatedAt` 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. - `telnyxAdvancedOrderId` string — Present on a pre-order: the carrier request placed for a number with no stock yet. - `registrantName` string, nullable — For regulated numbers, who it's registered for (company or person), set from the submitted KYC. - `endUserFirstName` string, nullable - `endUserLastName` string, nullable - `regulatoryDeclineReason` string, nullable — Reviewer rejection reason when status is regulatory_declined. - `regulatoryReviewComment` string — The latest reviewer comment on a regulated number still in review. - `regulatoryInfoStatus` string — `action_required` when the reviewer is waiting on you. - `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. - `verifyUrl` string, nullable — Stable redirect to the live Onfido session. Prefer it over `onfidoVerificationUrl`, since it always resolves to a fresh session. - `onfidoOpened` boolean — True once the verify link has been opened at least once. - `metaPreverifiedId` string - `metaVerificationStatus` 'pending' | 'code_requested' | 'verified' | 'expired' - `metaVerifiedAt` string, date-time - `metaVerificationExpiresAt` string, date-time - `socialAccountId` string, nullable — The WhatsApp account the number is linked to; null when WhatsApp is not connected. - `ownerAccountId` string, nullable — The telephony account that owns Calls and SMS on the number. - `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. - `whatsAppRequested` boolean — False for a standalone phone bought for Calls or SMS only. - `smsRequested` boolean - `provisionedAt` string, date-time - `activatedAt` string, date-time - `connectedAt` string, date-time - `suspendedAt` string, date-time - `releasedAt` string, date-time - `signupError` string — Meta's Embedded Signup error from the last failed connect attempt (raw text, often localized). - `signupErrorAt` string, date-time - `signupErrorStep` string - `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. - `smsCapable` boolean — Whether the number can send SMS. Absent while unknown. - `mmsCapable` boolean — Whether the number can send MMS. Absent while unknown. - `domesticOnly` boolean — True when the number can only text numbers in its own country. Absent while unknown. - `smsRegistrationPending` boolean — True while a 10DLC registration covering this number is in review. - `smsSendApproved` boolean — True when outbound SMS is unlocked: an approved 10DLC covers the number, or the number is outside the US. - `smsBrandName` string, nullable — Brand of the 10DLC registration covering the number. - `features` object - `calls` boolean - `whatsapp` boolean - `smsPending` boolean - `callingEnabled` boolean — Whether WhatsApp Business Calling is enabled on this number (manage via /v1/whatsapp/phone-numbers/{id}/calling). - `forwardTo` string — WhatsApp calling forward destination. - `sipAuthUsername` string — SIP digest username for a sip: forward destination. The password is never returned. - `callerIdVerifiedAt` string, date-time - `maxCallDurationSeconds` integer - `recordingEnabled` boolean - `transcriptionEnabled` boolean - `transcriptionLanguage` 'auto' | 'en' | 'es' - `callIconCountries` string[] - `forwardCallerId` 'business' | 'caller' - `pstnVoiceEnabled` boolean — Whether Calls (PSTN voice) is on. - `pstnForwardTo` string - `voicemailEnabled` boolean - `voicemailGreeting` string - `businessHoursEnabled` boolean - `businessHoursTimezone` string - `businessHours` object[] - `day` integer - `open` string - `close` string - `blockedCallers` string[] - `ivrEnabled` boolean - `ivrPrompt` string - `ivrOptions` object[] - `digit` string - `forwardTo` string - `label` string - `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 - `401` — Unauthorized ## Changes - **2026-09-25** `2c04683ce694` — 2 breaking, 4 warning, 47 info - added `subschema #1, subschema #2` to the `numbers/items/profileId` response property `oneOf` list for the response status `200` - the `numbers/items/profileId` response's property type changed from `object` to no type for status `200` - added the new `code_requested` enum value to the `numbers/items/metaVerificationStatus` response property for the response status `200` - added the new `expired` enum value to the `numbers/items/metaVerificationStatus` response property for the response status `200` - …49 more - **2026-09-21** `339f59df69dd` — 1 info - added the optional property `imessage` to the response with the `200` 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/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/b2325332041a?raw)