Skip to main content
By the end of this page you’ll have created an API key, configured a reusable agent, and placed a real phone call through the CallingBox API. If you want the full Python setup flow (install, number management, polling, error handling), see the Python SDK guide.

​
Prerequisites

  • A CallingBox account. Sign up for free. No credit card required, and you get $5 in credits.
  • A purchased phone number in your organization (see Numbers)
  • A phone number to call
1

Create an API key

Go to API Keys in the dashboard and click Create key. Name it whatever you want and copy the value. It starts with sk_ and you’ll only see it once.
2

Create an outbound agent

The agent is where you define persona, instructions, structured returns, and which phone numbers can be used as caller ID. Swap in a number_id from GET /v1/numbers.
curl -X POST https://api.callingbox.io/v1/agents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Appointment reminders",
    "type": "outbound",
    "instructions": "Confirm dental appointments. Offer to reschedule if needed.",
    "returns": { "confirmed": "boolean", "reschedule_to": "string" },
    "number_ids": ["YOUR_NUMBER_ID"],
    "primary_number_id": "YOUR_NUMBER_ID"
  }'
The response includes the agent’s id. Save it. You’ll reference it on every call dispatch.
3

Dispatch a call

Pass the agent id, the destination number, and any per-call overrides. Everything else comes from the agent.
curl -X POST https://api.callingbox.io/v1/calls \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "YOUR_AGENT_ID",
    "to": "+15551234567",
    "context": { "patient": "Maria Lopez", "doctor": "Dr. Chen" }
  }'
You’ll get back a call object with status: "queued". The phone starts ringing within seconds.
4

Check the result

Poll the call to see where it’s at. Once it’s done, the structured result is in the response.
curl https://api.callingbox.io/v1/calls/CALL_ID \
  -H "Authorization: Bearer YOUR_API_KEY"
Status goes queued → initiated → ringing → in_progress → completed. If nobody picks up, you’ll see no_answer or busy instead.
Using Python? The full SDK guide covers environment-based auth, from_, number purchase, and error handling: Python SDK.
5

(Optional) Add a webhook

Don’t want to poll? Attach a webhook_url to the agent once and it applies to every call that agent handles, or pass webhook_url on the call itself to override for a single call:
curl -X POST https://api.callingbox.io/v1/calls \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "YOUR_AGENT_ID",
    "to": "+15551234567",
    "webhook_url": "https://your-server.com/callingbox-webhook"
  }'
CallingBox POSTs the full call object to your URL when the call finishes. See Webhooks for the full event catalog and signature verification.

​
Next steps

Agents

The reusable primitive. Where persona, returns, tools, and numbers live.

Outbound calls

Every dispatch field and per-call override.

Inbound calls

Let an inbound agent answer your numbers.

Webhooks

Polling vs webhooks for getting results.