Skip to main content
When you create a call, you can pass a returns object that describes the data you want out of the conversation. After the call ends, CallingBox reads the transcript and extracts those fields into structured JSON.

​
Defining a schema

Each key in returns is a field name. Each value is a type hint: "boolean", "string", or "number". 
{
  "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",
    "reason": "string"
  }
}

​
Reading the result

Once the call finishes and extraction completes, the result field on the call object has the extracted data: 
{
  "result": {
    "confirmed": true,
    "reschedule_to": null,
    "reason": null
  },
  "result_status": "completed"
}
Fields that didn’t come up in the conversation come back as null.

​
Result statuses

Extraction is a separate step that runs after the call ends. Track it with result_status:
StatusWhat it means
pendingStill extracting
completedDone; data is in result
failedExtraction broke; reason is in result_error

​
When extraction doesn’t run

If the call ends without a real conversation (no answer, voicemail, busy), no extraction runs. All return fields come back as null and result_status stays pending. If you didn’t pass a returns schema at all, the result field is null.

​
Tips

  • Keep schemas flat. One level of keys with simple types works best.
  • Use descriptive field names. reschedule_to extracts better than field_2.
  • One goal per call. The more focused the prompt, the more accurate the extraction.

Calls

All the request fields for creating calls.

Delivery

Polling vs webhooks for getting results.

Call object

Every field on the call response.