API reference

Phone numbers

A phone number is a DID you claim from the TelVox pool in the dashboard. Point its webhook URL at your app and inbound calls reach you. You manage numbers in the dashboard only: there is no numbers API.

Claiming a number

In the dashboard, open Numbers, then Claim a number.
Pick a number from the pool.
Edit it to set the webhook URL and, if you want status callbacks, the Hangup URL.

If the pool does not have what you need, talk to us. Connect is live; the API is v0.x, so field names may change before v1.

Number settings

Each number has these settings in the dashboard.

Setting	Type	Description
Phone number	E.164	The number itself, for example +918045670100. Use this exact value as from on POST /api/calls.
Webhook URL	url	Connect POSTs {from, to, direction: "inbound"} here when a call comes in. Your reply is the markup that runs the call.
Response format	xml \| json	The markup your webhook returns. XML is the full verb set; JSON is a smaller subset.
Hangup URL	url	The status callback for calls on this number. Connect POSTs the call status here, including the final status whether or not the call connected. Same fields as the status callbacks on Calls.
Client reference	string	Your own ID for the end client this number serves (up to 64 characters). Sent back as ClientRef in status callbacks.
Active	on \| off	When off, inbound calls to the number are hung up without reaching your webhook, and you cannot place calls from it.
Incoming schedule	timezone + hours	Weekly business hours for the number. Outside them, the after-hours action runs instead of your webhook.
After-hours action	enum	What happens outside the schedule: hangup, voicemail, forward (to a number) or webhook (a different URL).
Incoming IVR menu	prompt + keys	A one-level keypress menu set up in the dashboard. When it is on, callers hear the menu and your webhook is not called. Each key can forward, go to voicemail, join a queue, hang up or replay the menu.
Recording policy	mode + tracks	Default mode (off, from answer, from ringing), tracks (inbound, outbound or both), an optional recording callback URL, and an Immutable switch that stops recording being paused or stopped through the API or markup.

What your webhook receives

When a call comes in during business hours (and the IVR menu is off), Connect POSTs JSON to the number's webhook URL. The body has no call SID; it arrives in the X-CPaaS-Call-Sid header. You have 5 seconds to reply. If the webhook fails or times out, the caller hears a short message and the call ends.

POSTyour.app/voice/incoming

{
  "from": "+919876500199",
  "to": "+918045670100",
  "direction": "inbound"
}

Reply with the markup that runs the call. The XML below greets the caller and collects one key; Connect then POSTs {"digit": "1"} to the Gather action URL. JSON has no Gather, so the JSON reply just connects the caller. Every verb is in Call-control markup.

Your reply

<Response>
  <Say>Thanks for calling Acme.</Say>
  <Gather action="https://your.app/voice/menu" numDigits="1" timeout="5">
    <Say>Press 1 for sales or 2 for support.</Say>
  </Gather>
</Response>

200 ok

Status callbacks for the call go to the Hangup URL. Their fields are on Calls, and every request Connect sends is listed on Webhooks & callbacks.

Calling from a number

The from on POST /api/calls must be a number you have claimed and that is active, written as the dashboard shows it. Anything else is refused before the call is placed:

POST /api/calls with a number you do not hold

HTTP/1.1 422 Unprocessable Content
Content-Type: application/json

{
  "error": "The 'from' number is not one of your active numbers. Claim it in the dashboard (Numbers → Claim a number) before calling from it."
}

422 unprocessable