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.Get the calendar timezone
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
America/Panama.
List events
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—userIdis missing (API-key callers must pass it).400 VALIDATION_ERROR—timeMin/timeMaxmissing 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—userIdis not a member of this organization.
Schedule a meeting
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
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—userIdis missing (API-key callers must pass it).400 VALIDATION_ERROR— invalidleadId, malformedstartAt, ordurationMinutesout 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—userIdis 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
Alead.communication_logged event is dispatched (a meeting, outbound), mirroring a logged communication so external integrations also see the booked meeting.
Update an event
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—userIdis missing (API-key callers must pass it).400 VALIDATION_ERROR— missingtitle, malformedstartAt, ordurationMinutesout 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—userIdis not a member of this organization.
Delete an event
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—userIdis 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—userIdis not a member of this organization.