API reference
Every endpoint of https://tvh-voice-api.gigaleads.nl, generated from the
OpenAPI 3.1 document (which also has full response schemas and examples).
Authentication: Authorization: Bearer vk_…. Conventions: API conventions.
#Agents
GET /v1/agents
List agents with live registration status
Responses
200 Default Response · 400 Default Response · 401 Default Response · 403 Default Response · 404 Default Response · 409 Default Response · 422 Default Response · 429 Default Response · 500 Default Response · 503 Default Response
POST /v1/agents
Create an agent (SIP account)
Creates SIP account agent_{agent_ref} with a random strong password. Enforces the max-agents limit.
Request body
| Field | Type | Description |
|---|---|---|
agent_ref required | string | Unique per workspace. 1-64 chars: letters, digits, "_" or "-". |
display_name | string | null |
Responses
201 Default Response · 400 Default Response · 401 Default Response · 403 Default Response · 404 Default Response · 409 Default Response · 422 Default Response · 429 Default Response · 500 Default Response · 503 Default Response
GET /v1/agents/{id}
Get an agent
Parameters
| Name | Type | Description |
|---|---|---|
id (path) required | string | Agent id or agent_ref. |
Responses
200 Default Response · 400 Default Response · 401 Default Response · 403 Default Response · 404 Default Response · 409 Default Response · 422 Default Response · 429 Default Response · 500 Default Response · 503 Default Response
PATCH /v1/agents/{id}
Update an agent
Parameters
| Name | Type | Description |
|---|---|---|
id (path) required | string | Agent id or agent_ref. |
Request body
| Field | Type | Description |
|---|---|---|
display_name | string | null | |
status | "active" | "disabled" |
Responses
200 Default Response · 400 Default Response · 401 Default Response · 403 Default Response · 404 Default Response · 409 Default Response · 422 Default Response · 429 Default Response · 500 Default Response · 503 Default Response
DELETE /v1/agents/{id}
Delete an agent
Parameters
| Name | Type | Description |
|---|---|---|
id (path) required | string | Agent id or agent_ref. |
Responses
204 Default Response · 400 Default Response · 401 Default Response · 403 Default Response · 404 Default Response · 409 Default Response · 422 Default Response · 429 Default Response · 500 Default Response · 503 Default Response
POST /v1/agents/{id}/reset-password
Rotate the long-lived SIP password
Parameters
| Name | Type | Description |
|---|---|---|
id (path) required | string | Agent id or agent_ref. |
Responses
200 Default Response · 400 Default Response · 401 Default Response · 403 Default Response · 404 Default Response · 409 Default Response · 422 Default Response · 429 Default Response · 500 Default Response · 503 Default Response
POST /v1/agents/{id}/softphone-config
Get browser softphone config with short-lived credentials
Returns the WSS URL, ICE/TURN servers and a SIP password that expires (default 1 hour). Call it from your backend and pass the result to the browser; refresh before sip.expires_at.
Parameters
| Name | Type | Description |
|---|---|---|
id (path) required | string | Agent id or agent_ref. |
Responses
200 Default Response · 400 Default Response · 401 Default Response · 403 Default Response · 404 Default Response · 409 Default Response · 422 Default Response · 429 Default Response · 500 Default Response · 503 Default Response
#Carriers
GET /v1/carrier-types
List supported carrier types and their default capabilities
Responses
200 Default Response · 400 Default Response · 401 Default Response · 403 Default Response · 404 Default Response · 409 Default Response · 422 Default Response · 429 Default Response · 500 Default Response · 503 Default Response
GET /v1/carriers
List carriers
Responses
200 Default Response · 400 Default Response · 401 Default Response · 403 Default Response · 404 Default Response · 409 Default Response · 422 Default Response · 429 Default Response · 500 Default Response · 503 Default Response
POST /v1/carriers
Connect a carrier account
Validates the credentials at the carrier, provisions what the carrier needs (SIP connection/trunk, outbound profile, origination settings), stores SIP credentials encrypted and creates the gateway. Health is reported asynchronously via carrier.health.changed.
Request body
| Field | Type | Description |
|---|---|---|
type required | "telnyx" | "twilio" | "generic-sip" | "mock" | |
name required | string | |
settings | object | |
credentials | object | Secret values (API keys, SIP passwords). Encrypted at rest, never returned or logged. |
failover_carrier_id | string (uuid) | null |
Responses
201 Default Response · 400 Default Response · 401 Default Response · 403 Default Response · 404 Default Response · 409 Default Response · 422 Default Response · 429 Default Response · 500 Default Response · 503 Default Response
GET /v1/carriers/{id}
Get a carrier
Parameters
| Name | Type | Description |
|---|---|---|
id (path) required | string | Resource id (UUID). |
Responses
200 Default Response · 400 Default Response · 401 Default Response · 403 Default Response · 404 Default Response · 409 Default Response · 422 Default Response · 429 Default Response · 500 Default Response · 503 Default Response
PATCH /v1/carriers/{id}
Update name, settings or failover
Parameters
| Name | Type | Description |
|---|---|---|
id (path) required | string | Resource id (UUID). |
Request body
| Field | Type | Description |
|---|---|---|
name | string | |
settings | object | |
failover_carrier_id | string (uuid) | null |
Responses
200 Default Response · 400 Default Response · 401 Default Response · 403 Default Response · 404 Default Response · 409 Default Response · 422 Default Response · 429 Default Response · 500 Default Response · 503 Default Response
DELETE /v1/carriers/{id}
Delete a carrier without active numbers
Parameters
| Name | Type | Description |
|---|---|---|
id (path) required | string | Resource id (UUID). |
Responses
204 Default Response · 400 Default Response · 401 Default Response · 403 Default Response · 404 Default Response · 409 Default Response · 422 Default Response · 429 Default Response · 500 Default Response · 503 Default Response
PUT /v1/carriers/{id}/credentials
Replace (rotate) the carrier credentials
The new credentials are validated at the carrier before the old ones are replaced.
Parameters
| Name | Type | Description |
|---|---|---|
id (path) required | string | Resource id (UUID). |
Request body
| Field | Type | Description |
|---|---|---|
credentials required | object |
Responses
200 Default Response · 400 Default Response · 401 Default Response · 403 Default Response · 404 Default Response · 409 Default Response · 422 Default Response · 429 Default Response · 500 Default Response · 503 Default Response
POST /v1/carriers/{id}/revoke
Revoke a carrier
Removes resources we created at the carrier, wipes all stored credentials and removes the gateway. Call history is kept.
Parameters
| Name | Type | Description |
|---|---|---|
id (path) required | string | Resource id (UUID). |
Responses
200 Default Response · 400 Default Response · 401 Default Response · 403 Default Response · 404 Default Response · 409 Default Response · 422 Default Response · 429 Default Response · 500 Default Response · 503 Default Response
POST /v1/carriers/{id}/health-check
Re-apply the gateway and re-check health now
Parameters
| Name | Type | Description |
|---|---|---|
id (path) required | string | Resource id (UUID). |
Responses
202 Default Response · 400 Default Response · 401 Default Response · 403 Default Response · 404 Default Response · 409 Default Response · 422 Default Response · 429 Default Response · 500 Default Response · 503 Default Response
#Numbers
GET /v1/numbers
List phone numbers
Parameters
| Name | Type | Description |
|---|---|---|
carrier_id (query) | string (uuid) |
Responses
200 Default Response · 400 Default Response · 401 Default Response · 403 Default Response · 404 Default Response · 409 Default Response · 422 Default Response · 429 Default Response · 500 Default Response · 503 Default Response
POST /v1/numbers
Add a number you already own at a carrier
Use this for carriers without a number API (generic SIP trunks) or for numbers bought outside the platform. To buy new numbers use number orders.
Request body
| Field | Type | Description |
|---|---|---|
e164 required | string | E.164, e.g. +31201234567 |
carrier_id required | string (uuid) | |
label | string | null | |
inbound_rule_id | string (uuid) | null |
Responses
201 Default Response · 400 Default Response · 401 Default Response · 403 Default Response · 404 Default Response · 409 Default Response · 422 Default Response · 429 Default Response · 500 Default Response · 503 Default Response
GET /v1/numbers/{id}
Get a number (by id or E.164)
Parameters
| Name | Type | Description |
|---|---|---|
id (path) required | string | Resource id (UUID). |
Responses
200 Default Response · 400 Default Response · 401 Default Response · 403 Default Response · 404 Default Response · 409 Default Response · 422 Default Response · 429 Default Response · 500 Default Response · 503 Default Response
PATCH /v1/numbers/{id}
Set label or inbound rule
Parameters
| Name | Type | Description |
|---|---|---|
id (path) required | string | Resource id (UUID). |
Request body
| Field | Type | Description |
|---|---|---|
label | string | null | |
inbound_rule_id | string (uuid) | null |
Responses
200 Default Response · 400 Default Response · 401 Default Response · 403 Default Response · 404 Default Response · 409 Default Response · 422 Default Response · 429 Default Response · 500 Default Response · 503 Default Response
DELETE /v1/numbers/{id}
Release a number
Releases the number at the carrier when the carrier supports it, and removes it from routing. Irreversible.
Parameters
| Name | Type | Description |
|---|---|---|
id (path) required | string | Resource id (UUID). |
Responses
200 Default Response · 400 Default Response · 401 Default Response · 403 Default Response · 404 Default Response · 409 Default Response · 422 Default Response · 429 Default Response · 500 Default Response · 503 Default Response
GET /v1/available-numbers
Search numbers you can order at a carrier
Parameters
| Name | Type | Description |
|---|---|---|
carrier_id (query) required | string (uuid) | |
country (query) required | string | |
number_type (query) | "local" | "mobile" | "toll_free" | "national" | |
contains (query) | string | |
locality (query) | string | |
limit (query) | integer |
Responses
200 Default Response · 400 Default Response · 401 Default Response · 403 Default Response · 404 Default Response · 409 Default Response · 422 Default Response · 429 Default Response · 500 Default Response · 503 Default Response
GET /v1/regulatory-requirements
What a carrier needs before it issues numbers of this country/type
Parameters
| Name | Type | Description |
|---|---|---|
carrier_id (query) required | string (uuid) | |
country (query) required | string | |
number_type (query) | "local" | "mobile" | "toll_free" | "national" |
Responses
200 Default Response · 400 Default Response · 401 Default Response · 403 Default Response · 404 Default Response · 409 Default Response · 422 Default Response · 429 Default Response · 500 Default Response · 503 Default Response
GET /v1/documents
List documents
Responses
200 Default Response · 400 Default Response · 401 Default Response · 403 Default Response · 404 Default Response · 409 Default Response · 422 Default Response · 429 Default Response · 500 Default Response · 503 Default Response
POST /v1/documents
Upload a regulatory document (PDF, JPEG, PNG; max 10 MB)
Request body
| Field | Type | Description |
|---|---|---|
filename required | string | |
content_type required | "application/pdf" | "image/jpeg" | "image/png" | |
content_base64 required | string | File content, base64-encoded. Max 10 MB decoded. |
Responses
201 Default Response · 400 Default Response · 401 Default Response · 403 Default Response · 404 Default Response · 409 Default Response · 422 Default Response · 429 Default Response · 500 Default Response · 503 Default Response
GET /v1/documents/{id}
Get a document
Parameters
| Name | Type | Description |
|---|---|---|
id (path) required | string | Resource id (UUID). |
Responses
200 Default Response · 400 Default Response · 401 Default Response · 403 Default Response · 404 Default Response · 409 Default Response · 422 Default Response · 429 Default Response · 500 Default Response · 503 Default Response
DELETE /v1/documents/{id}
Delete a document not used by a submitted group
Parameters
| Name | Type | Description |
|---|---|---|
id (path) required | string | Resource id (UUID). |
Responses
204 Default Response · 400 Default Response · 401 Default Response · 403 Default Response · 404 Default Response · 409 Default Response · 422 Default Response · 429 Default Response · 500 Default Response · 503 Default Response
GET /v1/requirement-groups
List requirement groups
Responses
200 Default Response · 400 Default Response · 401 Default Response · 403 Default Response · 404 Default Response · 409 Default Response · 422 Default Response · 429 Default Response · 500 Default Response · 503 Default Response
POST /v1/requirement-groups
Collect regulatory information for a country/number type
Items are keyed by the key from GET /v1/regulatory-requirements. Missing items can be added later with PATCH; submit when complete.
Request body
| Field | Type | Description |
|---|---|---|
carrier_id required | string (uuid) | |
country required | string | |
number_type required | "local" | "mobile" | "toll_free" | "national" | |
customer_reference | string | null | |
items | object[] |
Responses
201 Default Response · 400 Default Response · 401 Default Response · 403 Default Response · 404 Default Response · 409 Default Response · 422 Default Response · 429 Default Response · 500 Default Response · 503 Default Response
GET /v1/requirement-groups/{id}
Get a requirement group
Parameters
| Name | Type | Description |
|---|---|---|
id (path) required | string | Resource id (UUID). |
Responses
200 Default Response · 400 Default Response · 401 Default Response · 403 Default Response · 404 Default Response · 409 Default Response · 422 Default Response · 429 Default Response · 500 Default Response · 503 Default Response
PATCH /v1/requirement-groups/{id}
Provide or correct items (draft or rejected groups)
Parameters
| Name | Type | Description |
|---|---|---|
id (path) required | string | Resource id (UUID). |
Request body
| Field | Type | Description |
|---|---|---|
items required | object[] |
Responses
200 Default Response · 400 Default Response · 401 Default Response · 403 Default Response · 404 Default Response · 409 Default Response · 422 Default Response · 429 Default Response · 500 Default Response · 503 Default Response
POST /v1/requirement-groups/{id}/submit
Submit for review at the carrier
Uploads the documents to the carrier and submits. Orders waiting for this group continue automatically. Follow progress with number.requirements.updated.
Parameters
| Name | Type | Description |
|---|---|---|
id (path) required | string | Resource id (UUID). |
Responses
200 Default Response · 400 Default Response · 401 Default Response · 403 Default Response · 404 Default Response · 409 Default Response · 422 Default Response · 429 Default Response · 500 Default Response · 503 Default Response
GET /v1/number-orders
List number orders
Responses
200 Default Response · 400 Default Response · 401 Default Response · 403 Default Response · 404 Default Response · 409 Default Response · 422 Default Response · 429 Default Response · 500 Default Response · 503 Default Response
POST /v1/number-orders
Order numbers
Status follows the carrier: completed creates the numbers (active, usable as caller ID and DID). requirements_needed means attach a requirement group (POST /v1/number-orders/{id}/requirement-group) or create one with the same country/type and submit it. Follow number.order.updated events.
Request body
| Field | Type | Description |
|---|---|---|
carrier_id required | string (uuid) | |
numbers required | string[] | E.164 numbers from GET /v1/available-numbers. |
requirement_group_id | string (uuid) | null | Required up front for carriers with synchronous ordering; otherwise attach later. |
customer_reference | string | null | |
label | string | null | Applied to the numbers when they become active. |
inbound_rule_id | string (uuid) | null | Applied to the numbers when they become active. |
Responses
201 Default Response · 400 Default Response · 401 Default Response · 403 Default Response · 404 Default Response · 409 Default Response · 422 Default Response · 429 Default Response · 500 Default Response · 503 Default Response
GET /v1/number-orders/{id}
Get a number order
Parameters
| Name | Type | Description |
|---|---|---|
id (path) required | string | Resource id (UUID). |
Responses
200 Default Response · 400 Default Response · 401 Default Response · 403 Default Response · 404 Default Response · 409 Default Response · 422 Default Response · 429 Default Response · 500 Default Response · 503 Default Response
POST /v1/number-orders/{id}/requirement-group
Attach a requirement group to an order waiting for requirements
Parameters
| Name | Type | Description |
|---|---|---|
id (path) required | string | Resource id (UUID). |
Request body
| Field | Type | Description |
|---|---|---|
requirement_group_id required | string (uuid) |
Responses
200 Default Response · 400 Default Response · 401 Default Response · 403 Default Response · 404 Default Response · 409 Default Response · 422 Default Response · 429 Default Response · 500 Default Response · 503 Default Response
POST /v1/numbers/sync
Import numbers you already own at a carrier
Request body
| Field | Type | Description |
|---|---|---|
carrier_id required | string (uuid) |
Responses
200 Default Response · 400 Default Response · 401 Default Response · 403 Default Response · 404 Default Response · 409 Default Response · 422 Default Response · 429 Default Response · 500 Default Response · 503 Default Response
#Routing
GET /v1/inbound-rules
List inbound rules
Responses
200 Default Response · 400 Default Response · 401 Default Response · 403 Default Response · 404 Default Response · 409 Default Response · 422 Default Response · 429 Default Response · 500 Default Response · 503 Default Response
POST /v1/inbound-rules
Create an inbound rule
Request body
| Field | Type | Description |
|---|---|---|
name required | string | |
target required | object | object | object | object | Where inbound calls go. |
Responses
201 Default Response · 400 Default Response · 401 Default Response · 403 Default Response · 404 Default Response · 409 Default Response · 422 Default Response · 429 Default Response · 500 Default Response · 503 Default Response
GET /v1/inbound-rules/{id}
Get an inbound rule
Parameters
| Name | Type | Description |
|---|---|---|
id (path) required | string | Resource id (UUID). |
Responses
200 Default Response · 400 Default Response · 401 Default Response · 403 Default Response · 404 Default Response · 409 Default Response · 422 Default Response · 429 Default Response · 500 Default Response · 503 Default Response
PUT /v1/inbound-rules/{id}
Replace an inbound rule
Parameters
| Name | Type | Description |
|---|---|---|
id (path) required | string | Resource id (UUID). |
Request body
| Field | Type | Description |
|---|---|---|
name required | string | |
target required | object | object | object | object | Where inbound calls go. |
Responses
200 Default Response · 400 Default Response · 401 Default Response · 403 Default Response · 404 Default Response · 409 Default Response · 422 Default Response · 429 Default Response · 500 Default Response · 503 Default Response
DELETE /v1/inbound-rules/{id}
Delete an inbound rule not used by any number
Parameters
| Name | Type | Description |
|---|---|---|
id (path) required | string | Resource id (UUID). |
Responses
204 Default Response · 400 Default Response · 401 Default Response · 403 Default Response · 404 Default Response · 409 Default Response · 422 Default Response · 429 Default Response · 500 Default Response · 503 Default Response
GET /v1/ring-groups
List ring groups
Responses
200 Default Response · 400 Default Response · 401 Default Response · 403 Default Response · 404 Default Response · 409 Default Response · 422 Default Response · 429 Default Response · 500 Default Response · 503 Default Response
POST /v1/ring-groups
Create a ring group
Request body
| Field | Type | Description |
|---|---|---|
name required | string | |
strategy | "simultaneous" | "sequential" | |
agent_ids required | string (uuid)[] | |
ring_timeout_seconds | integer |
Responses
201 Default Response · 400 Default Response · 401 Default Response · 403 Default Response · 404 Default Response · 409 Default Response · 422 Default Response · 429 Default Response · 500 Default Response · 503 Default Response
GET /v1/ring-groups/{id}
Get a ring group
Parameters
| Name | Type | Description |
|---|---|---|
id (path) required | string | Resource id (UUID). |
Responses
200 Default Response · 400 Default Response · 401 Default Response · 403 Default Response · 404 Default Response · 409 Default Response · 422 Default Response · 429 Default Response · 500 Default Response · 503 Default Response
PUT /v1/ring-groups/{id}
Replace a ring group
Parameters
| Name | Type | Description |
|---|---|---|
id (path) required | string | Resource id (UUID). |
Request body
| Field | Type | Description |
|---|---|---|
name required | string | |
strategy | "simultaneous" | "sequential" | |
agent_ids required | string (uuid)[] | |
ring_timeout_seconds | integer |
Responses
200 Default Response · 400 Default Response · 401 Default Response · 403 Default Response · 404 Default Response · 409 Default Response · 422 Default Response · 429 Default Response · 500 Default Response · 503 Default Response
DELETE /v1/ring-groups/{id}
Delete a ring group
Parameters
| Name | Type | Description |
|---|---|---|
id (path) required | string | Resource id (UUID). |
Responses
204 Default Response · 400 Default Response · 401 Default Response · 403 Default Response · 404 Default Response · 409 Default Response · 422 Default Response · 429 Default Response · 500 Default Response · 503 Default Response
#Calls
GET /v1/calls
Call log (newest first)
Parameters
| Name | Type | Description |
|---|---|---|
status (query) | string | Comma-separated statuses. |
direction (query) | "outbound" | "inbound" | "internal" | |
agent_id (query) | string (uuid) | |
carrier_id (query) | string (uuid) | |
q (query) | string | Substring of from/to number or external_ref. |
from (query) | string (date-time) | |
to (query) | string (date-time) | |
live (query) | boolean | Only calls in progress. |
limit (query) | integer | |
cursor (query) | string | Opaque cursor from next_cursor of the previous page. |
Responses
200 Default Response · 400 Default Response · 401 Default Response · 403 Default Response · 404 Default Response · 409 Default Response · 422 Default Response · 429 Default Response · 500 Default Response · 503 Default Response
POST /v1/calls
Click-to-call
Rings the agent first; when the agent answers, dials to through the carrier of caller_id and connects both. Returns immediately with status initiated; follow progress with call.* events or GET /v1/calls/{id}. Send an Idempotency-Key header to make retries safe.
Request body
| Field | Type | Description |
|---|---|---|
agent required | string | agent_ref or agent id. The agent must be registered; their phone rings first. |
to required | string | Destination in E.164, e.g. +31612345678. |
caller_id | string,null | One of your active numbers (E.164). The carrier of this number places the call. Defaults to the workspace default caller ID. |
external_ref | string | null | Your id for this call (e.g. CRM activity id). Searchable. |
metadata | object | |
record | boolean | Override the workspace recording policy for this call. |
ring_timeout_seconds | integer | How long the agent phone rings (default 30). |
Responses
201 Default Response · 400 Default Response · 401 Default Response · 403 Default Response · 404 Default Response · 409 Default Response · 422 Default Response · 429 Default Response · 500 Default Response · 503 Default Response
GET /v1/calls/export.csv
Export the call log as CSV (same filters as the list)
Parameters
| Name | Type | Description |
|---|---|---|
status (query) | string | Comma-separated statuses. |
direction (query) | "outbound" | "inbound" | "internal" | |
agent_id (query) | string (uuid) | |
carrier_id (query) | string (uuid) | |
q (query) | string | Substring of from/to number or external_ref. |
from (query) | string (date-time) | |
to (query) | string (date-time) | |
live (query) | boolean | Only calls in progress. |
Responses
200 Default Response
GET /v1/calls/{id}
Get a call with its full event timeline
Parameters
| Name | Type | Description |
|---|---|---|
id (path) required | string | Resource id (UUID). |
Responses
200 Default Response · 400 Default Response · 401 Default Response · 403 Default Response · 404 Default Response · 409 Default Response · 422 Default Response · 429 Default Response · 500 Default Response · 503 Default Response
POST /v1/calls/{id}/hangup
Hang up all legs
Parameters
| Name | Type | Description |
|---|---|---|
id (path) required | string | Resource id (UUID). |
Responses
200 Default Response · 400 Default Response · 401 Default Response · 403 Default Response · 404 Default Response · 409 Default Response · 422 Default Response · 429 Default Response · 500 Default Response · 503 Default Response
POST /v1/calls/{id}/hold
Put the remote party on hold (music)
Parameters
| Name | Type | Description |
|---|---|---|
id (path) required | string | Resource id (UUID). |
Responses
200 Default Response · 400 Default Response · 401 Default Response · 403 Default Response · 404 Default Response · 409 Default Response · 422 Default Response · 429 Default Response · 500 Default Response · 503 Default Response
POST /v1/calls/{id}/unhold
Resume a held call
Parameters
| Name | Type | Description |
|---|---|---|
id (path) required | string | Resource id (UUID). |
Responses
200 Default Response · 400 Default Response · 401 Default Response · 403 Default Response · 404 Default Response · 409 Default Response · 422 Default Response · 429 Default Response · 500 Default Response · 503 Default Response
POST /v1/calls/{id}/dtmf
Send DTMF digits to the remote party
Parameters
| Name | Type | Description |
|---|---|---|
id (path) required | string | Resource id (UUID). |
Request body
| Field | Type | Description |
|---|---|---|
digits required | string |
Responses
200 Default Response · 400 Default Response · 401 Default Response · 403 Default Response · 404 Default Response · 409 Default Response · 422 Default Response · 429 Default Response · 500 Default Response · 503 Default Response
POST /v1/calls/{id}/transfer
Blind or attended transfer
Blind: the remote party is moved to another agent or number and the current agent is released. Attended: first place a consultation call (e.g. POST /v1/calls), then connect the two remote parties.
Parameters
| Name | Type | Description |
|---|---|---|
id (path) required | string | Resource id (UUID). |
Request body
Responses
200 Default Response · 400 Default Response · 401 Default Response · 403 Default Response · 404 Default Response · 409 Default Response · 422 Default Response · 429 Default Response · 500 Default Response · 503 Default Response
GET /v1/calls/{id}/recording
Signed playback URL for the call recording (valid 15 minutes)
Parameters
| Name | Type | Description |
|---|---|---|
id (path) required | string | Resource id (UUID). |
Responses
200 Default Response · 400 Default Response · 401 Default Response · 403 Default Response · 404 Default Response · 409 Default Response · 422 Default Response · 429 Default Response · 500 Default Response · 503 Default Response
DELETE /v1/calls/{id}/recording
Delete the recording now (GDPR erasure)
Parameters
| Name | Type | Description |
|---|---|---|
id (path) required | string | Resource id (UUID). |
Responses
204 Default Response · 400 Default Response · 401 Default Response · 403 Default Response · 404 Default Response · 409 Default Response · 422 Default Response · 429 Default Response · 500 Default Response · 503 Default Response
#Webhooks
GET /v1/webhook-endpoints
List webhook endpoints
Responses
200 Default Response · 400 Default Response · 401 Default Response · 403 Default Response · 404 Default Response · 409 Default Response · 422 Default Response · 429 Default Response · 500 Default Response · 503 Default Response
POST /v1/webhook-endpoints
Create a webhook endpoint
Request body
| Field | Type | Description |
|---|---|---|
url required | string (uri) | |
description | string | null | |
event_types | "call.initiated" | "call.ringing" | "call.answered" | "call.ended" | "call.incoming" | "call.updated" | "recording.ready" | "agent.registered" | "agent.unregistered" | "number.order.updated" | "number.requirements.updated" | "carrier.health.changed" | "usage.alert" | "webhook.test" | "*"[] | |
version | 1 |
Responses
201 Default Response · 400 Default Response · 401 Default Response · 403 Default Response · 404 Default Response · 409 Default Response · 422 Default Response · 429 Default Response · 500 Default Response · 503 Default Response
GET /v1/webhook-endpoints/{id}
Get a webhook endpoint
Parameters
| Name | Type | Description |
|---|---|---|
id (path) required | string | Resource id (UUID). |
Responses
200 Default Response · 400 Default Response · 401 Default Response · 403 Default Response · 404 Default Response · 409 Default Response · 422 Default Response · 429 Default Response · 500 Default Response · 503 Default Response
PATCH /v1/webhook-endpoints/{id}
Update or disable a webhook endpoint
Parameters
| Name | Type | Description |
|---|---|---|
id (path) required | string | Resource id (UUID). |
Request body
| Field | Type | Description |
|---|---|---|
url | string (uri) | |
description | string | null | |
event_types | "call.initiated" | "call.ringing" | "call.answered" | "call.ended" | "call.incoming" | "call.updated" | "recording.ready" | "agent.registered" | "agent.unregistered" | "number.order.updated" | "number.requirements.updated" | "carrier.health.changed" | "usage.alert" | "webhook.test" | "*"[] | |
enabled | boolean |
Responses
200 Default Response · 400 Default Response · 401 Default Response · 403 Default Response · 404 Default Response · 409 Default Response · 422 Default Response · 429 Default Response · 500 Default Response · 503 Default Response
DELETE /v1/webhook-endpoints/{id}
Delete a webhook endpoint
Parameters
| Name | Type | Description |
|---|---|---|
id (path) required | string | Resource id (UUID). |
Responses
204 Default Response · 400 Default Response · 401 Default Response · 403 Default Response · 404 Default Response · 409 Default Response · 422 Default Response · 429 Default Response · 500 Default Response · 503 Default Response
POST /v1/webhook-endpoints/{id}/rotate-secret
Issue a new signing secret (old one stops working immediately)
Parameters
| Name | Type | Description |
|---|---|---|
id (path) required | string | Resource id (UUID). |
Responses
200 Default Response · 400 Default Response · 401 Default Response · 403 Default Response · 404 Default Response · 409 Default Response · 422 Default Response · 429 Default Response · 500 Default Response · 503 Default Response
POST /v1/webhook-endpoints/{id}/test
Send a webhook.test event to this endpoint only
Parameters
| Name | Type | Description |
|---|---|---|
id (path) required | string | Resource id (UUID). |
Responses
202 Default Response · 400 Default Response · 401 Default Response · 403 Default Response · 404 Default Response · 409 Default Response · 422 Default Response · 429 Default Response · 500 Default Response · 503 Default Response
GET /v1/webhook-deliveries
Delivery log (newest first)
Parameters
| Name | Type | Description |
|---|---|---|
limit (query) | integer | |
cursor (query) | string | Opaque cursor from next_cursor of the previous page. |
endpoint_id (query) | string (uuid) | |
event_id (query) | string (uuid) | |
status (query) | "pending" | "retrying" | "succeeded" | "failed" |
Responses
200 Default Response · 400 Default Response · 401 Default Response · 403 Default Response · 404 Default Response · 409 Default Response · 422 Default Response · 429 Default Response · 500 Default Response · 503 Default Response
GET /v1/webhook-deliveries/{id}
Get a delivery
Parameters
| Name | Type | Description |
|---|---|---|
id (path) required | string | Resource id (UUID). |
Responses
200 Default Response · 400 Default Response · 401 Default Response · 403 Default Response · 404 Default Response · 409 Default Response · 422 Default Response · 429 Default Response · 500 Default Response · 503 Default Response
POST /v1/webhook-deliveries/{id}/replay
Deliver the same event again (new delivery, same webhook-id semantics: dedupe on the event id)
Parameters
| Name | Type | Description |
|---|---|---|
id (path) required | string | Resource id (UUID). |
Responses
202 Default Response · 400 Default Response · 401 Default Response · 403 Default Response · 404 Default Response · 409 Default Response · 422 Default Response · 429 Default Response · 500 Default Response · 503 Default Response
#Workspace
GET /v1/workspace
Workspace, limits and settings
Responses
200 Default Response · 400 Default Response · 401 Default Response · 403 Default Response · 404 Default Response · 409 Default Response · 422 Default Response · 429 Default Response · 500 Default Response · 503 Default Response
PATCH /v1/workspace/limits
Update limits and the toll-fraud guard (admin)
Request body
| Field | Type | Description |
|---|---|---|
max_agents | integer | |
max_concurrent_calls | integer | |
max_calls_per_hour | integer | |
max_calls_per_day | integer | |
allowed_destination_countries | string[] | ISO 3166-1 alpha-2. Outbound calls elsewhere are refused. |
blocked_prefixes | string[] | E.164 prefixes always refused (e.g. premium rate). |
outbound_minutes_per_day_alert | integer | Emits usage.alert when exceeded. |
outbound_minutes_per_day_hard_stop | integer | Outbound calls are refused (SPEND_GUARD_TRIPPED) beyond this. |
Responses
200 Default Response · 400 Default Response · 401 Default Response · 403 Default Response · 404 Default Response · 409 Default Response · 422 Default Response · 429 Default Response · 500 Default Response · 503 Default Response
PATCH /v1/workspace/settings
Update recording policy, retention and defaults (admin)
Request body
| Field | Type | Description |
|---|---|---|
recording | object | |
call_log_retention_days | integer | |
softphone_credential_ttl_seconds | integer | |
default_caller_id | string,null |
Responses
200 Default Response · 400 Default Response · 401 Default Response · 403 Default Response · 404 Default Response · 409 Default Response · 422 Default Response · 429 Default Response · 500 Default Response · 503 Default Response
POST /v1/workspace/spend-guard/reset
Resume outbound calling after a spend-guard hard stop (admin)
Review usage first. If today's outbound minutes are still above the hard stop, raise the limit as well, otherwise calls stay refused.
Responses
200 Default Response · 400 Default Response · 401 Default Response · 403 Default Response · 404 Default Response · 409 Default Response · 422 Default Response · 429 Default Response · 500 Default Response · 503 Default Response
GET /v1/usage
Current usage against the limits
Responses
200 Default Response · 400 Default Response · 401 Default Response · 403 Default Response · 404 Default Response · 409 Default Response · 422 Default Response · 429 Default Response · 500 Default Response · 503 Default Response
#Admin
GET /v1/api-keys
List API keys
Responses
200 Default Response · 400 Default Response · 401 Default Response · 403 Default Response · 404 Default Response · 409 Default Response · 422 Default Response · 429 Default Response · 500 Default Response · 503 Default Response
POST /v1/api-keys
Create an API key (the key is returned once)
Request body
| Field | Type | Description |
|---|---|---|
name required | string | |
scopes required | "calls:read" | "calls:write" | "agents:read" | "agents:write" | "numbers:read" | "numbers:write" | "carriers:read" | "carriers:write" | "routing:read" | "routing:write" | "webhooks:read" | "webhooks:write" | "events:read" | "recordings:read" | "admin"[] | |
expires_at | string (date-time) | null |
Responses
201 Default Response · 400 Default Response · 401 Default Response · 403 Default Response · 404 Default Response · 409 Default Response · 422 Default Response · 429 Default Response · 500 Default Response · 503 Default Response
POST /v1/api-keys/{id}/rotate
Replace a key: new secret, same name/scopes; the old key stops working now
Parameters
| Name | Type | Description |
|---|---|---|
id (path) required | string | Resource id (UUID). |
Responses
200 Default Response · 400 Default Response · 401 Default Response · 403 Default Response · 404 Default Response · 409 Default Response · 422 Default Response · 429 Default Response · 500 Default Response · 503 Default Response
DELETE /v1/api-keys/{id}
Revoke an API key
Parameters
| Name | Type | Description |
|---|---|---|
id (path) required | string | Resource id (UUID). |
Responses
200 Default Response · 400 Default Response · 401 Default Response · 403 Default Response · 404 Default Response · 409 Default Response · 422 Default Response · 429 Default Response · 500 Default Response · 503 Default Response
GET /v1/audit-log
Audit log of admin and configuration actions (newest first)
Parameters
| Name | Type | Description |
|---|---|---|
limit (query) | integer | |
cursor (query) | string | Opaque cursor from next_cursor of the previous page. |
action (query) | string | |
target_id (query) | string |
Responses
200 Default Response · 400 Default Response · 401 Default Response · 403 Default Response · 404 Default Response · 409 Default Response · 422 Default Response · 429 Default Response · 500 Default Response · 503 Default Response
#Events
GET /v1/events
List events (newest first)
Parameters
| Name | Type | Description |
|---|---|---|
limit (query) | integer | |
cursor (query) | string | Opaque cursor from next_cursor of the previous page. |
type (query) | string | |
call_id (query) | string (uuid) |
Responses
200 Default Response · 400 Default Response · 401 Default Response · 403 Default Response · 404 Default Response · 409 Default Response · 422 Default Response · 429 Default Response · 500 Default Response · 503 Default Response
GET /v1/events/{id}
Get an event
Parameters
| Name | Type | Description |
|---|---|---|
id (path) required | string | Resource id (UUID). |
Responses
200 Default Response · 400 Default Response · 401 Default Response · 403 Default Response · 404 Default Response · 409 Default Response · 422 Default Response · 429 Default Response · 500 Default Response · 503 Default Response
GET /v1/events/stream
Live event stream (Server-Sent Events)
Each event is sent as event: <type> + data: <envelope JSON>. Filter with types=call.*,agent.registered. A comment line is sent every 15 s as keep-alive.
Parameters
| Name | Type | Description |
|---|---|---|
types (query) | string | Comma-separated event types; "call.*" style prefixes allowed. |
Responses
200 Default Response