Bookings and Calendar

Create a Cal.com booking on behalf of the tenant, or configure a per-receptionist calendar so the voice AI books appointments automatically during calls.

Create a booking

POST /api/v1/bookings creates a Cal.com booking for an attendee. Scope: book. Requires an active Cal.com integration; wire the API key at Settings > Integrations. AutoRev uses Cal.com v2 under the hood (bearer auth plus the cal-api-version: 2024-08-13 header).

camelCase fields

Unlike the rest of the API, this endpoint uses camelCase field names, matching the Cal.com v2 API it wraps.

Request body

{
  "eventTypeId": 12345,
  "attendeeName": "Jane Doe",
  "attendeeEmail": "jane@example.com",
  "attendeePhone": "+15551234567",
  "startTime": "2026-04-25T15:00:00Z",
  "timeZone": "America/New_York",
  "notes": "Wants AC tune-up quote"
}

Field	Required	Description
eventTypeId	Yes	Number. The Cal.com event type to book
attendeeName	Yes	Attendee full name
attendeeEmail	Yes	Attendee email
attendeePhone	No	Attendee phone
startTime	Yes	ISO 8601 UTC
timeZone	No	IANA timezone
notes	No	Free-text notes

Response (201 Created)

{
  "booking": {
    "id": 12345,
    "uid": "abc123xyz",
    "location": "Zoom",
    "meeting_url": "https://zoom.us/j/123456789",
    "start": "2026-04-25T15:00:00Z",
    "end": "2026-04-25T15:30:00Z",
    "event_type": { "slug": "intro-call" }
  }
}

Example (curl)

curl -X POST https://app.autorev.ai/api/v1/bookings \
  -H "Authorization: Bearer ar_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "eventTypeId": 12345,
    "attendeeName": "Jane Doe",
    "attendeeEmail": "jane@example.com",
    "attendeePhone": "+15551234567",
    "startTime": "2026-04-25T15:00:00Z",
    "timeZone": "America/New_York",
    "notes": "Wants AC tune-up quote"
  }'

Error codes

Error code	HTTP status	Meaning
cal_com_not_configured	424	No Cal.com integration is wired; connect it first
invalid_event_type	400	The eventTypeId does not belong to the connected Cal.com account
slot_taken	409	The startTime is already booked or no available users
cal_com_error	422	Cal.com rejected the booking (passthrough message, e.g. a required booking field the event type defines)
cal_com_timeout	503	Cal.com did not answer within 25s, or Cal.com itself failed. Cal.com may have created the booking before the timeout: check the calendar before retrying

This endpoint creates the booking; it does not send an SMS confirmation. For a full inbound-call booking flow (check availability, confirm, SMS the meeting link), use an AI receptionist with its calendar field configured; the voice AI handles the whole conversation automatically.

Per-receptionist calendar configuration

Each receptionist can have its own Cal.com calendar integration. When configured, the AI automatically checks availability and books meetings during calls without any manual intervention. Because configuration is per-receptionist, different receptionists can connect to different calendars, event types, and timezones, which is useful when managing multiple businesses or departments from a single account.

Pass a calendar object when creating or updating a receptionist:

Create receptionist with calendar

curl -X POST https://app.autorev.ai/api/v1/receptionists \
  -H "Authorization: Bearer ar_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "business_name": "Acme Consulting",
    "system_prompt": "You are a scheduling assistant for Acme Consulting...",
    "calendar": {
      "api_key": "cal_live_abc123...",
      "event_type_id": 12345,
      "booking_link": "https://cal.com/acme/30min",
      "timezone": "America/New_York"
    }
  }'

Calendar fields

Field	Type	Description
api_key	string	Your Cal.com API key (starts with cal_live_)
event_type_id	number	The Cal.com event type ID to book
booking_link	string	Public Cal.com booking URL (sent in confirmation SMS)
timezone	string	IANA timezone for availability display (e.g. America/New_York)

How it works during calls

When a caller wants to book an appointment, the AI uses the check_availability tool to query open slots from Cal.com, offers time options to the caller, and uses create_booking to confirm the meeting. The caller receives an SMS confirmation with the booking link.

You can update or remove calendar configuration at any time via PATCH /api/v1/receptionists/:id. Pass calendar: null to disconnect the calendar.