Guest Flows

Returns the organization's configured guest pre-registration flows for the authenticated customer. Generated URLs contain presentation and registration configuration; customer credentials are not placed in them.

Endpoint

GET /guest-flows

Example request

curl "https://edge.tiquo.app/api/client/v1/guest-flows" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9..."

Response

{
  "success": true,
  "data": {
    "guestFlows": [
      {
        "id": "guest_flow_123",
        "label": "Invite a guest",
        "themeId": "theme_123",
        "guestPassTypeId": "pass_type_123",
        "inviteMessage": "Register your guest before arrival.",
        "venueName": "Main Club",
        "locations": [{ "id": "location_123", "name": "Main Club" }],
        "maxGuestsPerSubmission": 3,
        "requiresGuestPass": true,
        "availableGuestPassQuantity": 5,
        "locationIds": ["location_123"],
        "invitationDestination": { "type": "custom", "url": "https://example.com/guests" },
        "hostedUrl": "https://portal.tiquo.app/guest-pre-registration/guest_flow_123?...",
        "embedUrl": "https://portal.tiquo.app/embed/guest-pre-registration/guest_flow_123?..."
      }
    ]
  }
}

Field	Type	Description
`id`	string	Guest-flow configuration ID
`label`	string	Public flow label
`themeId`	string	Theme used by the registration experience
`guestPassTypeId`	string or omitted	Required guest-pass type when guest-pass limits are enabled
`inviteMessage`	string	Configured invitation message
`venueName`	string	Location name when one location is available; otherwise `the selected location` until the inviter chooses
`locations`	object[]	Eligible location choices, each with an `id` and `name`
`maxGuestsPerSubmission`	integer	Per-submission guest limit when `requiresGuestPass` is false
`requiresGuestPass`	boolean	Whether invitations reserve a Guest Pass; use the available pass quantity as the limit when true
`availableGuestPassQuantity`	integer	Available unassigned uses of the required type in limited mode; the per-submission guest count in unlimited mode
`locationIds`	string[]	Parent location IDs associated with the flow, matching `locations`
`invitationDestination`	object or omitted	Where invited guests land. See Invitation destination and allowance
`hostedUrl`	string	Standalone guest-registration URL
`embedUrl`	string	Embeddable guest-registration URL

To find a flow's id, open Settings > Registration, find the flow under Guest Pre-Registration, and choose Copy Guest Flow ID from its menu.

When no customer profile is linked, or no guest flow is available, the endpoint returns 200 OK with an empty guestFlows array.

Locations and pass use

Guest Flows are configured against parent locations, not individual sublocations. A location is offered only when it has a sublocation that allows guest registration. Show a Location selector when locations has more than one entry. Use the only entry automatically when there is one. Do not render a sublocation selector from this response.

The selected location's name supplies the {{venue}} invitation variable. locationIds replaces the legacy sublocationIds flow field. New integrations should use locationIds and locations.

Sending an invitation reserves a Guest Pass in limited mode. Acceptance holds the reservation; staff registration consumes it. In unlimited mode, guestPassTypeId is omitted and availableGuestPassQuantity is not an owned pass balance. A returned flow can have zero available uses in limited mode, so do not treat its presence as proof that another invitation can be sent.

This endpoint lists invitation flows, not the customer's sent or received invitations. For the staff and customer behaviour, see Guest Passes and Customer Registration.

Hosted Package

The Hosted Package exposes this endpoint as window.Tiquo.getGuestFlows() and can render it with the data-tiquo-guest-flows collection attribute. The result is cached for the session; pass { refresh: true } or use getGuestFlow(flowId) for fresh data. The DOM Package has the same getGuestFlows() and getGuestFlow(flowId) methods and doesn't cache.

const { guestFlows } = await window.Tiquo.getGuestFlows();
const flow = await window.Tiquo.getGuestFlow('guest_flow_123');

Errors

Status	Description
`401`	Missing, invalid, or expired access token
`500`	Internal server error

Invitation destination and allowance

requiresGuestPass identifies limited flows. When true, use availableGuestPassQuantity for the invitation limit. When false, use maxGuestsPerSubmission; the available quantity is not an owned pass balance.

An optional invitationDestination is { type: 'portal', portalId } or { type: 'custom', url }. Legacy flows may omit it. Invitation creation returns the authoritative share URL for that saved destination. For a custom destination, the share URL is your page with ?invitation=<token> added; see Guest landing page on your own site.

Use Guest Invitations and Passes to create, inspect, or accept invitations, and to list live assignments.