Rimo Global · Hotel Distribution API

Rimo Global Hotels API

Direct connectivity to Rimo Global's worldwide hotel inventory. Real-time availability, net B2B rates and full booking management through a single JSON API, for online travel agencies, tour operators, wholesalers and travel management companies.

Inventory: About 3 million properties worldwide
Rates: Net B2B rates, taxes included
Mapping: Hotel mapping file, GIATA-compatible
Security: Bearer token + IP whitelisting

Shopping

Lowest prices across your selected hotels for listing pages, then full room, board and cancellation detail per property.

Rate validation

Live re-pricing and pre-booking that lock the rate and surface supplier terms before payment.

Booking

Multi-room bookings with adults and children, confirmed room by room.

Post-booking

Booking retrieval, cancellation charges, cancellation and reconciliation search.

Partner onboarding Postman collection Certification checklist

Partner onboarding

API access is available to contracted Rimo Global partners. Onboarding runs in four stages.

1
Commercial agreement
Agree terms with your Rimo Global account manager: markets, volumes, settlement currency and credit.
2
Technical onboarding
Email api@rimoglobal.com with your company name, technical contact and the static public IP addresses of your servers. We issue your API token and whitelist your IPs; whitelisting takes effect within about one hour. We also send the hotel mapping file.
3
Integration and certification
Integrate the endpoints below against the live system, following the certification booking rules. Then submit the certification checklist with your certification booking references and a sample voucher.
4
Go-live
After our review we agree the go-live date with you and monitor your first live transactions together.

Credential security

Your token is a live credential that can create real bookings against your account. Store it on your servers only, never in a website, mobile app or shared document. If you suspect exposure, contact api@rimoglobal.com immediately and we will rotate it.

Authentication

Send your token in the Authorization header of every request.

HTTP headers

POST https://apiout.rimoglobal.com/api/xconnect/Availabilitywithcancellation
Authorization: Bearer <your token>
Content-Type: application/json
Accept: application/json
Accept-Encoding: gzip, deflate

First call (cURL)

curl -X POST 'https://apiout.rimoglobal.com/api/xconnect/Countries' \
  -H 'Authorization: Bearer <your token>' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  --compressed \
  -d '{}'

Booking flow

Every booking follows the same five-step sequence.

1AvailabilityPrices, rooms, cancellationSearchKey
2ReCheckLive price + essential infoonce
3PreBookBookingToken + UniqueIdsonce
4BookCreates the bookingnever retry
5BookingDetailConfirmed?always

To cancel: Cancellation charges → CancelBooking → BookingDetail shows Cancelled.

Rules for every request

POST only, with a JSON body, to https://apiout.rimoglobal.com/api/xconnect/<Endpoint>.
Dates are MM-DD-YYYY (for example 05-12-2027). One exception: the stay and booking dates inside the BookingDetail response are DD-MM-YYYY.
AdvancedOptions goes in every request: Currency (your account currency) and CustomerIpAddress (your end customer's public IP).
Field names: send them as shown on this page. Some responses come back in camelCase (bookRS, bookingToken), others in PascalCase. Read field names without caring about upper or lower case.
Errors come in an Error array. An empty array means success. Check it on every response, even with HTTP 200.
Guests: adults are 13 and older; children are 1 to 12. Every guest needs a real name in Latin letters.
Prices are totals for the whole stay in your account currency, taxes included.
Compression: responses are compressed. Send Accept-Encoding: gzip, deflate.

Error response

{
  "Error": [
    {
      "type": "SearchKeyExpired",
      "code": "SearchKey_Error",
      "description": "Access to search key is no longer available"
    }
  ]
}

Timing and limits

SearchKey lasts 25 minutes. Finish ReCheck, PreBook and Book within that time, or search again.
BookingToken from PreBook is short-lived. Book within a few minutes.
Response time: an availability call takes about 9 to 12 seconds. Send batches in parallel instead of one big call.
Rate limit: HTTP 429 means too many requests per second. Pause and retry.

Timeouts

Call	Timeout we suggest	Retry on timeout?
Availability	35 s	Yes
ReCheck	15 s	Yes
PreBook	20 s	No: search again
Book	90 s	Never: call BookingDetail
BookingDetail	15 s	Yes
Cancellation charges	15 s	Yes
CancelBooking	45 s	No: call BookingDetail first

Certification bookings

All environments are live

Your token connects to the live system, and every booking reaches a real hotel. Certification bookings are subject to the same terms as any other booking.

Book refundable rates only, with at least seven days of free cancellation remaining.
Book stays at least several months ahead. Never same-day or next-day arrivals, including for promotional rates.
Use real guest names. Placeholder names such as "Test" are rejected by some suppliers.
Cancel every certification booking immediately through the API. If a cancellation fails, contact api@rimoglobal.com at once.
Choose low-value rates and do not automate certification bookings; automated test traffic may lead to account suspension.
Use a unique InternalReference on every Book request.

Bookings left uncancelled past their free-cancellation deadline are invoiced under your agreement.

Static data

Countries

POST/api/xconnect/Countries

All countries. Use CountryId to get cities, and the country Name as the guest Nationality in searches.

Request

Request body

{}

Response

[
  {
    "CountryId": "25773",
    "Name": "AFGHANISTAN"
  }
]

Parent	Field	Description
	`CountryId`	Unique country id.
	`Name`	Country name. Send it as Nationality.

Implementation notes

Static data changes rarely. Load it once a day, not on every search.

Static data

Cities

POST/api/xconnect/Cities

All cities of one country. Every availability search is for one CityId.

Request

Request body

{
  "Request": {
    "CountryId": "25773"
  }
}

Parent	Field	Description	Required
`Request`	`CountryId`	Country id from Countries.	Yes

Response

[
  {
    "CityId": 26467,
    "Name": "KABUL"
  }
]

Parent	Field	Description
	`CityId`	Unique city id.
	`Name`	City name.

Implementation notes

City and hotel ids belong to this API. Ids from other systems will not work.
Hotel ids, names, addresses and coordinates come in the Rimo Global hotel mapping file, which we send during onboarding (api@rimoglobal.com). Partners with a GIATA MultiCodes subscription can also request the Rimo Global mapping from GIATA.

Booking flow

Availability with cancellation

POST/api/xconnect/Availabilitywithcancellation

Prices, rooms and cancellation policies for a list of hotels in one city, for given dates, rooms and guest nationality. It returns the SearchKey that every later step needs.

Request

Request body

{
  "Request": {
    "Rooms": [
      {
        "RoomNo": 1,
        "NoofAdults": 2,
        "NoOfChild": 1,
        "ChildAge": [
          7
        ]
      },
      {
        "RoomNo": 2,
        "NoofAdults": 1,
        "NoOfChild": 0,
        "ChildAge": []
      }
    ],
    "CityID": "284794",
    "CheckInDate": "05-12-2027",
    "CheckOutDate": "05-14-2027",
    "NoofNights": "2",
    "Nationality": "Egypt",
    "Filters": {
      "IsRecommendedOnly": "0",
      "IsShowRooms": "1",
      "IsOnlyAvailable": "1",
      "StarRating": {
        "Min": 0,
        "Max": 5
      },
      "HotelIDs": "1166537,629886"
    }
  },
  "AdvancedOptions": {
    "Currency": "USD",
    "CustomerIpAddress": "203.0.113.25"
  }
}

Parent	Field	Description	Required
`Request`	`Rooms`	One entry per room. Each room can have different guests.	Yes
`Rooms`	`RoomNo`	1, 2, 3… in order.	Yes
`Rooms`	`NoofAdults`	Adults in the room (13 years and older).	Yes
`Rooms`	`NoOfChild`	Children in the room.	Yes
`Rooms`	`ChildAge`	One age per child, 1 to 12. Send `[]` when there are no children.	Yes
`Request`	`CityID`	City id from Cities.	Yes
`Request`	`CheckInDate / CheckOutDate`	MM-DD-YYYY.	Yes
`Request`	`NoofNights`	Nights between the two dates.	Yes
`Request`	`Nationality`	Guest nationality: a country Name from Countries. Prices can change by nationality.	Yes
`Filters`	`IsShowRooms`	`0` = lowest price per hotel only (fast, for listings). `1` = all rooms with RoomTokens and cancellation policies.	Yes
`Filters`	`IsOnlyAvailable`	`1` = bookable now only. `0` = also on-request rooms.	Yes
`Filters`	`IsRecommendedOnly`	`1` = preferred hotels only. `0` = all hotels.	Yes
`Filters`	`StarRating`	`Min` / `Max`, 0 to 5. 0 covers unrated hotels and apartments.	Yes
`Filters`	`HotelIDs`	Comma-separated hotel ids in this city. Send ids: a search with an empty list returns no results.	Yes
`AdvancedOptions`	`Currency`	Your account currency. It is set when the account is created.	Yes
`AdvancedOptions`	`CustomerIpAddress`	Public IP address of the end customer.	Yes

Response

{
  "Error": [],
  "AvailabilityRS": {
    "SearchKey": "RG-021_1ca18_321648911163372936",
    "Count": 1,
    "Currency": "USD",
    "HotelResult": [
      {
        "StartPrice": 13.98,
        "HotelId": 1166537,
        "HotelOption": [
          {
            "HotelOptionId": "0|1166537|4|0",
            "MinPrice": 13.98,
            "IsCombineRoom": true,
            "HotelRooms": [
              [
                {
                  "RoomNo": "1",
                  "RoomTypeName": "Standard Queen Room",
                  "MealName": "Room_Only",
                  "MappedMealName": "Room Only",
                  "Price": 13.98,
                  "BookingStatus": "Available",
                  "RoomToken": "MHwwfDB8MA==",
                  "CancellationPolicy": [
                    {
                      "FromDate": "10-11-2026",
                      "ToDate": "05-06-2027",
                      "CancellationPrice": 0
                    },
                    {
                      "FromDate": "05-07-2027",
                      "ToDate": "05-12-2027",
                      "CancellationPrice": 13.98
                    }
                  ]
                }
              ]
            ]
          }
        ]
      }
    ]
  }
}

Parent	Field	Description
`AvailabilityRS`	`SearchKey`	Needed by ReCheck, PreBook and Book. Valid for 25 minutes.
`AvailabilityRS`	`Currency`	Currency of every price in the response.
`HotelResult`	`HotelId / StartPrice`	Hotel id and its lowest total price.
`HotelOption`	`HotelOptionId`	Id of one offer. Send it unchanged to ReCheck and PreBook.
`HotelOption`	`IsCombineRoom`	`true`: the rooms of this offer are sold together.
`HotelOption`	`HotelRooms`	An array of arrays. Each inner array is one bookable choice, with one room per requested room. Book the rooms of one inner array together.
`HotelRooms`	`RoomTypeName / MealName`	Room and board as the supplier names them.
`HotelRooms`	`MappedMealName`	Board in standard words (Room Only, Breakfast, Half Board…). `NotMapped` or empty when unknown.
`HotelRooms`	`Price`	Total for this room for the whole stay, taxes included.
`HotelRooms`	`BookingStatus`	`Available`, or on request when IsOnlyAvailable = 0.
`HotelRooms`	`RoomToken`	Id of this room. Send it to ReCheck and PreBook.
`CancellationPolicy`	`FromDate / ToDate / CancellationPrice`	What cancelling costs in each date range (MM-DD-YYYY). 0 = free. No lines at all = treat as non-refundable.

Implementation notes

Every call takes about 9 to 12 seconds, whatever its size. Split long hotel lists into batches and send them in parallel: about 25 hotels per call with IsShowRooms = 0, and about 10 with IsShowRooms = 1 (very large responses can make the SearchKey expire).
Run IsShowRooms = 0 for a listing page, then IsShowRooms = 1 only for the hotel the guest opens.
Prices are totals for the whole stay and include taxes. Some hotels also collect a local fee at the hotel; ReCheck tells you (EssentialInformation).

Booking flow

ReCheck

POST/api/xconnect/ReCheck

Checks the chosen offer again: live price, availability, cancellation policy, and the essential information the guest must see before paying. Call it once per booking, when the guest picks a room.

Request

Request body

{
  "Request": {
    "SearchKey": "RG-021_1ca18_321648911163372936",
    "HotelOption": {
      "HotelOptionId": "0|1166537|4|0",
      "HotelRooms": [
        {
          "RoomNo": "1",
          "RoomToken": "MHwwfDB8MA=="
        }
      ]
    }
  },
  "AdvancedOptions": {
    "Currency": "USD",
    "CustomerIpAddress": "203.0.113.25"
  }
}

Parent	Field	Description	Required
`Request`	`SearchKey`	From the availability response.	Yes
`HotelOption`	`HotelOptionId`	The chosen offer.	Yes
`HotelRooms`	`RoomNo / RoomToken`	Every room of the chosen inner array.	Yes
`AdvancedOptions`	`Currency / CustomerIpAddress`	As in availability.	Yes

Response

{
  "Error": [],
  "Currency": "USD",
  "ReCheckRS": [
    {
      "RoomNo": "1",
      "RoomTypeName": "Superior Room",
      "MealName": "OB",
      "MappedMealName": "Room Only",
      "Price": 19.15,
      "BookingStatus": "Available",
      "EssentialInformation": "Hotel will invoice the total amount in case of no show.<br>City tax is paid at the hotel.",
      "CancellationPolicy": [
        {
          "FromDate": "10-12-2026",
          "ToDate": "05-05-2027",
          "CancellationPrice": 0
        },
        {
          "FromDate": "05-06-2027",
          "ToDate": "05-12-2027",
          "CancellationPrice": 19.15
        }
      ],
      "RoomToken": "MjZ8MHwwfDA="
    }
  ]
}

Parent	Field	Description
`ReCheckRS`	`BookingStatus`	Continue only when every room is `Available`.
`ReCheckRS`	`Price`	Current price of the room.
`ReCheckRS`	`CancellationPolicy`	The policy that applies to this booking. Show it to the guest.
`ReCheckRS`	`EssentialInformation`	Supplier notes: fees paid at the hotel, check-in rules, no-show terms. May contain HTML `<br>`. Show it before payment.

Implementation notes

If the price changed, show the new price before going on.

Booking flow

PreBook

POST/api/xconnect/PreBook

Holds the offer for booking and returns the BookingToken and one UniqueId per room. Call it once per booking, right before you take the guest's payment.

Request

Request body

{
  "Request": {
    "SearchKey": "RG-021_1ca18_321648911163372936",
    "HotelOption": {
      "HotelOptionId": "0|1166537|4|0",
      "HotelRooms": [
        {
          "RoomNo": "1",
          "RoomToken": "MHwwfDB8MA=="
        }
      ]
    }
  },
  "AdvancedOptions": {
    "Currency": "USD",
    "CustomerIpAddress": "203.0.113.25"
  }
}

Parent	Field	Description	Required
`Request`	`SearchKey / HotelOption`	Same body as ReCheck.	Yes

Response

{
  "Error": [],
  "PreBookRS": {
    "HotelOption": {
      "HotelName": "Four Pyramids Guest House",
      "Nationality": "egypt",
      "BookingToken": "OGE3MmI1ZDgtOTZkZS00MTJk…",
      "Status": "Bookable",
      "IsPriceChange": 0,
      "CheckInDate": "04-14-2027",
      "CheckOutDate": "04-15-2027",
      "TotalPrice": 18.94,
      "HotelRooms": [
        {
          "UniqueId": 1730,
          "RoomNo": "1",
          "RoomTypeName": "Double Room",
          "MealName": "Room Only",
          "Price": 18.94,
          "PriceChange": {
            "OldPrice": 0,
            "NewPrice": 0
          }
        }
      ]
    },
    "Currency": "USD"
  }
}

Parent	Field	Description
`HotelOption`	`Status`	Book only when it is `Bookable`.
`HotelOption`	`IsPriceChange`	`1` = the price changed. Show the new TotalPrice to the guest and get their OK before Book.
`HotelOption`	`BookingToken`	Send it to Book. Short-lived: book within a few minutes.
`HotelOption`	`TotalPrice`	The amount to send in Book.
`HotelRooms`	`UniqueId`	One per room. Every guest in that room carries this id in Book.
`HotelRooms`	`PriceChange`	Old and new price of each room when IsPriceChange = 1.

Implementation notes

Calling PreBook twice for the same offer returns a duplication error. To try again, search again.
When IsCombineRoom is true, the total is split across the rooms. The total does not change.

Booking flow

Book

POST/api/xconnect/Book

Creates the booking. Send it once, after the guest has paid (or after you hold the payment). Then always call BookingDetail: only BookingDetail tells you if the hotel confirmed.

Request

Request body

{
  "Request": {
    "SearchKey": "RG-021_1ca18_321648911163372936",
    "BookRQ": {
      "BookingToken": "OGE3MmI1ZDgtOTZkZS00MTJk…",
      "TotalPrice": 18.94,
      "InternalReference": "YOURREF-000123",
      "HotelRooms": [
        {
          "UniqueId": 1730,
          "RoomNo": "1",
          "IsLead": "1",
          "PaxType": "Adult",
          "Prefix": "Mr.",
          "FirstName": "John",
          "LastName": "Smith",
          "ChildAge": "0"
        },
        {
          "UniqueId": 1730,
          "RoomNo": "1",
          "IsLead": "0",
          "PaxType": "Adult",
          "Prefix": "Mrs.",
          "FirstName": "Anna",
          "LastName": "Smith",
          "ChildAge": "0"
        },
        {
          "UniqueId": 1730,
          "RoomNo": "1",
          "IsLead": "0",
          "PaxType": "Child",
          "Prefix": "Ms.",
          "FirstName": "Lily",
          "LastName": "Smith",
          "ChildAge": "7"
        }
      ]
    }
  },
  "AdvancedOptions": {
    "Currency": "USD",
    "CustomerIpAddress": "203.0.113.25"
  }
}

Parent	Field	Description	Required
`Request`	`SearchKey`	From the availability response.	Yes
`BookRQ`	`BookingToken`	From PreBook.	Yes
`BookRQ`	`TotalPrice`	TotalPrice from PreBook.	Yes
`BookRQ`	`InternalReference`	Your own booking reference. Must be new on every Book call.	Yes
`BookRQ`	`HotelRooms`	One entry per guest (adults and children), for all rooms.	Yes
`HotelRooms`	`UniqueId / RoomNo`	From PreBook: the room this guest stays in.	Yes
`HotelRooms`	`IsLead`	`"1"` on exactly one adult (the lead guest), `"0"` on everyone else.	Yes
`HotelRooms`	`PaxType`	`Adult` or `Child`.	Yes
`HotelRooms`	`Prefix`	Adults: `Mr.`, `Mrs.`, `Ms.`, `Miss`. Children: `Mr.` for a boy, `Ms.` for a girl.	Yes
`HotelRooms`	`FirstName / LastName`	The real guest name, Latin letters only. Every guest needs a name.	Yes
`HotelRooms`	`ChildAge`	Child's age as in the search (1 to 12). `"0"` for adults.	Yes
`AdvancedOptions`	`Currency / CustomerIpAddress`	As in availability.	Yes

Response

{
  "error": [],
  "bookRS": {
    "bookingId": 0,
    "referenceNo": "RIMO2026100123",
    "internalReference": "YOURREF-000123",
    "currency": "USD"
  }
}

Parent	Field	Description
`BookRS`	`ReferenceNo`	Rimo Global booking reference.
`BookRS`	`InternalReference`	Your reference, as you sent it.
`BookRS`	`BookingId`	Usually 0 here. The real id comes from BookingDetail.

Implementation notes

Never send Book again for the same booking, not even after a timeout or a network error. The booking may already exist. Call BookingDetail with your InternalReference instead.
The flat guest list above is the format the live API accepts. Some older documents show a nested Pax list with Title and Age; do not use it.
Some suppliers reject Mstr. for children. Use Mr. / Ms..
Allow up to 90 seconds for Book. Some suppliers are slow.

After booking

BookingDetail

POST/api/xconnect/BookingDetail

The real status of a booking, room by room. Call it after every Book, and whenever you need the current status.

Request

Request body

{
  "Request": {
    "BookingDetailRQ": {
      "BookingId": "0",
      "ReferenceNo": "RIMO2026100123",
      "InternalReference": "YOURREF-000123"
    }
  },
  "AdvancedOptions": {
    "Currency": "USD",
    "CustomerIpAddress": "203.0.113.25"
  }
}

Parent	Field	Description	Required
`BookingDetailRQ`	`ReferenceNo`	From Book. Send ReferenceNo, InternalReference, or both.	One of the two
`BookingDetailRQ`	`InternalReference`	Your reference. Works even when Book timed out and you have no ReferenceNo.	One of the two
`BookingDetailRQ`	`BookingId`	Send `"0"` if you do not have it.	No

Response

{
  "error": [],
  "bookingDetailRS": {
    "hotelOption": {
      "hotelName": "Four Pyramids Guest House",
      "bookingId": 381,
      "internalReference": "YOURREF-000123",
      "referenceNo": "RIMO2026100123",
      "checkInDate": "14-04-2027",
      "checkOutDate": "15-04-2027",
      "bookingDate": "12-10-2026",
      "leadPaxName": "Mr. John Smith",
      "totalPrice": 18.94,
      "hotelRooms": [
        {
          "roomNo": "1",
          "roomTypeName": "Double Room",
          "mealName": "Room Only",
          "price": 18.94,
          "bookingStatus": "Confirmed",
          "cancellationPolicy": [
            {
              "fromDate": "10-12-2026",
              "toDate": "04-08-2027",
              "cancellationPrice": 0
            },
            {
              "fromDate": "04-09-2027",
              "toDate": "04-14-2027",
              "cancellationPrice": 18.94
            }
          ],
          "passenger": [
            {
              "isLead": 1,
              "paxType": "Adult",
              "name": "Mr. John Smith",
              "childAge": "0"
            },
            {
              "isLead": 0,
              "paxType": "Adult",
              "name": "Mrs. Anna Smith",
              "childAge": "0"
            }
          ]
        }
      ]
    },
    "currency": "USD"
  }
}

Parent	Field	Description
`HotelOption`	`BookingId`	Rimo Global booking id. Needed to cancel.
`HotelRooms`	`BookingStatus`	Status of each room. See Booking statuses.
`HotelOption`	`CheckInDate / CheckOutDate / BookingDate`	DD-MM-YYYY in this response, unlike the rest of the API.
`HotelRooms`	`CancellationPolicy`	MM-DD-YYYY, like the rest of the API.
`HotelRooms`	`Passenger`	Guests as booked.

Implementation notes

The booking is sold only when every room says Confirmed.
After a Book timeout, call BookingDetail with your InternalReference a few times: right away, then after about 3, 7, 15, 20 and 25 seconds.

After booking

Cancellation charges

POST/api/xconnect/CheckHotelCancellationCharges

What cancelling costs right now, and the CancelCode needed to cancel. Call it right before CancelBooking and show the charge to the guest.

Request

Request body

{
  "Request": {
    "CheckHotelCancellationChargesRQ": {
      "BookingId": "381",
      "InternalReference": "YOURREF-000123",
      "ReferenceNo": "RIMO2026100123"
    }
  },
  "AdvancedOptions": {
    "Currency": "USD",
    "CustomerIpAddress": "203.0.113.25"
  }
}

Parent	Field	Description	Required
`CheckHotelCancellationChargesRQ`	`BookingId`	From BookingDetail.	Yes
`CheckHotelCancellationChargesRQ`	`ReferenceNo`	From Book or BookingDetail.	Yes
`CheckHotelCancellationChargesRQ`	`InternalReference`	Your reference.	Yes

Response

{
  "Error": [],
  "CheckHotelCancellationChargesRS": {
    "HotelOption": {
      "BookingId": 381,
      "TotalPrice": 18.94,
      "TotalCharge": 0,
      "TotalRefund": 18.94,
      "CancelCode": "Q0FOQ0VMLTM4MS0x…",
      "HotelRooms": [
        {
          "BookingDetailId": 66147,
          "RoomTypeName": "Double Room",
          "Price": 18.94,
          "RefundAmount": 18.94
        }
      ]
    },
    "Currency": "USD"
  }
}

Parent	Field	Description
`HotelOption`	`TotalCharge`	What you pay if you cancel now. 0 = free.
`HotelOption`	`TotalRefund`	What comes back to you.
`HotelOption`	`CancelCode`	Send it to CancelBooking.
`HotelRooms`	`BookingDetailId`	Room id. Send it to CancelBooking.

Implementation notes

A booking that was never confirmed has nothing to cancel: this call returns NOCOUNT_ERROR.

After booking

CancelBooking

POST/api/xconnect/CancelBooking

Cancels a confirmed booking. Then call BookingDetail: it must show Cancelled.

Request

Request body

{
  "Request": {
    "CancelRQ": {
      "BookingId": 381,
      "BookingDetailId": 66147,
      "CancelCode": "Q0FOQ0VMLTM4MS0x…",
      "CancelAll": 1,
      "Reason": "Guest changed plans"
    }
  },
  "AdvancedOptions": {
    "Currency": "USD",
    "CustomerIpAddress": "203.0.113.25"
  }
}

Parent	Field	Description	Required
`CancelRQ`	`BookingId`	From BookingDetail.	Yes
`CancelRQ`	`BookingDetailId`	From cancellation charges.	Yes
`CancelRQ`	`CancelCode`	From cancellation charges.	Yes
`CancelRQ`	`CancelAll`	`1` = cancel every room of the booking.	Yes
`CancelRQ`	`Reason`	Short text.	Yes

Response

{
  "Error": [],
  "CancelRS": {
    "HotelOption": {
      "BookingId": 381,
      "HotelRooms": [
        {
          "RoomTypeName": "Double Room",
          "Message": "Room Cancelled Successfully!!!",
          "CancelStatus": 1
        }
      ]
    },
    "Currency": "USD"
  }
}

Parent	Field	Description
`HotelRooms`	`CancelStatus`	`1` = this room is cancelled.

After booking

Booking search

POST/api/xconnect/BookingSearch

Your bookings in a date range. Useful for daily reconciliation.

Request

Request body

{
  "Request": {
    "BookingSearchRQ": {
      "SearchBy": "bookingdate",
      "SearchCriteria": {
        "Dates": {
          "FromDate": "10-01-2026",
          "ToDate": "10-31-2026"
        }
      }
    }
  },
  "AdvancedOptions": {
    "Currency": "USD",
    "CustomerIpAddress": "203.0.113.25"
  }
}

Parent	Field	Description	Required
`BookingSearchRQ`	`SearchBy`	`bookingdate`.	Yes
`Dates`	`FromDate / ToDate`	MM-DD-YYYY.	Yes
`SearchCriteria`	`ReferenceNo / InternalReference`	Find one booking.	No
`SearchCriteria`	`BookingStatus`	`Confirmed`, `Cancelled` or `All`.	No

Response

{
  "Error": [],
  "BookingSearchRS": {
    "Bookings": [
      {
        "ReferenceNo": "RIMO2026100123",
        "InternalReference": "YOURREF-000123",
        "HotelName": "Four Pyramids Guest House",
        "CheckInDate": "04-14-2027",
        "CheckOutDate": "04-15-2027",
        "BookingDate": "10-12-2026",
        "TotalPrice": 18.94,
        "Currency": "USD",
        "Status": "Confirmed"
      }
    ]
  }
}

Parent	Field	Description
`Bookings`	`Status`	Booking status.

Booking statuses

BookingDetail returns a status for each room. Use these rules.

Confirmed

The hotel has the booking. Issue the voucher.

Not Confirmed

The supplier could not confirm the room. The booking does not exist: do not issue a voucher and do not charge the guest. Search again; avoid offering the same room from the same supplier for a while.

Cancelled

Cancelled, by you or by Rimo Global.

Pending / On Request

Only for on-request rooms (IsOnlyAvailable = 0). Not confirmed yet: no voucher. Check BookingDetail again later.

Errors

Code	Type	What it means / what to do
`NOCOUNT_ERROR`	GENERAL	No results for these criteria, or the offer is no longer available (also after a price change in PreBook). Search again.
`SearchKey_Error / CacheNotAvailable`	SearchKeyExpired	The SearchKey expired (25 minutes) or its data was dropped. Search again.
`MISMATCH_ERROR`	Mismatch	Rate missing, or data that does not match the previous response. Search again.
`DUPLICATION_ERROR`	Duplicate	PreBook or Book sent twice for the same offer, or a reused InternalReference.
`NOTPERMITTED_ERROR`	Permission	Your account may not book this (for example a booking already inside the cancellation deadline). Contact support.
`INVALID_REQUEST`	RequestError	The request is not well formed. Check the body against this page.
`INTERNAL_ERROR`	API_ERROR	Server error. Safe to retry for searches and BookingDetail; never retry Book.

HTTP status codes

HTTP	Meaning
`200`	OK. Still check the `Error` array.
`400`	Bad request.
`401`	Missing or wrong token.
`403`	Your IP address is not whitelisted, or the token is not allowed.
`404`	Wrong endpoint name or URL.
`429`	Too many requests per second. Slow down and retry after a short pause.
`500`	Server error.
`503`	Service unavailable. Retry later.

Best practices

Never retry Book. After a timeout or network error, find the booking with BookingDetail and your InternalReference.
Sell only what is Confirmed. Take the guest's money (or capture a held payment) only after every room shows Confirmed.
ReCheck and PreBook once per booking attempt. To try again, search again.
Show before payment: the final price, the cancellation policy, and EssentialInformation (fees paid at the hotel, no-show rules).
Check charges before cancelling, and show them to the guest.
Keep logs of every booking and cancellation request and response for at least 6 months. Remove the token from the logs.
Cache static data (countries, cities, hotel mapping) and refresh it daily. Do not cache prices for more than a few minutes.

Postman collection

A ready-made collection covering all 11 calls in booking order. Each request validates its response, carries the required values into the next step, and shows the result in the Visualize tab.

CollectionRimoGlobal-Hotels-API.postman_collection.json EnvironmentRimoGlobal-Hotels-API.postman_environment.json

In Postman, choose Import and drop both files. Select the Rimo Global Hotels API environment.
In the environment, paste your token, and put the public IP of the computer running Postman in customerIp. That IP must be whitelisted, or every call returns 403.
In the collection variables, set countrySearch and citySearch (steps 1 and 2 save the ids), nationality, and hotelIds from the hotel mapping file.
Run steps 3 to 6. Step 4 picks the cheapest refundable room under maxPrice; change pickIndex to pick another row.
Before step 7 (Book), set firstName and lastName to a real guest. Then run 8, 9 and 10 to confirm and cancel.

Safeguards

Default stay: 90 days from today, 1 night.
Step 4 only selects refundable rooms with at least 7 days of free cancellation.
Step 7 refuses to book above maxPrice (50 by default) or without real Latin-letter names.

Partner support

Integration support, credentials, IP whitelisting and booking escalations: api@rimoglobal.com. For a specific booking, include its InternalReference and ReferenceNo.