Cal.com#
Cal.com is registered for API-key sync with sync-coupled user import. It pulls bookings visible to the authenticated Cal.com user into a reviewable import session, proposes TeamBoost user mappings from booking actors, and projects each booking into a conservative task-create draft for operator review.
| Capability | Method | Status |
|---|---|---|
SYNC |
Pull bookings from Cal.com API v2 | Built |
USER_IMPORT |
Bring the profile and booking actors into task-import mapping | Built as part of API sync |
CSV_IMPORT |
Upload a Cal.com export | Not built |
WEBHOOK |
Verify Cal.com webhook events | Not built |
The endpoints below live under /api/v1/providers/cal-com/.... They are generic:
the same routes serve any registered provider by substituting the {provider}
path segment. All routes require an organization-scoped user token (see
Authentication).
Discovery#
GET /api/v1/providers/cal-com
{
"status": "success",
"data": { "provider": "cal-com", "capabilities": ["SYNC", "USER_IMPORT"] }
}
Credential Verification#
Cal.com API keys can be stored and verified for API sync:
PUT /api/v1/providers/cal-com/credentials?organization_id=<id>
POST /api/v1/providers/cal-com/credentials/verify?organization_id=<id>
The stored secret is a Cal.com API key beginning with cal_:
{ "secret": "<cal-com-api-key>" }
Verification sends the key as a bearer token to GET /v2/me, then performs a
one-item, one-second bounded GET /v2/bookings probe. This proves both profile
and booking read access. A malformed key, rejected key, or booking-access refusal
returns invalid_api_key. Stored secrets are encrypted at rest and are never
returned by credential endpoints.
Importing From Cal.com#
POST /api/v1/providers/cal-com/imports/sync?organization_id=<id>
The adapter uses the organization's stored encrypted key and calls:
GET https://api.cal.com/v2/meGET https://api.cal.com/v2/bookings
Booking requests send cal-api-version: 2026-05-01, an explicit TeamBoost
service User-Agent, and a maximum page size of 100. The first shipped window is
bounded to seven days in the past through 90 days in the future. It follows
nextCursor while hasMore is true and rejects missing or repeated cursors
instead of returning a partial import.
Network failures, rate limits (429), and transient server failures are retried
with bounded backoff. Authentication and permission failures are not retried.
The sync requests all booking states returned within the window; it does not
attempt organization-wide directory or booking access.
User Mapping#
USER_IMPORT rides the booking sync. The adapter proposes mappings from:
- the authenticated Cal.com profile;
- every booking host;
- booking attendees;
- guest email addresses.
Cal.com numeric user id is the primary identity when present, followed by a
case-insensitive email match. A name is display-only and does not merge otherwise
unidentified users. The first mapped host may become creatorId; additional
hosts, attendees, and guests stay in review context and are not assigned as task
owners or requesters.
Projection Field Coverage#
| Cal.com source | TeamBoost draft field | Notes |
|---|---|---|
Booking title |
title |
Missing or shorter-than-two-character titles are blocking projection errors |
| Booking | type |
Meetings default to OTHER with a mapping note |
Booking description |
description |
Passed through when present |
Booking status |
status |
accepted, pending, and awaiting_host map to NOT_STARTED; cancelled and rejected map to CANCELED; unknown values are left unset |
| No native task priority | priority |
Defaults to UNKNOWN with a mapping note |
| First host | creatorId |
Resolved by Cal.com id, then email, when a TeamBoost mapping exists |
| Attendees and guests | ownerId, requestedById |
Both remain unset; actors are preserved for mapping and review context |
Booking start / end |
plannedStartDate, estimatedStartDate, plannedEndDate |
Missing, invalid, or reversed required dates are blocking errors |
| Cal.com | projectTitle |
Defaults to Cal.com |
| Booking ids, status, event type, actors, location, meeting URL, fields, cancellation, reschedule links, and sync profile | descriptionJson |
Preserved for review |
Meeting duration is preserved as context and is not converted into TeamBoost effort. An elapsed meeting is never inferred to be completed merely from its end time. A missing stable booking UID is a blocking projection error.
Not Built Yet#
- CSV import.
- OAuth app installation.
- Organization-wide booking or directory access.
- Standalone user-directory import before sync.
- Webhook registration and event verification.
- Provider-specific sync filters or persisted incremental sync state.
- Background sync jobs.