Get started
Receive inbound calls
Buy a number, send its calls to a call flow or your own answer URL, and follow every call as it arrives with the call.inbound webhook.
In this quickstart a number of yours answers its callers: with a call flow Trovacast runs for you, or with your own server answering each call. Every call that arrives also reaches your webhook as call.inbound. Renting the number itself is Buy a number; the reference is Inbound calls.
Before you start
- A live key with
numbers:read,numbers:write,call-flows:writeorapplications:write,calls:readandwebhooks:manage. - A number of yours, assigned and paid for — follow Buy a number to its
201and keep itsidandversion. (A toll-free, 140- or 160-series number in India also needs an accepted letter of authority on file, whoever you are.) - A webhook endpoint of yours — see Receive webhooks.
Subscribe to call.inbound
curl -X POST 'https://api.trovacast.com/v1/webhook-endpoints' \
-H "Authorization: Bearer $TROVACAST_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"url": "https://api.example.com/trovacast/webhook",
"events": [
"call.inbound",
"call.completed"
]
}'Store the secret from the answer — it is shown once, and every delivery is signed with it.
Choose what answers
A call flow (no server of your own)
curl -X POST 'https://api.trovacast.com/v1/call-flows' \
-H "Authorization: Bearer $TROVACAST_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"name": "Main line",
"definition": {
"version": 1,
"start": "main",
"nodes": {
"main": [
{
"verb": "say",
"text": "Thank you for calling Acme. Please hold for the next person."
},
{
"verb": "hangup"
}
]
}
}
}'Publish it (POST /v1/call-flows/{callFlowId}/publish) — a number only runs a published version. The IVR quickstart builds a real menu.
Or your own server (a voice application)
curl -X POST 'https://api.trovacast.com/v1/applications' \
-H "Authorization: Bearer $TROVACAST_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"name": "Main line",
"answerUrl": "https://voice.example.com/answer",
"fallbackUrl": "https://voice.example.com/fallback",
"timeoutMs": 3000
}'Store its secret (shown once). Each answered call is a signed POST to the answer URL, and your server replies with the verbs to run — { "verbs": [{ "verb": "say", "text": "Hello" }, { "verb": "hangup" }] }. The SDKs build and check these documents for you.
Route the number
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,
"route": {
"kind": "flow",
"targetId": "2e3f4a5b-6c7d-4e8f-9a0b-1c2d3e4f5a6b"
}
}'Or { "kind": "application", "targetId": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b" } for your application. The answer is the number with its new route and version.
Call it
Call the number from any phone. You hear the flow (or what your answer URL replied), and call.inbound arrives at your webhook with the call — direction: inbound, the caller masked to their last four digits — then call.completed when it ends. Verify each delivery’s signature, and dedupe on the event id.
{
"id": "evt_…",
"type": "call.inbound",
"createdAt": "2026-11-06T10:00:00.000Z",
"data": {
"call": {
"object": "call",
"id": "2c9d8e7f-6a5b-4c3d-9e2f-1a0b9c8d7e6f",
"direction": "inbound",
"status": "in_progress",
"flow": {
"source": "call_flow",
"callFlowId": "2e3f4a5b-6c7d-4e8f-9a0b-1c2d3e4f5a6b",
"applicationId": null
}
}
}
}