> ## Documentation Index
> Fetch the complete documentation index at: https://docs.powerdialer.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Scheduled callbacks

> Create, reschedule and cancel callbacks, and reconcile their lifecycle.

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](/guides/contact-lists#create-a-list).
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:

```json theme={null}
{
  "ownerId": "user_synthetic",
  "contactId": 123,
  "scheduledAt": "2030-10-15T14:00:00-04:00",
  "notes": "Follow up at the contact's requested time"
}
```

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:

```json theme={null}
{
  "scheduledAt": "2030-10-16T14:00:00-04:00",
  "notes": "Rescheduled at the contact's request"
}
```

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](/guides/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](/guides/webhooks) instead of treating lifecycle
events as a complete record of current state.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.