> ## 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. # Change Batch Call Phone Number > Change Batch Call Phone Number switches an eligible batch to another outbound number linked to its agent. Changes state - verify before retry Change Batch Call Phone Number switches the From number for a draft, scheduled, or paused batch. Undialed calls and parked retries use the new number. Calls already placed keep their original number, and the batch keeps its agent version and status. ## Before you begin * Find the batch ID with [List Batch Calls](/docs/api-reference/v1/batches/list). * Choose a `phn_` ID from the batch agent's outbound list in [List Agent Phone Numbers](/docs/api-reference/v1/agents/list-phone-numbers). * If the batch is running or waiting, [pause it](/docs/api-reference/v1/batches/status) and wait for its calls in progress to finish. Completed, cancelled or deleted batches cannot change numbers. ## Change Batch Call Phone Number request ```bash theme={null} curl -X PATCH "https://api.dialnexa.com/v1/batch-calls/batch_abc123/phone-number" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"phone_number_id": "phn_abc123"}' ``` The number must already be linked to the same agent for outbound calls. This request does not attach a number, change the batch's agent, or resume a paused batch. ## Verify the result HTTP `200` confirms the change. The API-key response is an empty object; it does not include the dashboard's campaign control result. Reopen the batch's **Change number** dialog and confirm the selected number is marked **Current**. After you resume the batch, inspect subsequent calls with [List Calls](/docs/api-reference/v1/calls/list) and `batch_call_id` to verify their `phone_number_id`. If the request times out, verify the saved selection before retrying. Repeating the same number does not create a batch or place calls, but the request can be refused if the batch has started or completed since the first request. ## Errors and recovery | Status | Code | Recovery | | - | - | - | | `400` | `PHONE_NUMBER_NOT_LINKED` | Attach the number to this agent for outbound calls, or choose one already linked. | | `400` | `BATCH_TERMINAL` | Completed, cancelled or deleted batches cannot change numbers. Prepare a new batch when another run is needed. | | `400` | none | Supply a non-empty string for `phone_number_id`. | | `404` | none | Check the batch ID and workspace. | | `409` | `BATCH_NOT_PAUSED` | Pause a running or waiting batch before changing its number. | | `409` | `BATCH_HAS_LIVE_CALLS` | Wait for the paused batch's calls in progress to finish. `data.live_calls` gives the count. | ## Related endpoints * [Create Batch Call](/docs/api-reference/v1/batches/create) * [Update Batch Call Status](/docs/api-reference/v1/batches/status) * [Attach Agent Phone Number](/docs/api-reference/v1/agents/attach-phone-number) ## OpenAPI ````yaml PATCH /v1/batch-calls/{id}/phone-number 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/batch-calls/{id}/phone-number: patch: tags: - Batch Calls summary: Change Batch Call Phone Number description: >- Changes the From number for a draft, scheduled, or paused batch to another outbound number linked to its agent. Pause running or waiting batches first and wait for in-progress calls to finish. Undialed calls and parked retries use the new number; placed calls keep their original number. The agent version and batch status stay the same. operationId: changeBatchCallPhoneNumber parameters: - name: id in: path required: true schema: type: string example: batch_abc123 description: Batch ID from List Batch Calls. requestBody: required: true content: application/json: schema: type: object properties: phone_number_id: type: string description: One of the batch agent's outbound phone number IDs. example: phn_abc123 required: - phone_number_id examples: request: value: phone_number_id: phn_abc123 responses: '200': description: >- The number was changed. API-key callers receive an empty object because the response projection omits the control result. content: application/json: schema: type: object properties: {} examples: success: value: {} '400': description: >- PHONE_NUMBER_NOT_LINKED: choose an outbound number of this agent. BATCH_TERMINAL: completed, cancelled, or deleted batches cannot change numbers. Invalid request bodies also return 400. content: application/json: schema: $ref: '#/components/schemas/FilteredErrorResponse' examples: error: value: message: >- Request validation failed: phone_number_id must be a string batchTerminal: summary: 400 Bad Request value: message: >- Request validation failed: Batch "Q3 Follow-up Batch" is completed; its number can no longer change. data: code: BATCH_TERMINAL phoneNumberNotLinked: summary: 400 Bad Request value: message: >- Request validation failed: Phone number phn_2g7Xy3tY53gRlp is not an outbound number of agent agent_mgao6051Rk718Y. data: code: PHONE_NUMBER_NOT_LINKED '404': description: Batch not found in this workspace. content: application/json: schema: $ref: '#/components/schemas/FilteredErrorResponse' examples: error: value: message: Campaign with ID 2g7Xy3tY53gRlp not found '409': description: >- BATCH_NOT_PAUSED: pause the batch first. BATCH_HAS_LIVE_CALLS: wait until its in-progress calls finish. content: application/json: schema: $ref: '#/components/schemas/FilteredErrorResponse' examples: error: value: message: Pause the batch before changing its phone number. data: code: BATCH_NOT_PAUSED batchHasLiveCalls: summary: 409 Conflict value: message: >- 2 call(s) from this batch are still in progress. Wait for them to finish, then retry. data: code: BATCH_HAS_LIVE_CALLS live_calls: 2 security: - bearer: [] components: schemas: FilteredErrorResponse: type: object description: >- Error body on calls, batch calls, voices, languages and LLMs, which return only the message (and data for a coded refusal). properties: message: type: string data: type: object properties: code: type: string description: Machine-readable refusal code. description: >- Present for a coded refusal: code and the details listed for that code. required: - message securitySchemes: bearer: scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.