> ## 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.

# Create Scheduled Call

> Create a new scheduled video call

## 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

```json theme={null}
{
  "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

```bash theme={null}
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
  }'
```