Get started
Buy a number and receive calls
Check your verification and credit, find a number, order it from your prepaid wallet and send its inbound calls to your application or a call flow.
In this quickstart you rent a phone number and point its inbound calls at something that answers them: your own server (a voice application’s answer URL) or a call flow you built. The full reference is Phone numbers.
Before you start
- A live key with
numbers:readandnumbers:write, plusverifications:readandbilling:readfor the checks below. Test keys cannot rent numbers. See Authentication. - A verified business, if you signed up on your own: live keys work once the verification is approved.
- Prepaid credit for the number’s setup fee and first month.
- Somewhere to send the calls: a voice application (see Inbound calls) or a published call flow (see Call flows), and its id.
Check the paperwork
Ask what the number type you want needs. Every requirement with satisfied: false must be uploaded in the console (Settings → Business verification) before the number can be activated; local and mobile numbers need only the business’s own documents, while 140-series, 160-series and toll-free numbers in India also need a letter of authority.
curl 'https://api.trovacast.com/v1/verifications?numberType=local' \
-H "Authorization: Bearer $TROVACAST_API_KEY"Check your credit
Activation debits the setup fee and the first month from your wallet at once. Read your balance and compare it with the number’s setupFeeMinor + monthlyFeeMinor from the search.
curl 'https://api.trovacast.com/v1/balance' \
-H "Authorization: Bearer $TROVACAST_API_KEY"Find a number
curl 'https://api.trovacast.com/v1/numbers/available?country=IN&type=local&includeSupplierStock=false' \
-H "Authorization: Bearer $TROVACAST_API_KEY"Pick an entry with orderable: true and keep its id and version: the version pins the price you saw.
Order it
curl -X POST 'https://api.trovacast.com/v1/numbers' \
-H "Authorization: Bearer $TROVACAST_API_KEY" \
-H 'Idempotency-Key: buy-6b0d4f3e-7c1a-4f5e-9d2b-1a3c5e7f9b11' \
-H 'Content-Type: application/json' \
-d '{
"numberId": "6b0d4f3e-7c1a-4f5e-9d2b-1a3c5e7f9b11",
"version": 1
}'{
"object": "number_order",
"activated": true,
"pending": null,
"number": {
"object": "phone_number",
"id": "6b0d4f3e-7c1a-4f5e-9d2b-1a3c5e7f9b11",
"number": "+918035550100",
"status": "assigned",
"paidThrough": "2026-12-05T10:00:00.000Z",
"route": {
"kind": "none",
"targetId": null
},
"version": 3
}
}If activated is false, the number is held for you and pending.code says why — upload the missing document or top up, then call POST /v1/numbers/{numberId}/activate with the number’s version before reservedUntil. Send an Idempotency-Key with the order, as above, so a retried request can never order twice.
Send its calls to your application
Route the number’s inbound calls to your voice application — Trovacast asks its answer URL what to do with each call — or to a call flow with kind: flow. Use the number’s current version.
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": "Main line",
"route": {
"kind": "application",
"targetId": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b"
}
}'Now call the number from any phone. Your application answers it (Inbound calls describes the request your answer URL receives and what it can reply), and the call’s minutes show up in usage under voice.