Voice
Phone numbers
Search for numbers, order one from your prepaid wallet, route its inbound calls to a call flow, an application, a queue or a person, and release it.
Numbers come from several carriers behind one inventory, so the same API orders and configures a number whichever carrier supplies it. A number you rent is your business’s own, so the API answers it in full. Numbers need two scopes: numbers:read to list and search, numbers:write to order, activate, configure and release — the scope that spends credit.
- GET
/v1/numbersLists the numbers the organization holds — on hold, assigned, suspended or being released - GET
/v1/numbers/{numberId}Reads one number the organization holds - GET
/v1/numbers/availableSearches the numbers for sale: the platform’s priced inventory, plus indicative supplier stock - POST
/v1/numbersOrders a number — from the platform’s inventory, or a carrier’s live stock at your plan’s price: holds it, and activates it (charging its setup fee and first month) when it can - POST
/v1/numbers/{numberId}/activateActivates a number on hold, charging its setup fee and first month - PATCH
/v1/numbers/{numberId}Labels a number, routes its inbound calls (to a flow, an application, a queue, a seat or an AI agent) or links its voice DLT header - POST
/v1/numbers/{numberId}/releaseCancels a hold, or releases a number (no further rentals) - POST
/v1/numbers/{numberId}/sms-senderRegisters one of your SMS-capable numbers outside India as an SMS sender (long code) - POST
/v1/numbers/port-requestsAsks to port the organization’s own numbers in from another carrier, with a letter of authority - GET
/v1/numbers/port-requestsLists the organization’s port-in requests, newest first - GET
/v1/numbers/port-requests/{portRequestId}Reads one port-in request - POST
/v1/numbers/port-requests/{portRequestId}/cancelWithdraws an open port-in request
Search what is for sale
Search by country (required), type and the digits after the country code. Numbers in our inventory carry their price — the monthly rental and a one-off setup fee, in minor units of currency — and the version you order with. Live stock at a carrier that provisions by API comes back too, as source: supplier, with the provider it lives on. It is orderable at your plan’s number price once we resell that carrier and your plan prices numbers of that type and country; otherwise it is indicative (orderable: false, unpriced), because a carrier’s cost is never our price — ask us to stock it. If a carrier cannot be searched just then, the answer still holds our inventory and every carrier that answered, and warnings names the one missing — NUMBER_SUPPLIER_UNAVAILABLE, with orderable (whether you could have bought its stock) and retryAfterSeconds — so a gap never reads as “nothing for sale”. Only when nothing could be searched at all is the search a 503: retry, or pass includeSupplierStock=false to search our own stock alone.
curl 'https://api.trovacast.com/v1/numbers/available?country=IN&type=local&prefix=80' \
-H "Authorization: Bearer $TROVACAST_API_KEY"{
"data": [
{
"object": "available_number",
"id": "6b0d4f3e-7c1a-4f5e-9d2b-1a3c5e7f9b11",
"number": "+918035550100",
"country": "IN",
"type": "local",
"capabilities": {
"voiceInbound": true,
"voiceOutbound": true,
"sms": false
},
"monthlyFeeMinor": 50000,
"setupFeeMinor": 10000,
"currency": "INR",
"source": "inventory",
"orderable": true,
"region": null,
"version": 1,
"provider": "plivo"
},
{
"object": "available_number",
"id": null,
"number": "+918035550199",
"country": "IN",
"type": "local",
"capabilities": {
"voiceInbound": true,
"voiceOutbound": true,
"sms": false
},
"monthlyFeeMinor": 50000,
"setupFeeMinor": 10000,
"currency": "INR",
"source": "supplier",
"orderable": true,
"region": "Bengaluru",
"version": null,
"provider": "plivo"
}
],
"nextCursor": null
}Order a number
Order an inventory number with the version its search showed — the price you saw is the price you pay; a number repriced since answers 409 NUMBER_VERSION_CONFLICT. The number is held for you (reserved) and activated at once when it can be: your business is verified, the number type’s paperwork is on file (a letter of authority for 140-series, 160-series and toll-free numbers in India; a verified DLT header for a 140-series number), and your wallet pays the setup fee and the first month. Either way the answer is 201.
curl -X POST 'https://api.trovacast.com/v1/numbers' \
-H "Authorization: Bearer $TROVACAST_API_KEY" \
-H 'Idempotency-Key: order-6b0d4f3e-7c1a-4f5e-9d2b-1a3c5e7f9b11' \
-H 'Content-Type: application/json' \
-d '{
"numberId": "6b0d4f3e-7c1a-4f5e-9d2b-1a3c5e7f9b11",
"version": 1
}'{
"object": "number_order",
"activated": false,
"pending": {
"code": "BILLING_INSUFFICIENT_CREDIT",
"message": "Add credit to cover the number’s setup fee and first month"
},
"number": {
"object": "phone_number",
"id": "6b0d4f3e-7c1a-4f5e-9d2b-1a3c5e7f9b11",
"number": "+918035550100",
"status": "reserved",
"route": {
"kind": "none",
"targetId": null
},
"monthlyFeeMinor": 50000,
"setupFeeMinor": 10000,
"currency": "INR",
"paidThrough": null,
"reservedUntil": "2026-11-12T10:00:00.000Z",
"version": 2
}
}pending.code says what held it: VERIFICATION_DOCUMENTS_REQUIRED, DLT_HEADER_REQUIRED, BILLING_INSUFFICIENT_CREDIT or NUMBER_CURRENCY_MISMATCH. Fix it — upload the document, top up — then activate the hold before reservedUntil, when it goes back on sale. Activation posts the setup fee and the first month to your wallet once; GET /v1/usage shows them under numbers.
Order supplier stock with its number and provider instead. It is held at your plan’s price, bought from the carrier when it activates (once — never twice), then charged like any number. If the carrier will not sell it, nothing is charged: the order answers pending.code NUMBER_SUPPLIER_ORDER_FAILED — activate again, or release the hold, which drops it.
curl -X POST 'https://api.trovacast.com/v1/numbers' \
-H "Authorization: Bearer $TROVACAST_API_KEY" \
-H 'Idempotency-Key: order-supplier-918035550199' \
-H 'Content-Type: application/json' \
-d '{
"number": "+918035550199",
"provider": "plivo"
}'curl -X POST 'https://api.trovacast.com/v1/numbers/6b0d4f3e-7c1a-4f5e-9d2b-1a3c5e7f9b11/activate' \
-H "Authorization: Bearer $TROVACAST_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"version": 2
}'Route its inbound calls
PATCH a number to label it, point its inbound calls somewhere, or link its voice DLT header — any of the three, with the version you read. A route goes to a published call flow, a voice application (your answer URL — see Inbound calls), a queue, one person (agent: their seat’s membership id), an AI agent that answers itself (ai: see AI over the API), and back to none. Only an assigned number that takes inbound calls can be routed.
curl -X PATCH 'https://api.trovacast.com/v1/numbers/6b0d4f3e-7c1a-4f5e-9d2b-1a3c5e7f9b11' \
-H "Authorization: Bearer $TROVACAST_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"version": 3,
"label": "Support line",
"route": {
"kind": "flow",
"targetId": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d"
}
}'{
"object": "phone_number",
"id": "6b0d4f3e-7c1a-4f5e-9d2b-1a3c5e7f9b11",
"number": "+918035550100",
"country": "IN",
"type": "local",
"provider": "plivo",
"capabilities": {
"voiceInbound": true,
"voiceOutbound": true,
"sms": false
},
"status": "assigned",
"suspensionReason": null,
"label": "Support line",
"route": {
"kind": "flow",
"targetId": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d"
},
"dltHeaderId": null,
"monthlyFeeMinor": 50000,
"setupFeeMinor": 10000,
"currency": "INR",
"assignedAt": "2026-11-05T10:00:00.000Z",
"paidThrough": "2026-12-05T10:00:00.000Z",
"reservedUntil": null,
"releasedAt": null,
"updatedAt": "2026-11-05T10:00:00.000Z",
"version": 5,
"warnings": []
}- Both halves of a change are checked before either is written, so a refusal leaves the number as it was. A route and a label together move
versionby two. - A target that is not yours — another organization’s flow, an archived one, an inactive queue — is
400 VALIDATION_FAILED. - A route your plan does not price is saved, and the number says so on every read until it is priced:
warnings: [{ code: "BILLING_RATE_UNAVAILABLE", direction: "inbound", provider, callType, agentId, reason, step, message }]—callTypefull_aifor a route to an AI agent,manualfor any other. With billing enforced, each such call is refused with a short apology and recordedfailedwith that code (call.failed); with shadow billing it is recorded unpriced, and charged only if your plan prices it within 7 days of the call.GET /v1/pricinglists your plan’s inbound rates. - A route that cannot answer for another reason warns too (2026-11-07):
AI_PROVIDER_UNAVAILABLEwhen the AI agent anairoute answers with — or one an AI step of aflowroute hands the caller to — cannot speak on this deployment, with thereasonGET /v1/agents/{agentId}reports;AI_AGENT_UNAVAILABLEwhen that agent cannot take the caller for any other reason its calls are refused on —reasonAI_CALLS_DISABLED(AI calls are switched off for your organization),AGENT_INACTIVE(the agent is switched off — switch it on — or archived — it cannot be switched back on, so the route or step must name another agent; themessagesays which) orTEST_AGENT; andBILLING_RATE_UNAVAILABLE(callType: full_ai) for a flow’s AI step whose AI call your plan does not price.step({ node, index }) names the flow step;nullwhen the warning is about the route itself. A route or step that fails for more than one cause has one warning per cause (2026-11-07). Each goes once its cause does. - A
PATCHthat leaves the number’s route target as it is — a label, the sameroutesent again, or both — always saves, with its warnings. APATCHthat changes the target is checked first: pointing the number at a new AI agent that cannot take calls is refused (409 AI_CALLS_DISABLED,422 AI_PROVIDER_UNAVAILABLE, or400for an agent that is switched off or not your live one). A price gap never refuses a save. - Routing a number on hold, suspended or being released is
409NUMBER_NOT_ASSIGNED. dltHeaderIdlinks a verified voice DLT header of the number’s own series (VOICE_140 for 140-series, VOICE_160 for 160-series) naming this very number;nullunlinks.
List your numbers
The numbers you hold — reserved, assigned, suspended (for unpaid rental, suspensionReason: non_payment, or by us) and releasing — newest first, paginated. paidThrough is when the next month’s rental is debited.
curl 'https://api.trovacast.com/v1/numbers?status=assigned' \
-H "Authorization: Bearer $TROVACAST_API_KEY"Read one number you hold with GET /v1/numbers/{numberId}; any other id — on sale, gone, another organization’s — is 404.
curl 'https://api.trovacast.com/v1/numbers/6b0d4f3e-7c1a-4f5e-9d2b-1a3c5e7f9b11' \
-H "Authorization: Bearer $TROVACAST_API_KEY"Send SMS from a long code
Outside India a text can come from an ordinary phone number. Make one of your SMS-capable numbers (GET /v1/numbers?capability=sms) an SMS sender: it is active at once — except in the United States and Canada, whose carriers register every sender (10DLC, toll-free verification), where it is pending_verification until the platform activates it (sms.sender.updated says when) — and it leaves with the number when you release it. An Indian number is refused with NUMBER_SMS_UNSUPPORTED — SMS in India is sent from a DLT header.
curl -X POST 'https://api.trovacast.com/v1/numbers/6b0d4f3e-7c1a-4f5e-9d2b-1a3c5e7f9b11/sms-sender' \
-H "Authorization: Bearer $TROVACAST_API_KEY" \
-H "Idempotency-Key: $(uuidgen)"Bring your own numbers (port-in)
Ask to bring numbers over from another carrier with the numbers, the carrier they are leaving and a signed letter of authority — a NUMBER_LOA document you upload to your business verification. Our team runs the port with the carrier; the request moves submitted → in_review → approved (with focDate, the date the carrier committed to) → completed, when the numbers are yours in GET /v1/numbers — or rejected, with reviewNote saying why. Each step is a number.port_request.updated event. Withdraw an open request with cancel. A test key cannot port.
curl -X POST 'https://api.trovacast.com/v1/numbers/port-requests' \
-H "Authorization: Bearer $TROVACAST_API_KEY" \
-H 'Idempotency-Key: port-918031150000' \
-H 'Content-Type: application/json' \
-d '{
"numbers": [
"+918031150000",
"+918031150001"
],
"country": "IN",
"numberType": "local",
"currentCarrier": "Airtel",
"loaDocumentId": "3c9a0e52-0f4f-4f63-9c1e-6a8b1c2d3e4f"
}'{
"object": "number_port_request",
"id": "5d2c1b0a-9f8e-4d7c-a6b5-4c3d2e1f0a9b",
"numbers": [
"+918031150000",
"+918031150001"
],
"country": "IN",
"numberType": "local",
"currentCarrier": "Airtel",
"loaDocumentId": "3c9a0e52-0f4f-4f63-9c1e-6a8b1c2d3e4f",
"status": "submitted",
"reviewNote": null,
"focDate": null,
"createdAt": "2026-11-05T10:00:00.000Z",
"updatedAt": "2026-11-05T10:00:00.000Z",
"reviewedAt": null,
"completedAt": null,
"cancelledAt": null,
"version": 1
}Release a number
Releasing a number on hold puts it straight back on sale (the answer shows status: available). Releasing an assigned number ends its rental, clears its route and any agent caller-ID that used it, and quarantines it (releasing) for 30 days before anyone else can rent it.
curl -X POST 'https://api.trovacast.com/v1/numbers/6b0d4f3e-7c1a-4f5e-9d2b-1a3c5e7f9b11/release' \
-H "Authorization: Bearer $TROVACAST_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"version": 5
}'Errors
| Code | Status | Meaning and what to do |
|---|---|---|
BILLING_INSUFFICIENT_CREDIT | 402 | The prepaid wallet, after any included plan minutes, cannot cover the messages at your plan's rate — or a call's ceiling: its maxDurationSec in started minutes, beside what your live API calls already in flight can still run to (inFlightMinutes), each at its own rate.What to do: Top up the prepaid balance (POST /v1/balance/top-ups, or Add credit in Settings → Billing), then retry. When the refusal carries maxDurationSecAvailable, a call with a maxDurationSec up to it is placed now; without it no shorter call fits — retry once a call in progress ends. See Limits and billing. |
DLT_HEADER_REQUIRED | 422 | The 140-series number has no verified DLT voice header of this organization — on a call from it, or on activating it.What to do: Register a voice header for this exact number under Settings → DLT registrations and wait for it to be verified, then retry; until then the same request fails the same way. |
NUMBER_CURRENCY_MISMATCH | 409 | The number is priced in a currency the organization's wallet does not hold.What to do: Pick a number whose currency in the search results is your wallet's, or contact us to have this one priced for your wallet. |
NUMBER_NOT_ASSIGNED | 409 | Only an assigned number can be routed — not one on hold, suspended or being released. See Phone numbers.What to do: Activate a held number first (POST /v1/numbers/{numberId}/activate), then set its route; a suspended number routes again once it is reactivated, one being released never does. |
NUMBER_NOT_AVAILABLE | 409 | The number is not in a state that allows this: someone else holds it (or you already hold it), it is quarantined after a release, or it is retired — or a release of a number already being released.What to do: Pick another number from a fresh search (GET /v1/numbers/available); retrying this one cannot succeed while it is held, quarantined or retired. A number you already hold is listed by GET /v1/numbers. |
NUMBER_NOT_PRICED | 422 | A carrier’s number your plan has no price for (that type in that country), so it cannot be ordered. Search shows it orderable: false.What to do: Order a number search shows orderable: true, or contact us to have that type and country priced on your plan. |
NUMBER_RESERVATION_LIMIT | 409 | The organization already holds the maximum number of pending number requests — five, or two while its business still awaits verification.What to do: Activate a held number (POST /v1/numbers/{numberId}/activate), release a hold you do not want (POST /v1/numbers/{numberId}/release) or wait for one to lapse, then order again. An approved business verification raises the limit to five. |
NUMBER_SMS_UNSUPPORTED | 422 | The number cannot be an SMS sender: it has no SMS capability, or it is Indian — SMS in India is sent from a DLT header, not a long code.What to do: Choose an SMS-capable number outside India (GET /v1/numbers?capability=sms); to text India, send from a DLT header instead. See SMS. |
NUMBER_SUPPLIER_ORDER_FAILED | 502 | The carrier did not complete the purchase of a held supplier number, so nothing was charged and the number stays on hold. It appears as pending.code on an order.What to do: Read the number for its new version and activate it again with a new Idempotency-Key (the same key replays this error), or release the hold, which drops it. |
NUMBER_SUPPLIER_ORDER_IN_PROGRESS | 409 | Another request is buying this held number from its carrier right now. A number is never bought twice.What to do: Retry in a moment, with the number’s current version (GET /v1/numbers/{numberId}). |
NUMBER_VERSION_CONFLICT | 409 | The number changed since you read it: another request routed, labelled, activated or released it, or its price changed while it was on sale.What to do: Read it again (GET /v1/numbers/{numberId}, or search again for one on sale) and retry with its new version — after checking the price, if it moved. |
PORT_LOA_REQUIRED | 422 | loaDocumentId is not a letter of authority (number_loa) your organization uploaded to its business verification.What to do: Upload the letter of authority (POST /v1/verifications/{verificationId}/documents, type number_loa) and send its document id as loaDocumentId. |
PORT_NUMBERS_NOT_ASSIGNED | 409 | A port request is completed only once every number is live on the platform and assigned to the organization; the message lists the ones still missing.What to do: Nothing to change on your side: the request completes once the listed numbers are assigned to you. Follow it with number.port_request.updated. |
PORT_NUMBER_ON_PLATFORM | 409 | A number in the request is already on the platform (yours or another organization’s), so it cannot be ported in. The message lists which.What to do: Leave the numbers the message lists out of the request and send it again. |
PORT_REQUEST_DUPLICATE | 409 | A number in the request is already in another open port request of yours.What to do: Cancel that request (POST /v1/numbers/port-requests/{portRequestId}/cancel) or wait for it to finish — or leave the number out of this one. |
PORT_REQUEST_INVALID_TRANSITION | 409 | The port request cannot move that way: a completed, rejected or cancelled request is final.What to do: Do not retry: create a new port request (POST /v1/numbers/port-requests) if the numbers still need porting. |
PORT_REQUEST_VERSION_CONFLICT | 409 | The port request changed since you read it.What to do: Read it again (GET /v1/numbers/port-requests/{portRequestId}) and retry with its new version. |
TEST_MODE_UNSUPPORTED | 422 | A test-mode key (tc_test_…) cannot perform this: either it has no sandbox — managing templates, the WhatsApp account or email domains, writing broadcasts, renting numbers — or it would read or change live data: a recording, a contact export, consent, changing or erasing an existing contact, or changing live call flows, applications and AI agents. (A live customer’s conversation, or a live message to quote or react to, is not refused but not found: 404.) See Authentication.What to do: Repeat the request with a live key (tc_live_…); no test key can do it. In test mode, work on the test records your test key created instead. |
VERIFICATION_DOCUMENTS_REQUIRED | 403 | This number type needs a document that is not on file and accepted yet — a letter of authority for 140-series, 160-series or toll-free numbers. Every organization needs it, including one an integration provisioned without a business verification.What to do: Upload the letter of authority (POST /v1/verifications/{verificationId}/documents with type number_loa, or Settings → Business verification); once the platform accepts it, activate the number again. |
VERIFICATION_REQUIRED | 403 | The feature (feature names it: numbers, live keys, live messaging, live calls or subaccounts) needs an approved business verification.What to do: Complete and submit the business verification (Settings → Business verification, or POST /v1/verifications then POST /v1/verifications/{verificationId}/submit), and retry once it is approved. See Business verification. |