API reference

The TelVox Connect REST API lets you place outbound calls, look up a call, control recording on a live call and download recordings, all over HTTPS with JSON. Call flow itself (IVRs, queues, conferences) is driven by the markup your webhook returns. This page covers the base URL, authentication and errors, then indexes every resource.

API stabilityConnect is live. The endpoints below are real, and the API is versioned v0.x, so field names and shapes may change before v1. Watch the changelog for breaking changes.

Base URL

All requests go to https://connect.telvox.dev/api. Send request bodies as JSON with Content-Type: application/json, and send Accept: application/json on every request. Without that header, a validation error comes back as a redirect instead of a JSON 422.

base URL

https://connect.telvox.dev/api

Authentication

Create an API key in the dashboard under API keys. It is shown once, starts with sk_live_, and goes in the Authorization header as a Bearer token. Keep it on your server. Accounts are set up with the TelVox team; after that you create and delete keys yourself. See the authentication concept for the full key model.

A missing key returns 401 with {"error":"API key required. Pass it as: Authorization: Bearer sk_live_..."}. A wrong or deleted key returns 401 with {"error":"Invalid or expired API key."}.

GET/api/calls/{callSid}

curl https://connect.telvox.dev/api/calls/CA7Q2M9X4K1B8N3T6R0W5Y2Z9C1V4H7JL5 \
  -H "Authorization: Bearer $TELVOX_API_KEY" \
  -H "Accept: application/json"

200 ok

Errors & status codes

Errors return a JSON body. Most use {"error": "..."}, a few add a code, and validation failures use the {"message", "errors"} shape. Check the HTTP status first, then read whichever field is there.

error responses

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

application/json

Field	Type	Description
error	string	What went wrong, in plain words. Present on most errors.
code	string	A machine-readable code, only on some errors, for example recording_immutable.
message	string	Used instead of error on 422 validation errors and on some 404s.
errors	object	Only on 422 validation errors. Keyed by field name, each with a list of messages.

Status codes

Code	Meaning
200 OK	The request worked.
201 Created	A call was placed, or a SIP trunk was created.
401 Unauthorized	The API key is missing, or it is wrong or deleted.
403 Forbidden	Your account is not enabled for SIP trunking (partner trunk endpoints only).
404 Not Found	Nothing exists at that path, or the call, recording or trunk is not on your account.
409 Conflict	The number's recording policy is locked, so recording on this call cannot be paused or stopped.
422 Unprocessable Entity	A field is missing or invalid, or the from number is not one of your active numbers.
500 Server Error	The call could not be placed. The error message says why.
502 Bad Gateway	The call engine rejected a recording command. The body includes engine_status and engine_body.
503 Service Unavailable	Recording controls are switched off.

Resources

Each resource page lists its endpoints or markup, samples, and the callbacks it sends.