Skip to main content
Use /scheduled-calls to manage callback records for an attributed contact and an authorized owner. Creating a callback does not initiate a call or add an automatic dialing scheduler.

​
Permissions and ownership

Reads require scheduled_calls:read; writes require scheduled_calls:write. Every write also requires an Idempotency-Key. Reuse that key and the identical request when retrying the same action, and use a new key for the next action. Choose an owner using workspace member lookup. The contact must be visible to your credential. Reads and updates require both a contact attributed to your workspace and a callback owner within your credential’s owner scope. Legacy callbacks without an attributed contact are excluded.

​
Create a callback

Send POST /scheduled-calls with a numeric contact ID and an authorized owner ID:
Replace the example IDs and date with your own values. Success returns 201 and the callback, including its numeric id. An optional phoneNumber must be E.164; when omitted, the contact’s primary number is used. scheduledAt must include Z or an explicit UTC offset. Responses normalize it to UTC and include the contact’s timeZone and timeZoneSource. The API does not infer timezones or enforce calling windows.

​
Find and reschedule callbacks

GET /scheduled-calls/{id} reads one callback. GET /scheduled-calls accepts ownerId, status, from, to, after and limit. The scheduled-time interval includes from and excludes to; when both are supplied, from must precede to. Status values are Pending, Completed, Failed and Cancelled. Collections return {data,nextCursor}. Follow nextCursor using after until it is null; limit defaults to 50 and accepts 1–200. Use PATCH /scheduled-calls/{id} with at least one of scheduledAt, status or notes. Omitted fields stay unchanged; notes: null clears the note. For example:
A callback’s callHistoryId can link it to call history. Explicit status updates are supported, so Completed alone is not proof that a call was placed. Use call evidence to reconcile actual calling activity.

​
Cancel and reconcile

DELETE /scheduled-calls/{id} retains the callback with status Cancelled and returns the updated record. A completed callback cannot be cancelled: both DELETE and PATCH with status: "Cancelled" return 409 scheduled_call_completed. Subscribe to scheduled_call.created, scheduled_call.completed and scheduled_call.cancelled for lifecycle snapshots. Physical deletion through a legacy flow emits scheduled_call.deleted with {id,deleted:true}. These events do not cover every edit: reschedules, notes, Failed status and owner or attribution changes need periodic collection reads. Combine enumeration with webhooks and the change feed instead of treating lifecycle events as a complete record of current state.