Skip to main content
Get a preview
All docs

Connect Cal.com

Cal.com is the preferred first scheduling source. Porchlight owns qualification and booking logic, while Cal.com remains the source of truth for real availability.

What you need

  • A Cal.com account.
  • A Cal.com API key with access to the event type.
  • One event type for the next step Porchlight should book: consult, showroom visit, design call, or site visit.
  • The event type ID, public booking URL, and time zone.

If you have not created the event type yet, create one in Cal.com under Event Types -> New. Name it clearly, such as Backyard project consult or Site visit.

Getting your API key

  1. Sign in to Cal.com.
  2. Go to Settings -> Developer -> API keys.
  3. Create an API key and copy the value.

API keys are sensitive. Store them only in Settings -> Integrations and do not paste them into chat, tickets, or docs.

Connecting in Porchlight

  1. Open Settings -> Integrations.
  2. Find Cal.com.
  3. Paste the booking URL, API key, event type ID, and time zone.
  4. Save.
  5. Click Ping Cal.com. A successful ping means Porchlight can fetch available slots through Cal.com API v2.

Porchlight uses Cal.com API v2 slot lookup and booking creation. Slot lookup uses the event type ID, date range, and time zone. Booking creation sends the selected start time, attendee name, email, phone when available, and Porchlight metadata.

How the agent uses it

When a buyer is ready, the agent:

  1. Pulls real availability.
  2. Offers a few natural time options.
  3. Confirms name and email.
  4. Books the appointment.
  5. Attaches homeowner name, phone, email, address or zip, project summary, budget, timeline, transcript link, source, and collected photo references when available.
  6. Updates the lead to Site visit scheduled, resolves the conversation, records the appointment, generates the draft quote, and sends the configured notifications.

Calendar strategy

Cal.com comes first because it is fast to wire and clean to operate. Google Calendar is next, Outlook later, and a lightweight Porchlight availability fallback can cover customers without a usable calendar.

When Cal.com is not configured, the agent reads Settings -> Availability and marks returned slots as fallback_availability. Those fallback slots are Porchlight-held appointment windows, not source-of-truth calendar availability.

If Cal.com is configured but unavailable during slot lookup, Porchlight will try local fallback availability and mark those slots as fallback. If Cal.com fails during booking, Porchlight keeps the lead, marks it for follow-up, creates a handoff, and tells the buyer the team will confirm timing manually.

Troubleshooting

If the agent cannot find slots, check the event type, availability rules, buffers, and future booking limits in Cal.com.

If bookings do not appear in the underlying calendar, confirm Cal.com is connected to Google, iCloud, or Outlook and that calendar sync is enabled.

If fallback slots are wrong, check Settings -> Availability for the weekly windows, time zone, and slot duration.

If scheduling should be disabled entirely, remove the Cal.com credentials and clear fallback availability windows. Porchlight will route ready buyers to follow-up instead.