Phone & voice · Phone Numbers

List phone numbers

Returns phone numbers.

GEThttps://api.pozy.ai/v1/phone-numbers

listPhoneNumbers

Guides: Phone numbers, Buy a number, Phone numbers for WhatsApp

Request

Send your API key as Authorization: Bearer pz_live_.... Read-only keys can call it. Keys with the telephony resource group disabled get 403 resource_group_disabled. Authentication

Query parameters

Name	Type	Notes
`status`	string	One of `provisioning`, `verifying`, `pending_payment`, `pending_regulatory`, `regulatory_declined`, `active`, `suspended`, `releasing`, `released`
`profileId`	string

Example

curl -X GET "https://api.pozy.ai/v1/phone-numbers" \
  -H "Authorization: Bearer $POZY_API_KEY"

const res = await fetch("https://api.pozy.ai/v1/phone-numbers", {
  headers: { Authorization: `Bearer ${process.env.POZY_API_KEY}` },
});
const data = await res.json();
if (!res.ok) throw new Error(data?.error ?? `Request failed with status ${res.status}`);
console.log(data);

import os
import requests

resp = requests.get(
    "https://api.pozy.ai/v1/phone-numbers",
    headers={"Authorization": f"Bearer {os.environ['POZY_API_KEY']}"},
    timeout=30,
)
resp.raise_for_status()
print(resp.json())

Response

200 on success

numbersarray of object
67 child fields
- _idstring
- phoneNumberstring
- countrystring
- numberTypestring
- statusstring
  One of pending_payment, pending_regulatory, regulatory_declined, provisioning, verifying, active, suspended, releasing, released.
- profileIdobject or string
  One of:
  Option 1 (2 fields)
  _idstring
  namestring
  Can be null.
  string
- createdAtstring (date-time)
- updatedAtstring (date-time)
- carrierOrderIdstring
  Can be null.
- carrierAdvancedOrderIdstring
- registrantNamestring
  Can be null.
- endUserFirstNamestring
  Can be null.
- endUserLastNamestring
  Can be null.
- regulatoryDeclineReasonstring
  Can be null.
- regulatoryReviewCommentstring
- regulatoryInfoStatusstring
- identityVerificationUrlstring
  Can be null.
- verifyUrlstring
  Can be null.
- identityVerificationOpenedboolean
- metaPreverifiedIdstring
- metaVerificationStatusstring
  One of pending, code_requested, verified, expired.
- metaVerifiedAtstring (date-time)
- metaVerificationExpiresAtstring (date-time)
- metaPoolAddRejectedAtstring (date-time)
- socialAccountIdstring
  Can be null.
- ownerAccountIdstring
  Can be null.
- sipTrunkIdstring
  Can be null.
- whatsAppRequestedboolean
- smsRequestedboolean
- provisionedAtstring (date-time)
- activatedAtstring (date-time)
- connectedAtstring (date-time)
- suspendedAtstring (date-time)
- releasedAtstring (date-time)
- signupErrorstring
- signupErrorAtstring (date-time)
- signupErrorStepstring
- monthlyCentsinteger
- hostedByPozyboolean
- smsCapableboolean
- mmsCapableboolean
- domesticOnlyboolean
- smsRegistrationPendingboolean
- smsSendApprovedboolean
- smsBrandNamestring
  Can be null.
- featuresobject
  3 child fields
  callsboolean
  whatsappboolean
  smsPendingboolean
- callingEnabledboolean
- forwardTostring
- sipAuthUsernamestring
- callerIdVerifiedAtstring (date-time)
- maxCallDurationSecondsinteger
- recordingEnabledboolean
- transcriptionEnabledboolean
- transcriptionLanguagestring
  One of auto, en, es.
- callIconCountriesarray of string
- forwardCallerIdstring
  One of business, caller.
- pstnVoiceEnabledboolean
- pstnForwardTostring
- voicemailEnabledboolean
- voicemailGreetingstring
- businessHoursEnabledboolean
- businessHoursTimezonestring
- businessHoursarray of object
  3 child fields
  dayinteger
  openstring
  closestring
- blockedCallersarray of string
- ivrEnabledboolean
- ivrPromptstring
- ivrOptionsarray of object
  3 child fields
  digitstring
  forwardTostring
  labelstring
connectedarray of object
- accountIdstring
- phoneNumberstring
  Can be null.
- displayNamestring
  Can be null.
- profileIdstring
  Can be null.
- connectedAtstring (date-time)
  Can be null.
- callingEnabledboolean
imessagearray of object
13 child fields
- idstring
- kindstring
  One of phone, email.
- regionstring
  One of US, GB. Can be null.
- handlestring
  Can be null.
- optInLinkstring
  Can be null.
- statusstring
  One of ordering, awaiting_payment, activating, active, suspended, canceled, failed.
- priceCentsinteger
- providerstring
- profileIdstring
- displayNamestring
  Can be null.
- failureReasonstring
  Can be null.
- accountIdstring
  Can be null.
- createdAtstring (date-time)
sandboxobject
Can be null.
- phoneNumberstring
- accountIdstring
  Can be null.
- templateobject
  2 child fields
  - namestring
  - languagestring
- isSandboxboolean

200 response

{
  "numbers": [
    {
      "_id": "635d87e261ae344ef27fd1df",
      "phoneNumber": "+14155550123",
      "country": "US",
      "numberType": "string",
      "status": "pending_payment",
      "profileId": {
        "_id": "635d87e261ae344ef27fd1df",
        "name": "Acme"
      },
      "createdAt": "2026-10-02T09:00:00.000Z",
      "updatedAt": "2026-10-02T09:00:00.000Z",
      "carrierOrderId": "6f9ea00d86b341f8430df722",
      "carrierAdvancedOrderId": "64664f75e6129fe78272e793",
      "registrantName": "Acme",
      "endUserFirstName": "Acme",
      "endUserLastName": "Acme",
      "regulatoryDeclineReason": "string",
      "regulatoryReviewComment": "string",
      "regulatoryInfoStatus": "active",
      "identityVerificationUrl": "https://pozy.ai/media/example-1.jpg",
      "verifyUrl": "https://pozy.ai/media/example-1.jpg",
      "identityVerificationOpened": true,
      "metaPreverifiedId": "608441ffe00bbbbd4b634fe0",
      "metaVerificationStatus": "pending",
      "metaVerifiedAt": "2026-10-02T09:00:00.000Z",
      "metaVerificationExpiresAt": "2026-10-02T09:00:00.000Z",
      "metaPoolAddRejectedAt": "2026-10-02T09:00:00.000Z",
      "socialAccountId": "6036fffd51dad00a2702955c",
      "ownerAccountId": "60f3dbe08e084dbe9b5f007c",
      "sipTrunkId": "64a65f5550725a070e2afc75",
      "whatsAppRequested": true,
      "smsRequested": true,
      "provisionedAt": "2026-10-02T09:00:00.000Z",
      "activatedAt": "2026-10-02T09:00:00.000Z",
      "connectedAt": "2026-10-02T09:00:00.000Z",
      "suspendedAt": "2026-10-02T09:00:00.000Z",
      "releasedAt": "2026-10-02T09:00:00.000Z",
      "signupError": "string",
      "signupErrorAt": "2026-10-02T09:00:00.000Z",
      "signupErrorStep": "string",
      "monthlyCents": 1,
      "hostedByPozy": true,
      "smsCapable": true,
      "mmsCapable": true,
      "domesticOnly": true,
      "smsRegistrationPending": true,
      "smsSendApproved": true,
      "smsBrandName": "Acme",
      "features": {
        "calls": true,
        "whatsapp": true,
        "smsPending": true
      },
      "callingEnabled": true,
      "forwardTo": "string",
      "sipAuthUsername": "acme",
      "callerIdVerifiedAt": "2026-10-02T09:00:00.000Z",
      "maxCallDurationSeconds": 1,
      "recordingEnabled": true,
      "transcriptionEnabled": true,
      "transcriptionLanguage": "auto",
      "callIconCountries": [
        "string"
      ],
      "forwardCallerId": "business",
      "pstnVoiceEnabled": true,
      "pstnForwardTo": "string",
      "voicemailEnabled": true,
      "voicemailGreeting": "alex@example.com",
      "businessHoursEnabled": true,
      "businessHoursTimezone": "string",
      "businessHours": [
        {
          "day": 1,
          "open": "string",
          "close": "string"
        }
      ],
      "blockedCallers": [
        "string"
      ],
      "ivrEnabled": true,
      "ivrPrompt": "string",
      "ivrOptions": [
        {
          "digit": "string",
          "forwardTo": "string",
          "label": "string"
        }
      ]
    }
  ],
  "connected": [
    {
      "accountId": "696e0b682d0a31188e7a2ba9",
      "phoneNumber": "+14155550123",
      "displayName": "Acme",
      "profileId": "6a0b6573846efc28aaa9a3ff",
      "connectedAt": "2026-10-02T09:00:00.000Z",
      "callingEnabled": true
    }
  ],
  "imessage": [
    {
      "id": "6bfebd43ddc270f6d2c56fc5",
      "kind": "phone",
      "region": "US",
      "handle": "acme",
      "optInLink": "string",
      "status": "ordering",
      "priceCents": 1,
      "provider": "string",
      "profileId": "6a0b6573846efc28aaa9a3ff",
      "displayName": "Acme",
      "failureReason": "string",
      "accountId": "696e0b682d0a31188e7a2ba9",
      "createdAt": "2026-10-02T09:00:00.000Z"
    }
  ],
  "sandbox": {
    "phoneNumber": "+14155550123",
    "accountId": "696e0b682d0a31188e7a2ba9",
    "template": {
      "name": "Acme",
      "language": "en"
    },
    "isSandbox": true
  }
}

Errors

Errors use one shape: { error, type, code, param?, details? }. The ones you are most likely to see here:

400	invalid_request_error	A parameter or body field is missing or invalid. `param` names it.
401	authentication_error	The API key is missing, revoked or expired.
403	permission_error	The key is scoped to other profiles or has this resource group disabled.
429	rate_limit_error	Too many requests this minute. Wait for `Retry-After` seconds.

Every code is listed in Errors.

More in Phone Numbers

GETGet phone number DELRelease phone number POSTPurchase phone number GETResolve a number claim GETList offerable number countries GETSearch available numbers GETCheck country availability GETGet KYC form spec POSTSubmit KYC GETView a KYC document on file POSTUpload a KYC document POSTPre-validate KYC address POSTCreate a hosted KYC link GETList port-in orders POSTPort numbers in POSTCheck portability GETResolve a port claim POSTUpload a porting document GETCountry porting requirements GETA port-in order's pending requirements DELCancel a port-in POSTPre-review a KYC packet GETGet declined requirements POSTResubmit a declined number POSTReply to the regulatory reviewer POSTRespond to the regulatory reviewer (message + corrections)GETList stock watches POSTWatch an out-of-stock country DELStop watching a country POSTRequest the WhatsApp verification code for a number