Quickstart Recipes

After creating an account and getting an agent with a phone number, incoming calls are handled by KaiCalls automatically -- your agent answers, qualifies the caller, and logs everything. To pull that data into your own system, start by listing your agents to grab the agent_id:

Step 1 -- List your agents

bash
curl https://kaicalls.com/api/v1/agents \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

json
{
  "agents": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Kai - Acme Contractors",
      "phone_number": "+15125559876",
      "status": "active"
    }
  ]
}

Step 2 -- Fetch recent calls

When calls come in, KaiCalls processes them end to end. You can poll for recent call records:

bash
curl "https://kaicalls.com/api/v1/calls?agent_id=a1b2c3d4-e5f6-7890-abcd-ef1234567890&limit=5" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

json
{
  "calls": [
    {
      "id": "c9d8e7f6-5a4b-3c2d-1e0f-9a8b7c6d5e4f",
      "agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "direction": "inbound",
      "status": "completed",
      "duration": 127,
      "summary": "Caller asked about kitchen remodel pricing. Qualified lead.",
      "created_at": "2026-04-18T14:32:00Z"
    }
  ],
  "has_more": true
}

Step 3 -- Real-time notifications

For real-time push notifications instead of polling, pass a webhook_url when making outbound calls (see Recipe 2). KaiCalls will POST call events to your endpoint as they happen.

Trigger a call from your agent to any phone number. Provide optional context so the agent knows why it is calling:

bash
curl -X POST https://kaicalls.com/api/v1/calls \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "to": "+15125551234",
    "customer_name": "Maria Garcia",
    "context": "Following up on her inquiry about a kitchen remodel estimate.",
    "first_message": "Hi Maria, this is Kai calling from Acme Contractors about your kitchen remodel inquiry."
  }'

Response:

json
{
  "id": "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f90",
  "conversation_id": "conv_7f8e9d0c-1b2a-3c4d-5e6f-7a8b9c0d1e2f",
  "status": "queued",
  "to": "+15125551234",
  "agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2026-04-18T15:10:00Z"
}

Pull full transcripts and AI-generated summaries for recent calls. By default the endpoint returns calls from the last 7 days:

bash
curl "https://kaicalls.com/api/v1/transcripts?limit=3&days=7" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

json
{
  "transcripts": [
    {
      "call_id": "c9d8e7f6-5a4b-3c2d-1e0f-9a8b7c6d5e4f",
      "agent_name": "Kai - Acme Contractors",
      "summary": "Caller asked about kitchen remodel pricing. Qualified lead.",
      "transcript": "Agent: Hi, thanks for calling Acme Contractors...\nCaller: Hi, I'm looking for a quote on a kitchen remodel...",
      "duration": 127,
      "created_at": "2026-04-18T14:32:00Z"
    }
  ],
  "has_more": false
}

Filter by agent

Add agent_id to scope results to a single agent:

bash
curl "https://kaicalls.com/api/v1/transcripts?agent_id=a1b2c3d4-e5f6-7890-abcd-ef1234567890&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Every call that generates a new contact creates a lead automatically. Use the leads endpoints to review and update them.

Step 1 -- List recent leads

bash
curl "https://kaicalls.com/api/v1/leads?status=new&limit=5" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

json
{
  "leads": [
    {
      "id": "f7e6d5c4-b3a2-1098-7654-321fedcba098",
      "name": "Maria Garcia",
      "phone": "+15125551234",
      "email": "maria@example.com",
      "status": "new",
      "source": "inbound_call",
      "created_at": "2026-04-18T14:33:00Z"
    }
  ],
  "has_more": false
}

Step 2 -- Update the lead

After reviewing a lead, update its status and add notes:

bash
curl -X PATCH https://kaicalls.com/api/v1/leads \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "f7e6d5c4-b3a2-1098-7654-321fedcba098",
    "status": "qualified",
    "notes": "Interested in premium package, budget confirmed at $5k"
  }'

Response:

json
{
  "success": true,
  "lead": {
    "id": "f7e6d5c4-b3a2-1098-7654-321fedcba098",
    "status": "qualified",
    "updated_at": "2026-04-18T16:05:00Z"
  }
}

Send a text message from your agent's phone number. The message is delivered via the agent's provisioned messaging service:

bash
curl -X POST https://kaicalls.com/api/v1/sms/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+15125551234",
    "from_agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "message": "Hi Maria, thanks for your call today. Here is a link to our service menu: https://acme.com/services"
  }'

Response:

json
{
  "success": true,
  "message_sid": "SM9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d",
  "to": "+15125551234",
  "from": "messaging_service"
}