Skip to content
Docs

Avoonta API

Send a lead that agreed to be called. An AI agent calls them within seconds, qualifies them, books a time, and tells your system what happened through a signed webhook.

Base URL

https://api.avoonta.com/v1

Every request and response body is JSON (UTF-8). All requests must use HTTPS.

What the API does today

EndpointWhat it doesAuth
POST /v1/ordersCreate a call order for one lead. OrdersAPI key
GET /v1/orders/{order_id}Read one order and its result. OrdersAPI key
GET /v1/ordersList orders, finished ones by default, newest first. OrdersAPI key
GET /v1/meCheck a key: its workspace and whether it is live or test. Workspace and agentsAPI key
GET /v1/agentsList the agents that can take orders. Workspace and agentsAPI key
GET /v1/recordings/{order_id}.mp3Download the call recording. RecordingsAPI key
GET /v1/recordings/{order_id}/linkGet a playable link that works for 15 minutes.API key
GET /v1/walletRead the workspace wallet balance in cents and dollars. Workspace and agentsAPI key
POST /v1/hooks/lead/{token}The no-code trigger URL for forms, Zapier and Make. Trigger URLThe secret token in the URL
POST /mcpJSON-RPC 2.0 endpoint for MCP-compatible AI assistants. Four tools: list agents, read orders, check wallet, place calls. AI tools (MCP)API key
Result webhookWe POST order.completed and order.updated to your URL. WebhooksSigned by us

Quickstart in 3 steps

1. Get an API key and an agent ID

You need two values from your Avoonta workspace:

See Authentication.

2. Send a lead

The consent object is required. Without it the order is refused with 400 consent_required before anything else happens.

curl https://api.avoonta.com/v1/orders \
  -H "Authorization: Bearer av_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: crm_contact_8821" \
  -d '{
    "agent_id": "agt_3f9c2a7b1d0e4c58a6b9e2f1d4c7a0b3",
    "lead": {
      "phone": "+14155550199",
      "first_name": "Daniel",
      "custom_context": "Asked for a solar quote on our website."
    },
    "consent": {
      "opt_in_confirmed": true,
      "consented_at": "2026-10-14T09:00:00Z",
      "source": "https://acme.example/quote-form"
    },
    "webhook_url": "https://crm.example.com/webhooks/avoonta",
    "external_reference_id": "crm_contact_8821"
  }'

You get 202 Accepted right away:

{
  "success": true,
  "order_id": "ord_9b1e0c4d2a7f4e8b9c3d5a6f7e8d9c0b",
  "status": "QUEUED",
  "estimated_dial_seconds": 15,
  "wallet_balance_cents": 4850
}

If it is outside 8am to 8pm where the lead lives, the order is still accepted and waits; estimated_dial_seconds then tells you how long. See Quiet hours.

3. Receive the result webhook

When the order ends, we POST an order.completed event to your webhook_url, signed with the X-Avoonta-Signature header:

{
  "event": "order.completed",
  "order_id": "ord_9b1e0c4d2a7f4e8b9c3d5a6f7e8d9c0b",
  "external_reference_id": "crm_contact_8821",
  "status": "BOOKED",
  "attempt_number": 1,
  "duration_seconds": 134,
  "billed_minutes": 3,
  "charged_cents": 75,
  "qualification": { "qualified": true, "score": 92, "extracted_answers": { "homeowner": "Yes" }, "summary": "Owns his home. Booked a consultation." },
  "appointment": { "booked": true, "start_time": "2026-10-22T14:00:00Z", "calendar_event_id": "e5b1c2…" },
  "recording_url": "https://api.avoonta.com/v1/recordings/ord_9b1e0c4d2a7f4e8b9c3d5a6f7e8d9c0b.mp3",
  "transcript": [ { "role": "agent", "text": "Hi, this is Alex calling from Acme Solar. I'm their virtual AI assistant. …" } ]
}

Verify the signature, then answer with any 2xx within 10 seconds. See Webhooks.

Before you build

There is no sandbox yet. Coming soon Keys that start with av_test_ are accepted, but today they behave exactly like live keys: they ring real phones and charge your wallet. Test with your own phone number.