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 }'
{
"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"
}
Phone Numbers
Buy a phone number
Buy a local US or Canada number for a workspace.
POST
/
phone-numbers
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 }'
{
"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"
}
This endpoint is for the VIP plan only. Other plans get a
403. See Plan access.string
required
The number in E.164 format, for example
+14155551234. US and Canada local numbers only.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.string
Workspace UUID. Required for an account API key. A workspace API key uses its own workspace.
Retries
You can send the same request again. If the workspace already owns the number, you get200 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.
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 }'
{
"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"
}
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 |
Was this page helpful?