API reference

Calls

Place an outbound call with an agent, schedule it, and stop it.

A call request creates an execution: the record of one call, with its status, transcript, costs and telephony details. The request returns as soon as the execution is queued; a worker then dials and runs the conversation. Read the result with the Executions routes or receive it on the agent's webhook.

Both routes need Authorization: Bearer <key>. Errors use the standard body {"error": <status>, "message": "..."}.

Engines and test numbers

Each call runs on an engine. The engine is taken from agent_data.engine, then from the agent's agent_config.engine, then from the platform default (DEFAULT_ENGINE, which is mock unless the operator changes it).

On the mock engine the last four digits of recipient_phone_number choose the outcome.

In a simulated conversation the caller's lines come from agent_data.mock_script, an array of strings. Without it the caller says three stock lines. agent_data.mock_tool_calls scripts function tool calls: [{"turn": 1, "name": "...", "arguments": {...}}]. Keys of agent_data that start with mock_ are never passed to a live engine.

Note: Mock calls run faster than real time by default (MOCK_TIME_SCALE). See Testing without a phone.

Operations

Make a call

POST /call

Queues an outbound call from an agent to one phone number, now or at a scheduled time.

Auth: API key or session token. Role: member and up. When the operator sets REQUIRE_VERIFIED_EMAIL, the login must have a verified email address.

This route accepts an Idempotency-Key header: a retry with the same key and body returns the first response instead of placing a second call. See Idempotency. It is also one of the routes with the lower rate limit; see Rate limits.

retry_config fields and defaults:

A retried call keeps the same execution id.

Request

curl -X POST https://api.sevennadi.si/call \
  -H "Authorization: Bearer vk-0123456789abcdef0123456789abcdef" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: renewal-2026-10-13-asha" \
  -d '{
    "agent_id": "f412f2b1-3493-4458-bcf2-8676cc798edd",
    "recipient_phone_number": "+919876500012",
    "from_phone_number": "+918045550100",
    "user_data": {"name": "Asha"},
    "agent_data": {"engine": "mock", "mock_script": ["Yes, speaking.", "Please renew it. Thank you, bye!"]}
  }'

Response 200 OK

{
  "message": "done",
  "status": "queued",
  "execution_id": "0b6c2c4e-7a55-4b0f-9a07-3d6b1f9f2a11"
}

status in this response is always queued. The execution itself starts as queued, scheduled (when you sent scheduled_at) or rescheduled (when the time falls outside the agent's calling hours). In the last case the response also carries "rescheduled": true and the new scheduled_at. A warnings array is added when the call is allowed but worth a look, for example a number found on a do-not-disturb registry while the account's dnd_check is warn.

Errors

Some problems appear only after the request has been accepted. An account without enough balance gets an execution that ends in balance-low with error_message Insufficient wallet balance. The do-not-call list, the frequency cap and verified numbers are covered in Compliance and Verified numbers.

Stop a call

POST /call/{execution_id}/stop

Stops one call. A call that has not been dialed yet (scheduled, prepared, queued, rescheduled) becomes stopped at once. A call in progress is hung up by its worker shortly after; its transcript and costs up to that point are kept.

Auth: API key or session token. Role: member and up.

Request

curl -X POST https://api.sevennadi.si/call/0b6c2c4e-7a55-4b0f-9a07-3d6b1f9f2a11/stop \
  -H "Authorization: Bearer vk-0123456789abcdef0123456789abcdef"

Response 200 OK

{
  "message": "done",
  "status": "stopped",
  "execution_id": "0b6c2c4e-7a55-4b0f-9a07-3d6b1f9f2a11"
}

For a call in progress the response says stopped before the execution reaches that status. Poll the execution or wait for the webhook to confirm.

Errors

Related

• To stop every waiting call of an agent, use Stop an agent's waiting calls.
• To call a list of contacts, use Batches.
• To test an agent by voice from a browser, see Voice test.