Trovacast

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.

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.

Search local numbers in an area code
curl 'https://api.trovacast.com/v1/numbers/available?country=IN&type=local&prefix=80' \
  -H "Authorization: Bearer $TROVACAST_API_KEY"
200 — inventory and supplier stock (json)
{
  "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.

Order a number
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
}'
201 — held, waiting for credit (json)
{
  "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.

Order a carrier’s number at your plan’s price
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"
}'
Activate the hold
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.

Send a number’s calls to a call flow
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"
  }
}'
200 — the number at its new version (json)
{
  "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 version by 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 }] — callType full_ai for a route to an AI agent, manual for any other. With billing enforced, each such call is refused with a short apology and recorded failed with 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/pricing lists your plan’s inbound rates.
  • A route that cannot answer for another reason warns too (2026-11-07): AI_PROVIDER_UNAVAILABLE when the AI agent an ai route answers with — or one an AI step of a flow route hands the caller to — cannot speak on this deployment, with the reason GET /v1/agents/{agentId} reports; AI_AGENT_UNAVAILABLE when that agent cannot take the caller for any other reason its calls are refused on — reason AI_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; the message says which) or TEST_AGENT; and BILLING_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; null when 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 PATCH that leaves the number’s route target as it is — a label, the same route sent again, or both — always saves, with its warnings. A PATCH that 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, or 400 for 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 409 NUMBER_NOT_ASSIGNED.
  • dltHeaderId links 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; null unlinks.

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.

List the assigned numbers
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.

Read one number
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.

Make a number an SMS sender
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.

Ask to port two numbers
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"
}'
201 — submitted (json)
{
  "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.

Release a number
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

CodeStatusMeaning and what to do
BILLING_INSUFFICIENT_CREDIT402The 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_REQUIRED422The 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_MISMATCH409The 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_ASSIGNED409Only 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_AVAILABLE409The 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_PRICED422A 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_LIMIT409The 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_UNSUPPORTED422The 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_FAILED502The 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_PROGRESS409Another 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_CONFLICT409The 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_REQUIRED422loaDocumentId 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_ASSIGNED409A 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_PLATFORM409A 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_DUPLICATE409A 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_TRANSITION409The 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_CONFLICT409The 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_UNSUPPORTED422A 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_REQUIRED403This 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_REQUIRED403The 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.