> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nedzo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Buy a phone number

> Buy a local US or Canada number for a workspace.

<Note>
  This endpoint is for the VIP plan only. Other plans get a `403`. See [Plan access](/api-reference/introduction#plan-access).
</Note>

The number is billed every month until you release it. Search first, then buy one of the numbers the search gave you.

<ParamField body="phoneNumber" type="string" required>
  The number in E.164 format, for example `+14155551234`. US and Canada local numbers only.
</ParamField>

<ParamField body="consent" type="boolean" required>
  Must be `true`. You agree to pay for this number every month until you release it. We record your API key, your IP address and your user agent with the purchase.
</ParamField>

<ParamField body="workspaceId" type="string">
  Workspace UUID. Required for an account API key. A workspace API key uses its own workspace.
</ParamField>

## Retries

You can send the same request again. If the workspace already owns the number, you get `200` with that number and nothing is charged. While a purchase of the number is still running, you get `409`.

If an earlier purchase of the number may have taken money and never finished, you also get `409`, at any age. The message has a reference. Contact support with it before you buy the number again.

When a purchase fails after the number was held for you, the number stays held for about 30 minutes. A retry before then is refused. Try again after that, or pick another number.

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.nedzo.ai/v1/phone-numbers" \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{ "phoneNumber": "+14155551234", "consent": true }'
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "id": "4d1f6b52-8c0e-4a51-9b7d-2f3c4e5a6b7c",
    "workspaceId": "19c3b12f-ec54-43ad-8686-00e921f1befd",
    "number": "+14155551234",
    "status": "active",
    "type": "inbound_outbound",
    "friendlyName": null,
    "inboundAgentId": null,
    "chatAgentId": null,
    "fallbackEnabled": false,
    "fallbackNumber": null,
    "fallbackRingDuration": 20,
    "activeHours": null,
    "monthlyPriceCents": 99,
    "purchasedAt": "2026-10-11T12:00:00Z",
    "createdAt": "2026-10-11T12:00:00Z",
    "updatedAt": "2026-10-11T12:00:00Z"
  }
  ```
</ResponseExample>

## Errors

| Status | When |
| - | - |
| `200` | The workspace already owns this number. Nothing was charged |
| `400` | The number is not a US or Canada local number, `consent` is not `true`, the number is no longer available, or the workspace reached its monthly spending limit |
| `400` | `Insufficient funds to complete purchase`: the workspace wallet does not have enough money for this number |
| `400` | `Too many reservation requests. Please try again later.`: wait a little, then try again |
| `400` | `This number is temporarily unavailable. Please try another number.` |
| `400` | `Phone number price exceeds maximum allowed`: this number costs more than we allow. Pick another one |
| `400` | `Purchase already in progress. Please wait.`: a purchase of this number is still running |
| `400` | `The phone number service refused this request. Check the number and try again.` |
| `402` | The plan cannot buy numbers yet: a trial, an unpaid plan or no plan |
| `404` | The workspace is not found, or not in this API key's scope |
| `409` | A purchase of this number is already running, or an earlier one may have taken money and is still being settled. The message says which |
| `500` | The purchase failed. The message says what happened to any charge, and whether the number is still held |
| `502` | The phone number service did not answer. Try again |
| `503` | A check could not run. Nothing was bought. The message says when you can try again |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.