Quickstart Recipes

Six cURL examples for a connected workspace. Replace the example key, IDs, and phone numbers with your own values and check the required permissions before running writes (find your key under Authentication).

Building provider activation? The partner onboarding guide covers referral codes, existing accounts, and email-verified signup with setup scopes. Its verification steps work without an outbound call or SMS.

Base URL: https://www.kaicalls.com/api/v1

Set Up Your Webhook and Receive Calls

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://www.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://www.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, register a webhook subscription. Store the returned secret immediately; KaiCalls uses it to sign each event.

bash
curl -X POST https://www.kaicalls.com/api/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "business_id": "uuid-biz456",
    "webhook_url": "https://partner.example.com/webhooks/kaicalls",
    "events": ["call.received", "call.completed", "sms.received"]
  }'

Make an Outbound Call

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://www.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"
}

Compliance note

The API caller is responsible for TCPA / DNC compliance. KaiCalls skips its built-in compliance checks on API-initiated outbound calls -- you must ensure you have consent to call the number.

Fetch Call Transcripts

Pull full transcripts and AI-generated summaries for recent calls. By default the endpoint looks back 30 days (max 90); pass days to narrow it:

bash
curl "https://www.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://www.kaicalls.com/api/v1/transcripts?agent_id=a1b2c3d4-e5f6-7890-abcd-ef1234567890&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Score and Update a Lead

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://www.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://www.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 (the updated lead record):

json
{
  "id": "f7e6d5c4-b3a2-1098-7654-321fedcba098",
  "name": "Maria Garcia",
  "phone": "+15125551234",
  "email": "maria@example.com",
  "status": "qualified",
  "notes": "Interested in premium package, budget confirmed at $5k",
  "updated_at": "2026-04-18T16:05:00Z"
}

Valid statuses

newcontactedqualifiedconvertedlostunqualifiedspamdo_not_contact

Send an SMS

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://www.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"
}

Phone format

Phone numbers must be in E.164 format: +15125551234 (country code + number, no spaces or dashes).

Validate a Communication Run

Partner systems such as Case Engine can validate a scheduled run before creating it. Use external_ref and per-touch touch_id values so webhook events can be matched back to your own run and touch records.

bash
curl -X POST https://www.kaicalls.com/api/v1/communication-runs/validate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "business_id": "uuid-biz456",
    "external_ref": "ce_run_8f12",
    "touches": [
      {
        "touch_id": "ce_touch_001",
        "channel": "call",
        "target": {
          "phone": "+15125551234",
          "timezone": "America/New_York"
        },
        "scheduled_at": "2026-06-09T19:00:00.000Z",
        "context": { "source": "case-engine" }
      }
    ]
  }'

After validation passes, call POST /communication-runs/preview to inspect the planned touches, then create the run with POST /communication-runs and an Idempotency-Key header.