Skip to main content
The canonical “answer a phone with an AI” flow. You’ll:
  1. Create an agent with a prompt and voice.
  2. Provision (or bring) a phone number and assign the agent as its inbound handler.
  3. Call the number. Observe the call log, transcript, and recording.
Total API calls: four. Total time: under five minutes.

​
1. Create an agent

An agent bundles the prompt, voice, and product tier that will drive the call. See Agents for every configuration field; the minimum is: 
curl -X POST https://api.thunderphone.com/v1/agents \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name":    "Acme Support",
    "prompt":  "You are a friendly support agent for Acme. Help callers with orders and returns. Keep answers short.",
    "voice":   "en-US-James1",
    "product": "spark"
  }'
Save the returned id — you’ll need it in step 2.
Pick spark for simple Q&A with the lowest latency. Upgrade to storm-base-with-ack when your prompt needs deeper reasoning and can tolerate a half-second filler while the model thinks. See product tiers.

​
2. Get a phone number

If you just need something to dial against, provision a demo number from ThunderPhone’s pool: 
curl -X POST https://api.thunderphone.com/v1/phone-numbers \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"area_code": "415"}'
The response includes an id and a number in E.164. Demo numbers start in status="provisioning" and become active within a few seconds — poll GET /v1/phone-numbers/{id} to watch the transition if you care.
For production, skip demo numbers and bring your own numbers via VoIP. Demo numbers are inbound-only and capped in volume.

​
3. Assign the agent

Associate the agent from step 1 with the number’s inbound direction: 
curl -X PATCH https://api.thunderphone.com/v1/phone-numbers/{phone_id} \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"inbound_agent_id": 12}'
That’s it — the number is live. You can also set outbound_agent_id in the same PATCH so the number is ready to call outbound too.

​
4. Take a call

Dial the number from your phone. The agent picks up, introduces itself per your prompt, and the conversation begins. While the call is in flight, it appears in GET /v1/calls with status="in_progress". When it ends, the record updates with end_reason, duration_seconds, billable_minutes, and (eventually) a recording URL and AI grade.

​
5. Inspect the results

Fetch the list of recent calls: 
curl 'https://api.thunderphone.com/v1/calls?limit=5' \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
Grab the transcript: 
curl https://api.thunderphone.com/v1/calls/{call_id}/transcript \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
And the recording URL (short-lived, signed): 
curl https://api.thunderphone.com/v1/calls/{call_id}/audio \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
If you subscribed to the telephony.complete webhook you’ll receive the same data as a POST to your server — see call.complete.

​
Next steps

Dynamic per-call config

Pick a different agent per caller based on the phone number or custom logic in a webhook.

Add tool integrations

Let the agent call your APIs mid-conversation.

Receive call.complete webhooks

Stream each finished call to your CRM / analytics pipeline.

AI grading and issue reports

Score every call automatically and route flagged ones for review.