Developer docs: Scheduled calls

Scheduled calls

Callbacks the AI places at a set time.

List scheduled calls (callbacks)Link to List scheduled calls (callbacks)

GET/scheduled-calls

Newest scheduledAt first by default.

Scope: calls:read

Query parameters

pagenumber: Default: 1
limitnumber: Default: 20 · Max 100
updatedSincestring: ISO 8601: only records changed at or after this instant. With sort=updatedAt&order=asc this is an incremental sync cursor
orderstring: One of: asc, desc · Default: desc
statusstring: One of: pending, queued, calling, completed, failed, cancelled
agentIdstring
fromstring: ISO date, filters scheduledAt >=
tostring: ISO date, filters scheduledAt <= (a date-only value covers the whole day)
sortstring: One of: scheduledAt, createdAt, updatedAt · Default: scheduledAt

curl "https://bookifycall.com/api/v1/external/scheduled-calls" \
  -H "X-API-Key: $BOOKIFYCALL_API_KEY"

Example response · 200

{
  "success": true,
  "data": [
    {
      "id": "00000000-0000-4000-8000-000000000005",
      "organizationId": "00000000-0000-4000-8000-000000000100",
      "leadId": "00000000-0000-4000-8000-000000000003",
      "agentId": "00000000-0000-4000-8000-000000000002",
      "scheduledAt": "2026-10-20T15:00:00.000Z",
      "timezone": "America/New_York",
      "reason": "Follow up on the demo request",
      "scenario": "scheduled_callback",
      "status": "pending",
      "notes": null,
      "reminderContext": null,
      "attempts": 0,
      "maxAttempts": 3,
      "failureReason": null,
      "lastAttemptAt": null,
      "completedCallId": null,
      "createdAt": "2026-10-16T12:00:00.000Z",
      "updatedAt": "2026-10-16T12:00:00.000Z",
      "lead": {
        "id": "00000000-0000-4000-8000-000000000003",
        "name": "Jane Doe",
        "phone": "+15551230001"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 4,
    "pages": 1
  }
}

Schedule a call to a lead or phone numberLink to Schedule a call to a lead or phone number

POST/scheduled-calls

The agent calls at scheduledAt and retries up to maxAttempts times (backing off 5, 10, 20, 40 min).

Scope: scheduled_calls:write
Idempotency-Key: supported

Body (JSON)

leadIdstring: An existing lead to call. Send leadId or phoneNumber, not both (SCHED_010)
phoneNumberstring: Any E.164 number: linked to your newest lead with that phone, else a new lead is created
contactNamestring: Name for a lead created from phoneNumber
agentIdstring: Omit to let BookifyCall pick an agent at dial time
scheduledAtstringrequired: ISO 8601, in the future (SCHED_002)
timezonestring
reasonstring
notesstring
maxAttemptsnumber: Default: 3 · Min 1 · Max 5

curl -X POST "https://bookifycall.com/api/v1/external/scheduled-calls" \
  -H "X-API-Key: $BOOKIFYCALL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"phoneNumber":"+15551230001","contactName":"Jane Doe","agentId":"00000000-0000-4000-8000-000000000002","scheduledAt":"2026-10-20T15:00:00Z","timezone":"America/New_York","reason":"Follow up on the demo request"}'

Example response · 201

{
  "success": true,
  "data": {
    "id": "00000000-0000-4000-8000-000000000005",
    "organizationId": "00000000-0000-4000-8000-000000000100",
    "leadId": "00000000-0000-4000-8000-000000000003",
    "agentId": "00000000-0000-4000-8000-000000000002",
    "scheduledAt": "2026-10-20T15:00:00.000Z",
    "timezone": "America/New_York",
    "reason": "Follow up on the demo request",
    "scenario": "scheduled_callback",
    "status": "pending",
    "notes": null,
    "reminderContext": null,
    "attempts": 0,
    "maxAttempts": 3,
    "failureReason": null,
    "lastAttemptAt": null,
    "completedCallId": null,
    "createdAt": "2026-10-16T12:00:00.000Z",
    "updatedAt": "2026-10-16T12:00:00.000Z"
  }
}

Get a scheduled callLink to Get a scheduled call

GET/scheduled-calls/{id}

Scope: calls:read
Not found: 404 SCHED_001

Path parameters

idstringrequired

curl "https://bookifycall.com/api/v1/external/scheduled-calls/00000000-0000-4000-8000-000000000005" \
  -H "X-API-Key: $BOOKIFYCALL_API_KEY"

Example response · 200

{
  "success": true,
  "data": {
    "id": "00000000-0000-4000-8000-000000000005",
    "organizationId": "00000000-0000-4000-8000-000000000100",
    "leadId": "00000000-0000-4000-8000-000000000003",
    "agentId": "00000000-0000-4000-8000-000000000002",
    "scheduledAt": "2026-10-20T15:00:00.000Z",
    "timezone": "America/New_York",
    "reason": "Follow up on the demo request",
    "scenario": "scheduled_callback",
    "status": "pending",
    "notes": null,
    "reminderContext": null,
    "attempts": 0,
    "maxAttempts": 3,
    "failureReason": null,
    "lastAttemptAt": null,
    "completedCallId": null,
    "createdAt": "2026-10-16T12:00:00.000Z",
    "updatedAt": "2026-10-16T12:00:00.000Z",
    "lead": {
      "id": "00000000-0000-4000-8000-000000000003",
      "name": "Jane Doe",
      "phone": "+15551230001"
    }
  }
}

Cancel a pending scheduled callLink to Cancel a pending scheduled call

DELETE/scheduled-calls/{id}

Only pending calls can be cancelled (409 SCHED_004 otherwise).

Scope: scheduled_calls:write
Not found: 404 SCHED_001

Path parameters

idstringrequired

curl -X DELETE "https://bookifycall.com/api/v1/external/scheduled-calls/00000000-0000-4000-8000-000000000005" \
  -H "X-API-Key: $BOOKIFYCALL_API_KEY"

Example response · 200

{
  "success": true,
  "data": {
    "id": "00000000-0000-4000-8000-000000000005",
    "status": "cancelled"
  }
}

Next: Leads