Guides

Session Setup

POST /v1/personas/session — bind a seat’s members and their ages for the session.

POST /v1/personas/session binds the seat roster for a passenger session: who is on which seat, and each member’s declared age band. This is what gives a member their real age tier — until you bind them, every member resolves to Unknown and is served the child-safe catalog. Do it once, early in the session, before scored serves or suggestions.

Session-scoped — requires the X-Session-Id header. Body (max 64 KiB):

FieldRequiredRules
membersyes1–20 entries. Empty or > 20 → 422 request.validation.
members[].seatIdyesNon-blank.
members[].ageBandyesNon-blank declared band — e.g. "adult", "8-12", "under-5". A binding input, not the authoritative tier.
members[].memberSlotnoWhich member on a shared seat. Omit for a solo traveler.
members[].archetypeIdnoOptional starting persona — an archetypeId from GET /v1/personas.
members[].roleInGroup, members[].gendernoOptional descriptors.
flightInstanceIdnoTop-level (not per member). Binds the session to a registered flight. 1–128 characters, non-blank, no control characters — otherwise 422 request.validation. The message names the field and never echoes your value back. Read the replace-in-full rule below before you omit it.
$curl -X POST "https://api.staging.westiq.ai/v1/personas/session" \
>  -H "Authorization: Bearer $ACCESS_TOKEN" \
>  -H "X-Session-Id: seat-12A-f3d9c1" \
>  -H "Content-Type: application/json" \
>  -d '{
>        "members": [
>          { "seatId": "12A", "ageBand": "adult" },
>          { "seatId": "12A", "memberSlot": "slot-2", "ageBand": "8-12" }
>        ],
>        "flightInstanceId": "NH0007-2026-07-27"
>      }'
1{
2  "schemaVersion": "1",
3  "correlationId": "req_0197c0a1b2c3d4e5f60718293a4b5c6d",
4  "boundMembers": 2,
5  "ageTiers": ["Adult", "Child"],
6  "flightBindingApplied": true
7}
  • boundMembers is how many profiles were persisted.
  • ageTiers is the server-resolved tier for each member, in the same order as your members array. It is echoed for your display only — every later serve / suggest / enrich call re-resolves the tier from the stored profile and never trusts this value back.

Age resolution is fail-closed. An unknown, blank, or unparseable ageBand resolves to Unknown — treated as the most-restrictive Child tier — never a permissive default. A member you don’t bind at all is also Unknown. So a Child/Unknown in ageTiers for someone you meant to be an adult means the ageBand string wasn’t recognized — check it.

Binding the session to a flight

Sending flightInstanceId binds this session to a registered flight. Once bound, and once that flight has an active catalog pushed, the session’s search, scored serve, and suggestions results are narrowed to the titles actually loaded on the aircraft.

Each call sets the flight context in full — it is never merged.

  • Supplying flightInstanceId replaces whatever flight the session was bound to.
  • Omitting it removes any binding an earlier call left on this session.

If you re-run session setup mid-flight — to add a member, say — and leave the field out, you are unbinding the flight, and results widen back to the full airline catalog. Send flightInstanceId on every call that should stay bound.

flightBindingApplied (boolean, always present) reports the outcome:

  • true — the flight outcome you asked for is in effect: bound to the id you supplied, or, when you omitted it, any earlier binding removed.
  • false — the flight step did not take effect. The roster bind still succeeded and the response is still a 200, but results are not narrowed to the flight you named — and a previously bound flight may still be narrowing them. Retrying the call re-applies it.

Treat false as “retry this call”, not as a failed session setup. Everything else in the response is valid.

Errors

Standard envelope: 400 session.unresolved (missing/invalid X-Session-Id), 401 / 403 auth, 422 request.validation (empty members, more than 20, any member missing seatId/ageBand, or a malformed flightInstanceId), 500.