Skip to content
Quikstik Developers

One guest with every booking, thread and held send

GET
/guests/{key}
curl --request GET \
  --url https://quikstik-core.fly.dev/guests/example \
  --header 'Authorization: Bearer <token>' \
  --header 'x-tenant-id: 2489E9AD-2EE2-8E00-8EC9-32D5F69181C0'

key is a GuestHit.key: person:{uuid} (the key whenever a person exists,), an email address (any case — a valid alias that resolves to the same person), booking:{uuid} (an obligation ref) or identity:{kind}:{value} (any identity the person owns: email, phone, viator_relay, gyg_relay, ota_ref). A person merged into another reads as the survivor. Bookings are newest departure first and include cancelled ones with their status; each carries its balance from the same read as GET /obligations/{obligation_ref}/balance. Threads are awaiting_us first, then by last activity. 404 when the key names nothing in this tenant, 422 invalid_key when malformed.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
key
required
string

Header Parameters

Section titled “Header Parameters”
x-tenant-id
required
string format: uuid

Tenant identifier (UUID).

Authn/authz semantics are intentionally TBD for this contract slice; this header exists to keep the contract explicitly multi-tenant from day 0.

Responses

Section titled “Responses”

200

Section titled “200”

The guest.

Media typeapplication/json
object
key
required
string
room
required

The person’s room, so the card opens it without a second lookup. Null when the guest is not a person yet.

object
ref_type
required
string
Allowed values: person
ref_id
required
string format: uuid
counts
required
object
guest
required

Guest-lane entries.

integer format: int64
team
required

Team-lane entries (0 on a guest session’s read).

integer format: int64
open_tasks
required

Task entries still open (0 on a guest session’s read).

integer format: int64
awaiting_us
required

Threads in this room awaiting our reply (0 on a guest session’s read).

integer format: int64
person
required
object
id
required
string format: uuid
display_name
required
string
email
required
string
nullable
status
required
string
Allowed values: active archived
display_name
required
string
email
required
string
nullable
phone
required
string
nullable
bookings
required

Newest departure first; cancelled bookings included with their status.

Array<object>
object
booking_id
required
string format: uuid
departure_id
required
string format: uuid
obligation_ref
required
string format: uuid
status
required
string
Allowed values: created cancelled
group_id
required
string format: uuid
nullable
created_at_ms
required
integer format: int64
updated_at_ms
required
integer format: int64
source_ref
required

OTA confirmation code (VIA-…, GET-…); null for storefront bookings.

string
nullable
channel_ref

The OTA’s own booking reference (BR-…, GYG-…), normalised; absent when the booking has none.

string
departure_start_time
required
string format: date-time
balance
required

Null when the booking’s obligation row is missing (the booking is then left out of the totals).

object
gross_minor
required
integer format: int64
settled_minor
required
integer format: int64
due_minor
required

gross_minor − settled_minor; equals GET /obligations/{ref}/balance.

integer format: int64
currency
required
string
suggested_condition

The condition a pin on this booking should carry: a balance due suggests obligation_settled/paid; null when nothing observable applies.

object
kind
required
string
Allowed values: obligation_settled outbound_on_thread departure_changed booking_status readiness inbound_on_thread ota_sync_succeeded booking_recorded
ref
required
string format: uuid
arg
object
key
additional properties
any
threads
required

awaiting_us first, then by latest activity.

Array<object>
object
id
required
string format: uuid
subject_norm
required
string
state
required

The thread’s state (open enum). notice: a bulk/system sender’s thread — in the stream and searchable, never waiting on us.

string
relay
required
string
Allowed values: none viator gyg
last_inbound_at_ms
required
integer format: int64
nullable
last_outbound_at_ms
required
integer format: int64
nullable
message_count
required
integer format: int64
suggested_condition

The condition a pin on this thread should carry: a thread awaiting us suggests outbound_on_thread; null otherwise.

object
kind
required
string
Allowed values: obligation_settled outbound_on_thread departure_changed booking_status readiness inbound_on_thread ota_sync_succeeded booking_recorded
ref
required
string format: uuid
arg
object
key
additional properties
any
held_sends
required
Array<object>
object
id
required
string format: uuid
thread_id
required
string format: uuid
created_at_ms
required
integer format: int64
hits
required
Array<object>
object
rule
required

Stable rule slug, e.g. fault_or_apology, amount_without_link, states_amount, no_cc.

string
matched
required
string
why
required

The rule in operator words.

string
prospect
required
object
status
required
string
Allowed values: inquired quoted booked lost
totals
required
object
bookings
required

Active (non-cancelled) bookings.

integer format: int64
balance_due_minor
required
integer format: int64
currency
required
string
nullable
open_threads
required
integer format: int64

Example 

{
  "room": {
    "ref_type": "person"
  },
  "person": {
    "status": "active"
  },
  "bookings": [
    {
      "status": "created",
      "suggested_condition": {
        "kind": "obligation_settled"
      }
    }
  ],
  "threads": [
    {
      "relay": "none",
      "suggested_condition": {
        "kind": "obligation_settled"
      }
    }
  ],
  "prospect": {
    "status": "inquired"
  }
}

401

Section titled “401”

Missing or invalid session bearer token

Media typeapplication/json
object
reason
required

Stable, machine-readable reason code (e.g. “sold_out”, “processor_not_configured”, “rail_refused”).

string

Example 

{
  "reason": "sold_out"
}

403

Section titled “403”

The session’s effect authority does not cover this operation

Media typeapplication/json
object
reason
required

Stable, machine-readable reason code (e.g. “sold_out”, “processor_not_configured”, “rail_refused”).

string

Example 

{
  "reason": "sold_out"
}

404

Section titled “404”

Expired, consumed, unknown, or unresolvable — indistinguishable by design

Media typeapplication/json
object
reason
required
string

Example generated

{
  "reason": "example"
}

422

Section titled “422”

key is not an email, person:{uuid} or booking:{uuid} (reason invalid_key).

Media typeapplication/json
object
code
required

Stable machine-readable error code

string
message
required

Human-readable explanation (never leaks SQL, URLs, or secrets)

string

Example generated

{
  "code": "example",
  "message": "example"
}

503

Section titled “503”

No durable backend is wired for this operation (fail-closed)

Media typeapplication/json
object
reason
required

Stable, machine-readable reason code (e.g. “sold_out”, “processor_not_configured”, “rail_refused”).

string

Example 

{
  "reason": "sold_out"
}