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

​
Prerequisites

  • A CallingBox account — sign up for free (no credit card required, you get $10 in credits)
  • 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

Make your first call

Swap in your real API key and a real phone number:
curl -X POST https://api.callingbox.io/v1/calls \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+15551234567",
    "prompt": "Confirm dental appointment tomorrow at 2pm for Maria Lopez",
    "context": { "patient": "Maria Lopez", "doctor": "Dr. Chen" },
    "returns": { "confirmed": "boolean", "reschedule_to": "string" }
  }'
You’ll get back a call object with status: "queued". The phone starts ringing within seconds.
3

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 local editable install, environment-based auth, from_, number purchase, and a runnable example: Python SDK.
4

(Optional) Add a webhook

Don’t want to poll? Pass a webhook_url and CallingBox will POST the result to your server when the call finishes:
curl -X POST https://api.callingbox.io/v1/calls \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+15551234567",
    "prompt": "Confirm appointment tomorrow at 2pm",
    "returns": { "confirmed": "boolean" },
    "webhook_url": "https://your-server.com/callingbox-webhook"
  }'
The webhook includes the full call object as JSON, with headers X-CallingBox-Event: call.completed and X-CallingBox-Call-Id.

​
Next steps

Call flow

What happens between your request and the result.

Calls

Every request field, with examples.

Structured results

Define a returns schema and get typed JSON back.

Delivery

Polling vs webhooks for getting results.