Review invitations

Permissions

This API is only available to partners with the ROLE_REVIEW_INVITATION_VIEWER and
ROLE_REVIEW_INVITATION_EDITOR roles on their API key. If your API key doesn't have these yet,
contact us — we'll assess the request and enable them for you.

• ROLE_REVIEW_INVITATION_VIEWER — read invitations.
• ROLE_REVIEW_INVITATION_EDITOR — mark an invitation as sent (includes viewer access).

All requests use the same authentication as our other endpoints: an X-Api-Key header with your
API key.

How it works

A review invitation is created automatically once a guest checks in. It holds:

• id — the invitation's own id.
• token — the invitation's own token (not the reservation's token).
• url — a ready-to-use link to our review page. Send this link as-is in your email; it needs no
  further changes.
• status — unsent or sent.
• sent — when the invitation was marked as sent, or null if it hasn't been yet.
• reservation — the linked reservation, as { "id": ... }.

The review page behind url is public and doesn't require a reservation token, so it's safe to
include directly in an email.

Sending a review invitation

For each reservation you want to send a review request for, follow these steps:

1. Fetch the invitation for the reservation.

GET /api/review_invitations/reservation?reservation={reservationId}&token={reservationToken}

Use the reservation's own id and token, the same pair you already use for other
reservation-scoped endpoints. This returns the invitation, including its url.

2. Send your own email, using the url from the response as the review link.

3. Mark the invitation as sent.

PUT /api/review_invitations/{id}/mark_sent

This tells us the invitation has been handled, so we don't send our own automatic review email for
the same reservation, and so it no longer shows up as outstanding (see below). It only works once —
an invitation that's already sent cannot be marked as sent again.

Checking for outstanding invitations

To find reservations that still need a review invitation sent, use the list endpoint:

GET /api/review_invitations/?status=unsent&dateFrom={date}&dateTo={date}&referenceDate=date-to

• status — filter by unsent or sent.
• dateFrom / dateTo — a date range (YYYY-MM-DD) on the reservation. Must be used together.
• referenceDate — which reservation date the range applies to. Required when dateFrom/dateTo
  are used. Options:
  • date — the reservation date
  • date-from — the reservation's arrival date
  • date-to — the reservation's departure date
  • period — the reservation's stay overlaps the given range

For example, to find unsent invitations for reservations that departed yesterday:

GET /api/review_invitations/?status=unsent&dateFrom=2026-08-12&dateTo=2026-08-12&referenceDate=date-to

The response is paginated (limit, default 25, max 100; offset, default 0). For each result, use
the reservation id together with the reservation's own token (from your own records) to fetch the
full invitation and its url via the reservation endpoint above, then continue with steps 2 and 3.