Skip to main content

​
Get Started in 5 Minutes

This guide will help you make your first AI phone call.
1

Sign In

Sign in at topcalls.ai. New to TopCalls? Book a call and we set up your account.
2

Get Your API Key

Once logged in, navigate to Settings > API Keys and create a new key. Copy it for the next step.
3

Make Your First Call

Use the example below to trigger your first AI phone call. Replace YOUR_API_KEY with your actual key.

​
Example: Simple Appointment Reminder

curl -X POST https://api.topcalls.ai/v1/calls \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+14155551234",
    "from_number": "+18005551234",
    "task": "You are Rachel, a friendly appointment coordinator. Call to confirm John's appointment tomorrow at 3 PM. Be warm, professional, and brief. If they need to reschedule, ask for their preferred time.",
    "voice": "alloy",
    "mode": "realtime"
  }'

​
Response

{
  "call_id": "564d4fd4-03bc-400a-abe0-05540fbeff88",
  "status": "queued"
}
The call will be placed within seconds. Make sure the phone_number is a number you can answer for testing.from_number is the caller ID the recipient sees. It must be a phone number provisioned for your TopCalls account. Provision one in your dashboard before making calls; if you omit the field, TopCalls falls back to a default sender that is not guaranteed to be the right caller ID for your traffic.

​
What Happens Next?

  1. Call is Queued: The system validates your request and queues the call
  2. Call Connects: Within a few seconds, the recipient receives the call
  3. AI Conversation: The AI agent speaks naturally, handles responses, and completes the task
  4. Call Completes: After the call ends, you receive a webhook (if configured) with the transcript and summary

​
Check Call Status

Use the call_id from the response to check the status: 
curl https://api.topcalls.ai/v1/calls/564d4fd4-03bc-400a-abe0-05540fbeff88 \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Next Steps

Customize Your Agent

Control your agent’s personality, voice, and behavior.

Setup Webhooks

Receive real-time events when calls start, end, or fail.

Explore Use Cases

See real-world examples for appointments, support, sales, and collections.

API Reference

Complete REST API documentation with interactive examples.

​
Need Help?