Search Property

POST

/v1/object-types/hospitality.property/search

const url = 'https://api.aerandil.com/v1/object-types/hospitality.property/search';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"branch":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","cursor":"example","filters":[{"property":"code","type":"eq","value":"example"}],"limit":1,"order":"asc","property_id":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","scope":{"level":"tenant"},"sort_by":"created_at"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://api.aerandil.com/v1/object-types/hospitality.property/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "branch": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "cursor": "example", "filters": [ { "property": "code", "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 single operated site — a hotel or resort, or a non-lodging business run on the same substrate (a standalone day spa). The property is the canonical home of most operational data and the anchor for local timezone, currency, and brand standards.

Authorizations

aerandil_oauth
objects:read
aerandil_oauth
objects:hospitality.property:read

Request Body^required

application/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: code

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 code name legal_name kind positioning timezone room_count opened_on standard_week_hours star_rating open_business_date business_date_opened_at visitor_key_grace_days waitlist_offer_hold_minutes request_soon_minutes waitlist_claim_url_base payment_request_reuse_terms description post_stay_charging_days hold_top_up_max_per_stay hold_top_up_interval_minutes credit_limit_overage fnb_open_checks_at_roll sca_chase_hours sca_chase_reminders

Responses

200

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

application/json

object

data

required

Array<object>

object

created_at

required

string format: date-time

required

string format: uuid

object_type

required

Allowed value: hospitality.property

properties

required

object

address

Property address

Address

object

city

required

string

country

required

string

line1

required

string

line2

string

postal_code

string

region

string

billing_identity

Property billing identity

Who this property is, legally, on a document it issues. Absent until an operator fills it in, and issue_invoice refuses without it — a tax invoice with no supplier registration number is not one. Snapshotted onto every invoice at issue, so editing this never rewrites a document already handed over.

object

bank_account

object

account_name

string

account_number

string

bic

string

iban

string

sort_code

string

company_registration_number

string

contact_email

string

contact_phone

string

invoice_address

object

city

required

string

country

required

string

line1

required

string

line2

string

postal_code

string

region

string

invoice_issue_deadline_days

integer

invoice_number_prefix

string

payment_terms_days

integer

simplified_invoice_threshold

object

amount

required

string format: decimal

currency

required

string format: iso-4217

tax_registration_number

string

tax_registration_scheme

required

string

Allowed values: vat gst sales_tax none

business_date_opened_at

Open business date opened at

When the open business date was opened. A posting stamped before this instant belongs to an earlier day and is dated by the property-local calendar instead.

string format: date-time

code

required

Property code

string

credit_limit_overage

What the night audit does once a stay's bill reaches what its holds are for: off, hold the excess, or charge (set_credit_limit_overage; off unset)

string

Allowed values: off hold charge

default_currency

required

Default currency (ISO 4217)

string format: iso-4217

description

Description

string

fnb_open_checks_at_roll

What the night audit does with the outlets' checks still open on the day it closes: carry them on their own business date, or refuse the close (set_fnb_open_checks_policy; carry unset)

string

Allowed values: carry refuse

hold_top_up

Whether the night audit tops up an in-house stay's card hold as its bill grows (set_hold_top_up; off unset)

boolean

hold_top_up_interval_minutes

How often, in minutes, the card rail plans the house's in-house stays' top-ups between night audits (60 to 1440; 0 or unset: at the audit and on the desk's press only)

integer

hold_top_up_max_per_stay

The most top-ups the card rail places for one stay

integer

hold_top_up_threshold

Property hold top up threshold

The smallest excess worth a top-up — the bill less what is held plus the rule’s allowance

object

amount

required

string format: decimal

currency

required

string format: iso-4217

kind

required

Property kind

string

Allowed values: hotel resort residences serviced_apartments hostel glamping mixed_use day_spa restaurant

legal_name

Legal name

string

location

Geo location

object

lat

required

number

lon

required

number

name

required

Property name

string

open_business_date

Open business date

The business date this property has open — the hotel date a posting made now is dated to. Written by open_business_date and the night audit’s close; unset while no day is open.

string format: date

opened_on

Opened on

string format: date

payment_request_messaging

Send pay links to the guest

When true, a payment request’s pay link is sent to the booking’s guest — by email, or by SMS when the profile holds no email — as soon as the card rail has minted it. Unset: off, and the desk sends the link itself.

boolean

payment_request_reuse_terms

Pay page card terms

What the pay page tells the guest about keeping their card (Stripe’s submit-button text, at most 1,200 characters): that the house may charge it without them present, for what, when and how often, and how each amount is set — the terms Stripe requires for a merchant-initiated charge. Set with set_payment_request_messaging. Unset: the card rail’s default wording.

string

positioning

Market positioning

string

Allowed values: luxury upper_upscale upscale upper_midscale midscale economy boutique lifestyle

post_stay_charging_days

Post-stay charging window, in days (0 = off)

How many business days after departure a charge found later (the minibar, damage, laundry) may still be posted to the departed stay’s bill and taken from its card. On (1–14), check-out keeps the stay’s largest card hold and releases the rest, and the window closes at the house’s midnight after its last day — 1 is OPERA’s “until the end of the business date”. Off (0 or unset), check-out releases every hold. Set with set_post_stay_charging.

integer

request_soon_minutes

Minutes ahead within which a request reads as soon

How many minutes before its due time a housekeeping request reads as soon on the housekeeping_requests read (and on the handset’s card). Unset: 30. Between 1 and 720. Set through set_request_urgency_window.

integer

room_count

Total rooms

integer

sca_chase

Chase a guest whose bank asks them to confirm

When true, a charge or hold the card rail tried with the guest absent that the issuer will only complete with the cardholder sends the guest a page to confirm it on (email first, else SMS, under the service-message consent gate), reminds them before the deadline, and tells the house when the deadline passes. Unset: off — the state and its deadline are still recorded and the desk sends the page itself. Set with set_sca_chase.

boolean

sca_chase_hours

Hours the guest has to confirm

The house’s deadline for a pending authentication, in hours from the moment the issuer asked (1–168). Unset: 24.

integer

sca_chase_reminders

Reminders before the deadline

How many reminders go to the guest before the deadline, spread evenly across it (0–3; 1 is one at half-time). Unset: 1.

integer

standard_week_hours

Standard work week hours

string format: decimal

star_rating

Star rating

string format: decimal

timezone

required

IANA timezone

string

visitor_key_grace_days

Days past the arrival night a visitor key is kept

How many days past a stay’s arrival night the night audit keeps the booking engine’s visitor key on its offers, turnaways and reservation before stripping it; the records themselves stay. Unset: 30. At most 365.

integer

waitlist_claim_url_base

Where a waitlist claim link points

The start of the link a waitlist offer carries; the offer’s claim token is appended as a path segment. Point it at the kernel’s own claim page (https://<kernel>/v1/waitlist-claims/) or at a booking site that calls the claim route. An https URL ending in /, with no query or fragment (plain http only to a loopback dev host). Unset: the offer goes out without a link and asks the guest to call.

string

waitlist_offer_hold_minutes

Minutes a waitlist offer keeps its room-nights

How many minutes a waitlist offer — the desk’s or the matcher’s — keeps its room-nights before they are given back and offered to the next entry. Unset: 30. Between 1 and 1440 (OPERA’s room-hold range).

integer

waitlist_offer_messaging

Send waitlist offers to the guest

When true, every waitlist offer — the desk’s or the matcher’s — is sent to the guest by SMS (or email when the profile holds no phone), with a link to claim it. Unset: off.

boolean

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.property",
      "properties": {
        "billing_identity": {
          "tax_registration_scheme": "vat"
        },
        "credit_limit_overage": "off",
        "fnb_open_checks_at_roll": "carry",
        "kind": "hotel",
        "positioning": "luxury"
      },
      "scope": {
        "level": "tenant"
      }
    }
  ]
}

422

Validation error — unknown property or filter type mismatch.

Search Property

Authorizations

Request Bodyrequired

Responses

200

Example

422

Request Body^required