voylo
Docs

REST API

Base URL, authentication, the resource endpoints, and the error model.

Base URL

https://api.voylo.io/v1. The full OpenAPI spec is served at /openapi.json with interactive docs at /docs.

Authentication

Programmatic requests use an API key as a bearer token and the X-Workspace-Id header (which workspace the call acts on). Create keys at API keys — the raw key is shown once.

Headers
Authorization: Bearer vlx_live_abc…
X-Workspace-Id: ws_…

Resources

The API is resource-based. The main collections:

  • /numbers — list, import (BYO), update destination + direction, SIP credentials
  • /trunks/inbound, /trunks/outbound — SIP routing
  • /applications — VoyloML apps (static or action-URL)
  • /calls — POST to place an outbound call (runs your app's VoyloML on answer); GET to read call records
  • /webhooks — event subscriptions + delivery log
  • /billing, /plans, /rentals — plans, wallet, invoices, number rentals
  • /voyloml/validate — lint a VoyloML document
GET /v1/numbers
curl https://api.voylo.io/v1/numbers \
-H "Authorization: Bearer $VOYLO_API_KEY" \
-H "X-Workspace-Id: $VOYLO_WORKSPACE_ID"
POST /v1/calls — place an outbound call
curl -X POST https://api.voylo.io/v1/calls \
-H "Authorization: Bearer $VOYLO_API_KEY" \
-H "Idempotency-Key: order-1234-call-1" \
-H "Content-Type: application/json" \
-d '{"from":"+2004446","to":"+201091447677","applicationId":"<uuid>","variables":{"order_id":"ORD-1234"}}'

Returns 202 with { publicId, status: "dialing" }. Voylo rings tofrom one of your workspace numbers, and on answer runs the chosen application's VoyloML. Progress arrives via webhooks: call.placed immediately, then call.answered / call.completed / call.failed. The Idempotency-Key header is honoured — replaying the same request returns the original call instead of dialling twice.

Custom variables are substituted as {{key}}in the application's static VoyloML AND ride as var_<key> on any action-URL POSTs. See the VoyloML reference for the full rules.

Errors

JSON body with statusCode, error, and message; validation failures (400) include field details. Full breakdown in Errors.

SDKs

The Node and Python SDKs wrap these endpoints (typed errors, workspace header handled) and include a VoyloML builder. Prefer them over raw HTTP.

← Previous
VoyloML reference
Next →
SDKs