Skip to main content
The Calls API schedules immediate outbound calls and exposes their current state. A call is externally visible and may be billable once accepted.

​
Before creating a call

  • The agent has a published version.
  • The destination uses E.164 format.
  • The workspace allows the destination country and prefix, or has a valid SIP/BYOC route.
  • metadata contains every dynamic variable used by the prompt, or {} when none are required.

​
Lifecycle

  1. Create Call returns a signed call ID.
  2. Get Call shows the current status and eventual result.
  3. List Calls reconciles recent requests after a timeout.
  4. Webhooks notify your system of terminal outcomes without constant polling.

​
Duplicate prevention

The current contract does not publish an idempotency key. Put a stable correlation value in metadata, store the returned call ID, and reconcile recent calls before repeating a timed-out create request. See Reliability and retries.

​
Calls vs. call logs

Use v1 Calls for scheduling-layer status and routing. Use legacy call-log endpoints only when you need fields that do not yet have a v1 equivalent, such as richer analytics. The legacy surface is supported only during the migration window.