> ## 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.

# Purchase Phone Number

> Use the purchase_phone_number MCP tool on the DialNexa remote MCP server.

<span data-api-safety-label="billable"><Badge color="yellow" size="sm" shape="pill">Billable - retry unsafe</Badge></span>

Purchases a phone number from Plivo and registers it to the organization. This is NOT a read-only action — it spends real money from the organization's wallet immediately. Use search\_plivo\_numbers first to find an available number and its telephony\_provider\_id. Requires confirm: true — only set this after the user has explicitly approved buying this specific number, never preemptively.

## Parameters

| Name                    | Type      | Required | Description                                                                                         |
| ----------------------- | --------- | -------- | --------------------------------------------------------------------------------------------------- |
| `phone_number`          | `string`  | Yes      | The phone number to purchase, e.g. +14155551234                                                     |
| `telephony_provider_id` | `string`  | Yes      | The telephony provider ID from search\_plivo\_numbers                                               |
| `country_iso`           | `string`  | Yes      | 2-letter country ISO code, e.g. US, IN                                                              |
| `confirm`               | `boolean` | Yes      | Must be true. Set this only after the user has explicitly approved purchasing this specific number. |

## Before you call

* Connect and initialize the MCP client with OAuth or an API key for the intended workspace.
* Provide the required parameters: `phone_number`, `telephony_provider_id`, `country_iso`, `confirm`.
* Set `confirm: true` only after the user approves the exact target and action.

## Example MCP request

Send `tools/call` after your client completes MCP initialization. Replace placeholder values with IDs and inputs from your workspace. For object and array parameters, follow the nested requirements in the parameter description instead of treating an empty value as complete.

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "purchase_phone_number",
    "arguments": {
      "phone_number": "+919876543210",
      "telephony_provider_id": "VALUE",
      "country_iso": "VALUE",
      "confirm": true
    }
  }
}
```

The server returns one text content block. Parse `content[0].text` as JSON when the tool succeeds. See [MCP responses and errors](/docs/mcp-tools/errors) for the full envelope and failure behavior.

## Verify the result

Store the returned resource ID and confirm the response is not marked `isError`. Call [Search Plivo Numbers](/docs/mcp-tools/phone-numbers/search-plivo-numbers) to read the affected resource. Verify the call, batch, or purchase state before retrying.

## Retry safety

This tool can spend wallet balance or start real calls. After a timeout, inspect the relevant resource before retrying so you do not duplicate the action.

## Related MCP tools

* [Search Plivo Numbers](/docs/mcp-tools/phone-numbers/search-plivo-numbers): `search_plivo_numbers`
* [List Organization Phone Numbers](/docs/mcp-tools/phone-numbers/list-organization-phone-numbers): `list_organization_phone_numbers`
* [Get Organization Phone Number](/docs/mcp-tools/phone-numbers/get-organization-phone-number): `get_organization_phone_number`

## Related guides

* [Connect to the DialNexa MCP server](/docs/mcp-tools/overview)
* [Phone Numbers MCP tools](/docs/mcp-tools/phone-numbers/overview)
* [MCP responses and errors](/docs/mcp-tools/errors)