> ## 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 Agent Phone Numbers > List the inbound and outbound phone numbers linked to a DialNexa agent. Read only List agent phone numbers to see which numbers ring an agent and which numbers it can call from. Phone numbers are linked to the agent, not to one of its versions, so every version uses the same numbers. Inbound calls run on the agent's latest published version. ## When to use this * **Before an outbound call or batch**: find the `phone_number_id` to send when the agent has more than one outbound number. * **Routing audits**: confirm which numbers answer with this agent. * **Before a detach**: get the ID and direction of the number to remove. ## Before you begin Get the agent ID from [List Agents](/docs/api-reference/v1/agents/list). ## List agent phone numbers request ```bash theme={null} curl "https://api.dialnexa.com/v1/agents/agent_2g7Xy3tY53gRlp/phone-numbers" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ## Verify the result A `200` response contains `data.inbound` and `data.outbound`. Each holds up to three numbers with `id`, `phone_number`, `country_iso`, `nickname`, `sip_trunk_enabled`, and `linked_at`. An empty array means no number is linked in that direction. [Get Agent Details](/docs/api-reference/v1/agents/get) returns the same lists as `inbound_phone_numbers` and `outbound_phone_numbers`. ## Errors and recovery * `401 Unauthorized` means the API key is missing or invalid. * `404 Not Found` means the agent does not exist in this workspace or was deleted. Reads are safe to retry. ## Related endpoints * [Attach Agent Phone Number](/docs/api-reference/v1/agents/attach-phone-number) * [Detach Agent Phone Number](/docs/api-reference/v1/agents/detach-phone-number) * [Get Agent Phone Number History](/docs/api-reference/v1/agents/phone-number-history) * [List Phone Numbers](/docs/api-reference/v1/phone-numbers/list) ## OpenAPI ````yaml GET /v1/agents/{agentId}/phone-numbers openapi: 3.0.0 info: title: DialNexa API description: Public `/v1` REST API for the DialNexa voice AI platform. version: 1.0.0 servers: - url: https://api.dialnexa.com description: DialNexa production API security: - bearer: [] tags: - name: Agents - name: Batch Calls - name: Calls - name: Knowledge Base - name: Languages - name: LLMs - name: Phone Numbers - name: Transcribers - name: Webhooks - name: Voices - name: Workflows - name: Workflow Leads - name: Authentication - name: Agent Builder paths: /v1/agents/{agentId}/phone-numbers: get: tags: - Agents summary: List Agent Phone Numbers description: >- Lists the inbound and outbound phone numbers linked to an agent. Every version of the agent uses them: inbound calls run on its latest published version. operationId: listAgentPhoneNumbers parameters: - name: agentId in: path required: true schema: example: agent_2g7Xy3tY53gRlp type: string description: Agent ID from List Agents. responses: '200': description: Successful response. content: application/json: schema: type: object properties: success: type: boolean error: type: boolean statusCode: type: integer message: type: string data: type: object properties: inbound: type: array items: type: object properties: id: type: string example: phn_abc123 phone_number: type: string example: '9876543210' description: The number without its country calling code. country_iso: type: string example: '91' description: Country calling code. nickname: type: string nullable: true description: Label set in the dashboard. sip_trunk_enabled: type: boolean linked_at: type: string format: date-time nullable: true description: >- When the number was linked to the agent, when known. required: - id - phone_number - country_iso - nickname - sip_trunk_enabled - linked_at outbound: type: array items: type: object properties: id: type: string example: phn_abc123 phone_number: type: string example: '9876543210' description: The number without its country calling code. country_iso: type: string example: '91' description: Country calling code. nickname: type: string nullable: true description: Label set in the dashboard. sip_trunk_enabled: type: boolean linked_at: type: string format: date-time nullable: true description: >- When the number was linked to the agent, when known. required: - id - phone_number - country_iso - nickname - sip_trunk_enabled - linked_at required: - inbound - outbound timestamp: type: string format: date-time required: - success - error - statusCode - message - data - timestamp examples: success: value: success: true error: false statusCode: 200 message: Success data: inbound: - id: phn_abc123 phone_number: '9876543210' country_iso: '91' nickname: Support line sip_trunk_enabled: false linked_at: '2026-09-30T06:00:00.000Z' outbound: - id: phn_abc123 phone_number: '9876543210' country_iso: '91' nickname: Support line sip_trunk_enabled: false linked_at: '2026-09-30T06:00:00.000Z' timestamp: '2026-09-07T06:00:00.000Z' '401': description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: error: value: statusCode: 401 error: true success: false data: [] message: Invalid API key errors: [] '404': description: The agent is not in this workspace. content: application/json: schema: $ref: '#/components/schemas/CodedErrorResponse' examples: agentNotFound: value: statusCode: 404 error: true success: false data: [] message: Agent agent_2g7Xy3tY53gRlp not found in your organization. errors: [] security: - bearer: [] components: schemas: ErrorResponse: type: object description: Error body on endpoints without response filtering. properties: statusCode: type: integer example: 404 error: type: boolean enum: - true success: type: boolean enum: - false data: oneOf: - type: object properties: code: type: string description: Machine-readable refusal code. - type: array items: {} description: >- For a coded refusal, an object with code and the details listed for that code. Otherwise an empty array. message: type: string errors: type: array items: type: string description: Validation messages for a 400. Empty for other errors. required: - statusCode - error - success - data - message - errors CodedErrorResponse: type: object description: Error body for a coded refusal; data carries code and its details. properties: statusCode: type: integer example: 404 error: type: boolean enum: - true success: type: boolean enum: - false data: oneOf: - type: object properties: code: type: string description: Machine-readable refusal code. - type: array items: {} description: >- For a coded refusal, an object with code and the details listed for that code. Otherwise an empty array. message: type: string errors: type: array items: type: string description: Validation messages for a 400. Empty for other errors. required: - statusCode - error - success - data - message - errors securitySchemes: bearer: scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.