Create Scheduled Call - ApifyCloud Docs

Endpoint

POST https://api.apifycloud.io/api/v1/video/{appId}/scheduled-calls

Authentication

Bearer token required. Scope: scheduling:write

Path parameters

appId (UUID, required)

Request body

Field	Type	Required	Description
`guestName`	string	yes	Guest display name.
`scheduledAtUtc`	string	yes	ISO-8601 UTC timestamp for the start of the call.
`appTimezone`	string	yes	IANA timezone used for display (e.g. `America/Bogota`).
`guestPhone`	string	conditional	Required if `guestEmail` is not provided.
`guestEmail`	string	conditional	Required if `guestPhone` is not provided.
`assignedAgentId`	string	optional	User id of the agent to assign the call to.
`assignmentMethod`	string	optional	`manual`, `self_selected`, `round_robin`, `pool`. Defaults to `manual`.
`guestTimezone`	string	optional	IANA timezone of the guest.
`guestIntakeNotes`	string	optional	Free-form notes attached to the booking.
`durationMinutes`	number	optional	Default 30.
`bufferBeforeMinutes`	number	optional	Default 0.
`bufferAfterMinutes`	number	optional	Default 0.
`requireConfirmation`	boolean	optional	Forces the call into `pending_confirmation` until the guest confirms.

Notes

bookingSource is always stamped as api server-side.
Recurrence is not exposed in v1. Create each instance individually.
When assignedAgentId is provided the endpoint takes an advisory lock on (agent, minute) so concurrent POSTs cannot double-book.
Customer rate limits configured on the app preset apply. Hitting the limit returns 429 with nextAllowedAt in the error details.

Response

{
  "data": {
    "call": {
      "id": "uuid",
      "app_id": "uuid",
      "booking_source": "api",
      "assigned_agent_id": "uuid",
      "guest_name": "Jane Doe",
      "guest_phone": "+57 300 555 0100",
      "guest_email": "jane@example.com",
      "scheduled_at": "2026-05-01T15:00:00.000Z",
      "duration_minutes": 30,
      "app_timezone": "America/Bogota",
      "status": "scheduled",
      "created_at": "2026-04-22T12:00:00.000Z"
    }
  }
}

Returns 201 Created.

Errors

400 invalid_request validation failed (past date, missing required fields)
403 forbidden scheduling not enabled on the app’s active preset, or missing scope
404 app_not_found
409 conflict slot overlaps an existing call, blocked exception, or DND window
429 rate_limit_exceeded either client rate limit or per-customer booking limit
500 server_error

Example

curl -X POST "https://api.apifycloud.io/api/v1/video/{appId}/scheduled-calls" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "assignedAgentId": "user_abc",
    "assignmentMethod": "manual",
    "guestName": "Jane Doe",
    "guestPhone": "+57 300 555 0100",
    "guestEmail": "jane@example.com",
    "guestTimezone": "America/Bogota",
    "guestIntakeNotes": "Wants to discuss contract renewal",
    "scheduledAtUtc": "2026-05-01T15:00:00.000Z",
    "durationMinutes": 30,
    "appTimezone": "America/Bogota",
    "bufferBeforeMinutes": 5,
    "bufferAfterMinutes": 5,
    "requireConfirmation": false
  }'

​Endpoint

​Authentication

​Path parameters

​Request body

​Notes

​Response

​Errors

​Example

Endpoint

Authentication

Path parameters

Request body

Notes

Response

Errors

Example