Hotel Availability
POST/v2.0/hotels/availability
Introduction
Returns rate availability for specific hotels, a registered region, or a geographic radius search, for a given period and one or more rooms.
Search destination
Exactly one of the three destination criteria must be provided in destination:
hotelIds: list of internal Niara hotel IDs.regionId: ID of a registered region.circleInfo: radius search around a geographic point (latitude/longitude/radius).
Providing more than one is not an error. Only one is used, in this order of
priority: circleInfo, then regionId, then hotelIds.
Rooms
rooms lists every room wanted, each with its own occupancy and an optional ref.
Rooms with the same occupancy are searched together, and each hotel's rates come back
grouped by occupancy in hotels[].rooms[], each group naming the rooms it serves.
A hotel is returned only when every room can be filled (unless includeUnavailableRoomRates
is set), and cheapestCombination sums the cheapest bookable rate for every room.
With more than one occupancy, the first one decides which hotels are on the page; the others are then searched only in those hotels.
Pagination
Results are paginated at 50 hotels per page — 25 with filterStrategy ALL_RATES,
which returns far more rates per hotel (see page on the request and totalPages
on the response).
Promotional code
promoCode is passed on to suppliers that support it (Omnibees PromotionCode). Each
rate the supplier applied a code to comes back with its own promoCode, which travels in
the rateToken through the price check and the booking — nothing else needs to be sent again.
Request
- application/json
Body
- Array [
- ]
Your id for this call, up to 128 printable characters. Returned as is in the response, success or error, and kept in our logs: quote it when contacting support, even if the response never reached you. Use a new value for each call.
When you sent this request, by your clock: ISO 8601 with a timezone offset, e.g. 2026-11-13T14:32:05.120-03:00. Kept in our logs.
destination objectrequired
List of Niara hotel IDs to search. Mutually exclusive with regionId and circleInfo.
ID of a region registered in Niara. Mutually exclusive with hotelIds and circleInfo.
circleInfo objectnullable
Radius search around a geographic point. Mutually exclusive with hotelIds and regionId.
Latitude of the search circle's center.
Longitude of the search circle's center.
Search radius from the center.
Possible values: [km, mi]
Default value: km
Unit of measure for the radius: kilometers ("km") or miles ("mi").
Check-in date (ISO 8601, e.g. 2026-10-01). Cannot be in the past.
Check-out date (ISO 8601, e.g. 2026-10-02). Must be after checkin.
rooms object[]required
One entry per room wanted, 1 to 8. Rooms with the same occupancy are searched together; each hotel's rates come back grouped by occupancy (hotels[].rooms[]).
Number of adults in this room (at least 1).
Ages of the children in this room (0 to 17), one entry per child.
Client name for this room: 1 to 20 characters [A-Za-z0-9_-], unique in the request. Defaults to r1, r2… by position. The response, the price check and the booking refer to the room by this name.
When true, restricts the result to the client's favorite hotels.
Possible values: [1, 2, 3, 4, 5]
Filters hotels by star rating. A hotel is included only if its rating exactly matches one of the values listed here (e.g. [4, 5] returns only 4- and 5-star hotels — it is not a "4 stars and up" threshold). Hotels with no rating on file are always excluded once this filter is set.
Possible values: [BEST_ONLY, BEST_PER_TYPE, ALL_RATES]
Default value: BEST_ONLY
How much to narrow down each hotel's rates. BEST_ONLY: only the cheapest overall rate per room group, regardless of type. BEST_PER_TYPE: the cheapest rate per distinct combination of room type, rate plan, cancel policy, meal plan and payment options (a group can still return multiple rates under this strategy). ALL_RATES: every available rate, unfiltered.
Default value: 1
Page number (1-indexed). Each page returns up to 50 hotels (25 with filterStrategy ALL_RATES) — see totalPages on the response.
When true, room groups also include unavailableRates: rates that were found but aren't currently bookable, with the reason why.
When true, each rate's price also has its breakdown (nights, taxes, discounts). v2.0/orders/checkPrice always returns it.
Language for the texts in the response: pt-BR (default), en-US or es-ES. pt, en and es are also accepted. Carried in the rateToken, so the price check uses it too.
quotationRequest objectnullable
Full name of the person requesting the quotation.
When true, the chatbot flow should send the quotation by email.
Promotional code to search with, up to 64 characters. Sent to suppliers that support it (Omnibees PromotionCode). Rates the code applies to come back with promoCode.
Responses
- 200
- default
- application/json
- Schema
- Example (from schema)
Schema
- Array [
- Array [
- Array [
- Array [
- ]
- Array [
- ]
- Array [
- ]
- Array [
- ]
- Array [
- ]
- Array [
- ]
- Array [
- ]
- ]
- Array [
- Array [
- ]
- Array [
- ]
- Array [
- ]
- Array [
- ]
- Array [
- ]
- ]
- ]
- ]
Our id for this call, also in the X-Request-Id header. Quote it when contacting support.
The externalRequestId of the request, as sent. Absent when it wasn't sent.
When we answered, by our clock: ISO 8601 in UTC, e.g. 2026-11-13T17:32:05.874Z.
hotels object[]
List of hotels found with their rates.
hotel objectrequired
Internal Niara ID of the hotel.
Hotel name.
Name of the hotel's city.
Name of the hotel's country.
Hotel address.
position objectnullable
Geographic coordinates of the hotel.
Latitude of the hotel.
Longitude of the hotel.
URL of the hotel's main image.
URL with the hotel's full descriptive content.
Hotel star rating, when known.
Whether this is one of the client's preferred hotels.
rooms object[]
One group per distinct occupancy requested, each listing the rooms it serves and its rates.
The requested rooms (rooms[].ref) this group serves.
occupancy objectrequired
Number of adults per room.
Ages of the children per room.
rates object[]
Available rates for one room of this occupancy, for the whole stay.
Token identifying this rate for this occupancy. Pass it to v2.0/orders/checkPrice (one entry per room, so rooms with the same occupancy may reuse it) to re-confirm it before booking. Expires 24 hours after the search.
roomType objectrequired
Room type ID.
Room type name.
Room description, as the supplier gives it. Only returned by v2.0/orders/checkPrice, not by the search, and left out when it only repeats the name.
Rooms of this rate still available: the smallest count over the stay's nights. Absent when the supplier doesn't say.
price objectrequired
Currency of every amount in this price (ISO 4217), except payAtProperty.
Price before taxes, when available.
Tax amount, when available.
Total value (base + taxes), when available.
Total discount on the rate. Informative: base and total already have it taken off. Absent when there is none.
commission objectnullable
What the client earns on this rate. Absent on rates without commission.
Commission amount, in the price's currency.
Commission rate, in percent (10.00 is 10%).
payAtProperty object[]nullable
Fees the guest pays at the hotel, each in the currency the hotel charges. Never included in total. Only returned by v2.0/orders/checkPrice. Absent when there is none.
What the fee is, as the supplier names it.
Monetary amount.
Currency the hotel charges the fee in (ISO 4217).
breakdown objectnullable
How the price splits up. See PriceBreakdown for when it is returned.
nights object[]nullable
Price of each night, in stay order. The nights' base add up to the rate's base. Absent when the supplier doesn't price each night.
Date of the night (YYYY-MM-DD).
Price of the night before taxes, in the price's currency.
taxes object[]nullable
The taxes in taxes, as the supplier details them. Informative. Absent when not detailed.
What the amount is, as the supplier names it.
Monetary amount, in the price's currency.
discounts object[]nullable
The discounts in discounts, as detailed. Informative. Absent when not detailed.
What the amount is, as the supplier names it.
Monetary amount, in the price's currency.
cancelPolicy objectrequired
Whether cancelling can be free at some point. false for non-refundable rates. Absent when unknown.
Currency of the penalty amounts (ISO 4217). Absent when no step has an amount.
penalties object[]nullable
Penalty steps in time order. Before the first step, cancelling is free. Absent when the supplier gives no penalty information.
When this step starts (ISO 8601 with UTC offset). Absent means from the moment of booking, as for non-refundable rates.
What cancelling costs from then on, for this room and the whole stay, in the policy's currency. Absent when the supplier doesn't say.
Cancellation policy as the supplier words it. Only returned by v2.0/orders/checkPrice, not by the search.
supplier objectnullable
Name of the supplier providing this rate.
URL of the supplier's logo. Absent when the credential has none on file.
offers object[]nullable
Promotional offers applied to the rate.
Offer name.
Discount value/percentage.
Number of free nights granted by the offer, when applicable.
Possible values: [STAY_DISCOUNT, DISCOUNT, FREE_NIGHT, LAST_MINUTE, null]
Discount type.
Nights required to qualify for the offer, when applicable.
paymentOptions object[]nullable
Payment/guarantee options available for this rate.
Payment option ID: pass it as is to v2.0/orders/booking (payments[].paymentOptionId). Opaque: don't parse it.
Possible values: [CREDITCARD, PAY_AT_PROPERTY, INVOICE, PAY_LATER]
CREDITCARD: paid by credit card. PAY_AT_PROPERTY: paid at the hotel, with a card as guarantee. INVOICE: billed to the client account. PAY_LATER: paid after booking, before a deadline. More types may be added: accept values you don't know.
Display name for the payment option.
mealPlan objectnullable
Possible values: [breakfast, lunch, dinner]
Meals included in the rate. An empty list means room only.
true when the rate is all-inclusive: every meal and usually drinks and more. Absent otherwise.
Meal plan name, as the supplier gives it.
Meal plan description, as the supplier gives it. Only returned by v2.0/orders/checkPrice, not by the search, and left out when it only repeats the name.
ratePlan objectnullable
Rate plan ID.
Rate plan name.
Whether the rate plan is publicly published.
Whether the rate plan is a package (bundled with extras).
Rate plan description, as the supplier gives it. Only returned by v2.0/orders/checkPrice, not by the search, and left out when it only repeats the name.
Promotional code the supplier applied to this rate (Omnibees PromotionCode). Carried in the rateToken, so the price check and the booking keep it. Absent when no code applies.
URL to a quotation generated for this specific rate. Only present when quotationRequest was sent, the search was for a single hotel (destination.hotelIds with exactly one ID), and this rate is Omnibees-supplied.
unavailableRates object[]nullable
Rates that were found but aren't currently bookable. Only present when includeUnavailableRoomRates was set on the request.
Rate/room ID. Informational only — cannot be price-checked or booked.
roomType objectnullable
Room type ID.
Room type name.
Room description, as the supplier gives it. Only returned by v2.0/orders/checkPrice, not by the search, and left out when it only repeats the name.
Why this rate is unavailable.
Minimum number of adults required, when the unavailability is an occupancy restriction.
Maximum number of adults allowed, when the unavailability is an occupancy restriction.
Minimum number of children required, when the unavailability is an occupancy restriction.
Maximum number of children allowed, when the unavailability is an occupancy restriction.
cancelPolicy objectnullable
Whether cancelling can be free at some point. false for non-refundable rates. Absent when unknown.
Currency of the penalty amounts (ISO 4217). Absent when no step has an amount.
penalties object[]nullable
Penalty steps in time order. Before the first step, cancelling is free. Absent when the supplier gives no penalty information.
When this step starts (ISO 8601 with UTC offset). Absent means from the moment of booking, as for non-refundable rates.
What cancelling costs from then on, for this room and the whole stay, in the policy's currency. Absent when the supplier doesn't say.
Cancellation policy as the supplier words it. Only returned by v2.0/orders/checkPrice, not by the search.
ratePlan objectnullable
Rate plan ID.
Rate plan name.
Whether the rate plan is publicly published.
Whether the rate plan is a package (bundled with extras).
Rate plan description, as the supplier gives it. Only returned by v2.0/orders/checkPrice, not by the search, and left out when it only repeats the name.
mealPlan objectnullable
Possible values: [breakfast, lunch, dinner]
Meals included in the rate. An empty list means room only.
true when the rate is all-inclusive: every meal and usually drinks and more. Absent otherwise.
Meal plan name, as the supplier gives it.
Meal plan description, as the supplier gives it. Only returned by v2.0/orders/checkPrice, not by the search, and left out when it only repeats the name.
price objectnullable
Currency of every amount in this price (ISO 4217), except payAtProperty.
Price before taxes, when available.
Tax amount, when available.
Total value (base + taxes), when available.
Total discount on the rate. Informative: base and total already have it taken off. Absent when there is none.
commission objectnullable
What the client earns on this rate. Absent on rates without commission.
Commission amount, in the price's currency.
Commission rate, in percent (10.00 is 10%).
payAtProperty object[]nullable
Fees the guest pays at the hotel, each in the currency the hotel charges. Never included in total. Only returned by v2.0/orders/checkPrice. Absent when there is none.
What the fee is, as the supplier names it.
Monetary amount.
Currency the hotel charges the fee in (ISO 4217).
breakdown objectnullable
How the price splits up. See PriceBreakdown for when it is returned.
nights object[]nullable
Price of each night, in stay order. The nights' base add up to the rate's base. Absent when the supplier doesn't price each night.
Date of the night (YYYY-MM-DD).
Price of the night before taxes, in the price's currency.
taxes object[]nullable
The taxes in taxes, as the supplier details them. Informative. Absent when not detailed.
What the amount is, as the supplier names it.
Monetary amount, in the price's currency.
discounts object[]nullable
The discounts in discounts, as detailed. Informative. Absent when not detailed.
What the amount is, as the supplier names it.
Monetary amount, in the price's currency.
cheapestCombination objectnullable
total objectrequired
Sum of the chosen rates over all requested rooms.
Monetary amount.
Currency code (ISO 4217).
rooms objectrequired
Room ref → the rateToken to check the price for.
Total number of hotels available for the given criteria (before pagination).
The page number returned, echoing the request's page.
Total number of pages available for the given criteria.
The language actually used for the texts, after normalization.
{
"requestId": "string",
"externalRequestId": "string",
"timestamp": "string",
"hotels": [
{
"hotel": {
"id": "string",
"name": "string",
"cityName": "string",
"countryName": "string",
"address": "string",
"position": {
"latitude": 0,
"longitude": 0
},
"imageUrl": "string",
"detailsUrl": "string",
"rating": 0,
"preferred": false
},
"rooms": [
{
"refs": [
"string"
],
"occupancy": {
"adults": 0,
"childrenAges": [
0
]
},
"rates": [
{
"rateToken": "string",
"roomType": {
"id": "string",
"name": "string",
"description": "string"
},
"unitsAvailable": 0,
"price": {
"currency": "string",
"base": "string",
"taxes": "string",
"total": "string",
"discounts": "string",
"commission": {
"amount": "string",
"percentage": "string"
},
"payAtProperty": [
{
"description": "string",
"amount": "string",
"currency": "string"
}
],
"breakdown": {
"nights": [
{
"date": "string",
"base": "string"
}
],
"taxes": [
{
"description": "string",
"amount": "string"
}
],
"discounts": [
{
"description": "string",
"amount": "string"
}
]
}
},
"cancelPolicy": {
"refundable": true,
"currency": "string",
"penalties": [
{
"from": "string",
"amount": "string"
}
],
"description": "string"
},
"supplier": {
"name": "string",
"logo": "string",
"offers": [
{
"name": "string",
"discount": 0,
"freeNights": 0,
"nightsRequired": 0
}
]
},
"paymentOptions": [
{
"id": "string",
"name": "string"
}
],
"mealPlan": {
"meals": [
null
],
"allInclusive": true,
"name": "string",
"description": "string"
},
"ratePlan": {
"id": "string",
"name": "string",
"public": true,
"package": true,
"description": "string"
},
"promoCode": "string",
"quotationLink": "string"
}
],
"unavailableRates": [
{
"id": "string",
"roomType": {
"id": "string",
"name": "string",
"description": "string"
},
"reason": "string",
"minAdultCount": 0,
"maxAdultCount": 0,
"minChildCount": 0,
"maxChildCount": 0,
"cancelPolicy": {
"refundable": true,
"currency": "string",
"penalties": [
{
"from": "string",
"amount": "string"
}
],
"description": "string"
},
"ratePlan": {
"id": "string",
"name": "string",
"public": true,
"package": true,
"description": "string"
},
"mealPlan": {
"meals": [
null
],
"allInclusive": true,
"name": "string",
"description": "string"
},
"price": {
"currency": "string",
"base": "string",
"taxes": "string",
"total": "string",
"discounts": "string",
"commission": {
"amount": "string",
"percentage": "string"
},
"payAtProperty": [
{
"description": "string",
"amount": "string",
"currency": "string"
}
],
"breakdown": {
"nights": [
{
"date": "string",
"base": "string"
}
],
"taxes": [
{
"description": "string",
"amount": "string"
}
],
"discounts": [
{
"description": "string",
"amount": "string"
}
]
}
}
}
]
}
],
"cheapestCombination": {
"total": {
"amount": "string",
"currency": "string"
},
"rooms": {}
}
}
],
"totalCount": 0,
"page": 0,
"totalPages": 0,
"language": "string"
}
Error. The status depends on error.code.
- application/json
- Schema
- Example (from schema)
Schema
- Array [
- ]
Our id for this call, also in the X-Request-Id header. Quote it when contacting support.
The externalRequestId of the request, as sent. Absent when it wasn't sent.
When we answered, by our clock: ISO 8601 in UTC, e.g. 2026-11-13T17:32:05.874Z.
error objectrequired
Stable reason; decide what to do based on it, not on message.
| Code | Status | When |
| --- | --- | --- |
| INVALID_REQUEST | 400 | The request was rejected; field problems are listed in details |
| UNAUTHORIZED | 401 | Missing or invalid credentials |
| FORBIDDEN | 403 | Valid credentials, access denied |
| NOT_FOUND | 404 | Order not found, or no endpoint for this method and path |
| TOKEN_EXPIRED | 409 | rateToken or bookingToken past its expiration; search or check the price again |
| DUPLICATE_REFERENCE | 409 | The booking's externalReference already has an order; read it with v2.0/orders/details |
| FEATURE_NOT_AVAILABLE | 422 | A valid request that isn't supported yet |
| RATE_LIMITED | 429 | Too many requests, or quota exceeded |
| SEARCH_FAILED | as received | The hotel search failed; message has the reason given |
| BOOKING_FAILED | as received | The booking was not completed; message has the reason given |
| CANCELLATION_FAILED | as received | The cancellation was not completed; message has the reason given |
| SUPPLIER_ERROR | 502 | A supplier failed or answered badly |
| TIMEOUT | 504 | The request took too long; a booking may still complete |
| INTERNAL_ERROR | 500 | Unexpected failure on our side |
Explanation for people. May change; don't parse it.
details object[]nullable
Every field problem found, even when there is only one. Only with INVALID_REQUEST.
INVALID_FIELD (a value is wrong) or REQUIRED_FIELD (a value is missing).
Path of the field in the request, e.g. items[0].rooms[1].rateToken. Absent when the problem involves several fields.
Explanation, in English.
{
"requestId": "string",
"externalRequestId": "string",
"timestamp": "string",
"error": {
"code": "string",
"message": "string",
"details": [
{
"code": "string",
"field": "string",
"message": "string"
}
]
}
}