> ## Documentation Index
> Fetch the complete documentation index at: https://dialnexa.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# List Phone Numbers
> List phone numbers provisioned in your workspace.
Read only
**Recommended.** This endpoint is part of the public `/v1` API reference and is the supported path for new integrations. See the [migration guide](/docs/api-reference/v1/migrating-to-v1) for versioning guidance.
Returns every phone number provisioned in your workspace, paginated. Each entry includes the E.164 `phone_number`, the `country_code`, the `type` (local, toll-free, or mobile), the display `nickname`, the `inbound_agent_id` currently routing incoming calls on this number, and the purchase timestamp. Use this to power a number management view, audit which numbers are in use, or sync your DialNexa number portfolio with an internal inventory.
## When to use this
* **Number management UIs**: render a table of every number with status, type, and assigned agent.
* **Routing audits**: confirm every active number has an agent assigned, or surface unrouted numbers as a follow-up task.
* **Cost reporting**: aggregate by `country_code` or `type` to attribute telephony spend per workspace, region, or use case.
* **Operational scripts**: enumerate numbers before auditing routing assignments or provisioning additional numbers.
## Query parameters
| Parameter | Description |
| -------------- | ------------------------------------------------------------------------------------ |
| `page` | Page number, starting from 1. |
| `limit` | Results per page (max 100, default 20). |
| `country_code` | Filter to numbers in a specific country, for example `IN` or `US`. |
| `type` | Filter to numbers of a specific type, for example `local`, `toll_free`, or `mobile`. |
## Errors
* `403 Forbidden` is returned when the API key cannot read phone number records.
## Related endpoints
* [Get Phone Number Details](/docs/api-reference/v1/phone-numbers/get): fetch a single number's detail.
* [Buy a Phone Number](/docs/api-reference/v1/phone-numbers/buy): purchase a new number.
* [Search Available Numbers](/docs/api-reference/v1/phone-numbers/search-plivo): find provider numbers available for purchase.
* [Link SIP Trunk](/docs/api-reference/v1/phone-numbers/link-sip-trunk): connect a bring-your-own number.
* [Delete Phone Number](/docs/api-reference/v1/phone-numbers/delete): remove a number you no longer use.
* [Pagination](/docs/api-reference/pagination): how DialNexa list endpoints paginate.
## OpenAPI
````yaml GET /v1/organization-phone-numbers
openapi: 3.0.0
info:
title: DialNexa API
description: >-
Public REST API for the DialNexa voice AI platform. Versioned endpoints are
under /v1; unversioned endpoints are legacy and deprecated.
version: 1.0.0
servers:
- url: https://api.dialnexa.com
description: DialNexa production API
security:
- bearer: []
tags:
- name: API Keys
- name: Agent Functions
- name: Agents V1
- name: Agents2
- name: Batch Calls
- name: Batch Calls V1
- name: Call Logs
- name: Calls
- name: Calls V1
- name: Campaign Leads
- name: Campaigns
- name: External Webhooks
- name: Knowledge Base
- name: Knowledge Base V1
- name: LLMs
- name: LLMs V1
- name: Languages
- name: Languages V1
- name: Organization Phone Numbers
- name: Organization Phone Numbers V1
- name: Phone Number Pricing
- name: Phone Number Pricing V1
- name: Transcribers
- name: Transcribers V1
- name: User Webhooks
- name: User Webhooks V1
- name: V1
- name: Voices
- name: Voices V1
- name: Webcall
- name: Workflow Leads
- name: Workflow Leads V1
- name: Workflows
- name: Workflows V1
paths:
/v1/organization-phone-numbers:
get:
tags:
- Organization Phone Numbers
- Organization Phone Numbers V1
- V1
summary: List Phone Numbers
description: >-
Returns phone numbers owned by the authenticated workspace with
pagination metadata.
operationId: OrganizationPhoneNumbersV1Controller_findAll
parameters:
- name: limit
required: false
in: query
schema:
example: 20
type: number
- name: page
required: false
in: query
schema:
type: number
example: 1
responses:
'200':
description: Phone numbers returned successfully.
content:
application/json:
schema:
type: object
properties:
items:
type: array
items:
type: object
properties:
id:
type: string
example: phn_abc123
phone_number:
type: string
example: '+919876543210'
provider:
type: string
status:
type: string
total:
type: number
page:
type: number
limit:
type: number
examples:
success:
summary: Successful response
value:
items:
- id: phn_abc123
phone_number: '+14155552671'
provider: plivo
status: active
country_code: US
nickname: US Sales Line
total: 1
page: 1
limit: 20
'401':
description: Unauthorized - missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
error:
summary: 401 Unauthorized
value:
statusCode: 401
message: API key is missing or invalid
error: Unauthorized
'403':
description: Forbidden - API key does not have access to this organization.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
error:
summary: 403 Forbidden
value:
statusCode: 403
message: You do not have permission to access this resource
error: Forbidden
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
error:
summary: 500 Internal Server Error
value:
statusCode: 500
message: Internal server error
error: Internal Server Error
security:
- bearer: []
components:
schemas:
ErrorResponse:
type: object
properties:
statusCode:
type: integer
example: 400
message:
oneOf:
- type: string
- type: array
items:
type: string
example: phone_number must be a valid E.164 phone number
error:
type: string
example: Bad Request
required:
- statusCode
- message
- error
securitySchemes:
bearer:
scheme: bearer
bearerFormat: JWT
type: http
````