Meetings API

The Meetings API manages scheduled meetings and calendar integration on the Altafid platform. It covers meeting creation and lifecycle, participant invitations and RSVP, staff availability checks, and two-way synchronisation with Google Calendar and Outlook.

Authentication and headers

Authenticated endpoints expect the standard gateway headers. Public RSVP links, OAuth callbacks, and provider webhooks are unauthenticated.

Meeting lifecycle

A typical meeting moves through availability checking, creation, invitation delivery, and external calendar sync. Participants then RSVP, and the host can update, resend, or cancel.

Meeting endpoints

POST/api/v1/meetings

Creates a meeting. Participants are supplied as platform contacts, platform staff, and free-form external attendees. Invitations are dispatched automatically and, if the host has a connected calendar, the meeting is queued for external sync. Returns 201 Created with a MeetingResponse.

{
  "title":            "Quarterly portfolio review",
  "startDateTime":    "2026-06-15T15:00:00",
  "endDateTime":      "2026-06-15T15:45:00",
  "timezone":         "America/Santiago",
  "allDay":           false,
  "locationType":     "ONLINE",
  "locationDetail":   "https://meet.google.com/abc-defg-hij",
  "description":      "Review Q2 performance and rebalancing plan.",
  "internalNotes":    "Bring the updated IPS draft.",
  "meetingProvider":  "GOOGLE_MEET",
  "meetingLink":      "https://meet.google.com/abc-defg-hij",
  "meetingPassword":  null,

  "contactIds":       ["C019B9D0FD0E5772F9E8ED189895D40C4"],
  "staffIds":         ["PS0199CA8F08C270B5A5B0DFD3B565B332"],
  "externalAttendees": [
    {
      "name":        "Jane Roe",
      "email":       "jane.roe@example.com",
      "language":    "ENGLISH",
      "countryCode": "+1",
      "phone":       "5551234567"
    }
  ]
}

List and filter

GET/api/v1/meetings returns the meetings on the current user's calendar as a MeetingListResponse.

POST/api/v2/meetings supports advanced filtering, paging, and sorting. Each filter condition names a field, an operator, and a value (or values / min / max depending on the operator).

{
  "filters": [
    { "field": "status",        "operator": "EQUALS", "value": "ACTIVE" },
    { "field": "startDateTime", "operator": "RANGE",  "min": "2026-06-01T00:00:00", "max": "2026-06-30T23:59:59" }
  ],
  "page": 0,
  "size": 20,
  "sort": ["startDateTime,asc"]
}

Update and cancel

PUT/api/v1/meetings/{meetingUuid} accepts the same fields as create — all optional. Omitted fields are left unchanged. Updating a meeting that is externally synced queues a follow-up sync.

POST/api/v1/meetings/{meetingUuid}/cancel moves the meeting to CANCELED and notifies participants. Use DELETE/api/v1/meetings/{meetingUuid}/calendar-visibility to remove a canceled meeting from the calendar view (204 No Content).

Invitations and sync

POST/api/v1/availability/check

Checks whether the given staff are free during a window. Returns one status per requested user.

{
  "userUuids":     ["PS0199CA8F08C270B5A5B0DFD3B565B332"],
  "startDateTime": "2026-06-15T15:00:00",
  "endDateTime":   "2026-06-15T15:45:00",
  "timezone":      "America/Santiago"
}

{
  "availabilities": [
    { "userUuid": "PS0199CA8F08C270B5A5B0DFD3B565B332", "status": "AVAILABLE" }
  ]
}

RSVP

Participants accept or decline an invitation. Authenticated users RSVP for themselves; guests use a per-participant public link delivered in their invitation email.

{ "status": "ACCEPTED" }

status is required and must be ACCEPTED or DECLINED. For the public GET link, pass it as a query parameter: ?status=ACCEPTED&token=....

Calendar connection

A host can connect a Google or Outlook calendar so meetings sync both ways. The OAuth flow is initiated from the API and completed in the provider's consent screen.

Webhooks

Providers push change notifications to these unauthenticated endpoints. They always return 200 even on internal sync errors, to prevent the provider from retrying.

Data model

Meeting

Returned by create, get, update, and sync. The summary form (used in list responses) carries a reduced subset.

Participant

ExternalAttendee

ResendInvitation

Returned by the resend endpoints: email and lastInvitationResentAt (null when the recipient was skipped).

Enum reference

The following fields accept a fixed set of values. Pass the exact string value shown.

locationType

status (meeting)

source

participantType

rsvpStatus

externalSyncStatus

lastSyncOperation

provider (calendar connection)

connection status

modal preference (firstTimeModalPref)

FilterOperator (v2 filtering)