> ## 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. # Detach Agent Phone Number > Detach a phone number from a DialNexa agent for inbound or outbound calls. Destructive Detach an agent phone number to stop routing that number through the agent in one direction. The number stays in your workspace and can be attached to this or another agent later. A number linked for both directions keeps the direction you did not detach. ## When to use this * **Move a number to another agent**: detach it here, then [attach it](/docs/api-reference/v1/agents/attach-phone-number) to the new agent. * **Free a slot**: an agent can hold only three numbers per direction. * **Stop inbound routing**: after an inbound detach, calls to the number no longer reach this agent. ## Before you detach The request is refused while the number is still in use: * Calls are live on the number. * For an outbound detach, a batch that is running, paused, scheduled, or waiting dials from the number. * For an outbound detach, an active workflow uses the number in a voice call step. ## Detach agent phone number request | Parameter | In | Required | Description | | - | - | - | - | | `agentId` | path | Yes | Agent ID from [List Agents](/docs/api-reference/v1/agents/list). | | `phoneNumberId` | path | Yes | Phone number ID from [List Agent Phone Numbers](/docs/api-reference/v1/agents/list-phone-numbers). | | `direction` | query | Yes | `inbound` or `outbound`. The other direction is left unchanged. | ```bash theme={null} curl -X DELETE "https://api.dialnexa.com/v1/agents/agent_2g7Xy3tY53gRlp/phone-numbers/phn_abc123?direction=outbound" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ## Verify the result A `200` response returns the closed link in `data`, with `unlinked_at` set and `unlink_reason` of `manual`. Call [List Agent Phone Numbers](/docs/api-reference/v1/agents/list-phone-numbers) to confirm the number is gone from that direction. ## Errors and recovery Refusals carry a code in `data.code`. | Status | Code | Cause and fix | | - | - | - | | `400` | none | `direction` is missing or is not `inbound` or `outbound`. | | `404` | none | The agent or number is not in this workspace, or the number is not linked to this agent in that direction. | | `409` | `NUMBER_USED_BY_BATCH` | Unfinished batches dial from the number (`data.batches`, `data.live_calls`). Change those batches' number or cancel them, then retry. A paused batch does not complete on its own. | | `409` | `PHONE_NUMBER_HAS_LIVE_CALLS` | Calls are in progress (`data.live_calls`). Wait for them to finish, then retry. | | `409` | `PHONE_NUMBER_USED_IN_ACTIVE_WORKFLOWS` | Active workflows use the number (`data.affected_workflows`). Pause them, then retry. | A retry after a successful detach returns `404` because the number is no longer linked in that direction. ## Related endpoints * [Attach Agent Phone Number](/docs/api-reference/v1/agents/attach-phone-number) * [Get Agent Phone Number History](/docs/api-reference/v1/agents/phone-number-history) * [Update Batch Call Status](/docs/api-reference/v1/batches/status) * [Update Workflow Status](/docs/api-reference/v1/workflows/status) ## OpenAPI ````yaml DELETE /v1/agents/{agentId}/phone-numbers/{phoneNumberId} 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/{phoneNumberId}: delete: tags: - Agents summary: Detach Agent Phone Number description: >- Unlinks a phone number from an agent for one direction. Live calls block either direction. Unfinished batches and active workflows using the number additionally block outbound detachment. operationId: detachAgentPhoneNumber parameters: - name: agentId in: path required: true schema: example: agent_2g7Xy3tY53gRlp type: string description: Agent ID from List Agents. - name: phoneNumberId in: path required: true schema: example: phn_2g7Xy3tY53gRlp type: string description: Phone number ID from List Agent Phone Numbers. - name: direction required: true in: query schema: type: string enum: - inbound - outbound description: >- The direction to detach. A number linked for both directions keeps the other one. 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: id: type: string description: Link record ID. agent_id: example: agent_2g7Xy3tY53gRlp type: string phone_number_id: type: string example: phn_abc123 direction: type: string enum: - inbound - outbound description: >- inbound: the number rings this agent. outbound: the agent calls from it. linked_at: type: string format: date-time linked_by: type: string nullable: true description: User who created the link, when known. unlinked_at: type: string format: date-time nullable: true description: Null while the link is current. unlinked_by: type: string nullable: true description: User who ended the link, when known. unlink_reason: type: string nullable: true enum: - manual - agent_deleted - number_deleted - number_released description: >- Why the link ended: manual (detached), agent_deleted, number_deleted, or number_released (the rental expired or the number was withdrawn). Null while the link is current. required: - id - agent_id - phone_number_id - direction - linked_at - unlinked_at - unlink_reason nullable: true 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: id: k2m9q4wz1abcde direction: outbound linked_at: '2026-09-30T06:00:00.000Z' linked_by: null unlinked_at: '2026-09-30T08:00:00.000Z' unlinked_by: null unlink_reason: manual agent_id: agent_2g7Xy3tY53gRlp phone_number_id: phn_abc123 timestamp: '2026-09-07T06:00:00.000Z' '400': description: direction is missing or is not inbound or outbound. content: application/json: schema: $ref: '#/components/schemas/CodedErrorResponse' examples: invalidDirection: value: statusCode: 400 error: true success: false data: [] message: >- direction must be one of the following values: inbound, outbound errors: - >- direction must be one of the following values: inbound, outbound '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 or number is not in this workspace, or the number is not linked to this agent in that direction. content: application/json: schema: $ref: '#/components/schemas/CodedErrorResponse' examples: notLinked: value: statusCode: 404 error: true success: false data: [] message: >- This number is not linked to this agent for outbound calls. errors: [] '409': description: The number is still in use. Resolve what data lists, then retry. content: application/json: schema: $ref: '#/components/schemas/CodedErrorResponse' examples: usedByBatch: value: statusCode: 409 error: true success: false data: code: NUMBER_USED_BY_BATCH batches: - id: batch_abc123 title: September renewals status: paused live_calls: 0 message: >- 1 unfinished batch(es) ("September renewals") and 0 live call(s) use this number. Change the batches' number or cancel them first. errors: [] liveCalls: value: statusCode: 409 error: true success: false data: code: PHONE_NUMBER_HAS_LIVE_CALLS live_calls: 2 batches: [] message: >- 2 call(s) are in progress on this number. Wait for them to finish, then retry. errors: [] activeWorkflows: value: statusCode: 409 error: true success: false data: code: PHONE_NUMBER_USED_IN_ACTIVE_WORKFLOWS affected_workflows: - id: Xy7Kp2mQ9rT4vB title: Lead follow-up status: active message: >- This phone number is used in 1 active workflow(s). Pause those workflows first, then retry. errors: [] security: - bearer: [] components: schemas: 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 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 securitySchemes: bearer: scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.