Customers and readiness

Persons and identities

A person is a durable customer identity within a tenant: a display name and, usually, an email (POST /persons). A person can carry several identities — the email they booked with, the alias an OTA relays their messages through, a phone — and GET/POST /persons/{person_id}/identities manages them. Two records that turn out to be one human are joined with POST /persons/{person_id}/merge and can be separated again with /unmerge; POST /persons/{person_id}/profile-corrections fixes a name or email with an audit trail.

GET /persons/{person_id}/participations lists everything the person has taken part in; GET /persons/{person_id}/correspondence lists the conversation history attached to them.

Participants

A participant is a person’s role in a context — most often a rider on a booking, but also a member of a programme or a lead on an offering. POST /participants attaches one to a context. The person link is optional: a storefront can record “two riders” before it knows who they are, and the names and details arrive later through a party link (/p/{token}) without inventing a person prematurely.

Participants can carry traits — typed facts such as height, a certification, a dietary note — defined per tenant (POST /participant-trait-definitions) and set per participant (POST /participant-trait-values).

Readiness and waivers

Readiness is whether a participant has done what the tenant requires before they can take part: signed the waiver, attested their age or ability, completed a briefing. The pieces are:

1. Requirements (POST /readiness-requirements) — what the tenant asks of participants on a given offering, versioned.
2. Readiness links (POST /readiness-links, or POST /participants/{id}/waiver-links) — a capability token minted per participant with a TTL, shown once. The guest opens /w/{token}, which returns their per-requirement status, and submits through POST /w/{token}/attestations.
3. Attestations (POST /readiness-attestations) — the immutable, effective-dated outcome of one requirement for one participant. A failing outcome is recorded too; it simply does not satisfy the gate. A mistake is corrected by appending a correction, never by editing.

GET /participants/{participant_id}/readiness and GET /bookings/{booking_id}/… reads show what is outstanding; POST /bookings/{booking_id}/readiness-requests re-sends the ask to everyone on the booking who has not completed theirs.

Organisations

An organisation (POST /organizations) models a company, school or group that books on behalf of people, with memberships (POST /org-memberships) and a parent tree. Relationship edges (POST /relationship-edges) record ties between persons — a guardian and a minor, a group leader and a member — and are superseded rather than deleted.

Guests

GET /guests and GET /guests/{key} are the operator’s read-optimised view of customers: one card per human with their bookings, open balances, readiness and recent messages, keyed by email or person id. Use it to render a customer screen; use /persons/* to change facts.

Customer self-service

A customer who signs in (see Authentication → customer sessions) reaches /account/*: their bookings and participations, a cancellation quote, a self-serve cancellation or rebook within the policy, their readiness status, and a balance link for anything owed. A customer session carries no operator authority and sees only its own person’s records.