--- title: "Get paginated provisional bookings" method: GET path: "/v4/provisional-booking/paginated" tags: ["Provisional Booking V4"] --- # Get paginated provisional bookings `GET /v4/provisional-booking/paginated` ## Request - Base URL: `https://developer.meetergo.com` (the document declares no server; this is the origin it was published from) - URL: `https://developer.meetergo.com/v4/provisional-booking/paginated` - Auth: one of: - API key in header `x-meetergo-api-user-id` - HTTP bearer - HTTP bearer Retrieves a paginated list of provisional bookings based on the provided criteria. ## Query parameters - `page` number, required - `pageSize` number, required - `all` boolean - `userId` string - `meetingTypeId` string - `workspaceId` string - `status` 'pending' | 'confirmed' | 'expired' | 'declined_by_host' - `type` 'doubleOptIn' | 'requireHostConfirmation' ## Response `200` Successfully retrieved paginated provisional bookings - PaginatedProvisionalBookingsResponseDto - `provisionalBookings` ProvisionalBookingPayloadResponseDto[], required - `id` string, required - `dto` BookingDto, required - `attendee` CreateAttendeeDto, required - `email` string, email: Attendee email address. Required for all standard bookings. Optional only when `BookingDto.phoneOnlyBooking` is true. Validated as email format when provided. - `firstname` string: Either fullname or firstname/lastname is required - `lastname` string: Either fullname or firstname/lastname is required - `fullname` string: Either fullname or firstname/lastname is required - `receiveReminders` boolean, required - `bringalongEmails` string[]: Additional attendee emails (max 5) - `notes` object, required: An object containing attendee form entries. - `billingDetails` BookingBillingDetailsDto - `company` string - `addressLine1` string - `addressLine2` string - `postalCode` string - `city` string - `countryCode` string: ISO 3166-1 alpha-2 - `vatId` string: USt-IdNr. - `phone` string - `language` 'en' | 'de' | 'fr' | 'es' | 'no' | 'nl' | 'it' | 'pl' | 'se' | 'tr' | 'da' - `timezone` string - `dataPolicyAccepted` boolean - `meetingTypeId` string, required: ID of the meeting type to book. - `hostIds` string[]: Host IDs for the booking. Required for one-on-one bookings (specific host selection). Optional for round-robin/queue bookings where queueId is provided instead. When sent TOGETHER with `queueId`, these IDs scope the round-robin to a subset of the queue: the backend rotates only among these hosts (used by `?hosts=` subset links). Empty/omitted with `queueId` = the whole queue. - `start` string, required - `appointmentId` string - `location` string - `locationSelectionContextId` string: Opaque Finder context exchanged immediately before entering booking. - `queueId` string: required when meeting type has a queue (round-robin / co-host) must be undefined for non-queue meetings (one-to-one / group) if host selection is true, queue id is required if fastest host selection is chosen if hosts selection is true, queue id must be undefined if a specific host is chosen to round-robin within a SUBSET of the queue, send queueId together with the subset `hostIds` (the backend rotates only among those hosts) - `bookingTargetToken` string: Opaque booking-block audience context from booking info. - `channel` 'local' | 'local-attendee' | 'google' | 'zoom' | 'phone' | 'phone-incoming' | 'whatsapp' | 'connect' | 'webex' | 'skypeForConsumer' | 'skypeForBusiness' | 'teamsForBusiness' | 'teamsForBusiness2' | 'teamsForExchange' | 'teams2ForExchange' | 'custom' | 'resource' | 'whereby' | 'kmeet' | 'zava' | 'jitsi' | 'nextcloudTalk' | 'openTalk' | 'alfaview': Meeting channel/location type - `duration` number: Duration in minutes for the booking. Optional. If not provided, uses the meeting type's default duration. If provided, must match either the default duration or one of the allowed durations configured for the meeting type. Primarily needed when meeting type has multiple duration options (allowedDurations). - `routingFormId` string - `utm` UtmDto - `utm_source` string - `utm_medium` string - `utm_campaign` string - `utm_content` string - `utm_term` string - `referrerUrl` string - `sourceChannel` 'booking_page' | 'embed' | 'web_widget' | 'whatsapp_agent' | 'phone_agent' | 'form' | 'gbp' | 'manual' | 'business_card' - `ignoreAvailability` boolean: Skips availability, working-hours, conflict and group-capacity checks (instant booker, Platform API). Only honored when the caller is authenticated as a member of the meeting type's company, by JWT or by API key plus `x-meetergo-api-user-id`; anonymous bookings have it normalized to false server-side. - `isTest` boolean: Marks the booking as a rehearsal the host made for themselves, so it is excluded from the activation milestone (`firstBookingAt` must only ever come from a real third party). The appointment itself is real: the calendar entry and the confirmation mail are produced exactly as they would be for an invitee, which is the point of the onboarding self-test. Same trust model as `ignoreAvailability`: only honored for authenticated callers from the meeting type's own company, so a public attendee cannot suppress a host's activation by sending the flag. - `attendeePendingId` number: ID of pending attendee that will be deleted after successful booking. This is only needed when "collect during form entry" feature is used. If not provided, a successful booking may show up in pending contacts. - `paymentId` string - `paymentProvider` 'paypal' | 'stripe' | 'mollie' | 'none': Selected payment provider for this booking. Required when the meeting type has multiple payment providers enabled. If not provided, falls back to the first enabled provider. - `couponCode` string: Coupon code for a discount on paid bookings. Validated during payment order creation and re-validated at booking time. - `resourceChannelIds` string[]: Ids of the resource channel entity - `oneTimeLinkId` string: Id of the one time booking link. Required in order to invalidate the booking link, once booking is done - `bookingProposalId` string, uuid: The booking proposal the invitee arrived through. Lets the booking pass the proposal's own hold on the chosen slot and consumes the proposal once the booking is made. - `skipNotifications` boolean: Skip sending email notifications to the attendee for this booking - `phoneOnlyBooking` boolean: When true, attendee email is not required and phone becomes the identifier. Requires the meeting type to have `allowPhoneOnlyBooking` enabled in its options. Designed for voice agent / phone scheduling use cases where collecting email from the caller is not viable. - `icsTitle` string: Custom ICS calendar invite title. If provided, overrides the configured meeting type ICS title for this specific booking. Useful for AI-generated titles based on conversation context (e.g., from calgent). - `icsDescription` string: Custom ICS calendar invite description. If provided, overrides the configured meeting type ICS description for this specific booking. Useful for AI-generated descriptions based on conversation context (e.g., from calgent). - `rwgToken` string: Google Actions Center token for conversion tracking. This token is passed via the rwg_token URL parameter when users click through from Google Maps/Search. - `rwgMerchantId` string: Merchant ID associated with the rwg_token for Google Actions Center. Used to determine if merchant changed during booking flow. - `bookingPassword` string: Password for accessing a password-protected booking page. Required when the meeting type has password protection enabled. - `referralCode` string: Advocate referral code (from the /r/ referred-person landing). In `auto_booking` qualification mode the booking creates a pending referral recommendation for that advocate; otherwise it is ignored. - `formRecipientToken` string: Token of the personal form link that routed here (the `?fr=` URL param a routing form appends when it sends a recipient to a booking page). Links the appointment to the recipient, so a returning recipient is shown the booking they hold instead of an empty calendar, and a second booking through the same link is refused. Identifies only: an unknown token is ignored rather than failing the booking. - `waitlistToken` string: Waitlist unsubscribe token. When provided (from the ?wl= URL param on the booking link), the corresponding waitlist entry is removed after successful booking and the attendee is tagged as originating from the waitlist. - `type` 'doubleOptIn' | 'requireHostConfirmation', required - `createdAt` string, required - `deletedAt` string - `queueBookingInfo` NextQueueHostsSelectionReasonDto - `userIds` string[], required - `groupId` string - `selectionReason` object, required - `hosts` UserBasicDto[] - `id` string, required - `givenName` string, required - `familyName` string, required - `picture` string - `slug` string, required - `userType` string, required - `meetingTypeId` string - `total` number, required ## Other responses - `400`: The request did not validate. `message` lists the constraints that failed. - `401`: Missing, malformed, or expired credentials. - `403`: Authenticated, but not allowed: the plan does not include this feature, or the token is scoped away from it. - `429`: Rate limited. Back off and retry. --- [API](https://skmtc.dev/meetergo/apis/meetergo-platform-api.md) · [All operations](https://skmtc.dev/meetergo/apis/meetergo-platform-api/llms.txt) · [OpenAPI document](https://skmtc.dev/meetergo/apis/meetergo-platform-api/revisions/b5d66cd8be67?raw)