Connect an account to a calendar

PUT/assistants/{id}/calendars/{calendarId}/connection

Connect the calendar to an account your organization already uses on its provider. The calendar takes the handle of that account (google_calendar_jane_at_example.com, then _2 for a second calendar on the same account); reconnecting the same account keeps the handle. Google's primary calendar, or the account's only event type, is picked right away; otherwise pick one with GET .../options and PUT .../selection.

Request

curl -X PUT "https://www.getrevox.com/api/assistants/3f6c2a1e-8b4d-4c7a-9e2f-5d1b7a9c0e34/calendars/b2d4f6a8-1c3e-4a5b-8d7f-9e0a1b2c3d4e/connection" \
  -H "Authorization: Bearer $REVOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "connection_id": "9b8a7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d" }'

const res = await fetch("https://www.getrevox.com/api/assistants/3f6c2a1e-8b4d-4c7a-9e2f-5d1b7a9c0e34/calendars/b2d4f6a8-1c3e-4a5b-8d7f-9e0a1b2c3d4e/connection", {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${process.env.REVOX_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    connection_id: "9b8a7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d",
  }),
});
const data = await res.json();
console.log(data);

import os

import requests

response = requests.put(
    "https://www.getrevox.com/api/assistants/3f6c2a1e-8b4d-4c7a-9e2f-5d1b7a9c0e34/calendars/b2d4f6a8-1c3e-4a5b-8d7f-9e0a1b2c3d4e/connection",
    headers={"Authorization": f"Bearer {os.environ['REVOX_API_KEY']}"},
    json={
        "connection_id": "9b8a7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d",
    },
    timeout=30,
)
response.raise_for_status()
print(response.json())

Try itSend this request live

Response

Success

{
  "calendar": {
    "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"
  }
}

{
  "message": "Request validation failed",
  "bodyErrors": {
    "issues": [
      {
        "path": ["connection_id"],
        "message": "Invalid input: expected string, received undefined",
        "code": "invalid_type"
      }
    ]
  }
}

{ "error": "Not found" }

Path parameters

idstringrequired
ID of the assistant, as returned by GET /assistants.
calendarIdstringrequired
ID of the calendar, from the assistant's calendars list or GET /assistants/{id}/calendars.

Request body

application/json

connection_idstringrequired
ID of a connection your organization already has to an account on the calendar's provider: the connection.connection_id of another calendar connected to that account. To connect a new account, create an invite link instead.

Response

200

calendarAssistantCalendar
- 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).

Errors

400Invalid request: a field or parameter failed validation{ "message"?: string, "error"?: string, "bodyErrors"?: {…} }
404Not found in your organization{ "message"?: string, "error"?: string, "bodyErrors"?: {…} }

Error bodies carry an error (or message) string; a 400 adds bodyErrors.issues. See Errors.