Guest Invitations and Passes

Use these endpoints with a customer bearer token under https://edge.tiquo.app/api/client/v1. The token determines the organisation and customer. Do not send organisation or customer IDs in the body.

The invitation endpoints need a signed-in customer with a completed profile and return 403 until the profile is complete; GET /guest-passes returns an empty list instead. For an end-to-end walkthrough with the browser packages, see Custom Guest Invitations.

How a Guest Pass moves

In limited mode (requiresGuestPass is true on the flow):

1. Creating an invitation reserves one use of the inviter's Guest Pass. A reserved use can't be spent on another guest.
2. Accepting keeps the use held for that guest. It doesn't deduct it.
3. Registering the guest at reception consumes the use.
4. Expiry or revocation returns the use to the inviter, without marking it consumed.

In unlimited mode nothing is reserved, and maxGuestsPerSubmission limits each submission instead. See Guest Passes for expiry times.

List live guest passes

GET /guest-passes

The response is { success: true, data: { guestPasses: [...] } }. A customer without a linked profile receives an empty array.

Each entry is one invitation, not a count of the customer's Guest Passes. For how many Guest Passes or Access Passes the customer has left, use GET /pass-balances.

Only live invitations are listed. Revoked and expired invitations, and ones already used at reception, drop off the list, so it has no history.

Tracking the invitations a member sent

GET /guest-passes doesn't return share tokens or invite links, and it shows a pending and an accepted sent invitation the same way (assigned). To show "waiting for your guest", or to let a member share a link again:

• Store each invitation's token and inviteUrl when you create it.
• Read its current status (pending, accepted, revoked or expired) with GET /guest-invitations?token=.

Create invitations

POST /guest-invitations

Retrieve the saved configuration with GET /guest-flows first. Generate one UUID v4 token per guest and retain it for retries of the same pending invitation.

const input = {
  flowId: 'guest_flow_123',
  visitDate: '2026-10-12',
  locationId: 'location_123',
  guests: [{ token: crypto.randomUUID(), guestFirstName: 'Alex' }],
};

const response = await fetch(
  'https://edge.tiquo.app/api/client/v1/guest-invitations',
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${accessToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(input),
  },
);
const result = await response.json();
if (!response.ok || !result.success) throw new Error(result.error);
const invitations = result.data.invitations;

flowId, visitDate, and a non-empty guests array are required. Each guest needs token and guestFirstName. Supply locationId when the flow has several eligible locations. The visit date uses the selected location's timezone.

When requiresGuestPass is true, available unassigned passes limit the invitation count. Otherwise, use maxGuestsPerSubmission. The server checks the saved flow, location, date, and allowance. The whole batch succeeds or fails together.

Successful creation returns data.invitations. Each invitation has its status, guest and venue details, expiry, inviteUrl, and substituted shareText. Use the returned inviteUrl: it reflects the saved portal or custom website destination. Do not construct a portal URL from the token.

Validation rules

• visitDate is YYYY-MM-DD and must be today or later in the location's timezone.
• guestFirstName is 1 to 100 characters after trimming.
• Each token is a UUID v4 and must be unique within the request.
• A customer can create up to 120 invitations an hour.

Retries and changes

Sending the same token again with exactly the same flow, date, location and guest name returns the existing pending invitation, so a retry never reserves a second pass. Changing any of those, or reusing the token of an invitation that is no longer pending, fails with This guest invitation link cannot be reused.

Invitations can't be edited. To change the date, location or guest, create a new invitation with a new token. The member can't cancel the old one through the API; it expires at the end of its visit date, or staff can revoke it (see Limitations).

Read an invitation

GET /guest-invitations?token=<invitation-token>

A signed-in customer with a completed profile can read the invitation's current state. The response is { success: true, data: { invitation } }. A missing invitation or an invitation from another organisation returns invitation: null. Omitting the token is a 400 error.

Invitation fields include token, organizationId, flowName, venueName, guestFirstName, visitDate, sublocationNames, status, expiresAt, and inviteUrl. Optional fields include inviterName, guestPassName, customInvitationUrl, and portalSlug. Status is pending, accepted, revoked, or expired.

Because the endpoint needs a signed-in customer, a custom landing page can't show the invitation's details to a guest before they sign in. Show a generic welcome, sign the guest in, then read and accept the invitation.

Accept as the guest

POST /guest-invitations/accept

Send { "token": "<invitation-token>" } using the guest's bearer token. The guest must have a completed profile in the invitation's organisation. Success returns data.organizationId and, when applicable, data.portalSlug.

Accepting an invitation already accepted by the same customer succeeds again. These are rejected:

• an expired or revoked invitation, or one from another organisation;
• an invitation already accepted by someone else;
• the inviter accepting their own invitation;
• an invitation whose reserved Guest Pass is no longer valid, for example because the inviter's pass expired.

Acceptance doesn't register the guest's arrival or consume the pass. Only accepted invitations can be registered at reception; see Customer Registration.

Guest landing page on your own site

A Guest Flow sends guests to the destination saved on the flow in Settings > Registration > Guest Pre-Registration, under Guest invitation destination: a customer portal, or My own website.

With My own website, each inviteUrl is your URL with the token added as ?invitation=<token>. The URL must use HTTPS; plain HTTP is accepted only for localhost. Portal destinations use /invite/<token> on the portal instead.

On your landing page:

1. Read the invitation query parameter.
2. Sign the guest in with the same organisation's Website SDK public key, and allow your domain under Settings > Website SDK.
3. Make sure the guest's customer profile is complete.
4. Call POST /guest-invitations/accept with the token.
5. Optionally list GET /guest-passes, where the received pass appears as accepted.

Limitations

• Cancelling: customers can't cancel or revoke an invitation they sent. Staff can revoke pending invitations in Settings > Registration, under Guest Flow invitations, which lists the latest 100 invitations. Revoking needs the registration permission. Accepted invitations can't be revoked; they expire on schedule.
• Editing: invitations can't be edited. Create a new one instead.
• Sent-invitation tracking: store tokens yourself, as described in Tracking the invitations a member sent.
• Pre-sign-in preview: an invitation can't be read before the guest signs in.

Errors

Most 400 responses carry a specific message you can show, such as Guest visit date must be today or later., Choose a location for this guest invitation., Each guest must have a unique invitation token., This guest invitation has expired. or You cannot accept your own guest invitation.. A badly formatted token or guest name, too few available passes, or too many invitations in an hour return a general message asking the customer to check the guest details, location, visit date and available passes.

Browser package helpers

The DOM Package (1.9.1 or newer) and the Hosted Package expose:

For pass counts, both packages also have getPassBalances(); see Pass Balances.

DOM Package failures throw a TiquoAuthError with code GUEST_PRE_REGISTRATION_FAILED and the server's message.

See Guest Passes for configuration and staff registration rules.