Calendar

Calendar events for users, and the external calendars (Google or Microsoft) their events sync to.

📄️ Add Calendar Event

Creates a new calendar event with the specified details including type, date, duration, and location. Omit `ownerId` to make the authenticated user the owner. Requires the `event:save` permission for the owner or attendee. Consultations created without an attendee may have a closer assigned automatically, depending on settings; if closer availability is enforced and no closer is available, the request fails unless `errorOnCloserUnavailable` is `false`. Use `/calendar/event/upsert` instead when syncing from an external system or when you do not know whether the event already exists.

📄️ Get Calendar Event

Retrieves a single calendar event by its ID, including owner, attendee, and team details, and whether the caller can delete it. Requires permission to read the event. Use `/calendar/event/list` instead to find events by date range, owner, team, or location. An event syncs to the external calendars of its owner and attendee; to see whether one of them has Google or Microsoft connected and which calendar it lands in, call `/oauth/list` as that user.

📄️ List Calendar Events

Lists calendar events within a date range, optionally filtered by owner, team, location, role, event type, or outcome. Without `companyId` or `teamIds`, returns events for `ownerId`, or for the authenticated user when `ownerId` is omitted. Pass `companyId` or `teamIds` for a broader view; results are limited to what the `event:read` permission allows. Use `/calendar/event/get` instead when you already have an event ID.

📄️ Update Calendar Event

Updates an existing calendar event, identified by `eventId`, with new information such as time, location, or attendee. Only the fields you provide are changed; set `attendeeId` to `null` to remove the attendee. Requires the `event:save` or `event:manage` permission, and changing the attendee requires `event:manage`. Use `/calendar/event/upsert` instead when you only have an external `sourceId` or do not know whether the event exists.

📄️ Upsert Calendar Event

Creates or updates a calendar event in a single call — no need to check whether the event already exists. This is the recommended endpoint for external integrations (e.g. Zapier, CRM sync) because it eliminates the if/else logic of calling add vs update.

📄️ Remove Calendar Event

Removes a calendar event by its ID. This action cannot be undone. Non-Consultation events require the `event:delete` permission. Consultation events require `event:manage`, unless the owner removes them within the time window allowed by company settings.

📄️ List Closer Timeslots

Lists closers and their open appointment timeslots, for finding a time to book a Consultation. Set `targetId` to a User ID for that closer only (fails if the user is not a closer), or to a Team ID for closers directly on that team; omit it to use closers from the authenticated user's teams. `startTime` defaults to the start of the current hour and `days` defaults to 7. Pass `locationId` to exclude closers whose service area does not cover the location.

📄️ List Calendar Connections

Lists the authenticated user's external calendar connections: for each connected provider (Google Calendar or Microsoft Outlook), the ID of the calendar in that account that Terros writes the user's events to, and `invalid`, which means a Google sync has failed since the user last connected (it does not mean sync stopped). An empty `connections` array means no external calendar is connected, so events are not synced anywhere. Use it to answer whether a user's events reach Google or Microsoft and which calendar they land in; the event itself comes from `/calendar/event/get`. There is no `userId` parameter: to see another user's connections, make the request as that user (impersonating them needs `user:login`). Access tokens are never returned. `calendarId` is absent until the first event syncs, and the calendar's name is not stored.

📄️ Calendar Webhooks

This webhook is triggered when an action is taken on a calendar event.