> Revox API docs for developers and AI agents. Index: https://www.getrevox.com/docs/api/llms.txt · Everything in one file: https://www.getrevox.com/docs/api/llms-full.txt · OpenAPI 3.1: https://www.getrevox.com/openapi.json · MCP server: https://www.getrevox.com/api/mcp-servers/generic/mcp
> Base URL https://www.getrevox.com/api · Auth: `Authorization: Bearer $REVOX_API_KEY`

# Pick what a calendar books on

`PUT https://www.getrevox.com/api/assistants/{id}/calendars/{calendarId}/selection`

Set the calendar (Google) or event type (Calendly, Cal.com) of the connected account the calendar books on, with an id from GET .../options. A Google calendar shared read-only is refused with 400. The calendar is then ready to take bookings.

## Request

```bash
curl -X PUT "https://www.getrevox.com/api/assistants/3f6c2a1e-8b4d-4c7a-9e2f-5d1b7a9c0e34/calendars/b2d4f6a8-1c3e-4a5b-8d7f-9e0a1b2c3d4e/selection" \
  -H "Authorization: Bearer $REVOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "option_id": "sales-team@example.com" }'
```

## Path parameters

- `id` (string, required): ID of the assistant, as returned by [`GET /assistants`](https://www.getrevox.com/docs/api/assistants/get-assistants.md).
- `calendarId` (string, required): ID of the calendar, from the assistant's `calendars` list or [`GET /assistants/{id}/calendars`](https://www.getrevox.com/docs/api/assistants/list-an-assistants-calendars.md).

## Body

JSON.

- `option_id` (string, required): The id of a bookable option from [`GET /assistants/{id}/calendars/{calendarId}/options`](https://www.getrevox.com/docs/api/assistants/list-what-a-calendar-can-book-on.md).

## Response 200

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

- `calendar` ([AssistantCalendar](https://www.getrevox.com/docs/api/objects/assistant-calendar.md))

## Errors

- `400` Invalid request: a field or parameter failed validation: `{"message":"Request validation failed","bodyErrors":{"issues":[{"path":["option_id"],"message":"Invalid input: expected string, received undefined","code":"invalid_type"}]}}`
- `404` Not found in your organization: `{"error":"Not found"}`
- Every status is explained under Errors in https://www.getrevox.com/docs/api.md#errors.

## Objects on this page

### AssistantCalendar

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` (string): Unique ID of the calendar: the {calendarId} of the calendar endpoints.
- `assistant_id` (string): ID of the assistant that books on this calendar.
- `handle` (string | null): 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. At most 255 characters. Example: `"google_calendar_jane_at_example.com"`.
- `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.
- `connection` (object | null): The connected account, on the calendar's provider. Null until one is connected.
  - One of 3, chosen by `connection.provider`: The calendar's provider, which tells which shape `settings` has.
  - `connection.connection_id` (string): ID of the connection to the account. Pass it to [`PUT /assistants/{id}/calendars/{calendarId}/connection`](https://www.getrevox.com/docs/api/assistants/connect-an-account-to-a-calendar.md) to connect another calendar to the same account.
  - When `provider` is `"google-calendar"`
    - `connection.settings` (object | null): What the calendar books on. Null until the calendar (Google) or event type (Calendly, Cal.com) is picked: until then the calendar takes no booking.
      - `connection.settings.calendar_id` (string): ID of the Google calendar to book on: 'primary' for the account's main calendar, or an id from [`GET /assistants/{id}/calendars/{calendarId}/options`](https://www.getrevox.com/docs/api/assistants/list-what-a-calendar-can-book-on.md). Example: `"primary"`.
      - `connection.settings.time_zone` (string): IANA timezone of start_time and end_time. Example: `"Europe/Paris"`.
      - `connection.settings.duration_minutes` (integer, default 30): Length of a booked meeting, in minutes. Default: 30. 5 to 480.
      - `connection.settings.days` (array of integer, default [1,2,3,4,5]): Open days, from 0 (Sunday) to 6 (Saturday). Default: Monday to Friday. Each item 0 to 6.
      - `connection.settings.start_time` (string, default "09:00"): Opening time of each open day, 'HH:mm' 24-hour, in time_zone: no meeting is booked before it. Default: '09:00'. Pattern ^\d{2}:\d{2}$.
      - `connection.settings.end_time` (string, default "18:00"): Closing time of each open day, 'HH:mm' 24-hour, in time_zone: a meeting must end by then. Default: '18:00'. Pattern ^\d{2}:\d{2}$.
      - `connection.settings.google_meet` (boolean, default true): Adds a Google Meet link to the meeting. Default: true. A calendar whose Google Workspace does not allow Meet gets the meeting without the link.
      - `connection.settings.location` (string | null, default null): Where the meeting takes place, written in the calendar event and the invitation. Can use the call's prompt variables, e.g. '{{site_address}}': a variable the call does not have is left out. Null (default): no location. At most 500 characters.
  - When `provider` is `"calendly"`
    - `connection.settings` (object | null): What the calendar books on. Null until the calendar (Google) or event type (Calendly, Cal.com) is picked: until then the calendar takes no booking.
      - `connection.settings.event_type_id` (string): The Calendly event type to book, by its URI, as [`GET /assistants/{id}/calendars/{calendarId}/options`](https://www.getrevox.com/docs/api/assistants/list-what-a-calendar-can-book-on.md) lists it. At least 1 character. Example: `"https://api.calendly.com/event_types/0b6e1f3a-7c2d-4e8b-9a5f-3d2c1b0a9e8f"`.
  - When `provider` is `"cal-com-oauth"` Example: `{"provider":"cal-com-oauth","connection_id":"9b8a7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d","settings":{"event_type_id":"1234567"}}`.
    - `connection.settings` (object | null): What the calendar books on. Null until the calendar (Google) or event type (Calendly, Cal.com) is picked: until then the calendar takes no booking.
      - `connection.settings.event_type_id` (string): ID of the Cal.com event type to book, as [`GET /assistants/{id}/calendars/{calendarId}/options`](https://www.getrevox.com/docs/api/assistants/list-what-a-calendar-can-book-on.md) lists it. At least 1 character. Example: `"1234567"`.
- `account_label` (string | null): The connected account, usually its email. Null when not connected, or when the provider did not say.
- `connected_via_invite` (boolean): True when the account was connected by a colleague from the invite link.
- `invite` (object | null): The invite link a colleague can use to connect their own account to this calendar ([`POST /assistants/{id}/calendars/{calendarId}/invite`](https://www.getrevox.com/docs/api/assistants/create-an-invite-link-for-a-calendar.md)). Null when no link was created, once it was revoked, and once an account was connected from the dashboard or the API instead.
  - `invite.url` (string | null): Page where a colleague without a Revox account connects their own calendar to this one. Anyone holding the link can, until it expires. Only given by the calendar endpoints, null on a calendar listed in an assistant.
  - `invite.status` ("pending" | "completed" | "expired"): Where the invite link stands.
    - `"pending"`: The link works and waits for the account owner.
    - `"completed"`: The owner connected their account and picked the calendar to book on.
    - `"expired"`: The link no longer works.
  - `invite.created_at` (string (date-time)): When the link was created (ISO 8601).
  - `invite.expires_at` (string (date-time)): When the link stops working (ISO 8601): 14 days after its creation, shortened to at most 60 minutes after the colleague connects their account, the time to pick their calendar.
- `created_at` (string (date-time)): When the calendar was added to the assistant (ISO 8601).