Single call
Place one outbound call with POST /api/v1/calls — body fields, the recording_enabled toggle, and the recording advisory in the response.
Single call
Place a single outbound call to one number. This is the fastest way to hear an agent live: publish an agent, then dial your own phone.
Prerequisites
The agent must be published (POST /agents/{id}/publish) and you need a
phone_number_id to call from. See Agents and
Phone numbers.
Request
curl -X POST https://api.agoralia.app/api/v1/calls \
-H "X-API-Key: ag_..." \
-H "Content-Type: application/json" \
-d '{
"to_number": "+393408994869",
"agent_id": "AGENT_ID",
"phone_number_id": "NUMBER_ID"
}'| Field | Required | What it is |
|---|---|---|
to_number | yes | Destination in E.164 form (e.g. +14155550123). |
agent_id | yes | A published agent. Unpublished → 422 Agent not synced. |
phone_number_id | yes | The number to call from. No auto-assign on single calls. |
recording_enabled | — | Per-call override. Omitted → use the agent's (compliance-aware) default. false → no audio recorded for this call. Cannot force recording on where a country forbids it. |
metadata | — | Arbitrary key/values. Threaded into the call so {{customer.X}} / {{X}} resolve in the prompt, and returned on the call record. |
Recording
When recording_enabled is false — or the destination country forbids recording — no
audio is captured, but the transcript, summary, and structured data are still produced.
You can never force recording on where a jurisdiction legally forbids it; the call is placed
with recording off in that case.
Response
202 Accepted — the call is queued and ringing. The response includes a recording
advisory describing what will actually happen for this destination.
{
"call_id": "...",
"status": "ringing",
"provider_call_id": "...",
"recording": {
"code": "...",
"message": "...",
"forbidden": false
}
}Read the advisory
The recording advisory tells you whether recording is on, off-by-request, or forbidden
by the destination country — surface it to your user. Full rules in
Compliance.
Get the result
Fetch the finished call (transcript, summary, analysis, recording_url) with
GET /calls/{call_id} or MCP get_call. See
Calls & transcripts.
Idempotency
Pass an Idempotency-Key header to make retries safe — a repeated key with the same body
returns the original response instead of placing a second call.
Next
- Campaigns — call many contacts with a launch gate.
- Calls & transcripts — read what happened.
Knowledge base
Attach a semantic knowledge base to an agent so it can answer from your own facts — add sources from text, Q&A pairs, or URLs.
Campaigns
Create a campaign, add leads, then launch through the deterministic pre-flight gate. Covers settings (country_code, purpose, recording_enabled) and the readiness check.