Overview

Abstract

This documentation defines the specifications of an API who’s responsibility is to provide access to a unique RoomerFlex™ service. The API is designed as stateless and RESTful and responds only with JSONs. The API endpoints work both with HTTP and HTTPS (SSL) protocols.

A split payment step, which is a credit card payment process upon RoomerFlex™ purchase is optional. The key point of this step is that Roomer Travel Inc. is a merchant of record.

REST API

A Restful web service (API) is a web service implemented using HTTP and the principles of REST. It is a collection of resources, with three defined aspects:

The base URL for the web service: api.roomerflex.com
The main MIME media type supported by the web service is application/json and the default encoding is UTF-8.
The set of operations supported by the web service using HTTP methods:
- GET
- POST
- PUT

Common

Every string passed to and from the RoomerFlex API needs to be UTF-8 encoded.
All dates must be in the following format: YYYY-MM-DD

Authentication

RoomerFlex uses HTTP Headers to authenticate all API requests.

Header key	Header value
`Authorization`	Token token=[token value]
`Partner`	noname@example.com
`API-Version`	v3
`Content-Type`	application/json
`Accept`	application/json

Errors Handling

Error Response Structure

{
  "success": false,
  "error-list": ["Error description"]
}

All errors encountered during request will render the same error structure. The only interchangeable part is a list of errors.

HTTP response status code is: 422 Unprocessable Entity

Sequence Diagrams

flex as an add-on

Diagram

flex as a rate type

Diagram

Endpoints Overview

Sandbox

https://api-sandbox.roomerflex.com/

Production (ssl - secure)

https://api.roomerflex.com/

Hotels

Step 1 - Request token and price for RoomerFlex protection (hotels)

At this stage, send all required details in order to generate a unique protection token. This token should be stored and sent back to the RoomerFlex API along with other needed data in the last stage. In addition to the protection token, the API response includes a total RoomerFlex fee and the fee per night.


URL	/api/protection/request_token
PROTOCOL	HTTP
METHOD	POST

Accepted parameters of a hotel

Hotel

{
  "hotel": {
    "name": "Park Lane Hotel",
    "roomType": "Junior Suite",
    "roomTypeDescription": "Continental breakfast included, Flat screen TV, Air conditioner",
    "boardName": "Bed & Breakfast",
    "address": "36 Central Park S",
    "zipCode": "10019",
    "city": "New York",
    "state": "NY",
    "country": "USA",
    "latitude": 40.759427,
    "longitude": -73.974948,
    "adults": "2",
    "children": "0",
    "checkIn": "2018-01-20",
    "checkOut": "2018-01-25",
    "price": 100.00,
    "tax": 20.00,
    "currency": "USD",
    "partnerHotelId": "2341984",
    "numberOfRooms": 1,
    "cancellationPolicy": {
      "text": "Cancellations or changes made after Jan 18, 2018, are subject to $30.00 (including tax) penalty.",
      "cancelPenalties": [
        {
          "dateFrom": "2018-01-18",
          "hoursBefore": 48,
          "amount": 30.00
        }
      ]
    },
    "locale": "en",
    "offerType": 1, // 1 | 2 | 3
    "userIP": "103.99.58.196",
    "userReference": "9d7d0f9b7a"
  }
}

Name	Type	Mandatory	Description
`name`	String	Required
`roomType`	String	Required
`roomTypeDescription`	String	Optional	Room amenities
`boardName`	String	Optional	Room only / Bed & Breakfast / All inclusive ...
`address`	String	Required	Hotel street address (without city, state, country)
`zipCode`	String	Required
`city`	String	Required
`state`	String	Required	If state not applicable for the county please place `XXX`. Please do not send us the country code twice
`country`	String	Required
`latitude`	Float	Required
`longitude`	Float	Required
`adults`	Integer	Required
`children`	Integer	Optional	A number of children (the default is 0)
`checkIn`	String	Required	Check in date to the hotel `YYYY-MM-DD`
`checkOut`	String	Required	Check out date to the hotel `YYYY-MM-DD`
`price`	Float	Required	Full price including tax and supplements in currency of non-refundable reservation
`refundablePrice`	Float	Optional	Full price including tax and supplements in currency of refundable reservation
`tax`	Float	Optional	In the same currency as the price
`currency`	String	Required	Currency abbreviation, 3 uppercase chars
`partnerHotelId`	String	Required	The hotel's personal ID given by the partner
`numberOfRooms`	Integer	Required	The number of rooms protected if > than 0. Price of booking needs to represent total price of all rooms
`cancellationPolicy`	Object	Optional	Information about a cancellation policy
`text`	String	Optional	A cancellation policy shown to a buyer
`cancelPenalties`	Array	Optional	List of cancellation penalties
`dateFrom`	String	Optional	Cancellation fees are applied between this date and the check in date
`hoursBefore`	Integer	Optional	Cancellation fees are applied this number of hours before the check in date
`amount`	Float	Optional	Cancellation fee to pay starting on the specified `dateFrom` or `hoursBefore` the check in date
`locale`	String	Optional	Language options: en ,de, es, fr, hu, it, nl, tr (the default one is EN)
`offerType`	Integer	Required	Indicates how Flex is offered to a buyer. Options: `1 (opt-in)`, `2 (opt-out)`, `3 (a rate type)`
`userIP`	String	Required	IPv4 or IPv6 address of a buyer (end user)
`userReference`	String	Optional	Unique identifier of a registered client (end user) on partner's side

Response

{
  "success": true,
  "lh-token": "801f21d6-4d1d-49e1-9dc2-7d665ff78dad",
  "lh-refund-rate": "80",
  "lh-fee": 24.00,
  "lh-fee-per-night": "1.2",
  "currency": "USD"
}

Restricted Response

On occasion you may receive a restricted response which looks like this:

{ "success": false, "error_list": ["Restricted"] }

This is the response before the RoomerFlex cancellation protection has been loaded or shown to the customer. An example of this would be if you are calling our API for same day check ins as the cancellation protection needs at least 24 hours before the check in date to be valid.

Step 2 - Register the roomer protection (hotels)

The protection token generated and sent back in the API response at the first step should be used now in order to make the protection valid and registered.


URL	/api/protection/create_protection
PROTOCOL	HTTP
METHOD	POST

Accepted parameters of a hotel

Hotel

{
  "hotel": {
    "register": {
      "itinerary": "23238323",
      "userEmail": "john.doe@example.com",
      "userFirstName": "John",
      "userLastName": "Doe",
      "userPhone": "+1-202-555-0124",
      "userBillingCountry": "US", // "US" | "USA",
      "userReference": "9d7d0f9b7a",
      "agentEmail": "uself1951@einrot.com",
      "comments": "",
      "additionalInfo": "Any additional information in JSON format",
      "payment": {
        "token": "tok_19n89O2kREHR5Kl1gs3hmTlk"
      },
      "cancellationPolicy": "non-refundable",
      "supplierName": "e.g. Tourico",
      "supplierConfirmationNumber": "198979",
      "property": {
        "contactEmail": "someone@hotelname.com",
        "directContract": true,
        "userCreditCard": {
          "last4Digits": "1881",
          "bin": "546747"
        }
      },
      "prepaidBooking": true,
      "prepaidAmount": 100.10,
      "lhToken": "880d8781-d46c-4a8e-b8bc-a408aa94d3cf"
    }
  }
}

Name	Type	Mandatory	Description
`itinerary`	String	Required	In case an error occurs RoomerFlex could identify the package reservation on the partners system. It has a 50 char length limit.
`userEmail`	String	Required	Email of a guest who is going to check in
`userFirstName`	String	Required	First name of a guest who is going to check in
`userLastName`	String	Required	Last name of a guest who is going to check in
`userPhone`	String	Optional	Phone number of a guest who is going to check in
`userBillingCountry`	String	Required	Country code in ISO 3166-1 alpha2 or ISO 3166-1 alpha3 formats from a buyer billing address
`userReference`	String	Optional	Unique identifier of a registered client (end user) on partner's side
`agentEmail`	String	Optional	Only for B2B integrations when a reservation sold by a travel agent
`comments`	String	Optional	Any comments (up to 255 chars)
`additionalInfo`	String	Optional	In JSON format
`payment`	Object	Optional	Is applicable to split payment type of integration and should contain a token from Stripe
`cancellationPolicy`	String	Optional
`supplierName`	String	Required	The supplier name of the original reservation (booking source)
`supplierConfirmationNumber`	String	Required	The supplier’s confirmation number of the reservation (PNR)
`property`	Object	Optional
`contactEmail`	String	Optional	A contact person email at the hotel (applicable for direct contracts)
`directContract`	Boolean	Optional	Was the inventory directly contracted with a hotel, or through a 3rd party supplier
`userCreditCard`	Object	Optional
`last4Digits`	String	Optional	Last 4 digits that appear on a credit card (applicable for direct contracts)
`bin`	String	Optional	A bank identification number. The initial 4 to 6 numbers that appear on a credit card (applicable for direct contracts)
`prepaidBooking`	Boolean	Required	Was a buyer charged 100% at time of booking?
`prepaidAmount`	Float	Required	Amount a buyer paid at time of booking (a full price by default)
`lhToken`	String	Required	The token from a API response of the "Step 1"

Response

{
  "success": true,
  "registered" : true,
  "lh-token" : "801f21d6-4d1d-49e1-9dc2-7d665ff78dad"
}

Optional - Convert guest payment details into a Stripe token for a split payment

A single Stripe token use Stripe token wraps the details of a credit card and can be securely used in place of it. In order to create such token you need to send a HTTP POST request to the following URL:

https://api.stripe.com/v1/tokens

A response from Stripe will look like this one:

Stripe response screenshot

The most important part is the token id key. RoomerFlex API needs to get this token during create_protection request. Please note that this token can only be used once. Alternatively, you can use the Stripe.js library if a client-side solution is preferable.

pk_test_IwgXZOyVP6cHq4uBr03vemro - is Roomer Travel authentication key for Stripe test environment.

Step 3 - Activate the roomer protection (hotels)

The protection token generated and sent back in the API response at the first step should be used in order to activate the protection and to start the refund flow.

An example of the request:

curl --header 'Accept: application/json' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Token token=PARTNER_TOKEN' \
 --header 'Partner: PARTNER_EMAIL' \
 --header 'API-Version: V3' \
 --request POST \
 https://api.roomerflex.com/api/protection/activate_protection?token=

HTTP request description


URL	/api/protection/activate_protection.
PROTOCOL	HTTP
METHOD	POST

Accepted parameters


URL QUERY PARAMETER	token

Response

{
  "success" : true,
  "activated" : true,
  "lh-token" : "801f21d6-4d1d-49e1-9dc2-7d665ff78dad"
}

Protection status

The API supports requests for protection status. A response is a JSON object with comprehensive details regarding the protection.

An example of the request:

curl --header 'Accept: application/json' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Token token=PARTNER_TOKEN' \
 --header 'Partner: PARTNER_EMAIL' \
 --header 'API-Version: V3' \
 --request GET \
 https://api.roomerflex.com/api/protection/protection_status?lh-token=

HTTP request description


URL	/api/protection/protection_status.
PROTOCOL	HTTP
METHOD	GET

Accepted parameters

For hotels:


URL QUERY PARAMETER	lh-token	A token from the response at the step one.
URL QUERY PARAMETER	ref-number	A itinerary number sent upon registration at the step two.

Response

{
  "success": true,
  "user_first_name": "John",
  "user_last_name": "Doe",
  "user_phone": "+1-202-555-0124",
  "user_email": "john.doe@example.com",
  "hotel_name": "Park Lane Hotel",
  "hotel_address": "36 Central Park S",
  "hotel_city": "New York",
  "hotel_country": "NY",
  "check_in": "2018-01-20",
  "check_out": "2018-01-25",
  "partner_hotel_id": "2341984",
  "supplier_name": null,
  "supplier_confirmation_number": null,
  "refund_percentage": 80,
  "rp_price": 6.00,
  "rp_price_per_night": "6.00",
  "tax": 20.00,
  "registered": true,
  "activated": false,
  "resold": true
}

Finance status

This endpoint returns RoomerFlex™ details (e.g. status) and partner's commission (revenue share) of RoomerFlex™ fee and room resale price.

An example of the request:

curl --header "Content-Type:application/json" \
 --header "Authorization: Token token=PARTNER_TOKEN" \
 --header "Partner: PARTNER_EMAIL" \
 --header "API-Version: V3" \
 --request POST \
 --data '{
    "searchKey":"checkInRange",
    "searchValue":["2019-12-01", "2019-12-31"]
 }' \
 https://api.roomerflex.com/api/protection/finance_status

HTTP request description


URL	/api/protection/finance_status
PROTOCOL	HTTP
METHOD	POST

Accepted parameters

Name	Type	Mandatory
`searchKey`	String	Required
`searchValue`	String or Array of Strings	Required

Allowed options:

{ "searchKey": "checkInRange", "searchValue": ["yyyy-mm-dd", "yyyy-mm-dd"] } From checkIn To checkIn

{ "searchKey": "checkOutRange", "searchValue": ["yyyy-mm-dd", "yyyy-mm-dd"] } From checkOut To checkOut

{ "searchKey": "dateCreatedRange", "searchValue": ["yyyy-mm-dd", "yyyy-mm-dd"] } From dateCreated To dateCreated

{ "searchKey": "dateModified", "searchValue": "yyyy-mm-dd" } Multiple dates are not allowed

{ "searchKey": "tokens", "searchValue": ["22beb098-e987", "723f388b-5ccc", "ec68c745-be57"] } Upto 1000 items maximum

{ "searchKey": "itineraries", "searchValue": ["45c73f", "3ff75c", "0634a3"] } Upto 1000 items maximum

{ "searchKey": "supplierConfirmationNumbers", "searchValue": ["45c73f", "3ff75c", "0634a3"] } Upto 1000 items maximum

RoomerFlex™ may have the following statuses:

registered
Confirmation that the cancellation protection has been added to the booking, or is included in a confirmed booking.
activated
The cancellation protection has been utilized by the customer and their booking has been cancelled, as such the customer is entitled to receive the refund.
IMPORTNAT: The Reservation is transferred to Roomer for the option of re-sell and should not be cancelled with the original supplier.
finished
The customer has activated their cancellation protection and has received the refund.
resold
The Reservation that was activated has been successfully re-sold.
fraud
Any customer undertaking fraudulent activity (as detected by Roomer) shall automatically lose their right to receive the Refund and the Cancellation Option Fee paid to purchase the Cancellation Option shall not be returned and/or refunded.
void
The cancellation protection option is no longer valid.

Response

{
  "success": true,
  "protections": [
    {
      "dateCreated": "yyyy-mm-dd",
      "status": "ONE OF SUPPORTED STATUSES",
      "itinerary": "45c73f",
      "token": "22beb098-e987",
      "supplierConfirmationNumber": "0634a3",
      "commission": {
        "currency": "USD",
        "feeRevShare": "xxx.xx",
        "resaleRevShare": "xxx.xx"
      }
    }
  ]
}

Remove protection (hotels)

This API endpoint allows to cancel (to rollback) a protection after it has registered.

An example of the request (hotel only):

curl --header 'Accept: application/json' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Token token=PARTNER_TOKEN' \
 --header 'Partner: PARTNER_EMAIL' \
 --header 'API-Version: V3' \
 --request POST \
 --data '{
    "hotel": {
        "lhToken": ""
    }
 }' \
 https://api.roomerflex.com/api/protection/remove_protection

HTTP request description


URL	/api/protection/remove_protection
PROTOCOL	HTTP
METHOD	POST

Accepted parameters

Name	Type	Mandatory	Description
`hotel`	Object	Required
`hotel.lhToken`	String	Required

Response

{
  "success": true
}

Offers for multiple room types

Get RoomerFlex fee estimations for multiple room types per hotel.

An example of the request:

{
  "hotel": [
    {
      "check_in": "2019-06-01",
      "check_out": "2019-06-04",
      "price": 100.00,
      "currency": "USD",
      "hotel_name": "Park Lane Hotel",
      "hotel_address": "36 Central Park S",
      "hotel_city": "New York",
      "hotel_state": "NY",
      "hotel_country": "USA",
      "hotel_postcode": "10019",
      "hotel_latitude": 40.759427,
      "hotel_longitude": -73.974948,
      "hotel_room_type": "Junior Suite",
      "partner_room_id": "104071_2108635"
    },
    {
      "check_in": "2019-06-01",
      "price": 200.00,
      "currency": "USD",
      "hotel_name": "Park Lane Hotel",
      "hotel_address": "36 Central Park S",
      "hotel_city": "New York",
      "hotel_state": "NY",
      "hotel_country": "USA",
      "hotel_postcode": "10019",
      "hotel_latitude": 40.759427,
      "hotel_longitude": -73.974948,
      "hotel_room_type": "Deluxe Room",
      "partner_room_id": "104071_238950"
    },
    {
      "check_in": "2019-06-01",
      "check_out": "2019-06-04",
      "price": 257.30,
      "currency": "USD",
      "hotel_name": "Park Lane Hotel",
      "hotel_address": "36 Central Park S",
      "hotel_city": "New York",
      "hotel_state": "NY",
      "hotel_country": "USA",
      "hotel_postcode": "10019",
      "hotel_latitude": 40.759427,
      "hotel_longitude": -73.974948,
      "hotel_room_type": "Superior Double Room",
      "partner_room_id": "104072_2108639"
    }
  ]
}

HTTP request description


URL	/api/protection/offers
PROTOCOL	HTTP
METHOD	POST

Accepted parameters

Name	Type	Mandatory	Description
`hotel`	List of objects	Required
`check_in`	String	Required	Check in date to the hotel `YYYY-MM-DD`
`check_out`	String	Required	Check out date to the hotel `YYYY-MM-DD`
`price`	Float	Required	Full price including tax and supplements in currency
`currency`	String	Required	Currency abbreviation, 3 uppercase chars
`hotel_name`	String	Optional
`hotel_address`	String	Optional	Hotel street address (without city, state, country)
`hotel_city`	String	Required
`hotel_state`	String	Required	Default value is `XXX` if not applicable
`hotel_country`	String	Required
`hotel_postcode`	String	Optional
`hotel_latitude`	Float	Optional
`hotel_longitude`	Float	Optional
`hotel_room_type`	String	Optional
`partner_room_id`	String	Required

Response

{
  "success": true,
  "hotels": {
    "104071_2108635": {
      "check_in": "2019-06-01",
      "check_out": "2019-06-04",
      "price": 100.00,
      "currency": "USD",
      "hotel_name": "Park Lane Hotel",
      "hotel_address": "36 Central Park S",
      "hotel_city": "New York",
      "hotel_state": "NY",
      "hotel_country": "USA",
      "hotel_postcode": "10019",
      "hotel_latitude": 40.759427,
      "hotel_longitude": -73.974948,
      "hotel_room_type": "Junior Suite",
      "partner_room_id": "104071_2108635",
      "rp_price": 6.00,
      "rp_price_per_night": 2.00
    },
    "104071_238950": {
      "check_in": "2019-06-01",
      "price": 200.00,
      "currency": "USD",
      "hotel_name": "Park Lane Hotel",
      "hotel_address": "36 Central Park S",
      "hotel_city": "New York",
      "hotel_state": "NY",
      "hotel_country": "USA",
      "hotel_postcode": "10019",
      "hotel_latitude": 40.759427,
      "hotel_longitude": -73.974948,
      "hotel_room_type": "Deluxe Room",
      "partner_room_id": "104071_238950",
      "error_list": ["Check out date is missing"]
    },
    "104072_2108639": {
      "check_in": "2019-06-01",
      "check_out": "2019-06-04",
      "price": 257.30,
      "currency": "USD",
      "hotel_name": "Park Lane Hotel",
      "hotel_address": "36 Central Park S",
      "hotel_city": "New York",
      "hotel_state": "NY",
      "hotel_country": "USA",
      "hotel_postcode": "10019",
      "hotel_latitude": 40.759427,
      "hotel_longitude": -73.974948,
      "hotel_room_type": "Superior Double Room",
      "partner_room_id": "104072_2108639",
      "rp_price": 15.438,
      "rp_price_per_night": 5.146
    }
  }
}

Offers for multiple hotels

Get RoomerFlex fee estimations for multiple hotels per request.

An example of the request:

{
  "hotels": [
    {
      "check_in": "2019-06-01",
      "check_out": "2019-06-04",
      "price": 100.00,
      "currency": "USD",
      "hotel_name": "Park Lane Hotel",
      "hotel_address": "36 Central Park S",
      "hotel_city": "New York",
      "hotel_state": "NY",
      "hotel_country": "USA",
      "hotel_postcode": "10019",
      "hotel_latitude": 40.759427,
      "hotel_longitude": -73.974948,
      "hotel_room_type": "Junior Suite",
      "partner_hotel_id": "10010",
      "cancellation_policy": {
        "text": "Cancellations or changes made after May 30, 2019, are subject to $30.00 (including tax) penalty.",
        "cancel_penalties": [
          {
            "date_from": "2019-05-30",
            "hours_before": 48,
            "amount": 30.00
          }
        ]
      }
    },
    {
      "check_in": "2019-06-01",
      "check_out": "2019-06-04",
      "price": 200.00,
      "currency": "USD",
      "hotel_name": "The Majestic Hotel",
      "hotel_address": "5 Jalan Sultan Hishamuddin",
      "hotel_city": "Kuala Lumpur",
      "hotel_state": "Wilayah Persekutuan Kuala Lumpur",
      "hotel_country": "Malaysia",
      "hotel_postcode": "50000",
      "hotel_latitude": 3.1392,
      "hotel_longitude": 101.6922,
      "hotel_room_type": "Deluxe Room",
      "partner_hotel_id": "20020",
      "cancellation_policy": {
        "text": "Cancellations or changes made after May 30, 2019, are subject to $30.00 (including tax) penalty.",
        "cancel_penalties": [
          {
            "date_from": "2019-05-30",
            "hours_before": 48,
            "amount": 60.00
           }
        ]
      }
    },
    {
      "check_in": "2019-06-01",
      "check_out": "2019-06-04",
      "price": 124.78,
      "currency": "USD",
      "hotel_name": "Ryugyong Hotel",
      "hotel_address": "North Korea, Pyongyang, KP",
      "hotel_city": "Pyongyang",
      "hotel_state": "KP",
      "hotel_country": "North Korea",
      "hotel_postcode": null,
      "hotel_latitude": 39.036636,
      "hotel_longitude": 125.730919,
      "hotel_room_type": "Room",
      "partner_hotel_id": "30030",
      "cancellation_policy": {
        "text": "Cancellations or changes made after May 30, 2019, are subject to $30.00 (including tax) penalty.",
        "cancel_penalties": [
          {
            "date_from": "2019-05-30",
            "hours_before": 48,
            "amount": 32.40
          }
        ]
      }
    }
  ]
}

HTTP request description


URL	/api/protection/offers
PROTOCOL	HTTP
METHOD	POST

Accepted parameters

Name	Type	Mandatory	Description
`hotels`	List of objects	Required
`check_in`	String	Required	Check in date to the hotel `YYYY-MM-DD`
`check_out`	String	Required	Check out date to the hotel `YYYY-MM-DD`
`price`	Float	Required	Full price including tax and supplements in currency
`currency`	String	Required	Currency abbreviation, 3 uppercase chars
`hotel_name`	String	Optional
`hotel_address`	String	Optional	Hotel street address (without city, state, country)
`hotel_city`	String	Required
`hotel_state`	String	Required	Default value is `XXX` if not applicable
`hotel_country`	String	Required
`hotel_postcode`	String	Optional
`hotel_latitude`	Float	Optional
`hotel_longitude`	Float	Optional
`hotel_room_type`	String	Optional
`partner_hotel_id`	String	Required
`cancellation_policy`	Object	Optional	Information about a cancellation policy
`text`	String	Optional	A cancellation policy shown to a buyer
`cancel_penalties`	Array	Optional	List of cancellation penalties
`date_from`	String	Optional	Cancellation fees are applied between this date and the check in date
`hours_before`	Integer	Optional	Cancellation fees are applied this number of hours before the check in date
`amount`	Float	Optional	Cancellation fee to pay starting on the specified `date_from` or `hours_before` the check in date

Response

{
  "success": true,
  "hotels": {
    "10010": {
      "check_in": "2019-06-01",
      "check_out": "2019-06-04",
      "price": 200.00,
      "currency": "USD",
      "hotel_name": "Park Lane Hotel",
      "hotel_address": "36 Central Park S",
      "hotel_city": "New York",
      "hotel_state": "NY",
      "hotel_country": "USA",
      "hotel_postcode": "10019",
      "hotel_latitude": 40.759427,
      "hotel_longitude": -73.974948,
      "hotel_room_type": "Junior Suite",
      "partner_hotel_id": "10010",
      "rp_price": 14.00,
      "rp_price_per_night": 4.67
    },
    "20020": {
      "check_in": "2019-06-01",
      "check_out": "2019-06-04",
      "price": 100.00,
      "currency": "USD",
      "hotel_name": "The Majestic Hotel",
      "hotel_address": "5 Jalan Sultan Hishamuddin",
      "hotel_city": "Kuala Lumpur",
      "hotel_state": "Wilayah Persekutuan Kuala Lumpur",
      "hotel_country": "Malaysia",
      "hotel_postcode": "50000",
      "hotel_latitude": 3.1392,
      "hotel_longitude": 101.6922,
      "hotel_room_type": "Deluxe Room",
      "partner_hotel_id": "20020",
      "rp_price": 7.00,
      "rp_price_per_night": 2.33
    },
    "30030": {
      "check_in": "2019-06-01",
      "check_out": "2019-06-04",
      "price": 124.78,
      "currency": "USD",
      "hotel_name": "Ryugyong Hotel",
      "hotel_address": "North Korea, Pyongyang, KP",
      "hotel_city": "Pyongyang",
      "hotel_state": "KP",
      "hotel_country": "North Korea",
      "hotel_postcode": null,
      "hotel_latitude": 39.036636,
      "hotel_longitude": 125.730919,
      "hotel_room_type": "Room",
      "partner_hotel_id": "30030",
      "error_list": ["Restricted"]
    }
  }
}

Flights

Step 1 - Request token and price for RoomerFlex protection (flights)


URL	/api/protection/request_token
PROTOCOL	HTTP
METHOD	POST

Accepted parameters of flight(s)

Flight(s)

{
  "package": {
    "name": "",
    "totalPrice": 1550.59,
    "totalTax": 200.00,
    "currency": "USD",
    "locale": "en",
    "offerType": 1, // 1 | 2 | 3,
    "userIP": "103.99.58.196",
    "items": [
      {
        "type": "flight",
        // ...
      }
    ]
  }
}

Name	Type	Mandatory	Description
`name`	String	Optional	Commercial title of the package
`totalPrice`	Float	Required	Full price including tax and supplements in specified currency
`totalTax`	Float	Optional	In specified currency
`currency`	String	Required	Currency abbreviation, 3 uppercase chars
`locale`	String	Optional	Language options: en ,de, es, fr, hu, it, nl, tr
`offerType`	Integer	Required	Indicates how Flex is offered to a buyer. Options: `1 (opt-in)`, `2 (opt-out)`, `3 (a rate type)`
`items`	List of objects	Required	A list of flights
`userIP`	String	Required	IPv4 or IPv6 address of a buyer (end user)

A flight item

{
  "type": "flight",
  "price": 1550.59,
  "currency": "USD",
  "adults": 2,
  "children": 0,
  "infants": 0,
  "segments": [
    {
      "origin": "BER",
      "destination": "LON",
      "departure": {
        "date": "2018-02-18",
        "time": "13:45",
        "timeZone": "CEST or UTC +0200"
      },
      "arrival": {
        "date": "2018-02-18",
        "time": "14:40",
        "timeZone": "BST or UTC +0100"
      },
      "class": "Y",
      "marketing": {
        "carrier": "SU"
      },
      "operating": {
        "carrier": "EZY",
        "flightNumber": "281"
      }
    },
    {
      "origin": "LHR",
      "destination": "JFK",
      "departure": {
        "date": "2018-02-21",
        "time": "20:15",
        "timeZone": "BST or UTC +0100"
      },
      "arrival": {
        "date": "2018-02-21",
        "time": "22:20",
        "timeZone": "EDT or UTC -0400"
      },
      "class": "Y",
      "marketing": {
        "carrier": "SU"
      },
      "operating": {
        "carrier": "DL",
        "flightNumber": "315"
      }
    },
    {
      "origin": "JFK",
      "destination": "BER",
      "departure": {
        "date": "2018-03-03",
        "time": "10:00",
        "timeZone": "EDT or UTC -0400"
      },
      "arrival": {
        "date": "2018-03-04",
        "time": "00:05",
        "timeZone": "CEST or UTC +0200"
      },
      "class": "Y",
      "marketing": {
        "carrier": "SU"
      },
      "operating": {
        "carrier": "UA",
        "flightNumber": "298"
      }
    }
  ]
}

Accepted parameters of a flight item

Name	Type	Mandatory	Description
`type`	String	Required	Specifies that current item is a flight
`price`	Float	Optional	Full price including tax and supplements in currency
`currency`	String	Required	Currency abbreviation, 3 uppercase chars
`adults`	Integer	Required
`children`	Integer	Required	Number of children (the default is 0)
`infants`	Integer	Required	Number of infants (the default is 0)
`segments`	List of objects	Required	A list of actual flights (e.g. two ways, a connection flight etc.)
`origin`	String	Required	City abbreviation
`destination`	String	Required	City abbreviation
`departure`	Object	Required	This includes details of departure date and time in a time zone of original
`arrival`	Object	Required	This includes details of arrival date and time in a time zone of destination
`date`	String	Required
`time`	String	Required
`timeZone`	String	Required
`class`	String	Required	A travel class
`marketing`	Object	Required	Details of a flight company that sells a flight
`carrier`	String	Optional	IATA airline code
`operating`	Object	Required	Details of a flight company that operates a flight
`carrier`	String	Required	IATA airline code
`flightNumber`	String	Required

Response

{
  "success": true,
  "lh-token": "801f21d6-4d1d-49e1-9dc2-7d665ff78dad",
  "lh-refund-rate": "80",
  "lh-fee": 24.00,
  "lh-fee-per-night": "1.2",
  "currency": "USD"
}

Restricted Response

On occasion you may receive a restricted response which looks like this:

{ "success": false, "error_list": ["Restricted"] }

Step 2 - Register the roomer protection (flights)

The protection token generated and sent back in the API response at the first step should be used now in order to make the protection valid and registered.


URL	/api/protection/create_protection
PROTOCOL	HTTP
METHOD	POST

Accepted parameters of flight(s)

Flight(s)

{
  "package": {
    "register": {
      "itinerary": "23238323",
      "agentEmail": "",
      "comments": "",
      "additionalInfo": "",
      "prepaidBooking": true,
      "lhToken": "880d8781-d46c-4a8e-b8bc-a408aa94d3cf",
      "payment": {
        "token": "tok_1AWPCU2kREHR5Kl1Tncn9LGg"
      },
      "buyer": {
        "firstName": "Jane",
        "lastName" : "Doe",
        "email" : "jane.doe@example.com",
        "phone" : "+1-202-555-0124",
        "billingCountry": "US", // "US" | "USA"
      },
      "items": [
        {
          "type": "flight",
          // ...
        }
      ]
    }
  }
}

Name	Type	Mandatory	Description
`itinerary`	String	Required	In case an error occurs RoomerFlex could identify the package reservation on the partners system. It has a 50 char length limit.
`agentEmail`	String	Optional	Only for B2B integrations when the sale is made by a travel agent
`comments`	String	Optional	Any comments (up to 255 chars)
`additionalInfo`	String	Optional	In JSON format
`prepaidBooking`	Boolean	Optional	Was a buyer charged 100% at time of booking?
`lhToken`	String	Required	The token from a API response of the "Step 1"
`payment`	Object	Optional	Is applicable to split payment type of integration and should contain a token from Stripe
`buyer`	Object	Required	Contains an information regarding a buyer of this package in form of JSON object with sub keys
`firstName`	String	Optional	Buyer’s first name (a sub key of the `buyer` object)
`lastName`	String	Optional	Buyer’s last name (a sub key of the `buyer` object)
`email`	String	Optional	Buyer’s email address (a sub key of the `buyer` object)
`phone`	String	Optional	Buyer’s phone number (a sub key of the `buyer` object)
`billingCountry`	String	Required	Country code in ISO 3166-1 alpha2 or ISO 3166-1 alpha3 formats from a buyer billing address (a sub key of the `buyer` object)
`items`	List of objects	Required	A list of flights

A flight item

{
  "type": "flight",
  "itinerary": "32106589",
  "supplierName": "SecretEscapes or third party",
  "supplierConfirmationNumber": "2014730",
  "passengers": [
    {
      "title": "Miss or Ms or Mr or Sir or Mrs or Dr",
      "firstName": "Jane",
      "lastName": "Doe",
      "passengerType": "Adult or Child or Infant",
      "tickets": [
        {
          "number": "8382177546344 / 3",
          "seat": "11A",
          "operating": {
            "carrier": "EZY",
            "flightNumber": "281"
          }
        },
        {
          "number": "A3217754S344 / 0",
          "seat": "05F",
          "operating": {
            "carrier": "DL",
            "flightNumber": "315"
          }
        },
        {
          "number": "32ED17754S3124",
          "seat": "12E",
          "operating": {
            "carrier": "UA",
            "flightNumber": "298"
          }
        }
      ],
      "specialRequest": ""
    },
    {
      "title": "Miss or Ms or Mr or Sir or Mrs or Dr",
      "firstName": "John",
      "lastName": "Doe",
      "passengerType": "Adult or Child or Infant",
      "tickets": [
        {
          "number": "8382177546344 / 3",
          "seat": "12A",
          "operating": {
            "carrier": "EZY",
            "flightNumber": "281"
          }
        },
        {
          "number": "A3217754S344 / 0",
          "seat": "06F",
          "operating": {
            "carrier": "DL",
            "flightNumber": "315"
          }
        },
        {
          "number": "32ED17754S3124",
          "seat": "13E",
          "operating": {
            "carrier": "UA",
            "flightNumber": "298"
          }
        }
      ],
      "specialRequest": ""
    }
  ]
}

Accepted parameters of a flight item

Name	Type	Mandatory	Description
`type`	String	Required	Specifies that current item is a flight
`itinerary`	String	Optional	Applies only to dynamically formed packages by the partner itself and not from the 3rd party supplier
`supplierName`	String	Required	The supplier name of the original reservation (booking source)
`supplierConfirmationNumber`	String	Required	The supplier’s confirmation number of the reservation (PNR)
`passengers`	List of objects	Required	Contains an information regarding passengers personal details and their tickets
`title`	String	Optional	Miss or Ms or Mr or Sir or Mrs or Dr (part of an object in the `passengers` array)
`firstName`	String	Required
`lastName`	String	Required
`passengerType`	String	Required	Adult or Child or Infant (part of an object in the `passengers` array)
`tickets`	List of object	Required	Contains an information regarding passengers flight tickets (two ways and / or with connections)
`number`	String	Required	The flight ticket number (part of an object in `tickets` array)
`seat`	String		A plane seat if specified in the ticket (part of an object in `tickets` array)
`operating`	Object	Required	The flight company details in format of the JSON object
`carrier`	String	Required	An abbreviation of the flight company
`flightNumber`	String	Required
`carrier`	String	Required	An abbreviation of the flight company
`specialRequest`	String	Optional	ny requests to the flight company (e.g. a special food).

Response

{
  "success": true,
  "registered" : true,
  "lh-token" : "801f21d6-4d1d-49e1-9dc2-7d665ff78dad"
}

Optional - Convert guest payment details into a Stripe token for a split payment

https://api.stripe.com/v1/tokens

A response from Stripe will look like this one:

Stripe response screenshot

pk_test_IwgXZOyVP6cHq4uBr03vemro - is Roomer Travel authentication key for Stripe test environment.

Step 3 - Activate the roomer protection (flights)

The protection token generated and sent back in the API response at the first step should be used in order to activate the protection and to start the refund flow.

An example of the request:

curl --request POST \
     --url 'https://api.roomerflex.com/api/protection/activate_protection?token=801f21d6-4d1d-49e1-9dc2-7d665ff78dad' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'Authorization: Token token="PARTNER TOKEN"' \
     --header 'partner: PARTNER EMAIL' \
     --header 'API-Version: V3'

HTTP request description


URL	/api/protection/activate_protection.
PROTOCOL	HTTP
METHOD	POST

Accepted parameters


URL QUERY PARAMETER	token

Response

{
  "success" : true,
  "activated" : true,
  "lh-token" : "801f21d6-4d1d-49e1-9dc2-7d665ff78dad"
}

Remove protection (flights)

This API endpoint allows to cancel (to rollback) a protection after it has registered.

An example of the request (flight only):

curl --header 'Accept: application/json' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Token token=PARTNER_TOKEN' \
 --header 'Partner: PARTNER_EMAIL' \
 --header 'API-Version: V3' \
 --request POST \
 --data '{
    "flight": {
        "lhToken": ""
    }
 }' \
 https://api.roomerflex.com/api/protection/remove_protection

HTTP request description


URL	/api/protection/remove_protection
PROTOCOL	HTTP
METHOD	POST

Accepted parameters

Name	Type	Mandatory	Description
`flight`	Object	Required
`flight.lhToken`	String	Required

Response

{
  "success": true
}

Vacation Packages

Step 1 - Request token and price for RoomerFlex protection (packages)


URL	/api/protection/request_token
PROTOCOL	HTTP
METHOD	POST

Accepted parameters of a package

Package

{
  "package": {
    "name": "",
    "totalPrice": 1650.59,
    "totalTax": 200.00,
    "currency": "USD",
    "locale": "en",
    "offerType": 1, // 1 | 2 | 3,
    "userIP": "103.99.58.196",
    "userReference": "9d7d0f9b7a",
    "items": [
      {
        "type": "hotel",
        // ...
      },
      {
        "type": "flight",
        // ...
      }
    ]
  }
}

Name	Type	Mandatory	Description
`name`	String	Optional	Commercial title of the package
`totalPrice`	Float	Required	Full price including tax and supplements in specified currency
`totalTax`	Float	Optional	In specified currency
`currency`	String	Required	Currency abbreviation, 3 uppercase chars
`locale`	String	Optional	Language options: en ,de, es, fr, hu, it, nl, tr
`offerType`	Integer	Required	Indicates how Flex is offered to a buyer. Options: `1 (opt-in)`, `2 (opt-out)`, `3 (a rate type)`
`items`	List of objects	Required	A list of items the package includes (e.g. a hotel, a flight etc.)
`userIP`	String	Required	IPv4 or IPv6 address of a buyer (end user)
`userReference`	String	Optional	Unique identifier of a registered client (end user) on partner's side

A hotel item of the package

{
  "type": "hotel",
  "name": "Park Lane Hotel",
  "roomType": "Junior Suite",
  "roomTypeDescription": "Continental breakfast included, Flat screen TV, Air conditioner",
  "boardName": "Bed & Breakfast",
  "address": "36 Central Park S",
  "zipCode": "10019",
  "city": "New York",
  "state": "NY",
  "country" : "USA",
  "latitude": "40.759427",
  "longitude": "-73.974948",
  "adults": "2",
  "children": "0",
  "checkIn": "2018-01-20",
  "checkOut": "2018-01-25",
  "price": 100.00,
  "currency": "USD",
  "partnerHotelId": "2341984",
  "numberOfRooms": 1,
  "cancellationPolicy": {
    "text": "Cancellations or changes made after Jan 18, 2018, are subject to $30.00 (including tax) penalty.",
    "cancelPenalties": [
      {
        "dateFrom": "2018-01-18",
        "hoursBefore": 48,
        "amount": 30.00
      }
    ]
  }
}

Accepted parameters of a hotel item in the package

Name	Type	Mandatory	Description
`type`	String	Required	Specifies that current item is a hotel
`name`	String	Required
`roomType`	String	Required
`roomTypeDescription`	String	Optional	Room amenities
`boardName`	String	Optional	Room only / Bed & Breakfast / All inclusive ...
`address`	string	Required	Hotel street address (without city, state, country)
`zipCode`	String	Required
`city`	String	Required
`state`	String	Required	If state not applicable for the county please place `XXX`. Please do not send us the country code twice
`country`	String	Required
`latitude`	Float	Required
`longitude`	Float	Required
`adults`	Float	Required
`children`	integer	Optional	A number of children (the default is 0)
`checkIn`	String	Required	Check in date to the hotel `YYYY-MM-DD`
`checkOut`	String	Required	Check out date from the hotel `YYYY-MM-DD`
`price`	Float	Optional	Full price including tax and supplements in currency
`currency`	String	Required	Currency abbreviation, 3 uppercase chars
`partnerHotelId`	String	Optional	The hotel's personal ID given by the partner
`numberOfRooms`	Integer	Required	The number of rooms protected if > than 0. Price of booking needs to represent total price of all rooms
`cancellationPolicy`	Object	Optional	Information about a cancellation policy
`text`	String	Optional	A cancellation policy shown to a buyer
`cancelPenalties`	Array	Optional	List of cancellation penalties
`dateFrom`	String	Optional	Cancellation fees are applied between this date and the check in date
`hoursBefore`	Integer	Optional	Cancellation fees are applied this number of hours before the check in date
`amount`	Float	Optional	Cancellation fee to pay starting on the specified `dateFrom` or `hoursBefore` the check in date

A flight item

{
  "type": "flight",
  "price": 1550.59,
  "currency": "USD",
  "adults": 2,
  "children": 0,
  "infants": 0,
  "segments": [
    {
      "origin": "BER",
      "destination": "LON",
      "departure": {
        "date": "2018-02-18",
        "time": "13:45",
        "timeZone": "CEST or UTC +0200"
      },
      "arrival": {
        "date": "2018-02-18",
        "time": "14:40",
        "timeZone": "BST or UTC +0100"
      },
      "class": "Y",
      "marketing": {
        "carrier": "SU"
      },
      "operating": {
        "carrier": "EZY",
        "flightNumber": "281"
      }
    },
    {
      "origin": "LHR",
      "destination": "JFK",
      "departure": {
        "date": "2018-02-21",
        "time": "20:15",
        "timeZone": "BST or UTC +0100"
      },
      "arrival": {
        "date": "2018-02-21",
        "time": "22:20",
        "timeZone": "EDT or UTC -0400"
      },
      "class": "Y",
      "marketing": {
        "carrier": "SU"
      },
      "operating": {
        "carrier": "DL",
        "flightNumber": "315"
      }
    },
    {
      "origin": "JFK",
      "destination": "BER",
      "departure": {
        "date": "2018-03-03",
        "time": "10:00",
        "timeZone": "EDT or UTC -0400"
      },
      "arrival": {
        "date": "2018-03-04",
        "time": "00:05",
        "timeZone": "CEST or UTC +0200"
      },
      "class": "Y",
      "marketing": {
        "carrier": "SU"
      },
      "operating": {
        "carrier": "UA",
        "flightNumber": "298"
      }
    }
  ]
}

Accepted parameters of a flight item

Name	Type	Mandatory	Description
`type`	String	Required	Specifies that current item is a flight
`price`	Float	Optional	Full price including tax and supplements in currency
`currency`	String	Required	Currency abbreviation, 3 uppercase chars
`adults`	Integer	Required
`children`	Integer	Required	Number of children (the default is 0)
`infants`	Integer	Required	Number of infants (the default is 0)
`segments`	List of objects	Required	A list of actual flights (e.g. two ways, a connection flight etc.)
`origin`	String	Required	City abbreviation
`destination`	String	Required	City abbreviation
`departure`	Object	Required	This includes details of departure date and time in a time zone of original
`arrival`	Object	Required	This includes details of arrival date and time in a time zone of destination
`date`	String	Required
`time`	String	Required
`timeZone`	String	Required
`class`	String	Required	A travel class
`marketing`	Object	Required	Details of a flight company that sells a flight
`carrier`	String	Optional	IATA airline code
`operating`	Object	Required	Details of a flight company that operates a flight
`carrier`	String	Required	IATA airline code
`flightNumber`	String	Required

Response

{
  "success": true,
  "lh-token": "801f21d6-4d1d-49e1-9dc2-7d665ff78dad",
  "lh-refund-rate": "80",
  "lh-fee": 24.00,
  "lh-fee-per-night": "1.2",
  "currency": "USD"
}

Restricted Response

On occasion you may receive a restricted response which looks like this:

{ "success": false, "error_list": ["Restricted"] }

Step 2 - Register the roomer protection (packages)

The protection token generated and sent back in the API response at the first step should be used now in order to make the protection valid and registered.


URL	/api/protection/create_protection
PROTOCOL	HTTP
METHOD	POST

Accepted parameters of a package

Package

{
  "package": {
    "register": {
      "itinerary": "23238323",
      "agentEmail": "",
      "comments": "",
      "additionalInfo": "",
      "prepaidBooking": true,
      "lhToken": "880d8781-d46c-4a8e-b8bc-a408aa94d3cf",
      "payment": {
        "token": "tok_1AWPCU2kREHR5Kl1Tncn9LGg"
      },
      "buyer": {
        "firstName": "Jane",
        "lastName" : "Doe",
        "email" : "jane.doe@example.com",
        "phone" : "+1-202-555-0124",
        "billingCountry": "US", // "US" | "USA",
        "userReference": "9d7d0f9b7a"
      },
      "items": [
        {
          "type": "hotel",
          // ...
        },
        {
          "type": "flight",
          // ...
        }
      ]
    }
  }
}

Name	Type	Mandatory	Description
`itinerary`	String	Required	In case an error occurs RoomerFlex could identify the package reservation on the partners system. It has a 50 char length limit.
`agentEmail`	String	Optional	Only for B2B integrations when the sale is made by a travel agent
`comments`	String	Optional	Any comments (up to 255 chars)
`additionalInfo`	String	Optional	In JSON format
`prepaidBooking`	Boolean	Optional	Was a buyer charged 100% at time of booking?
`lhToken`	String	Required	The token from a API response of the "Step 1"
`payment`	Object	Optional	Is applicable to split payment type of integration and should contain a token from Stripe
`buyer`	Object	Required	Contains an information regarding a buyer of this package in form of JSON object with sub keys
`firstName`	String	Optional	Buyer’s first name (a sub key of the `buyer` object)
`lastName`	String	Optional	Buyer’s last name (a sub key of the `buyer` object)
`email`	String	Optional	Buyer’s email address (a sub key of the `buyer` object)
`phone`	String	Optional	Buyer’s phone number (a sub key of the `buyer` object)
`billingCountry`	String	Required	Country code in ISO 3166-1 alpha2 or ISO 3166-1 alpha3 formats from a buyer billing address (a sub key of the `buyer` object)
`userReference`	String	Optional	Unique identifier of a registered client (end user) on partner's side
`items`	List of objects	Required	A list of items the package includes (e.g. a hotel, a flight etc.)

A hotel item of the package

{
  "type": "hotel",
  "itinerary" : "24AD121",
  "userEmail" : "jane.doe@example.com",
  "userFirstName" : "Jane",
  "userLastName" : "Doe",
  "userPhone" : "+1-202-555-0124",
  "agentEmail" : "",
  "comments" : "",
  "additionalInfo" : "",
  "supplierName": "SecretEscapes or third party",
  "supplierConfirmationNumber": "198979",
  "property": {
    "contactEmail": "someone@hotelname.com",
    "directContract": true,
    "userCreditCard": {
      "last4Digits": "1881",
      "bin": "546747"
    }
  }
}

Accepted parameters of a hotel item in the package

Name	Type	Mandatory	Description
`type`	String	Required	Specifies that current item is a hotel
`itinerary`	String	Optional	Applies only to dynamically formed packages by the partner itself and not from the 3rd party supplier
`userEmail`	String	Required	Email of a guest who is going to check in
`userFirstName`	String	Required	First name of a guest who is going to check in
`userLastName`	String	Required	Last name of a guest who is going to check in
`userPhone`	String	Optional	Phone of a guest who is going to check in
`agentEmail`	String	Optional	Only for B2B integrations when the sale is made by a travel agent
`comments`	String	Optional	Any comments (up to 255 chars)
`additionalInfo`	Float	Optional	In JSON format
`supplierName`	String	Required	The supplier name of the original reservation (booking source)
`supplierConfirmationNumber`	String	Required	The supplier’s confirmation number of the reservation (PNR)
`property`	Object	Optional
`contactEmail`	String	Optional	A contact person email at the hotel (applicable for direct contracts)
`directContract`	Boolean	Optional	Was the inventory directly contracted with a hotel, or through a 3rd party supplier
`userCreditCard`	Object	Optional
`last4Digits`	String	Optional	Last 4 digits of the card holder for the reservation (applicable for direct contracts)
`bin`	String	Optional	A bank identification number. The initial 4 to 6 numbers that appear on a credit card (applicable for direct contracts)

A flight item

{
  "type": "flight",
  "itinerary": "32106589",
  "supplierName": "SecretEscapes or third party",
  "supplierConfirmationNumber": "2014730",
  "passengers": [
    {
      "title": "Miss or Ms or Mr or Sir or Mrs or Dr",
      "firstName": "Jane",
      "lastName": "Doe",
      "passengerType": "Adult or Child or Infant",
      "tickets": [
        {
          "number": "8382177546344 / 3",
          "seat": "11A",
          "operating": {
            "carrier": "EZY",
            "flightNumber": "281"
          }
        },
        {
          "number": "A3217754S344 / 0",
          "seat": "05F",
          "operating": {
            "carrier": "DL",
            "flightNumber": "315"
          }
        },
        {
          "number": "32ED17754S3124",
          "seat": "12E",
          "operating": {
            "carrier": "UA",
            "flightNumber": "298"
          }
        }
      ],
      "specialRequest": ""
    },
    {
      "title": "Miss or Ms or Mr or Sir or Mrs or Dr",
      "firstName": "John",
      "lastName": "Doe",
      "passengerType": "Adult or Child or Infant",
      "tickets": [
        {
          "number": "8382177546344 / 3",
          "seat": "12A",
          "operating": {
            "carrier": "EZY",
            "flightNumber": "281"
          }
        },
        {
          "number": "A3217754S344 / 0",
          "seat": "06F",
          "operating": {
            "carrier": "DL",
            "flightNumber": "315"
          }
        },
        {
          "number": "32ED17754S3124",
          "seat": "13E",
          "operating": {
            "carrier": "UA",
            "flightNumber": "298"
          }
        }
      ],
      "specialRequest": ""
    }
  ]
}

Accepted parameters of a flight item

Name	Type	Mandatory	Description
`type`	String	Required	Specifies that current item is a flight
`itinerary`	String	Optional	Applies only to dynamically formed packages by the partner itself and not from the 3rd party supplier
`supplierName`	String	Required	The supplier name of the original reservation (booking source)
`supplierConfirmationNumber`	String	Required	The supplier’s confirmation number of the reservation (PNR)
`passengers`	List of objects	Required	Contains an information regarding passengers personal details and their tickets
`title`	String	Optional	Miss or Ms or Mr or Sir or Mrs or Dr (part of an object in the `passengers` array)
`firstName`	String	Required
`lastName`	String	Required
`passengerType`	String	Required	Adult or Child or Infant (part of an object in the `passengers` array)
`tickets`	List of object	Required	Contains an information regarding passengers flight tickets (two ways and / or with connections)
`number`	String	Required	The flight ticket number (part of an object in `tickets` array)
`seat`	String		A plane seat if specified in the ticket (part of an object in `tickets` array)
`operating`	Object	Required	The flight company details in format of the JSON object
`carrier`	String	Required	An abbreviation of the flight company
`flightNumber`	String	Required
`carrier`	String	Required	An abbreviation of the flight company
`specialRequest`	String	Optional	ny requests to the flight company (e.g. a special food).

Response

{
  "success": true,
  "registered" : true,
  "lh-token" : "801f21d6-4d1d-49e1-9dc2-7d665ff78dad"
}

Optional - Convert guest payment details into a Stripe token for a split payment

https://api.stripe.com/v1/tokens

A response from Stripe will look like this one:

Stripe response screenshot

pk_test_IwgXZOyVP6cHq4uBr03vemro - is Roomer Travel authentication key for Stripe test environment.

Step 3 - Activate the roomer protection (packages)

The protection token generated and sent back in the API response at the first step should be used in order to activate the protection and to start the refund flow.

An example of the request:

curl --request POST \
     --url 'https://api.roomerflex.com/api/protection/activate_protection?token=801f21d6-4d1d-49e1-9dc2-7d665ff78dad' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'Authorization: Token token="PARTNER TOKEN"' \
     --header 'partner: PARTNER EMAIL' \
     --header 'API-Version: V3'

HTTP request description


URL	/api/protection/activate_protection.
PROTOCOL	HTTP
METHOD	POST

Accepted parameters

For packages:


URL QUERY PARAMETER	token

Response

{
  "success" : true,
  "activated" : true,
  "lh-token" : "801f21d6-4d1d-49e1-9dc2-7d665ff78dad"
}

Remove protection (packages)

This API endpoint allows to cancel (to rollback) a protection after it has registered.

An example of the request (vacation package):

curl --header 'Accept: application/json' \
 --header 'Content-Type: application/json' \
 --header 'Authorization: Token token=PARTNER_TOKEN' \
 --header 'Partner: PARTNER_EMAIL' \
 --header 'API-Version: V3' \
 --request POST \
 --data '{
    "package": {
        "lhToken": ""
    }
 }' \
 https://api.roomerflex.com/api/protection/remove_protection

HTTP request description


URL	/api/protection/remove_protection
PROTOCOL	HTTP
METHOD	POST

Accepted parameters

Name	Type	Mandatory	Description
`package`	Object	Required
`package.lhToken`	String	Required

Response

{
  "success": true
}

BI Collection

For Roomer Travel to identify conversion stats, please add the following to the review page ("Checkout page") and the confirmation page ("Thank you page").

Diagram

Checkout page ("Review")

<img src=”//tracker.roomerflex.com/tracker/pixel/request.jpg?partner={partner_id}&token={replace with token}” height=”1px” width=”1px”>

Confirmation page pixel ("Thank you")

<img src=”//tracker.roomerflex.com/tracker/pixel/register.jpg?partner={partner_id}” height=”1px” width=”1px”>

Errors

Partner and token parameters are mandatory otherwise the server will respond with a status code 400 Bad Request.

Partners Dashboard

Sandbox

https://dashboard-sandbox.roomerflex.com/

Production

https://dashboard.roomerflex.com/

Overview

Abstract

REST API

Common

Authentication

Errors Handling

Sequence Diagrams

flex as an add-on

flex as a rate type

Endpoints Overview

Hotels

Step 1 - Request token and price for RoomerFlex protection (hotels)

Accepted parameters of a hotel

Restricted Response

Step 2 - Register the roomer protection (hotels)

Accepted parameters of a hotel

Optional - Convert guest payment details into a Stripe token for a split payment

Step 3 - Activate the roomer protection (hotels)

Accepted parameters

Protection status

Accepted parameters

Finance status

Accepted parameters

Remove protection (hotels)

Accepted parameters

Offers for multiple room types

Accepted parameters

Offers for multiple hotels

Accepted parameters

Flights

Step 1 - Request token and price for RoomerFlex protection (flights)

Accepted parameters of flight(s)

Accepted parameters of a flight item

Restricted Response

Step 2 - Register the roomer protection (flights)

Accepted parameters of flight(s)

Accepted parameters of a flight item

Optional - Convert guest payment details into a Stripe token for a split payment

Step 3 - Activate the roomer protection (flights)

Accepted parameters

Remove protection (flights)

Accepted parameters

Vacation Packages

Step 1 - Request token and price for RoomerFlex protection (packages)

Accepted parameters of a package

Accepted parameters of a hotel item in the package

Accepted parameters of a flight item

Restricted Response

Step 2 - Register the roomer protection (packages)

Accepted parameters of a package

Accepted parameters of a hotel item in the package

Accepted parameters of a flight item

Optional - Convert guest payment details into a Stripe token for a split payment

Step 3 - Activate the roomer protection (packages)

Accepted parameters

Remove protection (packages)

Accepted parameters

BI Collection

Checkout page ("Review")

Confirmation page pixel ("Thank you")

Errors

Partners Dashboard

API Explorer