Skip to content
aerandil.com
GitHub

Search Waitlist entry

POST
/v1/object-types/hospitality.waitlist_entry/search
curl --request POST \
  --url https://api.aerandil.com/v1/object-types/hospitality.waitlist_entry/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "branch": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "cursor": "example", "filters": [ { "property": "id", "type": "eq", "value": "example" } ], "limit": 1, "order": "asc", "property_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "scope": { "level": "tenant" }, "sort_by": "created_at" }'

Search for instances. Filters eq, contains, gte and lte AND-compose; or / not are additive follow-ups. Pages with an opaque cursor; the +1 fetch returns has_more without a second round-trip. Ordered by sort_by (default created_at) in order (default ascending), id breaking ties; rows with no value for a property key sort last.

A reservation request the house could not take, waiting for inventory to free up. Not a reservation status and not a reservation: nothing traverses a waitlist entry, so it consumes no availability by construction. Carries the request (property, guest, room type, rate plan, dates, occupancy) so accept_waitlist_entry can replay it through the ordinary guarded create path, plus the wait’s own bookkeeping — reason for turnaway analysis, priority tier and requested_at for the working order (tier, then FIFO within tier), and telephone for OPERA’s call-to-confirm flow. An offer — the desk’s, or the automation lane’s matcher on a freed room-night — keeps the room-nights for the guest in the ledger’s blocked count until offer_deadline, listing them in held_nights so accept, cancel, a lapse and expiry give back exactly what was held; a lapsed offer returns the entry to waiting and the matcher passes the room to the next. The night audit expires the entry two business days after its requested departure.

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
branch

Optional open-branch id. Search composes that branch’s copy-on-first-write overlay instead of main, so a preview reads its own hypothetical writes. Omit to read main.

string format: uuid
cursor

Opaque cursor from a prior response’s next_cursor. Pass back verbatim; do not introspect.

string
filters

Conjunctive list of predicates. Empty or omitted matches every row in scope, capped by limit.

Array
One of:
object
property
required
Allowed value: id
type
required
Allowed value: eq
value
required
string
limit

Page size. Server defaults to 50, silently clamps at 500 (AIP-158 §3).

integer
>= 1 <= 500
order

Direction of sort_by: asc (oldest / smallest first) or desc. A cursor is bound to the sort_by and order it was minted under; another pair is refused (422).

string
default: asc
Allowed values: asc desc
property_id

The house a desk stands in: keeps this property’s rows (property- or venue-scoped there) and every row scoped to no property (tenant, brand, portfolio), and drops a sibling house’s — the meaning property_id has on the event tail.

string format: uuid
scope
One of: discriminator: level
object
level
required
string
Allowed value: tenant
Allowed values: tenant
sort_by

What the page is ordered by: the row’s created_at or updated_at, or a property whose type orders — strings, enums and dates as text, ints, decimals and durations as numbers, datetimes as instants. Rows with no value sort last in either direction. A property the caller is not cleared to read is refused (403).

string
default: created_at
Allowed values: created_at updated_at id status reason priority requested_at arrival_date departure_date adults children telephone notes offered_at offer_notes accepted_at cancelled_at cancel_reason expired_at offer_deadline offer_origin offer_lapsed_at guest_notified_at guest_notice_note claim_token_hash claimed_at

Responses

Section titled “Responses”

200

Section titled “200”

Search results, ordered by (sort_by, id) in the requested order (ascending by default).

Media typeapplication/json
object
data
required
Array<object>
object
created_at
required
string format: date-time
id
required
string format: uuid
object_type
required
Allowed value: hospitality.waitlist_entry
properties
required
object
accepted_at
When the entry became a reservation
string format: date-time
adults
required
Adults
integer
arrival_date
required
Requested arrival
string format: date
cancel_reason
Why the wait was withdrawn
string
cancelled_at
When the wait was withdrawn
string format: date-time
children
Children
integer
claim_token_hash
SHA-256 of the current offer's claim-link secret
string
claimed_at
When the guest took the offer through its claim link
string format: date-time
departure_date
required
Requested departure
string format: date
expired_at
When the night audit aged the entry out
string format: date-time
guest_notice_note
Why the guest was not sent the current offer, when they were not
string
guest_notice_ref
The outbound message that told the guest of the current offer
string format: uuid
guest_notified_at
When the current offer was sent to the guest
string format: date-time
held_nights
The ledger nights the current offer holds (JSON array of dates)
id
required
Waitlist entry id
string
notes
Desk notes on the request
string
offer_deadline
When the current offer lapses and its held nights go back
string format: date-time
offer_lapsed_at
When an offer last lapsed unanswered; the matcher passes over the entry after
string format: date-time
offer_notes
What was offered on the last contact, and what the guest said
string
offer_origin
Who made the current offer: the desk, or the matcher on a freed room-night
string
Allowed values: desk matched
offered_at
When the desk last reached the guest with an offer
string format: date-time
priority
required
Priority tier (FIFO applies within a tier)
string
Allowed values: high normal low
quoted_rate
Waitlist entry quoted rate

Rate quoted when the request was taken (indicative only)

object
amount
required
string format: decimal
currency
required
string format: iso-4217
reason
required
Why the request could not be booked
string
Allowed values: sold_out room_type_unavailable rate_unavailable restriction guest_request
requested_at
required
When the guest asked (defaults to now; the FIFO key)
string format: date-time
status
required
Status
string
Allowed values: waiting offered accepted cancelled expired
telephone
Number to call when the room frees (the call-to-confirm flow)
string
provenance

Per-property source attribution and pins. An entry under properties means the property’s current value came from that source (on the source’s own clock, source_updated_at); an entry under pins is a human override protecting the property from sourced writes.

object
pins
object
key
additional properties
object
pinned_at
string format: date-time
pinned_by
object
reason
required
string
properties
object
key
additional properties
object
external_id
string
recorded_at
required
string format: date-time
source
required
string
source_updated_at
string format: date-time
stream
string
scope
required
One of: discriminator: level
object
level
required
string
Allowed value: tenant
Allowed values: tenant
tenant_id
required
string format: uuid
updated_at
required
string format: date-time
version
required
integer
>= 1
has_more
required
boolean
next_cursor

Cursor for the next page; omitted when the result set is exhausted.

string
Example
{
  "data": [
    {
      "object_type": "hospitality.waitlist_entry",
      "properties": {
        "offer_origin": "desk",
        "priority": "high",
        "reason": "sold_out",
        "status": "waiting"
      },
      "scope": {
        "level": "tenant"
      }
    }
  ]
}

422

Section titled “422”

Validation error — unknown property or filter type mismatch.