Skip to main content
You create calls with POST /v1/calls. Here’s what you can pass in and how to think about each field.

​
Request fields

FieldTypeRequiredDefaultDescription
tostringYes—Phone number to call, E.164 format (e.g. +15551234567)
promptstringNo"Hello from CallingBox."What the AI should do on the call
contextobjectNo{}Background info the AI can reference mid-conversation
returnsobjectNo{}Schema for structured data extraction
languagestringNo"en"Language code
from_numberstringNoorg defaultCaller ID, E.164 format
webhook_urlstringNo—Where to POST the result when the call finishes (details)

​
The prompt field

Think of the prompt like a briefing for a human caller. What’s the goal? What tone? What should they find out? 
{
  "prompt": "Call to confirm a dental appointment tomorrow at 2pm. Be polite and professional. If the patient wants to reschedule, ask for their preferred date and time."
}
One goal per call. A prompt that tries to confirm an appointment, collect feedback, and upsell something will do all three badly. Split it into separate calls.

​
The context field

Context is background info the AI has access to during the conversation. It doesn’t go into the prompt directly — the AI just knows it and can bring it up when relevant. 
{
  "context": {
    "patient": "Maria Lopez",
    "doctor": "Dr. Chen",
    "appointment_date": "2025-04-16",
    "appointment_time": "2:00 PM"
  }
}

​
The language field

English (en) is fully supported. Spanish (es) is in beta.
Only US phone numbers are supported right now. International calling is on the roadmap.

​
Examples

​
Appointment confirmation

{
  "to": "+15551234567",
  "prompt": "Confirm dental appointment tomorrow at 2pm for the patient",
  "context": { "patient": "Maria Lopez", "doctor": "Dr. Chen" },
  "returns": { "confirmed": "boolean", "reschedule_to": "string" }
}

​
Lead qualification

{
  "to": "+15559876543",
  "prompt": "Qualify this lead for the enterprise plan. Ask about team size, current tools, and timeline.",
  "context": { "lead": "Sarah Kim", "company": "Acme Corp" },
  "returns": { "qualified": "boolean", "team_size": "number", "timeline": "string" }
}

​
Payment collection

{
  "to": "+15554567890",
  "prompt": "Follow up on overdue balance. Offer a payment plan if needed.",
  "context": { "customer": "Roberto Méndez", "balance": 4850.00, "days_overdue": 45 },
  "returns": { "commitment": "boolean", "amount": "number", "pay_by": "string" },
  "language": "es"
}

Structured results

How the returns schema and extraction work.

Delivery

Polling vs webhooks for getting results.

Call object

Every field on the call response.