openapi: 3.2.0 info: title: Meetings Meeting External API version: 0.99.0 servers: - description: Production url: https://prod.apigateway.co/grpc tags: - name: MeetingExternal paths: /v1/meetings/book: post: description: Book a new meeting for a specified event type in a given business. operationId: MeetingExternal_BookMeeting requestBody: content: application/json: schema: $ref: '#/components/schemas/v1BookMeetingExternalRequest' description: Request message for booking a new meeting for a specified event type in a given business. required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/v1BookMeetingExternalResponse' description: A successful response. default: content: application/json: schema: $ref: '#/components/schemas/rpcStatus' description: An unexpected error response. security: - OAuth2: - meeting - business-app summary: Book meeting tags: - MeetingExternal /v1/meetings/cancel: post: description: Cancel a booked meeting identified by meeting ID for a given business. operationId: MeetingExternal_CancelMeeting requestBody: content: application/json: schema: $ref: '#/components/schemas/v1ExternalCancelMeetingRequest' description: Request message for cancelling an existing meeting. required: true responses: '200': content: application/json: schema: type: object description: A successful response. default: content: application/json: schema: $ref: '#/components/schemas/rpcStatus' description: An unexpected error response. security: - OAuth2: - meeting - business-app summary: Cancel meeting tags: - MeetingExternal /v1/meetings/event-type-availability-slots: post: description: List available time slots for a specified event type in a given business. operationId: MeetingExternal_ListAvailableTimeSlots requestBody: content: application/json: schema: $ref: '#/components/schemas/v1AvailableTimeSlotsRequest' description: Request message for listing available time slots for booking a meeting of a specific event type. required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/v1AvailableTimeSlotsResponse' description: A successful response. default: content: application/json: schema: $ref: '#/components/schemas/rpcStatus' description: An unexpected error response. security: - OAuth2: - meeting - business-app summary: List available time slots tags: - MeetingExternal /v1/meetings/event-types: post: description: List team event types for a given business (paginated). operationId: MeetingExternal_ListTeamEventTypes requestBody: content: application/json: schema: $ref: '#/components/schemas/v1ListTeamEventTypesRequest' description: Request message for listing team event types for a given business (paginated). required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/v1ListTeamEventTypesResponse' description: A successful response. default: content: application/json: schema: $ref: '#/components/schemas/rpcStatus' description: An unexpected error response. security: - OAuth2: - meeting - business-app summary: List team event types tags: - MeetingExternal /v1/meetings/groups: post: description: List all groups for a given business. operationId: MeetingExternal_ListGroups requestBody: content: application/json: schema: $ref: '#/components/schemas/v1GroupsRequest' description: Request message for listing all groups for a given business. required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/v1GroupsResponse' description: A successful response. default: content: application/json: schema: $ref: '#/components/schemas/rpcStatus' description: An unexpected error response. security: - OAuth2: - meeting - business-app summary: List groups tags: - MeetingExternal /v1/meetings/reschedule: post: description: Reschedule an existing meeting to a new time and/or location for a given business. operationId: MeetingExternal_RescheduleMeeting requestBody: content: application/json: schema: $ref: '#/components/schemas/v1ExternalRescheduleMeetingRequest' description: Request message for rescheduling an existing meeting to a new time and/or location. Either start_time or location is required. required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/v1ExternalRescheduleMeetingResponse' description: A successful response. default: content: application/json: schema: $ref: '#/components/schemas/rpcStatus' description: An unexpected error response. security: - OAuth2: - meeting - business-app summary: Reschedule meeting tags: - MeetingExternal /v1/meetings/services: post: description: List all services for a given business. operationId: MeetingExternal_ListServices requestBody: content: application/json: schema: $ref: '#/components/schemas/v1ServicesRequest' description: Request message for listing all services for a given business. required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/v1ServicesResponse' description: A successful response. default: content: application/json: schema: $ref: '#/components/schemas/rpcStatus' description: An unexpected error response. security: - OAuth2: - meeting - business-app summary: List services tags: - MeetingExternal /v1/meetings/user-event-types: post: description: List personal and team event types for a user. operationId: MeetingExternal_ListUserEventTypes requestBody: content: application/json: schema: $ref: '#/components/schemas/v1ListUserEventTypesRequest' description: Request message for listing event types for a user (personal and team) scoped by partner/business. required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/v1ListUserEventTypesResponse' description: A successful response. default: content: application/json: schema: $ref: '#/components/schemas/rpcStatus' description: An unexpected error response. security: - OAuth2: - meeting - business-app summary: List user event types tags: - MeetingExternal /v1/meetings/users: post: description: List users for a given business (paginated). operationId: MeetingExternal_GetUsers requestBody: content: application/json: schema: $ref: '#/components/schemas/v1GetUsersRequest' description: Request message for listing users with their meeting configuration status for a given business. required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/v1GetUsersResponse' description: A successful response. default: content: application/json: schema: $ref: '#/components/schemas/rpcStatus' description: An unexpected error response. security: - OAuth2: - meeting - business-app summary: List users tags: - MeetingExternal components: schemas: rpcStatus: properties: code: format: int32 type: integer details: items: $ref: '#/components/schemas/protobufAny' type: array message: type: string type: object v1IsoDateTimeRange: properties: end: type: string start: type: string type: object v1FormFieldType: default: FORM_FIELD_TYPE_INVALID description: " - FORM_FIELD_TYPE_SELECT: Legacy single-select; superseded by FORM_FIELD_TYPE_DROPDOWN.\n - FORM_FIELD_TYPE_MULTIPLE_CHOICE: Multiple choice: guest selects one or more of Field.options.\n - FORM_FIELD_TYPE_DROPDOWN: Dropdown: guest selects exactly one of Field.options." enum: - FORM_FIELD_TYPE_INVALID - FORM_FIELD_TYPE_TEXT - FORM_FIELD_TYPE_EMAIL - FORM_FIELD_TYPE_PHONE_NUMBER - FORM_FIELD_TYPE_SELECT - FORM_FIELD_TYPE_MULTIPLE_CHOICE - FORM_FIELD_TYPE_DROPDOWN type: string v1EventType: description: Event type configuration describing a bookable meeting type, including duration, location, and host details. properties: bookingUrl: description: Output only. Public booking URL where attendees can schedule this event type. readOnly: true type: string bookingWindow: $ref: '#/components/schemas/v1EventTypeDateRange' calendarType: description: Output only. Type or identifier of the calendar used when booking this event. readOnly: true type: string description: description: Output only. Optional. Description of the event type, visible in booking experiences. readOnly: true type: string duration: description: Output only. Duration of the scheduled meeting for this event type. readOnly: true type: string hostOrderDetails: description: Output only. Ordering or assignment details used to select a host for new bookings. items: $ref: '#/components/schemas/v1HostOrderDetails' readOnly: true type: array hostUsers: description: Output only. Users who can host meetings for this event type. items: $ref: '#/components/schemas/v1UserResponse' readOnly: true type: array id: description: Output only. Unique identifier of the event type. readOnly: true type: string isEmailRequired: description: Output only. Whether an attendee email address is required when booking. readOnly: true type: boolean isPhoneNumberRequired: description: Output only. Whether an attendee phone number is required when booking. readOnly: true type: boolean isVideoConferencingEnabled: description: Output only. Whether video conferencing is enabled. readOnly: true type: boolean location: description: Output only. Default location details for the meeting (e.g., address or meeting link). readOnly: true type: string locationGuidelines: description: Output only. Optional. Additional instructions or guidelines about the meeting location. readOnly: true type: string locationType: $ref: '#/components/schemas/v1MeetingLocationType' meetingType: $ref: '#/components/schemas/v1TeamEventMeetingType' name: description: Output only. Name of the event type shown to users and invitees. readOnly: true type: string title: EventType type: object v1Answer: properties: answer: items: type: string type: array id: type: string label: type: string type: $ref: '#/components/schemas/v1FormFieldType' type: object v1AvailableTimeSlotsResponse: description: Response containing a list of available time slots for booking. properties: timeSlots: description: Output only. Ordered list of available time slots in ISO date-time format, in the requested time zone. items: $ref: '#/components/schemas/v1IsoDateTimeRange' readOnly: true type: array title: AvailableTimeSlotsResponse type: object v1ServicesResponse: description: Response containing a list of all services for the specified business. properties: services: description: Output only. List of services available for the specified business. items: $ref: '#/components/schemas/v1ServiceResponse' readOnly: true type: array title: ServicesResponse type: object v1ListTeamEventTypesRequest: description: Request message for listing team event types for a given business (paginated). properties: businessId: description: Required. The business ID (starts with "AG-"). type: string cursor: description: Optional. Pagination cursor from previous response. Empty for first request. type: string pageSize: description: Optional. Number of items to return per page. Default/max page size is 50. format: int64 type: string required: - businessId title: ListTeamEventTypesRequest type: object v1DateRangeType: default: RELATIVE enum: - RELATIVE - CUSTOM type: string v1GroupsResponse: description: Response containing a list of all groups for the specified business. properties: groups: description: Output only. List of groups available for the specified business. items: $ref: '#/components/schemas/v1GroupResponse' readOnly: true type: array title: GroupsResponse type: object meetingsv1Contact: properties: email: type: string firstName: type: string isPrimary: type: boolean lastName: type: string phoneFields: $ref: '#/components/schemas/v1PhoneFields' phoneNumber: type: string timeZone: $ref: '#/components/schemas/typeTimeZone' title: 'TODO: For v2 of API, we''d like to merge Contact and Attendee into one message type' type: object v1BookMeetingExternalResponse: description: Response containing the details of the successfully booked meeting. properties: attendeeEmails: description: Output only. List of email addresses for all attendees successfully added to the meeting. items: type: string readOnly: true type: array eventTypeId: description: Output only. Unique identifier of the event type that was booked. readOnly: true type: string location: description: Output only. Location of the meeting. Empty for virtual; physical address for in-person. readOnly: true type: string meetingEndTime: description: Output only. Scheduled end time of the meeting in UTC. format: date-time readOnly: true type: string meetingId: description: Output only. Unique identifier of the booked meeting; use for rescheduling, cancellation, or retrieval. readOnly: true type: string meetingStartTime: description: Output only. Scheduled start time of the meeting in UTC. format: date-time readOnly: true type: string title: description: Output only. Title or subject of the meeting as it appears in calendar invitations. readOnly: true type: string userId: description: Output only. Unique identifier of the calendar owner (host) for this meeting. readOnly: true type: string title: BookMeetingExternalResponse type: object v1ServicesRequest: description: Request message for listing all services for a given business. properties: businessId: description: Required. The business ID (starts with "AG-"). type: string required: - businessId title: ServicesRequest type: object v1ListUserEventTypesResponse: description: Response containing the list of event types accessible for the given user and context. properties: eventTypes: description: Output only. List of event types (personal and team) the user has access to. items: $ref: '#/components/schemas/v1EventType' readOnly: true type: array title: ListUserEventTypesResponse type: object v1HostOrderDetails: properties: hostOrder: format: int64 type: string userId: type: string type: object v1GroupResponse: description: Details of a single group within a business. properties: bookingUrl: description: Output only. Public URL where users can book meetings with this group. readOnly: true type: string description: description: Output only. Optional. Description of the group and its purpose. readOnly: true type: string hexColor: description: Output only. Hex color code used for visual representation of the group. readOnly: true type: string id: description: Output only. Unique identifier of the group. readOnly: true type: string name: description: Output only. Display name of the group. readOnly: true type: string title: GroupResponse type: object v1Answers: properties: formAnswers: items: $ref: '#/components/schemas/v1Answer' title: The order of fields specified here is the order they will be displayed in type: array type: object typeTimeZone: description: 'Represents a time zone from the [IANA Time Zone Database](https://www.iana.org/time-zones).' properties: id: description: IANA Time Zone Database time zone, e.g. "America/New_York". type: string version: description: Optional. IANA Time Zone Database version number, e.g. "2019a". type: string type: object v1GroupsRequest: description: Request message for listing all groups for a given business. properties: businessId: description: Required. The business ID (starts with "AG-"). type: string required: - businessId title: GroupsRequest type: object v1BookMeetingExternalRequest: description: Request message for booking a new meeting for a specified event type in a given business. properties: attendees: description: Required. List of attendees to invite. Each must include at minimum a valid email address or valid phone number based on event type configuration. items: $ref: '#/components/schemas/meetingsv1Contact' type: array businessId: description: Required. The business ID (starts with "AG-"). type: string comment: description: Optional. Additional notes or description for the meeting; included in calendar invitations. type: string eventTypeId: description: Required. Unique identifier of the event type to be booked (defines duration, availability, and settings). type: string formAnswers: $ref: '#/components/schemas/v1Answers' hostUserId: description: 'Optional. Host user ID. Required for Team event type - ClientChoice and PriorityRoundRobin; ignored for RoundRobin and MultiHost. Must be one of the event type''s configured host user IDs.' type: string location: description: Optional. Location for the meeting. Empty for virtual; physical address for in-person. type: string start: description: Required. Desired start time of the meeting in UTC. System validates the slot is available. format: date-time type: string required: - businessId - eventTypeId - start - attendees title: BookMeetingExternalRequest type: object v1PhoneFields: properties: countryCode: title: Numeric country calling code (e.g., 1 for Canada, 91 for India) type: string extension: title: An extension number type: string nationalNumber: title: The main phone number without the country code type: string type: object v1ListTeamEventTypesResponse: description: Response containing a paginated list of team event types. properties: eventTypes: description: Output only. List of event types available for the specified business. items: $ref: '#/components/schemas/v1EventType' readOnly: true type: array hasMore: description: Output only. Whether more results are available beyond the current page. readOnly: true type: boolean nextCursor: description: Output only. Cursor for next page. Pass to ListTeamEventTypesRequest.cursor. Empty means no more pages. readOnly: true type: string title: ListTeamEventTypesResponse type: object v1GetUsersResponse: description: Response containing a list of users with their meeting connection status. properties: users: description: Output only. List of users with their configuration status. items: $ref: '#/components/schemas/v1UserResponse' readOnly: true type: array title: GetUsersResponse type: object v1ServiceResponse: description: Details of a single service within a business. properties: bookingUrl: description: Output only. Public URL where users can book meetings for this service. readOnly: true type: string description: description: Output only. Optional. Description of the service and its purpose. readOnly: true type: string hexColor: description: Output only. Hex color code used for visual representation of the service. readOnly: true type: string id: description: Output only. Unique identifier of the service. readOnly: true type: string name: description: Output only. Display name of the service. readOnly: true type: string title: ServiceResponse type: object v1ExternalRescheduleMeetingResponse: description: Response containing the updated details of the rescheduled meeting. properties: endTime: description: Output only. New scheduled end time of the meeting in UTC. format: date-time readOnly: true type: string eventTypeId: description: Output only. Identifier of the event type for this meeting. readOnly: true type: string location: description: Output only. Location of the meeting. Empty for virtual; physical address for in-person. readOnly: true type: string meetingId: description: Output only. Unique identifier of the rescheduled meeting. readOnly: true type: string startTime: description: Output only. New scheduled start time of the meeting in UTC. format: date-time readOnly: true type: string title: description: Output only. Title or subject of the meeting as it appears in calendar invitations. readOnly: true type: string title: ExternalRescheduleMeetingResponse type: object v1ExternalCancelMeetingRequest: description: Request message for cancelling an existing meeting. properties: businessId: description: Required. The business ID (starts with "AG-"). type: string cancellationReason: description: Optional. Reason for the cancellation. type: string meetingId: description: Required. Identifier for the meeting to cancel. type: string required: - businessId - meetingId title: ExternalCancelMeetingRequest type: object v1ListUserEventTypesRequest: description: Request message for listing event types for a user (personal and team) scoped by partner/business. properties: businessId: description: Required. The business ID (starts with "AG-"). type: string userId: description: Required. Unique identifier of the user to get their event types (user must belong to business). type: string required: - businessId - userId title: ListUserEventTypesRequest type: object v1RelativeDateRange: properties: unit: $ref: '#/components/schemas/v1RelativeTimeUnit' value: format: int64 type: string type: object v1ExternalRescheduleMeetingRequest: description: Request message for rescheduling an existing meeting to a new time and/or location. Either start_time or location is required. properties: businessId: description: Required. The business ID (starts with "AG-"). type: string location: description: Optional. The new location for the meeting. For virtual meetings, leave empty. For in-person, use physical address. type: string meetingId: description: Required. Identifier for the meeting to reschedule. type: string startTime: description: Optional. The new desired start time for the meeting in UTC. Either start_time or location is required. format: date-time type: string timeZone: $ref: '#/components/schemas/typeTimeZone' required: - businessId - meetingId - timeZone title: ExternalRescheduleMeetingRequest type: object v1MeetingLocationType: default: VIDEO enum: - VIDEO - IN_PERSON_USER_SITE - IN_PERSON_CLIENT_SITE type: string protobufAny: additionalProperties: {} properties: '@type': type: string type: object v1RelativeTimeUnit: default: DAYS enum: - DAYS - WEEKS - MONTHS type: string v1EventTypeDateRange: properties: customDateRange: $ref: '#/components/schemas/vendastatypesDateRange' dateRangeType: $ref: '#/components/schemas/v1DateRangeType' relativeDateRange: $ref: '#/components/schemas/v1RelativeDateRange' type: object v1TeamEventMeetingType: default: ROUND_ROBIN enum: - ROUND_ROBIN - CLIENT_CHOICE - MULTI_HOST - PRIORITY_ROUND_ROBIN type: string v1AvailableTimeSlotsRequest: description: Request message for listing available time slots for booking a meeting of a specific event type. properties: businessId: description: Required. The business ID (starts with "AG-"). type: string eventTypeId: description: Required. Identifier for the event type to retrieve available time slots for. type: string hostUserId: description: Optional. Host user ID; only used for ClientChoice and PriorityRoundRobin event types. Other types use event type's configured hosts. type: string timeSpan: $ref: '#/components/schemas/vendastatypesDateRange' timeZone: $ref: '#/components/schemas/typeTimeZone' required: - businessId - eventTypeId - timeSpan - timeZone title: AvailableTimeSlotsRequest type: object v1GetUsersRequest: description: Request message for listing users with their meeting configuration status for a given business. properties: businessId: description: Required. The business ID (starts with "AG-"). type: string required: - businessId title: GetUsersRequest type: object vendastatypesDateRange: properties: end: format: date-time type: string start: format: date-time type: string type: object v1UserResponse: description: User information including meeting connection status. properties: displayName: description: Output only. Full display name of the user. readOnly: true type: string isConnected: description: 'Output only. Whether the user has active connections to both a calendar provider (Google Calendar, Microsoft Outlook) and a meeting app (Google Meet, Microsoft Teams, or Zoom). Returns false if either connection is missing or inactive.' readOnly: true type: boolean userId: description: Output only. Unique identifier of the user (IAM user ID). readOnly: true type: string title: UserResponse type: object securitySchemes: OAuth2: flows: authorizationCode: authorizationUrl: https://sso-api-prod.apigateway.co/oauth2/auth scopes: business-app: Allows the application to manage all features of Business App meeting: Allows the application to book and manage meetings for your business(es) tokenUrl: https://sso-api-prod.apigateway.co/oauth2/token type: oauth2