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

# Scheduling API

> The Scheduling API lets you manage scheduling pages, event types, meetings, and availability schedules programmatically.

The Scheduling API lets you manage scheduling pages, event types, meetings, and availability schedules programmatically. Requires `scheduling:read`, `scheduling:write`, `meetings:read`, or `meetings:write` scopes.

## Scheduling Pages

Scheduling pages are booking pages your contacts use to schedule meetings. Each page can contain multiple event types.

### Endpoints

| Method   | Endpoint                    | Description                            |
| -------- | --------------------------- | -------------------------------------- |
| `GET`    | `/v1/scheduling-pages`      | List scheduling pages                  |
| `POST`   | `/v1/scheduling-pages`      | Create a scheduling page               |
| `GET`    | `/v1/scheduling-pages/{id}` | Get a scheduling page with event types |
| `PATCH`  | `/v1/scheduling-pages/{id}` | Update a scheduling page               |
| `DELETE` | `/v1/scheduling-pages/{id}` | Delete a scheduling page               |

### Query Parameters

Use these when listing scheduling pages:

| Parameter  | Type    | Description                              |
| ---------- | ------- | ---------------------------------------- |
| `page`     | integer | Page number (default: 1)                 |
| `per_page` | integer | Results per page (default: 20, max: 100) |
| `status`   | string  | Filter by status: draft or published     |

### List Scheduling Pages

```bash theme={null}
curl https://api.orbitforms.ai/v1/scheduling-pages \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```json theme={null}
{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "title": "Book a Demo",
      "slug": "book-a-demo",
      "description": "Schedule a product demo with our team",
      "type": "schedule",
      "page_type": "one_on_one",
      "status": "published",
      "settings": {
        "confirmation_message": "You're booked!",
        "show_avatar": true
      },
      "created_at": "2026-01-15T10:00:00Z",
      "updated_at": "2026-01-20T14:30:00Z",
      "published_at": "2026-01-16T09:00:00Z"
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "per_page": 20,
    "total_pages": 1
  }
}
```

### Create a Scheduling Page

```bash theme={null}
curl -X POST https://api.orbitforms.ai/v1/scheduling-pages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Book a Demo",
    "slug": "book-a-demo",
    "description": "Schedule a product demo",
    "page_type": "one_on_one"
  }'
```

### Get Scheduling Page

Returns the scheduling page with its event types included.

```json theme={null}
{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Book a Demo",
    "slug": "book-a-demo",
    "description": "Schedule a product demo with our team",
    "type": "schedule",
    "page_type": "one_on_one",
    "status": "published",
    "settings": {
      "confirmation_message": "You're booked!",
      "show_avatar": true,
      "redirect_url": "https://example.com/confirmed"
    },
    "remove_branding": false,
    "event_types": [
      {
        "id": "660e8400-e29b-41d4-a716-446655440001",
        "title": "30 Min Meeting",
        "slug": "30-min-meeting",
        "duration_minutes": 30,
        "location_type": "google_meet",
        "is_active": true,
        "color": "#3B82F6",
        "position": 0,
        "buffer_time_before": 0,
        "buffer_time_after": 10,
        "min_notice_minutes": 60,
        "max_booking_days": 14,
        "start_time_increment": 30,
        "requires_confirmation": false,
        "guests_allowed": true
      }
    ],
    "created_at": "2026-01-15T10:00:00Z",
    "updated_at": "2026-01-20T14:30:00Z"
  }
}
```

## Event Types

Event types define the different kinds of meetings available on a scheduling page (e.g., "30 Min Demo", "15 Min Quick Call"). Event type endpoints are nested under their parent scheduling page.

### Endpoints

| Method   | Endpoint                                              | Description                 |
| -------- | ----------------------------------------------------- | --------------------------- |
| `GET`    | `/v1/scheduling-pages/{id}/event-types`               | List event types for a page |
| `POST`   | `/v1/scheduling-pages/{id}/event-types`               | Create an event type        |
| `GET`    | `/v1/scheduling-pages/{id}/event-types/{eventTypeId}` | Get an event type           |
| `PATCH`  | `/v1/scheduling-pages/{id}/event-types/{eventTypeId}` | Update an event type        |
| `DELETE` | `/v1/scheduling-pages/{id}/event-types/{eventTypeId}` | Delete an event type        |

### Event Type Fields

| Field                   | Type    | Description                                                        |
| ----------------------- | ------- | ------------------------------------------------------------------ |
| `title`                 | string  | Display name (e.g., "30 Min Meeting")                              |
| `slug`                  | string  | URL-friendly identifier (auto-generated from title if omitted)     |
| `duration_minutes`      | integer | Meeting duration in minutes (default: 30)                          |
| `location_type`         | string  | google\_meet, zoom, microsoft\_teams, phone, in\_person, or custom |
| `buffer_time_before`    | integer | Minutes of buffer before the meeting (default: 0)                  |
| `buffer_time_after`     | integer | Minutes of buffer after the meeting (default: 0)                   |
| `min_notice_minutes`    | integer | Minimum advance notice required (default: 60)                      |
| `max_booking_days`      | integer | How far in advance bookings are allowed (default: 14)              |
| `start_time_increment`  | integer | Time slot intervals: 5, 10, 15, 30, or 60 minutes                  |
| `requires_confirmation` | boolean | Whether the host must confirm the booking                          |
| `guests_allowed`        | boolean | Whether attendees can add guests                                   |

## Meetings

Meetings represent booked appointments. You can list, retrieve, update the status of, or delete meetings.

### Endpoints

| Method   | Endpoint            | Description                                                                 |
| -------- | ------------------- | --------------------------------------------------------------------------- |
| `GET`    | `/v1/meetings`      | List meetings                                                               |
| `GET`    | `/v1/meetings/{id}` | Get a meeting                                                               |
| `PATCH`  | `/v1/meetings/{id}` | Update a meeting (status, notes). Cancelling cleans up Zoom and calendar.   |
| `DELETE` | `/v1/meetings/{id}` | Delete a meeting. Cleans up the associated Zoom meeting and calendar event. |

### Query Parameters

Use these when listing meetings:

| Parameter            | Type    | Description                                                                           |
| -------------------- | ------- | ------------------------------------------------------------------------------------- |
| `page`               | integer | Page number (default: 1)                                                              |
| `per_page`           | integer | Results per page (default: 20, max: 100)                                              |
| `status`             | string  | Filter: scheduled, completed, cancelled, pending\_confirmation, no\_show, rescheduled |
| `since`              | string  | ISO date. Only meetings starting after this time.                                     |
| `until`              | string  | ISO date. Only meetings starting before this time.                                    |
| `scheduling_page_id` | string  | Filter by scheduling page UUID                                                        |

### List Meetings

```bash theme={null}
curl "https://api.orbitforms.ai/v1/meetings?status=scheduled&since=2026-02-01T00:00:00Z" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```json theme={null}
{
  "data": [
    {
      "id": "770e8400-e29b-41d4-a716-446655440010",
      "attendee_name": "Jane Smith",
      "attendee_email": "jane@example.com",
      "start_time": "2026-02-10T14:00:00Z",
      "end_time": "2026-02-10T14:30:00Z",
      "timezone": "America/New_York",
      "status": "scheduled",
      "meeting_link": "https://meet.google.com/abc-defg-hij",
      "notes": null,
      "guests": [],
      "contact_id": "880e8400-e29b-41d4-a716-446655440020",
      "host_user_id": "990e8400-e29b-41d4-a716-446655440030",
      "event_type_id": "660e8400-e29b-41d4-a716-446655440001",
      "scheduling_page_id": "550e8400-e29b-41d4-a716-446655440000",
      "created_at": "2026-02-08T09:15:00Z",
      "updated_at": "2026-02-08T09:15:00Z"
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "per_page": 20,
    "total_pages": 1
  }
}
```

### Update a Meeting

You can update the `status` (to *scheduled*, *completed*, *cancelled*, or *no\_show*), `notes`, and `cancellation_reason` (when cancelling).

<Info>
  **Cancellation cleanup:** When you set the status to *cancelled*, OrbitForms automatically deletes the associated Zoom meeting (if one was created), removes the calendar event, and sends a cancellation notification email to the attendee.
</Info>

```bash theme={null}
curl -X PATCH https://api.orbitforms.ai/v1/meetings/{id} \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "completed",
    "notes": "Great demo call, follow-up scheduled"
  }'
```

## Availability Schedules

Availability schedules define working hours and date-specific overrides (holidays, vacation, etc.) for team members. These endpoints are **read-only** via the public API since availability is tied to individual user calendars.

### Endpoints

| Method | Endpoint                          | Description                      |
| ------ | --------------------------------- | -------------------------------- |
| `GET`  | `/v1/availability-schedules`      | List availability schedules      |
| `GET`  | `/v1/availability-schedules/{id}` | Get schedule with date overrides |

### Query Parameters

| Parameter | Type   | Description                              |
| --------- | ------ | ---------------------------------------- |
| `user_id` | string | Filter schedules by a specific user UUID |

### Get Availability Schedule

Returns the schedule with its weekly rules and any date-specific overrides.

```bash theme={null}
curl https://api.orbitforms.ai/v1/availability-schedules/{id} \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```json theme={null}
{
  "data": {
    "id": "aa0e8400-e29b-41d4-a716-446655440040",
    "user_id": "990e8400-e29b-41d4-a716-446655440030",
    "name": "Working Hours",
    "timezone": "America/New_York",
    "is_default": true,
    "rules": [
      { "day": 1, "start": "09:00", "end": "17:00", "enabled": true },
      { "day": 2, "start": "09:00", "end": "17:00", "enabled": true },
      { "day": 3, "start": "09:00", "end": "17:00", "enabled": true },
      { "day": 4, "start": "09:00", "end": "17:00", "enabled": true },
      { "day": 5, "start": "09:00", "end": "17:00", "enabled": true }
    ],
    "date_overrides": [
      {
        "id": "bb0e8400-e29b-41d4-a716-446655440050",
        "date": "2026-02-17",
        "is_unavailable": true,
        "reason": "Holiday"
      }
    ],
    "created_at": "2026-01-01T00:00:00Z",
    "updated_at": "2026-01-10T08:00:00Z"
  }
}
```

## Calendar

These public-facing endpoints power the booking widget. They allow your contacts to check available time slots and book meetings without authentication. The availability endpoint accounts for the host's calendar events, buffer times, and date overrides. The booking endpoint creates the calendar event, generates the meeting link (Zoom or Google Meet), and sends a confirmation email to both parties. Microsoft Teams support coming soon.

<Note>
  These are public-facing endpoints used by the booking widget. They do not require an API key or authentication.
</Note>

### Endpoints

| Method | Endpoint                     | Description                          |
| ------ | ---------------------------- | ------------------------------------ |
| `GET`  | `/api/calendar/availability` | Get available time slots for booking |
| `POST` | `/api/calendar/book`         | Book a meeting                       |

### Get Available Time Slots

Returns available time slots for a given event type and date range. Slots are calculated based on the host's availability schedule, existing calendar events, buffer times, and minimum notice requirements.

#### Query Parameters

| Parameter       | Type   | Description                                              |
| --------------- | ------ | -------------------------------------------------------- |
| `event_type_id` | string | The event type UUID to check availability for (required) |
| `start_date`    | string | Start date in ISO format, e.g. 2026-02-10 (required)     |
| `end_date`      | string | End date in ISO format, e.g. 2026-02-14 (required)       |
| `timezone`      | string | IANA timezone, e.g. America/New\_York (required)         |

```bash theme={null}
curl "https://api.orbitforms.ai/api/calendar/availability?event_type_id=660e8400-e29b-41d4-a716-446655440001&start_date=2026-02-10&end_date=2026-02-14&timezone=America/New_York"
```

```json theme={null}
{
  "data": {
    "slots": [
      {
        "start": "2026-02-10T09:00:00-05:00",
        "end": "2026-02-10T09:30:00-05:00"
      },
      {
        "start": "2026-02-10T09:30:00-05:00",
        "end": "2026-02-10T10:00:00-05:00"
      },
      {
        "start": "2026-02-10T10:00:00-05:00",
        "end": "2026-02-10T10:30:00-05:00"
      },
      {
        "start": "2026-02-10T14:00:00-05:00",
        "end": "2026-02-10T14:30:00-05:00"
      }
    ],
    "timezone": "America/New_York",
    "event_type": {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "title": "30 Min Meeting",
      "duration_minutes": 30
    }
  }
}
```

### Book a Meeting

Books a meeting for the selected time slot. Creates a calendar event on the host's calendar, generates a meeting link (Zoom or Google Meet depending on the event type configuration; Microsoft Teams coming soon), and sends a confirmation email to both the host and attendee.

#### Request Body

| Parameter       | Type      | Description                                              |
| --------------- | --------- | -------------------------------------------------------- |
| `event_type_id` | string    | The event type UUID to book (required)                   |
| `start_time`    | string    | Meeting start time in ISO format (required)              |
| `end_time`      | string    | Meeting end time in ISO format (required)                |
| `timezone`      | string    | IANA timezone of the attendee (required)                 |
| `name`          | string    | Attendee full name (required)                            |
| `email`         | string    | Attendee email address (required)                        |
| `phone`         | string    | Attendee phone number (optional)                         |
| `guests`        | string\[] | Array of additional guest email addresses (optional)     |
| `notes`         | string    | Additional notes or message from the attendee (optional) |

```bash theme={null}
curl -X POST https://api.orbitforms.ai/api/calendar/book \
  -H "Content-Type: application/json" \
  -d '{
    "event_type_id": "660e8400-e29b-41d4-a716-446655440001",
    "start_time": "2026-02-10T14:00:00-05:00",
    "end_time": "2026-02-10T14:30:00-05:00",
    "timezone": "America/New_York",
    "name": "Jane Smith",
    "email": "jane@example.com",
    "phone": "+15551234567",
    "guests": ["colleague@example.com"],
    "notes": "Interested in the enterprise plan"
  }'
```

```json theme={null}
{
  "data": {
    "id": "770e8400-e29b-41d4-a716-446655440099",
    "attendee_name": "Jane Smith",
    "attendee_email": "jane@example.com",
    "attendee_phone": "+15551234567",
    "start_time": "2026-02-10T14:00:00Z",
    "end_time": "2026-02-10T14:30:00Z",
    "timezone": "America/New_York",
    "status": "scheduled",
    "meeting_link": "https://meet.google.com/abc-defg-hij",
    "notes": "Interested in the enterprise plan",
    "guests": ["colleague@example.com"],
    "event_type_id": "660e8400-e29b-41d4-a716-446655440001",
    "scheduling_page_id": "550e8400-e29b-41d4-a716-446655440000",
    "confirmation_email_sent": true,
    "created_at": "2026-02-08T12:00:00Z"
  }
}
```

## Required Scopes

| Scope               | Description                                                    |
| ------------------- | -------------------------------------------------------------- |
| `scheduling:read`   | Read scheduling pages, event types, and availability schedules |
| `scheduling:write`  | Create and update scheduling pages and event types             |
| `scheduling:delete` | Delete scheduling pages and event types                        |
| `meetings:read`     | Read meetings                                                  |
| `meetings:write`    | Update meetings (status changes, notes)                        |
| `meetings:delete`   | Delete meetings                                                |

[Next: Rate Limits](/developers/api/rate-limits)