> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nedzo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# List phone numbers

> List the phone numbers a workspace owns, newest first.

<Note>
  This endpoint is for the VIP plan only. Other plans get a `403`. See [Plan access](/api-reference/introduction#plan-access).
</Note>

<ParamField query="workspaceId" type="string">
  Workspace UUID. Required for an account API key. A workspace API key uses its own workspace.
</ParamField>

<ParamField query="limit" type="integer" default="100">
  Numbers per page, 1 to 1,000.
</ParamField>

<ParamField query="offset" type="integer" default="0">
  How many numbers to skip, up to 100,000.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl "https://api.nedzo.ai/v1/phone-numbers?limit=50" \
      -H "Authorization: Bearer YOUR_API_KEY"
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "items": [
      {
        "id": "4d1f6b52-8c0e-4a51-9b7d-2f3c4e5a6b7c",
        "workspaceId": "19c3b12f-ec54-43ad-8686-00e921f1befd",
        "number": "+14155551234",
        "status": "active",
        "type": "inbound_outbound",
        "friendlyName": "Main line",
        "inboundAgentId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
        "chatAgentId": null,
        "fallbackEnabled": false,
        "fallbackNumber": null,
        "fallbackRingDuration": 20,
        "activeHours": null,
        "monthlyPriceCents": 99,
        "purchasedAt": "2026-10-11T12:00:00Z",
        "createdAt": "2026-10-11T12:00:00Z",
        "updatedAt": "2026-10-11T12:00:00Z"
      }
    ],
    "total": 1,
    "limit": 50,
    "offset": 0,
    "hasMore": false
  }
  ```
</ResponseExample>

## Fields

| Field | Meaning |
| - | - |
| `status` | `pending`, `active`, `payment_failed` or `activation_failed` |
| `type` | `inbound_outbound` or `outbound_only` |
| `inboundAgentId` | The voice agent that answers and calls from this number |
| `chatAgentId` | The chat agent that answers texts on this number |
| `fallbackEnabled` | Ring a person first, then the agent |
| `fallbackNumber` | The person to ring first |
| `fallbackRingDuration` | Seconds to ring the person before the agent answers |
| `activeHours` | When to ring the person first. `null` uses the workspace office hours |
| `monthlyPriceCents` | What the number costs each month, in cents |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.