Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.apifycloud.io/llms.txt

Use this file to discover all available pages before exploring further.

​
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

FieldTypeRequiredDescription
guestNamestringyesGuest display name.
scheduledAtUtcstringyesISO-8601 UTC timestamp for the start of the call.
appTimezonestringyesIANA timezone used for display (e.g. America/Bogota).
guestPhonestringconditionalRequired if guestEmail is not provided.
guestEmailstringconditionalRequired if guestPhone is not provided.
assignedAgentIdstringoptionalUser id of the agent to assign the call to.
assignmentMethodstringoptionalmanual, self_selected, round_robin, pool. Defaults to manual.
guestTimezonestringoptionalIANA timezone of the guest.
guestIntakeNotesstringoptionalFree-form notes attached to the booking.
durationMinutesnumberoptionalDefault 30.
bufferBeforeMinutesnumberoptionalDefault 0.
bufferAfterMinutesnumberoptionalDefault 0.
requireConfirmationbooleanoptionalForces 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
  }'