curl --request POST \
--url https://api.ryvo.so/v1/calls \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"agent_id": "4d0f3c2a-6b7e-4a1c-9f2d-1e2b3c4d5e6f",
"to": "+5215555550100"
}
'{
"id": "call_conv_01abcdef",
"agent_id": "4d0f3c2a-6b7e-4a1c-9f2d-1e2b3c4d5e6f",
"to": "+5215555550100",
"status": "initiated",
"created_at": "2026-04-30T18:32:11.123Z"
}{
"error": "unauthorized",
"message": "Invalid or revoked API key.",
"request_id": "f0c0a9d2-8b1e-4d8a-9c2f-6e5b7a1d2c3b"
}{
"error": "unauthorized",
"message": "Invalid or revoked API key.",
"request_id": "f0c0a9d2-8b1e-4d8a-9c2f-6e5b7a1d2c3b"
}{
"error": "unauthorized",
"message": "Invalid or revoked API key.",
"request_id": "f0c0a9d2-8b1e-4d8a-9c2f-6e5b7a1d2c3b",
"primary_reason": "wallet",
"reasons": [
"wallet",
"agent:pausado"
]
}{
"error": "unauthorized",
"message": "Invalid or revoked API key.",
"request_id": "f0c0a9d2-8b1e-4d8a-9c2f-6e5b7a1d2c3b"
}{
"error": "unauthorized",
"message": "Invalid or revoked API key.",
"request_id": "f0c0a9d2-8b1e-4d8a-9c2f-6e5b7a1d2c3b"
}{
"error": "unauthorized",
"message": "Invalid or revoked API key.",
"request_id": "f0c0a9d2-8b1e-4d8a-9c2f-6e5b7a1d2c3b",
"primary_reason": "wallet",
"reasons": [
"wallet",
"agent:pausado"
]
}{
"error": "rate_limit_exceeded",
"message": "Rate limit exceeded. Retry in 32s (see the Retry-After header).",
"request_id": "f0c0a9d2-8b1e-4d8a-9c2f-6e5b7a1d2c3b"
}{
"error": "unauthorized",
"message": "Invalid or revoked API key.",
"request_id": "f0c0a9d2-8b1e-4d8a-9c2f-6e5b7a1d2c3b"
}{
"error": "unauthorized",
"message": "Invalid or revoked API key.",
"request_id": "f0c0a9d2-8b1e-4d8a-9c2f-6e5b7a1d2c3b"
}Trigger an outbound call
Starts an outbound call from one of your agents to a number in E.164 format. The call is charged to your wallet when it ends (not when it is triggered) at your plan’s per-minute voice rate, prorated by the second. The API is available from the Starter plan up.
This endpoint dials with agents on the ElevenLabs runtime. agent_id
accepts the Ryvo uuid of the agent (as listed by GET /v1/agents) or
its ElevenLabs id (agent_...). Engine agents cannot be dialed by API
yet.
If your wallet is empty, your subscription lapsed or the agent is
paused, the request answers 402 or 422 and the call is not
placed.
This endpoint has its own per-IP limit of 10 requests per minute. To
avoid duplicates on retries, send an Idempotency-Key header.
curl --request POST \
--url https://api.ryvo.so/v1/calls \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"agent_id": "4d0f3c2a-6b7e-4a1c-9f2d-1e2b3c4d5e6f",
"to": "+5215555550100"
}
'{
"id": "call_conv_01abcdef",
"agent_id": "4d0f3c2a-6b7e-4a1c-9f2d-1e2b3c4d5e6f",
"to": "+5215555550100",
"status": "initiated",
"created_at": "2026-04-30T18:32:11.123Z"
}{
"error": "unauthorized",
"message": "Invalid or revoked API key.",
"request_id": "f0c0a9d2-8b1e-4d8a-9c2f-6e5b7a1d2c3b"
}{
"error": "unauthorized",
"message": "Invalid or revoked API key.",
"request_id": "f0c0a9d2-8b1e-4d8a-9c2f-6e5b7a1d2c3b"
}{
"error": "unauthorized",
"message": "Invalid or revoked API key.",
"request_id": "f0c0a9d2-8b1e-4d8a-9c2f-6e5b7a1d2c3b",
"primary_reason": "wallet",
"reasons": [
"wallet",
"agent:pausado"
]
}{
"error": "unauthorized",
"message": "Invalid or revoked API key.",
"request_id": "f0c0a9d2-8b1e-4d8a-9c2f-6e5b7a1d2c3b"
}{
"error": "unauthorized",
"message": "Invalid or revoked API key.",
"request_id": "f0c0a9d2-8b1e-4d8a-9c2f-6e5b7a1d2c3b"
}{
"error": "unauthorized",
"message": "Invalid or revoked API key.",
"request_id": "f0c0a9d2-8b1e-4d8a-9c2f-6e5b7a1d2c3b",
"primary_reason": "wallet",
"reasons": [
"wallet",
"agent:pausado"
]
}{
"error": "rate_limit_exceeded",
"message": "Rate limit exceeded. Retry in 32s (see the Retry-After header).",
"request_id": "f0c0a9d2-8b1e-4d8a-9c2f-6e5b7a1d2c3b"
}{
"error": "unauthorized",
"message": "Invalid or revoked API key.",
"request_id": "f0c0a9d2-8b1e-4d8a-9c2f-6e5b7a1d2c3b"
}{
"error": "unauthorized",
"message": "Invalid or revoked API key.",
"request_id": "f0c0a9d2-8b1e-4d8a-9c2f-6e5b7a1d2c3b"
}Authorizations
A Bearer token. Create keys in the portal under Settings > API keys
(https://app.ryvo.so/developers). The token has the form
ryvo_live_<64 hex characters> and is shown once.
Header: Authorization: Bearer ryvo_live_...
Headers
A unique identifier (1 to 255 printable ASCII characters) so that
retries of the same request return the same response without
placing a second call. Cached for 24 hours. Reusing the key with
a different body returns 409 idempotency_conflict.
255"lead-abc-2026-04-30-001"
Body
The Ryvo uuid of the agent, or its ElevenLabs id (agent_...). Must belong to your account.
"4d0f3c2a-6b7e-4a1c-9f2d-1e2b3c4d5e6f"
The destination number in E.164 format.
^\+[1-9]\d{6,14}$"+5215555550100"
Optional variables passed to the agent as dynamic variables. At most 5 KB. Keys up to 64 characters; values must be strings (up to 2000 characters), numbers, booleans or null.
Show child attributes
Show child attributes
{
"lead_name": "Juan García",
"deal_id": "OPP-2026-0042"
}
Response
The call was placed.
The call handle (call_<conversation_id>). Accepted by GET /v1/calls/{id}.
"call_conv_01abcdef"
The agent_id you sent.
"4d0f3c2a-6b7e-4a1c-9f2d-1e2b3c4d5e6f"
"+5215555550100"
To learn how the call ended, subscribe to call.completed and call.failed webhooks or poll GET /v1/calls/{id}.
initiated "2026-04-30T18:32:11.123Z"