The VIP journey

This is the flow our concierge desk actually runs, and the endpoint behind each step. Most integrations only need the first five; the rest happen whether or not you call anything.

Nothing here is mandatory. You can go straight from GET /v1/offers to POST /v1/redemptions and skip the whole interest stage — it behaves exactly as it always has. The steps below are what makes the concierge’s job possible before the points move, rather than after.

At a glance

#	Step	Endpoint	Who calls it
1	Browse experiences	`GET /v1/offers`	member or server
2	Register interest — opens a conversation	`POST /v1/interests`	member or server
3	Talk to a concierge	`POST /v1/conversations/{id}/messages`	member
4	Share dates and details	`PUT /v1/interests/{id}/intake`	member or server
5	Accept terms (if enabled)	`POST /v1/terms/acceptance`	member or server
6	Redeem — inherits the conversation	`POST /v1/redemptions`	member or server
7	Confirmation	`redemption.created` webhook	—
8	Logistics, itinerary, tickets	`GET /v1/conversations/{id}/messages`	member
9	Live updates	`streamMessages(id)`	member
10	Score the experience	`PUT /v1/redemptions/{id}/feedback`	member or server

1–2. Interest opens the conversation

A member does not have to spend anything to start talking to a concierge. An interest registers that they want an experience and opens the thread — no points debited, no inventory held.

curl -X POST https://api.expys.com/v1/interests \
  -H "Authorization: Bearer $MEMBER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "offer": "off_123", "preferredDates": ["2026-11-06"], "adults": 2 }'

The response carries conversationId. That thread is live immediately.

An interest holds no stock. A member who takes a week to decide can still lose the last unit — which is honest, where a silent hold would let one undecided member freeze inventory indefinitely. Show availability from the offer.

3–4. Chat, and the intake form

Pass conversationId to sendMessage and the member is talking to a concierge. Dates, party size and the rest go through the intake endpoint, which replaces the whole block each time. The three health fields — dietary, allergies, accessibility — are accepted here and never stored. See Interests and intake.

5. Terms, if your organisation requires them

Off by default. When Expys enables it, POST /v1/redemptions refuses an unaccepted member with TERMS_NOT_ACCEPTED and names the version, so you can open the sheet straight from the error. See Terms of service.

6. Redeeming from the interest

curl -X POST https://api.expys.com/v1/redemptions \
  -H "Authorization: Bearer $MEMBER_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "offer": "off_123", "interest": "req_abc" }'

Passing interest means the redemption inherits that conversation and the intake. No second thread opens, and the member keeps one continuous chat from first curiosity to post-trip follow-up.

redemption.conversationId is therefore not the redemption’s own id. For bookings made without an interest the two happen to be equal, and clients have relied on that. Read the field.

7–9. Fulfilment

Everything from here is our concierge team working, and reaches you without you asking:

redemption.* webhooks for every status transition
conversation.message_created for each concierge reply, with hasAttachments when they send tickets or an itinerary
streamMessages(conversationId) for the live thread in-app

Attachments come back on the message with short-lived signed links — fetch the message again rather than storing the URL. See Conversations.

10. Afterwards

curl -X PUT https://api.expys.com/v1/redemptions/req_123/feedback \
  -H "Authorization: Bearer $MEMBER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "rating": 9, "comment": "The guide made the whole trip." }'

Only a completed redemption accepts it. Averages come back per experience on GET /v1/analytics/offers.

What each step needs

Step	Credential	Idempotent
Interests, redemptions, terms	either	send an `Idempotency-Key`
Sending messages, the SSE stream	member token only	send a key on writes
Wallet credit, member upserts	Org-API-Key only	send a key

A member token acts as itself. An Org-API-Key names the member with externalUserID. See Authentication.

Getting started

Catalog and pricing

Booking and members

Wallets and points

Concierge

Server-side operations

Reliability and reference

The VIP journey

At a glance

1–2. Interest opens the conversation

3–4. Chat, and the intake form

5. Terms, if your organisation requires them

6. Redeeming from the interest

7–9. Fulfilment

10. Afterwards

What each step needs

​At a glance

​1–2. Interest opens the conversation

​3–4. Chat, and the intake form

​5. Terms, if your organisation requires them

​6. Redeeming from the interest

​7–9. Fulfilment

​10. Afterwards

​What each step needs

At a glance

1–2. Interest opens the conversation

3–4. Chat, and the intake form

5. Terms, if your organisation requires them

6. Redeeming from the interest

7–9. Fulfilment

10. Afterwards

What each step needs