The AssistantCalendar object

A calendar an assistant books meetings on during calls: one provider, one connected account, and the calendar or event type of that account it books on.

{
  "id": "b2d4f6a8-1c3e-4a5b-8d7f-9e0a1b2c3d4e",
  "assistant_id": "3f6c2a1e-8b4d-4c7a-9e2f-5d1b7a9c0e34",
  "handle": "google_calendar_jane_at_example.com",
  "provider": "google-calendar",
  "status": "ready",
  "connection": {
    "provider": "google-calendar",
    "connection_id": "9b8a7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d",
    "settings": {
      "calendar_id": "primary",
      "time_zone": "Europe/Paris",
      "duration_minutes": 30,
      "days": [1, 2, 3, 4, 5],
      "start_time": "09:00",
      "end_time": "18:00",
      "google_meet": false,
      "location": "{{site_address}}"
    }
  },
  "account_label": "Main line",
  "connected_via_invite": false,
  "invite": {
    "url": "https://example.com",
    "status": "completed",
    "created_at": "2026-11-05T09:00:00Z",
    "expires_at": "2026-11-05T09:00:00Z"
  },
  "created_at": "2026-11-05T09:00:00Z"
}

Fields

idstring
Unique ID of the calendar: the {calendarId} of the calendar endpoints.
assistant_idstring
ID of the assistant that books on this calendar.
handlestringnullable
How the prompt names this calendar, as @handle: the provider, then the connected account (e.g. google_calendar_jane_at_example.com). Null until an account is connected, unique within the assistant, kept when it is disconnected.
Example "google_calendar_jane_at_example.com"at most 255 characters
provider"google-calendar" | "calendly" | "cal-com-oauth"
Calendar provider.
"google-calendar"
Google Calendar: books on a calendar of the account, with the opening hours and meeting length of its settings.
"calendly"
Calendly: books an event type of the account.
"cal-com-oauth"
Cal.com: books an event type of the account.
status"not_connected" | "needs_setup" | "ready"
Whether the calendar takes bookings.
"not_connected"
No account is connected yet: send the invite link to the account owner, or connect an account of your organization.
"needs_setup"
An account is connected, but the calendar (Google) or event type (Calendly, Cal.com) to book on is not picked: list them with GET .../options and pick one with PUT .../selection.
"ready"
Takes bookings: the agent can book on it during calls.
connectionobjectnullable
The connected account, on the calendar's provider. Null until one is connected.
account_labelstringnullable
The connected account, usually its email. Null when not connected, or when the provider did not say.
connected_via_inviteboolean
True when the account was connected by a colleague from the invite link.
inviteobjectnullable
The invite link a colleague can use to connect their own account to this calendar (POST /assistants/{id}/calendars/{calendarId}/invite). Null when no link was created, once it was revoked, and once an account was connected from the dashboard or the API instead.
created_atstring (date-time)
When the calendar was added to the assistant (ISO 8601).