Trovacast

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:read and numbers:write, plus verifications:read and billing:read for 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.

What a local number needs
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.

Read the balance
curl 'https://api.trovacast.com/v1/balance' \
  -H "Authorization: Bearer $TROVACAST_API_KEY"

Find a number

Search our inventory only
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

Order the number
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
}'
201 — yours now (json)
{
  "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.

Route to an application
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.

Next steps