Skip to main content
The Calendar API operates on a specific organization member’s connected Google Calendar. It is member-scoped: every event read or written acts on one member’s primary Google Calendar. Because API keys are organization-scoped (not tied to a single user), the caller must identify the acting member with a userId on every event call. That member must have connected Google Calendar inside FlowEstate.
Member resolution. For API-key callers, userId is required — pass the id of the member whose calendar to use. For OAuth-token callers, userId is optional and defaults to the token’s owner. If userId is supplied but is not a member of the authenticated organization, the API returns 404 INVALID_MEMBER. If the resolved member has not connected (or has disconnected) Google Calendar, the API returns 403 FORBIDDEN with a reconnect message.
Scheduling a meeting respects the same lead-visibility rules as the rest of the API: a member can only schedule on leads they are allowed to access.

Get the calendar timezone

Scope: calendar:read. Returns the organization’s IANA timezone. Use it to render and interpret the local wall-clock times accepted by the event endpoints. This call is org-scoped and does not require userId.

Request

Response 200

When the organization has no timezone configured, FlowEstate falls back to America/Panama.

List events

Scope: calendar:read. Lists the acting member’s primary-calendar events within a time window. Recurring events are expanded into individual instances and ordered by start time.

Query parameters

Request

Response 200

Event fields

Common errors

  • 400 BAD_REQUEST — userId is missing (API-key callers must pass it).
  • 400 VALIDATION_ERROR — timeMin / timeMax missing or not ISO 8601 with offset.
  • 403 FORBIDDEN — the member has not connected Google Calendar, or their authorization expired. The message asks them to reconnect their calendar in FlowEstate.
  • 404 INVALID_MEMBER — userId is not a member of this organization.

Schedule a meeting

Scope: calendar:write. Creates a Google Calendar event on the member’s primary calendar and logs a meeting activity on the lead’s timeline. The lead’s email (when present) is added as an attendee, and Google sends invitations to all attendees.

Request body

Use GET /calendar/timezone to confirm the organization timezone, then send startAt as a naive local time. Do not include an offset — that is added by the server.

Response 201

activityId is the id of the meeting activity logged on the lead. It may be absent if the activity could not be persisted.

Common errors

  • 400 BAD_REQUEST — userId is missing (API-key callers must pass it).
  • 400 VALIDATION_ERROR — invalid leadId, malformed startAt, or durationMinutes out of range.
  • 403 FORBIDDEN — the member has not connected Google Calendar, or their authorization expired. The message asks them to reconnect their calendar.
  • 404 INVALID_MEMBER — userId is not a member of this organization.
  • 404 NOT_FOUND — the lead does not exist or is not visible to the acting member.

Webhook side effects

A lead.communication_logged event is dispatched (a meeting, outbound), mirroring a logged communication so external integrations also see the booked meeting.

Update an event

Scope: calendar:write. Updates the member’s event. Only the fields you send are changed; existing attendees are preserved. When the event is linked to a lead’s meeting activity, FlowEstate keeps that activity’s time and note in sync (best effort).

Request body

eventId comes from the path — do not include it in the body.

Response 200

Common errors

  • 400 BAD_REQUEST — userId is missing (API-key callers must pass it).
  • 400 VALIDATION_ERROR — missing title, malformed startAt, or durationMinutes out of range.
  • 403 FORBIDDEN — the member has not connected Google Calendar, or their authorization expired. The message asks them to reconnect their calendar.
  • 404 INVALID_MEMBER — userId is not a member of this organization.

Delete an event

Scope: calendar:write. Deletes the member’s event from Google Calendar and removes the linked lead meeting activity, if any. Deleting an already-deleted event is treated as success.

Query parameters

Request

Response 200

Common errors

  • 400 BAD_REQUEST — userId is missing (API-key callers must pass it).
  • 403 FORBIDDEN — the member has not connected Google Calendar, or their authorization expired. The message asks them to reconnect their calendar.
  • 404 INVALID_MEMBER — userId is not a member of this organization.