API Reference
Phone Numbers API
List your workspace's numbers, search the numbers for sale and buy one. Every purchase waits for an owner's or admin's approval.
Keys need phone_numbers:read to list the workspace's numbers and search the numbers for sale, and phone_numbers:write to buy one. Only owners and admins can give a key phone_numbers:write, and only a key one of them created buys.
Numbers are sold in the United States, Canada and Mexico. Search by area code, or in Mexico by city name, and the answer says what this workspace pays: the first month when the purchase is approved, then the same every month, in the workspace's billing currency.
Every purchase waits for approval
POST /v1/phone-numbers never buys on its own, whatever the key's approval settings: it answers 202 with a change request, and nothing is charged until a workspace owner or admin approves it in NuTalk (Settings → API keys → Approvals), seeing the number, the price, the monthly cost and the card. Follow it with GET /v1/change-requests/:id. The price you were quoted is fixed in the request: if it changes before the approval, the purchase is refused and nothing is charged.
Done in the dashboard
Adding a card (and its 3-D Secure check), the Mexican compliance profile (business details and identity document) and releasing a number are done in NuTalk. A new number takes calls once it is on a voice channel; Mexican numbers are reviewed by the carrier first (status carrier_review, usually a day or two).
List phone numbers
/v1/phone-numbersThe workspace's phone numbers, newest first: the ones bought through NuTalk and its own numbers verified as caller ID, with their status, the channel their calls ring, and what the workspace pays for them.
phone_numbers:readFields: id, phone_number, country, type, status, capabilities, receives_calls_on, billing, created_at.
Query parameters
| Name | Type | Description |
|---|---|---|
limit | integer | Results per page. 1–100. Default: |
offset | integer | Results to skip. At least 0. Default: |
Example request
curl -X GET "https://www.nutalk.ai/v1/phone-numbers?limit=20" \ -H "Authorization: Bearer YOUR_API_KEY"A page of numbers. Each has the fields below.
{
"success": true,
"data": [
{
"id": "2f6d8b0a-4c1e-4f3a-9b5d-7e9f1a3c5b72",
"phone_number": "+528155550123",
"country": "MX",
"type": "purchased",
"status": "active",
"capabilities": {
"voice": true,
"sms": false
},
"receives_calls_on": {
"id": "9f19ef32-eaef-452c-bebc-14d9759cdb64",
"name": "Support line"
},
"billing": {
"included": false,
"monthly_price": {
"amount_cents": 30000,
"currency": "mxn"
},
"next_billing_at": "2026-11-23T18:20:05.000Z"
},
"created_at": "2026-10-23T18:20:05.117+00:00"
}
],
"pagination": {
"total": 1,
"limit": 20,
"offset": 0,
"has_more": false
}
}Errors
| Status | Code | When |
|---|---|---|
| 400 | validation_error | A query parameter is invalid (details.errors lists each one). |
Plus the errors every request can return (401, 403, 429, 500): Errors.
Get a phone number
/v1/phone-numbers/:idOne of the workspace's phone numbers.
phone_numbers:readPath parameters
| Name | Type | Description |
|---|---|---|
idRequired | uuid | The phone number id. |
Example request
curl -X GET "https://www.nutalk.ai/v1/phone-numbers/2f6d8b0a-4c1e-4f3a-9b5d-7e9f1a3c5b72" \ -H "Authorization: Bearer YOUR_API_KEY"The number.
{
"success": true,
"data": {
"id": "2f6d8b0a-4c1e-4f3a-9b5d-7e9f1a3c5b72",
"phone_number": "+528155550123",
"country": "MX",
"type": "purchased",
"status": "active",
"capabilities": {
"voice": true,
"sms": false
},
"receives_calls_on": {
"id": "9f19ef32-eaef-452c-bebc-14d9759cdb64",
"name": "Support line"
},
"billing": {
"included": false,
"monthly_price": {
"amount_cents": 30000,
"currency": "mxn"
},
"next_billing_at": "2026-11-23T18:20:05.000Z"
},
"created_at": "2026-10-23T18:20:05.117+00:00"
}
}Errors
| Status | Code | When |
|---|---|---|
| 404 | not_found | No phone number with this id in your workspace (ids of other workspaces answer the same). |
Plus the errors every request can return (401, 403, 429, 500): Errors.
Search numbers to buy
/v1/phone-numbers/availableNumbers the carrier has for sale in the United States, Canada or Mexico (local numbers that take calls), by area code or, in Mexico, by city name. Easy-to-remember numbers come first (memorable). price is what this workspace pays for any of them: the first month when the purchase is approved, then the same every month, in the workspace's billing currency.
phone_numbers:readAn empty data means the carrier has no number for sale there now; try another area code or city.
Query parameters
| Name | Type | Description |
|---|---|---|
countryRequired | string | The country. One of: US, CA, MX. |
area_code | string | Only numbers with this area code (2 or 3 digits: 81 Monterrey, 212 New York). |
city | string | Mexico only: the city's name instead of its area code ( |
currency | string | The currency to price in when the workspace doesn't pay in one yet ( |
limit | integer | Numbers to return. 1–50. Default: |
Example request
curl -X GET "https://www.nutalk.ai/v1/phone-numbers/available?country=MX&city=Monterrey" \ -H "Authorization: Bearer YOUR_API_KEY"The numbers for sale and their price.
{
"success": true,
"data": [
{
"phone_number": "+528155550123",
"country": "MX",
"locality": "Monterrey",
"region": "NL",
"capabilities": {
"voice": true,
"sms": false
},
"memorable": true
}
],
"price": {
"currency": "mxn",
"charged_today_cents": 30000,
"monthly_price_cents": 30000,
"currency_locked": true
}
}Errors
| Status | Code | When |
|---|---|---|
| 400 | validation_error | A query parameter is invalid (details.errors lists each one). |
| 400 | validation_error | city names no Mexican city NuTalk sells numbers in (details.reason UNKNOWN_CITY), or is used outside Mexico. |
| 403 | forbidden | The key's creator is not an owner or admin, has left the workspace, or number purchases are not enabled for the workspace (details.reason PURCHASES_NOT_ENABLED). |
| 503 | service_unavailable | NuTalk doesn't sell numbers in the country right now (PURCHASES_UNAVAILABLE, PRICE_UNAVAILABLE), or the carrier is busy or didn't answer (CARRIER_BUSY, CARRIER_SEARCH_FAILED): try again in a few seconds. |
Plus the errors every request can return (401, 403, 429, 500): Errors.
Buy a phone number
/v1/phone-numbersAsks to buy a number found with GET /v1/phone-numbers/available. **It always waits for an owner's or admin's approval**, whatever the key's approval settings: the call answers 202 with data.change_request (status pending) and data.purchase (the number, the currency and the price), and nothing is charged until an owner or admin approves it in NuTalk (Settings → API keys → Approvals), where they see the number, the price, the monthly cost and the card. Follow it with GET /v1/change-requests/:id: once approved, the workspace's card is charged for the first month and the number is ordered from the carrier; the request's result is the number, as GET /v1/phone-numbers/:id answers it.
phone_numbers:writeAlways waits for approvalWorkspace keys only · acts as the key's creatorEvery check is made when you ask, so a purchase the workspace can't make is refused at once instead of waiting; they are all made again when it is approved.
Once approved, a card that is declined fails the request (its result is a 402 payment_failed, with details.reason CARD_DECLINED), and a number the carrier can no longer sell (it was taken while the purchase waited) is refunded at once (502, details.refunded).
Cards are added in NuTalk (Settings → Billing), never through the API, and the charge goes to the workspace's default card. A card that needs 3-D Secure is declined here (402): pay with another card, or buy the number in the dashboard.
Only a key created by an owner or admin buys, and only owners and admins can give a key phone_numbers:write. A reseller key never buys.
Request body (JSON)
| Name | Type | Description |
|---|---|---|
phone_numberRequired | string | The number to buy, in E.164 (+528155550123). |
country | string | For a +1 number only: |
currency | string | Required when the workspace doesn't pay in a currency yet (this purchase sets it for good); otherwise its currency, and another one is refused. One of: usd, mxn. |
monthly_price_cents | integer | The monthly price you were quoted ( |
compliance_profile_id | uuid | null | Mexico: the company profile to order the number under (default: the workspace's best one). Profiles are completed once in NuTalk (Phone numbers → Compliance). |
Example request
curl -X POST "https://www.nutalk.ai/v1/phone-numbers" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "phone_number": "+528155550123", "currency": "mxn", "monthly_price_cents": 30000}'The purchase waits for approval. Nothing was charged; the price and the compliance profile are fixed in the request.
{
"success": true,
"data": {
"change_request": {
"id": "3f2b1c9e-6d4a-4e8b-9c1f-2a5d7e9b0c34",
"status": "pending",
"approval": "change",
"operation": "buyPhoneNumber",
"method": "POST",
"path": "/v1/phone-numbers",
"summary": "Buy a phone number (POST /v1/phone-numbers)",
"created_at": "2026-10-23T18:20:05.117+00:00",
"expires_at": "2026-10-24T18:20:05.117+00:00",
"decided_at": null,
"finished_at": null,
"result": null
},
"purchase": {
"phone_number": "+528155550123",
"country": "MX",
"currency": "mxn",
"charged_today_cents": 30000,
"monthly_price_cents": 30000,
"compliance_profile_id": "8f9e6d2c-3b4a-4c5d-8e7f-0a1b2c3d4e5f"
}
},
"message": "Buying a number waits for an owner's or admin's approval in NuTalk: nothing is charged until it is approved. Check it with GET /v1/change-requests/{id}."
}The approved purchase, as the change request's result holds it: the new number. It takes calls once it is on a voice channel; a Mexican number is first reviewed by the carrier (carrier_review).
{
"success": true,
"data": {
"id": "2f6d8b0a-4c1e-4f3a-9b5d-7e9f1a3c5b72",
"phone_number": "+528155550123",
"country": "MX",
"type": "purchased",
"status": "active",
"capabilities": {
"voice": true,
"sms": false
},
"receives_calls_on": null,
"billing": {
"included": false,
"monthly_price": {
"amount_cents": 30000,
"currency": "mxn"
},
"next_billing_at": "2026-11-23T18:20:05.000Z"
},
"created_at": "2026-10-23T18:20:05.117+00:00"
}
}Errors
| Status | Code | When |
|---|---|---|
| 400 | validation_error | The body is not JSON, or a field is missing or invalid (details.errors lists each field). |
| 400 | validation_error | The number is not in the US, Canada or Mexico, or currency is missing for a workspace that doesn't pay in one yet (CURRENCY_REQUIRED). |
| 403 | forbidden | The key's creator is not an owner or admin, has left the workspace, or number purchases are not enabled for the workspace (details.reason PURCHASES_NOT_ENABLED). |
| 409 | conflict | The workspace already has the number (ALREADY_OWNED), it isn't available (NUMBER_NOT_AVAILABLE), an earlier purchase of it is being refunded or reviewed (REFUND_IN_PROGRESS, PURCHASE_IN_REVIEW), the workspace has no billing account or card on file (NO_BILLING_ACCOUNT, NO_PAYMENT_METHOD), pays in another currency (BILLING_CURRENCY_MISMATCH), the price changed (PRICE_CHANGED, with the new price), or a Mexican number has no usable compliance profile (NO_REGULATORY_BUNDLE). |
| 503 | service_unavailable | NuTalk doesn't sell numbers in the country right now (PURCHASES_UNAVAILABLE, PRICE_UNAVAILABLE). |
Plus the errors every request can return (401, 403, 429, 500): Errors.