Business Travel Suite Knowledge Base

As part of our design update, the screenshots are currently being revised.

TABLE OF CONTENTS

Availability API
Livecheck API
Book
Cancel
Query Reservation List
Query Reservation Detail

Availability API

Availability API is used by distributors to check real-time availability to get all available rooms and rates for a single hotel. A call will be sent to the hotel supplier’s system to get real-time results.

POST /availability/{supplierId} HTTP/1.1
URL: {endpoint}/availability/{supplierId}
Authorization:Bearer {apiKey}
Accept-Encoding: gzip Content-Encoding: gzip Content-Type: application/json;charset=utf-8

Request Example

{
  "header": {
    "supplierId": "HILTON",
    "distributorId": "GTA",
    "version": "v4",
    "token": "18393849028490234"
  },
  "corpCode": "string",
  "hotelId": "GATHI",
  "stayRange": {
    "checkin": "2018-01-01",
    "checkout": "2018-01-04"
  },
  "roomCriteria": {
    "roomCount": 2,
    "adultCount": 1,
    "childCount": 2,
    "childAges": [
      4,
      8
    ]
  },
  "iata": "string",
  "loyaltyAccount": {
    "programCode": "BW",
    "accountId": "1234567890123457"
  },
  "corpAccount": {
    "corpProgramCode": "CR",
    "corpId": "A-1232"
  },
  "isAfterPromotion": false,
  "promoteCode": "string",
  "bookingChannel": "string",
  "extensions": {
    "key1": "value1",
    "key2": "value2"
  }
}

Request Specification

Attribute	Type	Required	Description	Example
header	object	Yes	/	/
@supplierId	string	Yes	MaxLength: 32 The ID of the hotel supplier in DerbySoft's system	HILTON
@distributorId	string	Yes	MaxLength: 32 The ID of the distributor in DerbySoft's system	MOCK_DISTRIBUTOR
@version	string	Yes	MaxLength: 20 Version of API	v1.0.0
@token	string	Yes	MaxLength: 64 A unique ID to identify request and response, normally it should be UUID.	18393849028490234
hotelId	string	Yes	Hotel ID in supplier's system	GATHI
stayRange	object	Yes	/	/
@checkin	string	Yes	Check-in, format with yyyy-MM-dd	2024-01-01
@checkout	string	Yes	Check out, format with yyyy-MM-dd	2024-01-04
roomCriteria	object	Yes	/	/
@roomCount	integer	Yes	Total room count per request	2
@adultCount	integer	Yes	Adult count per room	1
@childCount	integer	No	Child count per room	2
@childAges	array	No	Child ages for each child, array size MUST be the same as a child count.	[ 4, 8 ]
corpCode	string	No	Corp ID in distributor’s system	DIS
iata	string	No	IATA of distributor	/
loyaltyAccount	object	No	/	/
@programCode	string	Yes	Loyalty program code of the supplier	BW
@accountId	string	Yes	Loyalty program account ED	1234567890123457
corpAccount	object	No	/	/
@corpProgramCode	string	Yes	Corporate Hotel Program of hotel supplier	CR
@corpId	string	Yes	Corporate ID in the program account	A-1232
isAfterPromotion	boolean	No	The flag indicates calculating the available room rates with the promotion rules or not. TRUE means checking the availability under the promotion rules provided by the supplier. FALSE means you do not need to check the availability under any promotions, basic live-check only.	false
promoteCode	string	No	Promote code defined by the hotel, is an optional field when you want to request the promotion rates (isAfterPromotion=true). If promote code is empty and there are multiple promotions available for one product at the same time, the promotion rule will be chosen according to multiPromotionsStategy.	/
bookingChannel	string	No	Sub-distributor ID	/
extensions	object	No	Optional: Additional agreed-upon attributes between suppliers and distributors (DerbySoft will provide the specified format). Please don't transmit sensitive information through this field. For more information refer to: Sensitive Information	/

Response Example

Success Response (HTTP Status 200) - OK

{
  "header": {
    "supplierId": "HILTON",
    "distributorId": "GTA",
    "version": "v4",
    "token": "18393849028490234"
  },
  "hotelId": "GATHI",
  "stayRange": {
    "checkin": "2018-01-01",
    "checkout": "2018-01-04"
  },
  "roomCriteria": {
    "roomCount": 2,
    "adultCount": 1,
    "childCount": 2,
    "childAges": [
      4,
      8
    ]
  },
  "iata": "string",
  "roomRates": [
    {
      "inventory": 2,
      "isAfterPromotion": true,
      "promoteCode": "discount001",
      "roomId": "K1D",
      "rateId": "ODAD01",
      "currency": "USD",
      "amountBeforeTax": [
        100,
        100,
        120
      ],
      "amountAfterTax": [
        110,
        110,
        130
      ],
      "mealPlan": "RO",
      "paymentType": "PayNow",
      "guarantee": {
        "guaranteeType": "CCG"
      },
      "fees": [
        {
          "dateRange": {
            "startDate": "2024-01-01",
            "endDate": "2024-01-04"
          },
          "fee": {
            "name": "Service Charge",
            "type": "Exclusive",
            "amount": 10,
            "amountType": "Percent",
            "chargeType": "PerRoomPerNight",
            "paymentType": "PayNow",
            "effectivePerson": 0
          }
        }
      ],
      "cancelPolicy": {
        "code": "AD100P_100P",
        "description": "Non Refundable",
        "cancelPenalties": [
          {
            "noShow": true,
            "cancellable": true,
            "cancelDeadline": {
              "offsetTimeDropType": "BeforeArrival",
              "offsetTimeUnit": "D",
              "offsetTimeValue": 999,
              "deadline": "string"
            },
            "penaltyCharge": {
              "chargeBase": "FullStay",
              "nights": 0,
              "amount": 0,
              "percent": 0
            }
          }
        ]
      }
    }
  ],
  "extensions": {
    "key1": "value1",
    "key2": "value2"
  }
}

Error Response(HTTP Status 401) - Unauthorized token

{
  "errorCode": "string",
  "supplierErrorCode": "string",
  "errorMessage": "string"
}

Error Response(HTTP Status 500) - Internal system error

{
  "errorCode": "string",
  "supplierErrorCode": "string",
  "errorMessage": "string"
}

Response Specification

Attribute	Type	Required	Description	Example
header	object	Yes	/	/
@supplierId	string	Yes	MaxLength: 32 The ID of the hotel supplier in DerbySoft's system	HILTON
@distributorId	string	Yes	MaxLength: 32 The ID of the distributor in DerbySoft's system	MOCK_DISTRIBUTOR
@version	string	Yes	MaxLength: 20 Version of API	v1.0.0
@token	string	Yes	MaxLength: 64 A unique ID to identify request and response, normally it should be UUID.	18393849028490234
hotelId	string	Yes	Hotel ID in supplier's system	GATHI
stayRange	object	Yes	/	/
@checkin	string	Yes	Check-in, format with yyyy-MM-dd	2024-01-01
@checkout	string	Yes	Check out, format with yyyy-MM-dd	2024-01-04
roomCriteria	object	Yes	/	/
@roomCount	integer	Yes	Total room count per request	2
@adultCount	integer	Yes	Adult count per room	1
@childCount	integer	No	Child count per room	2
@childAges	array	No	Child ages for each child, array size MUST be the same as the child count/	[ 4, 8 ]
iata	string	No	IATA of distributor	/
roomRates		Yes	Meal plan, fee, and cancel policy are optional fields as some distributors do not support these in the API.	/
@inventory	integer	Yes	Available inventory count according to request criteria	1
@isAfterPromotion	boolean	No	The flag indicates calculating the available room rates with the promotion rules or not. Default is false if null TRUE means to check the availability that is under the promotion rules provided by the supplier. FALSE means you do not need to check the availability under any promotions, basic live-check only.	false
@promoteCode	string	No	the code for the promotion applied to this rate, It's required when isAfterPromotion = true.	discount001
@roomId	string	Yes	Room ID in supplier system	10000101
@rateId	string	Yes	Rate ID in supplier system	123456
@currency	string	Yes	Currency code [ISO-4217]	USD
@amountBeforeTax	array[number]	No	The daily amount of rate without tax & fee	[ 100, 100, 120 ]
@amountAfterTax	array[number]	No	The daily amount of rate with tax & fee	[ 110, 110, 130 ]
@mealPlan	string	No	meal plan code list.	RO
@paymentType	enum	No	Indicates the product is prepaid to the hotel (PayNow) or pay at the hotel (PayLater) Enum: [ PayLater, PayNow ]	PayNow
roomRates / guarantee	object	No	Guarantee information for this room rate.	/
@guaranteeType	string	Yes	guarantee type list.	CCG
roomRates.fees	array[object]	No	Fee or tax by date range.	/
fees.dateRange	object	Yes	/	/
@startDate	string	Yes	Start date of date range, format with yyyy-MM-dd	2024-01-01
@endDate	string	Yes	End date of date range, format with yyyy-MM-dd	2024-01-04
fees.fee		Yes	/	/
@name	string	Yes	Pattern: \w[\w\d]+	Service Charge
@type	enum	Yes	The fee or tax is included in the amount before tax or not. Enum: [ Inclusive, Exclusive ]	Exclusive
@amount	number	Yes	Amount value of fee or tax	10
@amountType	string	Yes	Indicates how to charge the tax, 10% per room per night in this example Enum: [ Fix, Percent ]	Percent
@chargeType	string	Yes	Enum: [ PerRoomPerNight, PerPersonPerNight, PerRoomPerStay, PerPersonPerStay ]	PerRoomPerNight
@paymentType	enum	No	Indicates the fee is prepaid to the hotel (PayNow) or pay at the hotel (PayLater) Enum: [ PayLater, PayNow ]	PayNow
@effectivePerson	number	No	This means the fee that will be charged based on how many persons, like extra person charge, usually applied from 3, so the 1 adult, 2 adults will be same, 3 adults will be charged an extra fee.	/
roomRates.cancelPolicy	object	No	Cancellation Policy"	/
@code	string	Yes	Max Length: 128 Code of cancel policy	AD100P_100P
@description	string	No	Max Length: 1024 cancel policy	Non Refundable
cancelPolicy. cancelPenalties		Yes	Detail about the cancel Penalty	/
@noShow	boolean	Yes	If true, it means the penaltyCharge applied for No-Show, and the cancellable, cancelDeadline will NOT exist.	/
@cancellable	boolean	No	Indicates cancel is allowed or not. If false, it cannot be canceled. If true, the cancelDeadline will exist.	/
cancelPenalties. cancelDeadline		No	/	/
@offsetTimeDropType	enum	No	Enum: [ BeforeArrival ] An enumerated type indicates when the deadline drop time goes into effect.	/
@offsetTimeUnit	enum	No	Enum: [ D, H ]	/
@offsetTimeValue	number	No	The number of offset times with the time unit.	/
@deadline	string	No	local deadline time allowed for cancellation, like 4 PM, or 6 PM.	/
cancelPenalties. penaltyCharge	/	/	/	/
@chargeBase	enum	No	Enum: [ FullStay, NightBase ] if FullStay, it will be a percentage or amount, if NightBase, the nights are required.	/
@nights	number	No	Exists if the penalty charge is based on the night, like the first night.	/
@amount	number	No	Exists if the penalty charge is a flat charge, like USD 30.00.	/
@percent	number	No	Exists if the penalty charge is percent, like 15.5 means 15.5%.	/
extensions	object	No	Optional: Additional agreed-upon attributes between suppliers and distributors (DerbySoft will provide the specified format). Please don't transmit sensitive information through this field. For more information refer to: Sensitive Information	/

Livecheck API

This api is used to check real-time availability before booking. It will be forward to the hotel supplier system to get real-time result.

OST /livecheck HTTP/1.1
URL: {endpoint}/livecheck/{supplierId}
Authorization:Bearer {apiKey}
Accept-Encoding: gzip 
Content-Encoding: gzip 
Content-Type: application/json;charset=utf-8

Request Example

{
  "header": {
    "supplierId": "HILTON",
    "distributorId": "GTA",
    "version": "v4",
    "token": "18393849028490234"
  },
  "corpCode": "string",
  "hotelId": "GATHI",
  "stayRange": {
    "checkin": "2018-01-01",
    "checkout": "2018-01-04"
  },
  "roomCriteria": {
    "roomCount": 2,
    "adultCount": 1,
    "childCount": 2,
    "childAges": [
      4,
      8
    ]
  },
  "productCandidate": {
    "roomId": "K1D",
    "rateId": "ODAD01"
  },
  "iata": "string",
  "loyaltyAccount": {
    "programCode": "BW",
    "accountId": "1234567890123457"
  },
  "corpAccount": {
    "corpProgramCode": "CR",
    "corpId": "A-1232"
  },
  "isAfterPromotion": false,
  "promoteCode": "string",
  "bookingChannel": "string",
  "extensions": {
    "key1": "value1",
    "key2": "value2"
  }
}

Request Specification

Attribute	Type	Required	Description	Example
header	object	Yes	/	/
@supplierId	string	Yes	MaxLength: 32 The ID of the hotel supplier in DerbySoft's system	HILTON
@distributorId	string	Yes	MaxLength: 32 The ID of the distributor in DerbySoft's system	MOCK_DISTRIBUTOR
@version	string	Yes	MaxLength: 20 Version of API	v1.0.0
@token	string	Yes	MaxLength: 64 A unique ID to identify request and response, normally it should be UUID.	18393849028490234
hotelId	string	Yes	Hotel ID in supplier's system	GATHI
stayRange	object	Yes	/	/
@checkin	string	Yes	Check-in, format with yyyy-MM-dd	2024-01-01
@checkout	string	Yes	Check out, format with yyyy-MM-dd	2024-01-04
roomCriteria	object	Yes	/	/
@roomCount	integer	Yes	Total room count per request	2
@adultCount	integer	Yes	Adult count per room	1
@childCount	integer	No	Child count per room	2
@childAges	array	No	Child ages for each child, array size MUST be the same as a child count.	[ 4, 8 ]
productCandidate	object	Yes	/	/
@roomId	string	Yes	Room ID in supplier's system	K1D
@rateId	string	Yes	Rate ID in supplier's system	ODAD01
corpCode	string	No	Corp ID in distributor’s system	DIS
iata	string	No	IATA of distributor	/
loyaltyAccount	object	No	/	/
@programCode	string	Yes	Loyalty program code of the supplier	BW
@accountId	string	Yes	Loyalty program account ED	1234567890123457
corpAccount	object	No	/	/
@corpProgramCode	string	Yes	Corporate Hotel Program of hotel supplier	CR
@corpId	string	Yes	Corporate ID in the program account	A-1232
isAfterPromotion	boolean	No	The flag indicates calculating the available room rates with the promotion rules or not. TRUE means checking the availability under the promotion rules provided by the supplier. FALSE means you do not need to check the availability under any promotions, basic live-check only.	false
promoteCode	string	No	Promote code defined by the hotel, is an optional field when you want to request the promotion rates (isAfterPromotion=true). If promote code is empty and there are multiple promotions available for one product at the same time, the promotion rule will be chosen according to multiPromotionsStategy.	/
bookingChannel	string	No	Sub-distributor ID	/
extensions	object	No	Optional: Additional agreed-upon attributes between suppliers and distributors (DerbySoft will provide the specified format). Please don't transmit sensitive information through this field. For more information refer to: Sensitive Information	/

Response Example

Success Response (HTTP Status 200) - OK

{
  "header": {
    "supplierId": "HILTON",
    "distributorId": "GTA",
    "version": "v4",
    "token": "18393849028490234"
  },
  "hotelId": "GATHI",
  "stayRange": {
    "checkin": "2018-01-01",
    "checkout": "2018-01-04"
  },
  "roomCriteria": {
    "roomCount": 2,
    "adultCount": 1,
    "childCount": 2,
    "childAges": [
      4,
      8
    ]
  },
  "productCandidate": {
    "roomId": "K1D",
    "rateId": "ODAD01"
  },
  "iata": "string",
  "roomRates": [
    {
      "inventory": 2,
      "isAfterPromotion": true,
      "promoteCode": "discount001",
      "roomId": "K1D",
      "rateId": "ODAD01",
      "currency": "USD",
      "amountBeforeTax": [
        100,
        100,
        120
      ],
      "amountAfterTax": [
        110,
        110,
        130
      ],
      "mealPlan": "RO",
      "paymentType": "PayNow",
      "guarantee": {
        "guaranteeType": "CCG"
      },
      "fees": [
        {
          "dateRange": {
            "startDate": "2024-01-01",
            "endDate": "2024-01-04"
          },
          "fee": {
            "name": "Service Charge",
            "type": "Exclusive",
            "amount": 10,
            "amountType": "Percent",
            "chargeType": "PerRoomPerNight",
            "paymentType": "PayNow",
            "effectivePerson": 0
          }
        }
      ],
      "cancelPolicy": {
        "code": "AD100P_100P",
        "description": "Non Refundable",
        "cancelPenalties": [
          {
            "noShow": true,
            "cancellable": true,
            "cancelDeadline": {
              "offsetTimeDropType": "BeforeArrival",
              "offsetTimeUnit": "D",
              "offsetTimeValue": 999,
              "deadline": "string"
            },
            "penaltyCharge": {
              "chargeBase": "FullStay",
              "nights": 0,
              "amount": 0,
              "percent": 0
            }
          }
        ]
      }
    }
  ],
  "extensions": {
    "key1": "value1",
    "key2": "value2"
  }
}

Error Response(HTTP Status 401) - Unauthorized token

{
  "errorCode": "string",
  "supplierErrorCode": "string",
  "errorMessage": "string"
}

Error Response (HTTP Status 500) - Internal system error

{
  "errorCode": "string",
  "supplierErrorCode": "string",
  "errorMessage": "string"
}

Response Specification

Attribute	Type	Required	Description	Example
header	object	Yes	/	/
@supplierId	string	Yes	MaxLength: 32 The ID of the hotel supplier in DerbySoft's system	HILTON
@distributorId	string	Yes	MaxLength: 32 The ID of the distributor in DerbySoft's system	MOCK_DISTRIBUTOR
@version	string	Yes	MaxLength: 20 Version of API	v1.0.0
@token	string	Yes	MaxLength: 64 A unique ID to identify request and response, normally it should be UUID.	18393849028490234
hotelId	string	Yes	Hotel ID in supplier's system	GATHI
stayRange	object	Yes	/	/
@checkin	string	Yes	Check-in, format with yyyy-MM-dd	2024-01-01
@checkout	string	Yes	Check out, format with yyyy-MM-dd	2024-01-04
roomCriteria	object	Yes	/	/
@roomCount	integer	Yes	Total room count per request	2
@adultCount	integer	Yes	Adult count per room	1
@childCount	integer	No	Child count per room	2
@childAges	array	No	Child ages for each child, array size MUST be the same as the child count/	[ 4, 8 ]
productCandidate	object	No	/	/
@roomId	string	No	Room ID in supplier system	K1D
@rateId	string	No	Rate ID in supplier system	ODAD01
iata	string	No	IATA of distributor	/
roomRates		Yes	Meal plan, fee, and cancel policy are optional fields as some distributors do not support these in the API.	/
@inventory	integer	Yes	Available inventory count according to request criteria	1
@isAfterPromotion	boolean	No	The flag indicates calculating the available room rates with the promotion rules or not. Default is false if null TRUE means to check the availability that is under the promotion rules provided by the supplier. FALSE means you do not need to check the availability under any promotions, basic live-check only.	false
@promoteCode	string	No	the code for the promotion applied to this rate, It's required when isAfterPromotion = true.	discount001
@roomId	string	Yes	Room ID in supplier system	10000101
@rateId	string	Yes	Rate ID in supplier system	123456
@currency	string	Yes	Currency code [ISO-4217]	USD
@amountBeforeTax	array[number]	No	The daily amount of rate without tax & fee	[ 100, 100, 120 ]
@amountAfterTax	array[number]	No	The daily amount of rate with tax & fee	[ 110, 110, 130 ]
@mealPlan	string	No	For meal plan code, refer to the standard meal plan code list.	RO
@paymentType	enum	No	Indicates the product is prepaid to the hotel (PayNow) or pay at the hotel (PayLater) Enum: [ PayLater, PayNow ]	PayNow
roomRates.guarantee	object	No	Guarantee information for this room rate.	/
@guaranteeType	string	Yes	The type of guarantee method, refer to the standard guarantee type list.	CCG
roomRates.fees	array[object]	No	Fee or tax by date range.	/
fees.dateRange	object	Yes	/	/
@startDate	string	Yes	Start date of date range, format with yyyy-MM-dd	2024-01-01
@endDate	string	Yes	End date of date range, format with yyyy-MM-dd	2024-01-04
fees.fee		Yes	/	/
@name	string	Yes	Pattern: \w[\w\d]+	Service Charge
@type	enum	Yes	The fee or tax is included in the amount before tax or not. Enum: [ Inclusive, Exclusive ]	Exclusive
@amount	number	Yes	Amount value of fee or tax	10
@amountType	string	Yes	Indicates how to charge the tax, 10% per room per night in this example Enum: [ Fix, Percent ]	Percent
@chargeType	string	Yes	Enum: [ PerRoomPerNight, PerPersonPerNight, PerRoomPerStay, PerPersonPerStay ]	PerRoomPerNight
@paymentType	enum	No	Indicates the fee is prepaid to the hotel (PayNow) or pay at the hotel (PayLater) Enum: [ PayLater, PayNow ]	PayNow
@effectivePerson	number	No	This means the fee that will be charged based on how many persons, like extra person charge, usually applied from 3, so the 1 adult, 2 adults will be same, 3 adults will be charged an extra fee.	/
roomRates.cancelPolicy	object	No	Cancellation policy defines what penalty will be charged when a guest cancels the booking at a certain advance time range. The penalty is related to No-show or a time range before No-show/	/
@code	string	Yes	Max Length: 128 Code of cancel policy	AD100P_100P
@description	string	No	Max Length: 1024 the description of the cancel policy	Non Refundable
cancelPolicy. cancelPenalties		Yes	Detail about the cancel Penalty	/
@noShow	boolean	Yes	If true, it means the penaltyCharge applied for No-Show, and the cancellable, cancelDeadline will NOT exist.	/
@cancellable	boolean	No	Indicates cancel is allowed or not. If false, it cannot be canceled. If true, the cancelDeadline will exist.	/
cancelPenalties / cancelDeadline		No	/	/
@offsetTimeDropType	enum	No	Enum: [ BeforeArrival ] An enumerated type indicates when the deadline drop time goes into effect.	/
@offsetTimeUnit	enum	No	Enum: [ D, H ]	/
@offsetTimeValue	number	No	The number of offset times with the time unit.	/
@deadline	string	No	local deadline time allowed for cancellation, like 4 PM, or 6 PM.	/
cancelPenalties. penaltyCharge	/	/	/	/
@chargeBase	enum	No	Enum: [ FullStay, NightBase ] if FullStay, it will be a percentage or amount, if NightBase, the nights are required.	/
@nights	number	No	Exists if the penalty charge is based on the night, like the first night.	/
@amount	number	No	Exists if the penalty charge is a flat charge, like USD 30.00.	/
@percent	number	No	Exists if the penalty charge is percent, like 15.5 means 15.5%.	/
extensions	object	No	Optional: Additional agreed-upon attributes between suppliers and distributors (DerbySoft will provide the specified format). Please don't transmit sensitive information through this field. For more information refer to: Sensitive Information	/

Book

This API is used by distributors to book rooms. A call will be sent to the hotel supplier system to get a real-time confirmation.

POST /reservation/book HTTP/1.1
URL: {{endpoint}}/reservation/book/{supplierId}
Authorization:Bearer {apiKey}
Accept-Encoding: gzip
Content-Encoding: gzip
Content-Type: application/json;charset=utf-8

Request Example

{
  "header": {
    "supplierId": "HILTON",
    "distributorId": "GTA",
    "version": "v4",
    "token": "18393849028490234"
  },
  "reservationIds": {
    "distributorResId": "C2084DFL0"
  },
  "iata": "string",
  "hotelId": "GATHI",
  "stayRange": {
    "checkin": "2018-01-01",
    "checkout": "2018-01-04"
  },
  "contactPerson": {
    "firstName": "James",
    "lastName": "Bond",
    "email": "[email protected]",
    "phone": "string",
    "address": "string",
    "age": 0,
    "gender": "Male",
    "birthday": "2018-01-01",
    "type": "Adult",
    "index": 1
  },
  "roomCriteria": {
    "roomCount": 2,
    "adultCount": 1,
    "childCount": 2,
    "childAges": [
      4,
      8
    ]
  },
  "total": {
    "amountBeforeTax": 640,
    "amountAfterTax": 700
  },
  "payment": {
    "cardCode": "VI",
    "cardNumber": "4111111111111111",
    "cardHolderName": "Sherlock Holmes",
    "expireDate": "119"
  },
  "loyaltyAccount": {
    "programCode": "BW",
    "accountId": "1234567890123457"
  },
  "corpAccount": {
    "corpProgramCode": "CR",
    "corpId": "A-1232"
  },
  "promoteCode": "string",
  "guests": [
    {
      "firstName": "James",
      "lastName": "Bond",
      "email": "[email protected]",
      "phone": "string",
      "address": "string",
      "age": 0,
      "gender": "Male",
      "birthday": "2018-01-01",
      "type": "Adult",
      "index": 1
    }
  ],
  "comments": [
    "no smoking",
    "high floor"
  ],
  "roomRates": [
    {
      "roomId": "K1D",
      "rateId": "ODAD01",
      "currency": "USD",
      "amountBeforeTax": [
        100,
        100,
        120
      ],
      "amountAfterTax": [
        110,
        110,
        130
      ],
      "mealPlan": "RO",
      "paymentType": "PayNow",
      "guarantee": {
        "guaranteeType": "CCG"
      },
      "fees": [
        {
          "dateRange": {
            "startDate": "2024-01-01",
            "endDate": "2024-01-04"
          },
          "fee": {
            "name": "Service Charge",
            "type": "Exclusive",
            "amount": 10,
            "amountType": "Percent",
            "chargeType": "PerRoomPerNight",
            "paymentType": "PayNow",
            "effectivePerson": 0
          }
        }
      ],
      "cancelPolicy": {
        "code": "AD100P_100P",
        "description": "Non Refundable",
        "cancelPenalties": [
          {
            "noShow": true,
            "cancellable": true,
            "cancelDeadline": {
              "offsetTimeDropType": "BeforeArrival",
              "offsetTimeUnit": "D",
              "offsetTimeValue": 999,
              "deadline": "string"
            },
            "penaltyCharge": {
              "chargeBase": "FullStay",
              "nights": 0,
              "amount": 0,
              "percent": 0
            }
          }
        ]
      }
    }
  ],
  "bookingChannel": "string",
  "productAddons": [
    {
      "type": "DisneyTicket",
      "code": "code",
      "date": "2018-01-01",
      "quantity": 1,
      "officeId": "string",
      "rate": {
        "ageQualifyingType": {
          "type": "Adult",
          "minAge": 18,
          "maxAge": 18
        },
        "currency": "USD",
        "amountBeforeTax": 123.23,
        "amountAfterTax": 134.34
      }
    }
  ],
  "corpCode": "string",
  "threeDomainSecurity": {
    "cavv": "string",
    "eci": "string",
    "xid": "string",
    "threeDomainSecurityVersion": "string",
    "transactionId": "string",
    "merchantName": "string",
    "extensions": {
      "key1": "value1",
      "key2": "value2"
    }
  },
  "bookingToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
  "extensions": {
    "key1": "value1",
    "key2": "value2"
  }
}

Request Specification

Attribute	Type	Required	Description	Example
header	object	Yes	/	/
@supplierId	string	Yes	Max Length: 32 The ID of the hotel supplier in DerbySoft's system	HILTON
@distributorId	string	Yes	Max Length: 32 The ID of distributor in DerbySoft's system	MOCK_DISTRIBUTOR
@version	string	Yes	Max Length: 20 Version of API	v4
@token	string	Yes	Max Length: 64 A unique ID to identify requests and responses, normally it should be UUID.	18393849028490234
reservationIds		Yes	/	/
@distributorResId	string	Yes	Reservation ID in distributor's system	C2084DFL0
corpCode	string	No	Corp ID in distributor’s system	DIS
iata	string	No	IATA	/
hotelId	string	Yes	Hotel ID in supplier's system	100001
stayRange	object	Yes	/	/
@checkin	string	Yes	Check-in, format with yyyy-MM-dd	2024-01-01
@checkout	string	Yes	Check out, format with yyyy-MM-dd	2024-01-04
contactPerson	object	Yes	/	/
@firstName	string	Yes	First Name	James
@lastName	string	Yes	Last Name	Bond
@email	string	No	Email	[email protected]
@phone	string	No	/	/
@address	string	No	/	/
roomCriteria	object	Yes	/	/
@roomCount	integer	Yes	Total room count per request	/
@adultCount	integer	Yes	Adult count per room	/
@childCount	integer	No	Child count per room	/
@childAges	array	No	For child ages for each child, the array size MUST be the same as the child count.	/
total	object	Yes	/	/
@amountBeforeTax	number	No	abbr. ABT It's required if AAT is not provided	640
@amountAfterTax	number	No	abbr. AAT It's required if ABT is not provided	700
payment	/	No	/	/
@cardCode	string	Yes	VI, MC, AX, etc. Card Code	VI
@cardNumber	string	Yes	Credit card number	4111111111111111
@cardHolderName	string	Yes	Cardholder name	Sherlock Holmes
@expireDate	string	Yes	It should be 2 digits for the month, 2 digits for the year, as "MMYY"	0119
@securityCode	string	No	Card verification value	123
loyaltyAccount	object	No	/	/
@programCode	string	Yes	Loyalty program code of the supplier	BW
@accountId	string	Yes	Loyalty program account ID	1234567890123457
corpAccount	object	No	/	/
@corpProgramCode	string	Yes	Corporate Hotel Program of hotel supplier	CR
@corpId	string	Yes	Corporate ID in the program account	A-1232
promoteCode	string	No	Promotion code defined by the hotel, the promotion code is required if making a reservation under the promotion	/
guests	array[object]	Yes	/
@firstName	string	Yes	First Name	James/
@lastName	string	Yes	Last Name	Bond
@email	string	No	Email	[email protected]
@phone	string	No	/	/
@address	string	No	/	/
@age	integer	No	Age of guest	/
@gender	enum	No	Gender of guest Enum: [Male, Female]	Male
@birthday	string	No	Birthday of guest format with yyyy-MM-dd	1970-12-20
@type	string	No	Type of guest, Adult, Child, or Infant Enum: [ Adult, Child, Infant ]	/
@index	integer	No	Indicate which guests will be allocated to which room. For one room reservation, the room index is 1 for all guests. For multi-room reservations, the index starts from 1 and the max room index is equal to the number of booked rooms.	index = 1, Indicate the guest will allocate to the first room. index = 2, Indicate the guest will allocate to the second room.
comments	array[string]	No	/	[ "no smoking", "high floor" ]
roomRates	array[object]	Yes	Min Items: 1 Max Items: 1 Meal plan, fee, and cancel policy are optional fields as some distributors do not support these in the API	/
@roomId	string	Yes	Room ID in supplier's system	10000101
@rateId	string	Yes	Rate ID in supplier's system	123456
@currency	string	Yes	Currency code [ISO-4217]	USD
@amountBeforeTax	array[number]	No	abbr. ABT The daily amount of rate without tax and fee. It's required if AAT is not provided	[ 100, 100, 120 ]
@amountAfterTax	array[number]	No	abbr. AAT The daily amount of rate with tax and fee. It's required if ABT is not provided	[ 110, 110, 130 ]
@mealPlan	string	No	Meal plan code, refer to the standard meal plan code list.	RO
@paymentType	enum	No	Indicates the product is prepaid to hotel (PayNow) or pay at hotel (PayLater). Enum: [ PayLater, PayNow ]	PayNow
roomRates/guarantee	object	No	Guarantee information for this room rate.	/
@guaranteeType	string	Yes	The type of guarantee method, refer to the standard guarantee type list.	CCG
roomRates.fees	array[object]	No	Fee or tax by date range.	/
fees.dateRange	object	Yes	/	/
@startDate	string	Yes	Start date of date range, format with yyyy-MM-dd	2024-01-01
@endDate	string	Yes	End date of date range, format with yyyy-MM-dd	2024-01-04
fees.fee		Yes	/	/
@name	string	Yes	Pattern: \w[\w\d]+	Service Charge
@type	enum	Yes	The fee or tax is included in the amount before tax or not Enum: [ Inclusive, Exclusive ]	Exclusive
@amount	number	Yes	Amount value of fee or tax	10
@amountType	string	Yes	Indicates how to charge the tax, 10% per room per night in this example Enum: [ Fix, Percent ]	Percent
@chargeType	string	Yes	Enum: [ PerRoomPerNight, PerPersonPerNight, PerRoomPerStay, PerPersonPerStay ]	PerRoomPerNight
@paymentType	enum	No	Indicates the fee is prepaid to the hotel (PayNow) or pay at the hotel (PayLater). Enum: [ PayLater, PayNow ]	PayNow
@effectivePerson	number	No	This means this fee will be charged based on how many persons, like an extra person charge, usually applied from 3, so the 1 adult, 2 adults will be same, 3 adults will be charged an extra fee.	/
roomRates.cancelPolicy	object	No	Cancellation policy defines what penalty will be a charge when a guest cancels the booking at a certain advance time range. The penalty is related to No-show or a time range before No-show. '.	/
@code	string	Yes	Max Length: 128 code of cancel policy	AD100P_100P
@description	string	No	Max Length: 1024 the description of the cancellation policy	Non Refundable
cancelPolicy / cancelPenalties		Yes	Detail about the cancel Penalty	/
@noShow	boolean	Yes	If true, it means the penaltyCharge applied for No-Show, and the cancellable, cancelDeadline will NOT exist	/
@cancellable	boolean	No	Indicates cancel is allowed or not. If false, it cannot be canceled. If true, the cancelDeadline will exist.	/
cancelPenalties. cancelDeadline	/	/	/	/
@offsetTimeDropType	enum	No	Enum: [ BeforeArrival ] An enumerated type indicates when the deadline drop time goes into effect.	/
@offsetTimeUnit	enum	No	Enum: [ D, H ]	/
@offsetTimeValue	number	No	The number of offset times with the time unit	/
@deadline	string	No	Local deadline times allowed for cancellation, like 4 PM, or 6 PM	/
cancelPenalties.penaltyCharge	/	/	/	/
@chargeBase	enum	No	Enum: [ FullStay, NightBase ] If FullStay, it will be a percentage or amount, if NightBase, the nights are required.	/
@nights	number	No	It exists if the penalty charge is based on the night, like the first night.	/
@amount	number	No	It exists if the penalty charge is a flat charge, like USD 30.00.	/
@percent	number	No	It exists if the penalty charge is percent, like 15.5 means 15.5%.	/
bookingChannel	string	No	Sub-distributor ID	/
productAddons	array[object]	No	/	/
@type	string	Yes	product addon type	/
@code	string	Yes	product addon code	/
@date	string	Yes	format with yyyy-MM-dd	2022-01-01
@quantity	integer	Yes	/	1
@officeId	string	No	/	/
productAddons.rate	object	No	/	/
rate.ageQualifyingType	object	No	/	/
@type	enum	Yes	Enum: [Adult, Child]	Adult
@minAge	string	Yes	/	18
@maxAge	integer	Yes	/	18
rate.currency	string	Yes	/	USD
rate.amountBeforeTax	number	No	/	123.23
rate.amountAfterTax	number	No	/	134.34
threeDomainSecurity	object	No	/	/
@cavv	string	No	Cardholder Authentication Verification Value Information is retrieved from the 3DS provider when authentication is successful.	/
@eci	string	No	The electronic commerce indicator.	/
@xid	string	No	Transaction identifier for a 3DS Version 1 provider, assigned by the Directory Server to identify a single transaction.	/
@threeDomainSecurityVersion	string	No	Include this only for 3D Secure 2.	/
@transactionId	string	No	Transaction identifier for a 3DS Version 2 provider, assigned by the Directory Server to identify a single transaction.	/
@merchantName	string	No	Identifier of the merchant completing the 3DS transaction.	/
@channelCode	enum	No	Specify the collection channel of payment cards Enum: [TO, EC, MO, FA] Refer to: PSD2-Channel Code	EC
@exemptionType	enum	No	Determines which exemption was used by the Payment Service Provider (PSP) Enum: [SC, DA, TA, TB, LV] Refer to: PSD2-Exemption Type	SC
bookingToken	string	Yes	Booking token used for booking	eyJhbGciOiJIUzI1NiIsInR5cCI6Ik pXVCJ9.eyJzdWIiOiIxMjM0NTY3 ODkwIiwibmFtZSI6IkpvaG4gRG9lIi wiaWF0IjoxNTE2MjM5MDIyfQ .SflKxwRJSMeKKF2QT4fwpMeJf36PO k6yJV_adQssw5c
extensions	object	No	Optional: Additional agreed-upon attributes between suppliers and distributors (DerbySoft will provide the specified format). Please don't transmit sensitive information through this field. For more information refer to: Sensitive Information	/

Response Example

Success Response (HTTP Status 200) - OK

{
  "header": {
    "supplierId": "HILTON",
    "distributorId": "GTA",
    "version": "v4",
    "token": "18393849028490234"
  },
  "reservationIds": {
    "distributorResId": "C2084DFL0",
    "derbyResId": "D15F893D34DF",
    "supplierResId": "89389494"
  },
  "extensions": {
    "key1": "value1",
    "key2": "value2"
  }
}

Error Response (HTTP Status 401) - Unauthorized token

{
  "errorCode": "string",
  "supplierErrorCode": "string",
  "errorMessage": "string"
}

Error Response (HTTP Status 500) - Internal system error

{
  "errorCode": "string",
  "supplierErrorCode": "string",
  "errorMessage": "string"
}

Response Specification

Attribute	Type	Required	Description	Example
header	object	Yes	/	/
@supplierId	string	Yes	Max Length: 32 The ID of the hotel supplier in DerbySoft's system	HILTON
@distributorId	string	Yes	Max Length: 32 The ID of the distributor in DerbySoft's system	MOCK_DISTRIBUTOR
@version	string	Yes	Max Length: 20 Version of API	v1.0.0
@token	string	Yes	Max Length: 64 A unique ID to identify requests and responses, normally it should be UUID.	18393849028490234
reservationIds		Yes	/	/
@distributorResId	string	Yes	Reservation ID in distributor's system	C2084DFL0
@derbyResId	string	No	Reservation ID in DerbySoft system, this is a unique ID as DerbySoft would be splitting the reservation.	D15F893D34DF
@supplierResId	string	No	Reservation ID in supplier's system	89389494
extensions	object	No	Optional: Additional agreed-upon attributes between suppliers and distributors (DerbySoft will provide the specified format). Please don't transmit sensitive information through this field. For more information refer to: Sensitive Information

Cancel

This is an API for DerbySoft to call suppliers' systems to cancel a booking. Since DerbySoft does splitting on original reservations, the supplier should cancel the reservation by unique derbyResId or supplierResId.

POST /reservation/cancel HTTP/1.1
URL: {endpoint}/reservation/cancel/{supplierId}
Authorization: Bearer {apiKey}
Accept-Encoding: gzip
Content-Encoding: gzip
Content-Type: application/json;charset=utf-8

Request Example

{
  "header": {
    "supplierId": "HILTON",
    "distributorId": "GTA",
    "version": "v4",
    "token": "18393849028490234"
  },
  "reservationIds": {
    "distributorResId": "C2084DFL0",
    "derbyResId": "D15F893D34DF",
    "supplierResId": "89389494"
  },
  "extensions": {
    "key1": "value1",
    "key2": "value2"
  }
}

Request Specification

Attribute	Type	Required	Description	Example
header	object	Yes	/	/
@supplierId	string	Yes	Max Length: 32 The ID of hotel supplier in DerbySoft's system.	HILTON
@distributorId	string	Yes	Max Length: 32 The ID of the distributor in DerbySoft's system.	MOCK_DISTRIBUTOR
@version	string	Yes	Max Length: 20 Version of API	v1.0.0
@token	string	Yes	Max Length: 64 A unique ID to identify requests and responses, normally it should be UUID.	18393849028490234
reservationIds		Yes	/	/
@distributorResId	string	Yes	Reservation ID in distributor's system	C2084DFL0
@derbyResId	string	No	Reservation ID in Derbysoft's system, it's a unique ID as DerbySoft would be splitting the reservation.	D15F893D34DF
@supplierResId	string	No	Reservation ID in supplier's system	89389494
extensions	object	No	Optional: Additional agreed-upon attributes between suppliers and distributors (DerbySoft will provide the specified format). Please don't transmit sensitive information through this field. For more information refer to: Sensitive Information	{"key": "value"}

Response Example

Success Response (HTTP Status 200) - OK

{
  "header": {
    "supplierId": "HILTON",
    "distributorId": "GTA",
    "version": "v4",
    "token": "18393849028490234"
  },
  "reservationIds": {
    "distributorResId": "C2084DFL0",
    "derbyResId": "D15F893D34DF",
    "supplierResId": "89389494"
  },
  "cancellationId": "C89389494",
  "extensions": {
    "key1": "value1",
    "key2": "value2"
  }
}

Error Response (HTTP Status 401) - Unauthorized token

{
  "errorCode": "string",
  "supplierErrorCode": "string",
  "errorMessage": "string"
}

Error Response (HTTP Status 500) - Internal system error

{
  "errorCode": "string",
  "supplierErrorCode": "string",
  "errorMessage": "string"
}

Response Specification

Attribute	Type	Required	Description	Example
header	object	Yes	/	/
@supplierId	string	Yes	Max Length: 32 The ID of hotel suppliers is in DerbySoft's system.	HILTON
@distributorId	string	Yes	Max Length: 32 The ID of the distributor in DerbySoft's system	MOCK_DISTRIBUTOR
@version	string	Yes	Max Length: 20 Version of API	v1.0.0
@token	string	Yes	Max Length: 64 A unique ID to identify requests and responses, normally it should be UUID.	18393849028490234
reservationIds	object	Yes	/	100001
@distributorResId	string	Yes	Reservation ID in distributor's system	C2084DFL0
@derbyResId	string	Yes	Reservation ID in Derbysoft's system, It's a unique ID as DerbySoft would be splitting the reservation.	D15F893D34DF
@supplierResId	string	Yes	Reservation ID in supplier's system	89389494
cancellationId	string	Yes	Cancellation confirmation number in supplier's system	C89389494
extensions	object	No	Optional: Additional agreed-upon attributes between suppliers and distributors (DerbySoft will provide the specified format)	/

Query Reservation List

This is an API to query a reservation list in DerbySoft's system and supplier's system with a timestamp range of the reservation's last modified date. It should be implemented by both DerbySoft and the supplier.

POST /reservations HTTP/1.1
URL: {{endpoint}}/reservations/(supplierId}
Authorization: Bearer 53ac07777cdffac2d53000002d698728ce964432d7167596bc005c5fc
Accept-Encoding: gzip
Content-Encoding: gzip
Content-Type: application/json;charset=utf-8

Request Example

{
  "header": {
    "supplierId": "HILTON",
    "distributorId": "GTA",
    "version": "v4",
    "token": "18393849028490234"
  },
  "dateRange": {
    "startDate": "2024-01-01",
    "endDate": "2024-01-04"
  },
  "hotelId": "GATHI"
}

Request Specification

Attribute	Type	Required	Description	Example
header	object	Yes	/
@supplierId	string	Yes	Max Length: 32 The ID of the hotel supplier in DerbySoft's system	HILTON
@distributorId	string	Yes	Max Length: 32 The ID of the distributor in DerbySoft's system	MOCK_DISTRIBUTOR
@version	string	Yes	Max Length: 20 Version of API	v1.0.0
@token	string	Yes	Max Length: 64 A unique ID to identify requests and responses, normally it should be UUID.	18393849028490234
dateRange	/	/	/	/
@startDate	string	Yes	Start date of date range, format with yyyy-MM-dd	2024-01-01
@endDate	string	Yes	End date of date range, format with yyyy-MM-dd	2024-01-04
hotelId	string	No	Supplier hotel ID in DerbySoft's system	GATHI

Response Example

Success Response (HTTP Status 200) - OK

{
  "header": {
    "supplierId": "HILTON",
    "distributorId": "GTA",
    "version": "v4",
    "token": "18393849028490234"
  },
  "reservations": [
    {
      "reservationIds": {
        "distributorResId": "C2084DFL0",
        "derbyResId": "D15F893D34DF",
        "supplierResId": "89389494"
      },
      "iata": "string",
      "hotelId": "GATHI",
      "stayRange": {
        "checkin": "2018-01-01",
        "checkout": "2018-01-04"
      },
      "contactPerson": {
        "firstName": "James",
        "lastName": "Bond",
        "email": "[email protected]",
        "phone": "string",
        "address": "string",
        "age": 0,
        "gender": "Male",
        "birthday": "2018-01-01",
        "type": "Adult",
        "index": 1
      },
      "roomCriteria": {
        "roomCount": 2,
        "adultCount": 1,
        "childCount": 2,
        "childAges": [
          4,
          8
        ]
      },
      "total": {
        "amountBeforeTax": 640,
        "amountAfterTax": 700
      },
      "status": "Confirmed",
      "cancellationId": "C89389494",
      "result": "Successful",
      "failCause": {
        "errorCode": "string",
        "supplierErrorCode": "string",
        "errorMessage": "string"
      }
    }
  ]
}

Error Response (HTTP Status 401) - Unauthorized token

{
  "errorCode": "string",
  "supplierErrorCode": "string",
  "errorMessage": "string"
}

Error Response (HTTP Status 500) - Internal system error

{
  "errorCode": "string",
  "supplierErrorCode": "string",
  "errorMessage": "string"
}

Response Specification

Attribute	Type	Required	Description	Example
header	object	Yes	/	/
@supplierId	string	Yes	Max Length: 32 The ID of hotel supplier in DerbySoft's system	HILTON
@distributorId	string	Yes	Max Length: 32 The ID of the distributor in DerbySoft's system	MOCK_DISTRIBUTOR
@version	string	Yes	Max Length: 20 Version of API	v1.0.0
@token	string	Yes	Max Length: 64 A unique ID to identify requests and responses, normally it should be UUID.	18393849028490234
reservations	/	/	/	/
reservations/reservationIds	/	/	/	/
@distributorResId	string	Yes	Reservation ID in distributor's system	C2084DFL0
@derbyResId	string	Yes	Reservation ID in Derbysoft's system, this is a unique ID as DerbySoft would be splitting the reservation.	D15F893D34DF
@supplierResId	string	Yes	Reservation ID in supplier's system	89389494
@iata	string	No	/	/
@hotelId	string	Yes	Hotel ID in supplier’s system	100001
reservations/stayRange	object	Yes	/	/
@checkin	string	Yes	Check-in, format with yyyy-MM-dd	2024-01-01
@checkout	string	Yes	Check out, format with yyyy-MM-dd	2024-01-04
reservations/roomCriteria	object	Yes	/
@roomCount	integer	Yes	Total room count per request
@adultCount	integer	Yes	Adult count per room
@childCount	integer	No	Child count per room
@childAges	array	No	For child ages for each child, array size MUST be the same as the child count.	[ 4, 8 ]
reservations/total	object	Yes	/	/
@amountBeforeTax	number	No	/	640
@amountAfterTax	number	No	/	700
@status	enum	Yes	Enum: [ Confirmed, Modified, Cancelled ] Status of reservation	/
cancellationId	string	No	Cancel confirmation number in supplier's system	C89389494
@result	enum	Yes	Enum: [ Successful, Failed, Processing ] Status of the reservation to send to supplier	/
reservations / failCause		No	/	/
@errorCode	string	Yes	Refer to Error Code Appendix	/
@supplierErrorCode	string	No	Error code from the supplier's system	/
@errorMessage	string	Yes	Error message	/

Query Reservation Detail

This API is used by distributors to query existing bookings. It can be used to check the reservation status of some timeout booking requests.

POST /reservation/detail HTTP/1.1
URL: {{endpoint}}/bts/api/reservation/detail/{supplierId}
Authorization: Bearer 53ac07777cdffac2d53000002d698728ce964432d7167596bc005c5fc
Accept-Encoding: gzip
Content-Encoding: gzip
Content-Type: application/json;charset=utf-8

Request Example

{
  "header": {
    "supplierId": "HILTON",
    "distributorId": "GTA",
    "version": "v4",
    "token": "18393849028490234"
  },
  "reservationIds": {
    "distributorResId": "C2084DFL0",
    "derbyResId": "D15F893D34DF",
    "supplierResId": "89389494"
  }
}

Request Specification

Attribute	Type	Required	Description	Example
header	object	Yes	/	/
@supplierId	string	Yes	Max Length: 32 The ID of the hotel supplier in DerbySoft's system.	HILTON
@distributorId	string	Yes	Max Length: 32 The ID of the distributor in DerbySoft's system	MOCK_DISTRIBUTOR
@version	string	Yes	Max Length: 20 Version of API	v1.0.0
@token	string	Yes	Max Length: 64 A unique ID to identify requests and responses, normally it should be UUID.	18393849028490234
reservationIds		Yes	/	/
@distributorResId	string	Yes	Reservation ID in distributor's system	C2084DFL0
@derbyResId	string	No	Reservation ID in Derbysoft's system, it's a unique ID as DerbySoft would be splitting the reservation.	D15F893D34DF
@supplierResId	string	No	Reservation ID in supplier's system	89389494

Response Example

Success Response (HTTP Status 200) - OK

{
  "header": {
    "supplierId": "HILTON",
    "distributorId": "GTA",
    "version": "v4",
    "token": "18393849028490234"
  },
  "reservations": [
    {
      "reservationIds": {
        "distributorResId": "C2084DFL0",
        "derbyResId": "D15F893D34DF",
        "supplierResId": "89389494"
      },
      "iata": "string",
      "hotelId": "GATHI",
      "stayRange": {
        "checkin": "2018-01-01",
        "checkout": "2018-01-04"
      },
      "contactPerson": {
        "firstName": "James",
        "lastName": "Bond",
        "email": "[email protected]",
        "phone": "string",
        "address": "string",
        "age": 0,
        "gender": "Male",
        "birthday": "2018-01-01",
        "type": "Adult",
        "index": 1
      },
      "roomCriteria": {
        "roomCount": 2,
        "adultCount": 1,
        "childCount": 2,
        "childAges": [
          4,
          8
        ]
      },
      "total": {
        "amountBeforeTax": 640,
        "amountAfterTax": 700
      },
      "payment": {
        "cardCode": "VI",
        "cardNumber": "4111111111111111",
        "cardHolderName": "Sherlock Holmes",
        "expireDate": "119"
      },
      "loyaltyAccount": {
        "programCode": "BW",
        "accountId": "1234567890123457"
      },
      "corpAccount": {
        "corpProgramCode": "CR",
        "corpId": "A-1232"
      },
      "promoteCode": "string",
      "guests": [
        {
          "firstName": "James",
          "lastName": "Bond",
          "email": "[email protected]",
          "phone": "string",
          "address": "string",
          "age": 0,
          "gender": "Male",
          "birthday": "2018-01-01",
          "type": "Adult",
          "index": 1
        }
      ],
      "comments": [
        "no smoking",
        "high floor"
      ],
      "roomRates": [
        {
          "roomId": "K1D",
          "rateId": "ODAD01",
          "currency": "USD",
          "amountBeforeTax": [
            100,
            100,
            120
          ],
          "amountAfterTax": [
            110,
            110,
            130
          ],
          "mealPlan": "RO",
          "paymentType": "PayNow",
          "guarantee": {
            "guaranteeType": "CCG"
          },
          "fees": [
            {
              "dateRange": {
                "startDate": "2024-01-01",
                "endDate": "2024-01-04"
              },
              "fee": {
                "name": "Service Charge",
                "type": "Exclusive",
                "amount": 10,
                "amountType": "Percent",
                "chargeType": "PerRoomPerNight",
                "paymentType": "PayNow",
                "effectivePerson": 0
              }
            }
          ],
          "cancelPolicy": {
            "code": "AD100P_100P",
            "description": "Non Refundable",
            "cancelPenalties": [
              {
                "noShow": true,
                "cancellable": true,
                "cancelDeadline": {
                  "offsetTimeDropType": "BeforeArrival",
                  "offsetTimeUnit": "D",
                  "offsetTimeValue": 999,
                  "deadline": "string"
                },
                "penaltyCharge": {
                  "chargeBase": "FullStay",
                  "nights": 0,
                  "amount": 0,
                  "percent": 0
                }
              }
            ]
          }
        }
      ],
      "bookingChannel": "string",
      "productAddons": [
        {
          "type": "DisneyTicket",
          "code": "code",
          "date": "2018-01-01",
          "quantity": 1,
          "officeId": "string",
          "rate": {
            "ageQualifyingType": {
              "type": "Adult",
              "minAge": 18,
              "maxAge": 18
            },
            "currency": "USD",
            "amountBeforeTax": 123.23,
            "amountAfterTax": 134.34
          }
        }
      ],
      "status": "Confirmed",
      "cancellationId": "C89389494",
      "result": "Successful",
      "failCause": {
        "errorCode": "string",
        "supplierErrorCode": "string",
        "errorMessage": "string"
      }
    }
  ]
}

Error Response (HTTP Status 401) - Unauthorized token

{
  "errorCode": "string",
  "supplierErrorCode": "string",
  "errorMessage": "string"
}

Error Response (HTTP Status 500) - Internal system error

{
  "errorCode": "string",
  "supplierErrorCode": "string",
  "errorMessage": "string"
}

Response Specification

Attribute	Type	Required	Description	Example
header	object	Yes	/	/
@supplierId	string	Yes	MaxLength: 32 The ID of the hotel supplier in DerbySoft's system	HILTON
@distributorId	string	Yes	MaxLength: 32 The ID of the distributor in DerbySoft's system	MOCK_DISTRIBUTOR
@version	string	Yes	MaxLength: 20 version of API	v1.0.0
@token	string	Yes	MaxLength: 64 A unique ID to identify request and response, normally it should be UUID.	18393849028490234
reservations	/	No	/	/
/reservationIds	/	/	/	/
@distributorResId	string	Yes	Reservation ID in distributor's system	C2084DFL0
@derbyResId	string	Yes	Reservation ID in DerbySoft system, this is a unique ID as DerbySoft would be splitting the reservation.	D15F893D34DF
@supplierResId	string	Yes	Reservation ID in supplier's system	89389494
iata	string	No	/	/
hotelId	string	Yes	Hotel ID in supplier’s system	100001
stayRange	object	Yes	/	/
@checkin	string	Yes	Check-in, format with yyyy-MM-dd	2024-01-01
@checkout	string	Yes	Check out, format with yyyy-MM-dd	2024-01-04
roomCriteria	object	Yes	/	/
@roomCount	integer	Yes	Total room count per request	/
@adultCount	integer	Yes	Adult count per room	/
@childCount	integer	No	Child count per room
@childAges	array	No	For child ages each child, the array size MUST be the same as the child count.	/
total	object	Yes	/	/
@amountBeforeTax	number	No	/	640
@amountAfterTax	number	No	/	700
loyaltyAccount	object	No	/	/
@programCode	string	Yes	Loyalty program code of the supplier	BW
@accountId	string	Yes	Loyalty program account ID	1234567890123457
corpAccount	object	No	/	/
@corpProgramCode	string	Yes	Corporate Hotel Program of hotel supplier	CR
@corpId	string	Yes	Corporate ID in the program account	A-1232
promoteCode	string	No	The promotion code is defined by the hotel, the promotion code is required if making a reservation under the promotion.	/
comments	array[string]	No	/	[ "no smoking", "high floor" ]
roomRates	array[object]	Yes	Min Items: 1 Max Item: 1 Meal plan, fee, and cancel policy are optional fields as some distributors do not support these in the API.	/
@roomId	string	Yes	Room ID in supplier's system	10000101
@rateId	string	Yes	Rate ID in supplier's system	123456
@currency	string	Yes	Currency code [ISO-4217]	USD
@amountBeforeTax	array[number]	No	The daily amount rate without tax and fee	[ 100, 100, 120 ]
@amountAfterTax	array[number]	No	The daily amount of rate with tax and fee	[ 110, 110, 130 ]
@mealPlan	string	No	Meal plan code, refer to the standard meal plan code list.	RO
@paymentType	enum	No	Indicates the product is prepaid to the hotel (PayNow) or pay at the hotel (PayLater). Enum: [ PayLater, PayNow ]	PayNow
roomRates/guarantee	object	No	Guarantee information for this room rate.	/
@guaranteeType	string	Yes	The type of guarantee method, refer to the standard guarantee type list.	CCG
roomRates/fees	array[object]	No	Fee or tax by date range.	/
fees/dateRange	object	Yes	/	/
@startDate	string	Yes	Start date of date range, format with yyyy-MM-dd	2024-01-01
@endDate	string	Yes	End date of date range, format with yyyy-MM-dd	2024-01-04
fees / fee	/	Yes	/	/
@name	string	Yes	Pattern: \w[\w\d]+	Service Charge
@type	enum	Yes	Indicates if the fee or tax is included in the amount before tax or not. Enum: [ Inclusive, Exclusive ]	Exclusive
@amount	number	Yes	Amount value of fee or tax	10
@amountType	string	Yes	Indicates how to charge the tax, 10% per room per night in this example Enum: [ Fix, Percent ]	Percent
@chargeType	string	Yes	Enum: [ PerRoomPerNight, PerPersonPerNight, PerRoomPerStay, PerPersonPerStay ]	PerRoomPerNight
@paymentType	enum	No	Indicates the fee is prepaid to the hotel (PayNow) or pay at the hotel (PayLater). Enum: [ PayLater, PayNow ]	PayNow
@effectivePerson	number		This means this fee will be charged based on how many persons, like extra person charge, usually applied from 3, so the 1 adult, 2 adults will be same, 3 adults will be charged an extra fee.	/
roomRates/cancelPolicy	object	No	Cancellation policy defines what penalty will be charged when a guest cancels the booking at a certain advance time range. The penalty is related to No-show or a time range before No-show.	/
@code	string		Max Length: 128 Code of cancel policy	AD100P_100P
@description	string		Max Length: 1024 The description of the cancellation policy	Non Refundable
cancelPolicy/cancelPenalties		Yes	Detail about the canceled Penalty	/
@noShow	boolean	Yes	If true, it means the penalty charge applied for No-Show, and the cancellable, cancelDeadline will NOT exist.	/
@cancellable	boolean	No	Indicates if cancellation is allowed or not. If false, it cannot be canceled. If true, the cancellation deadline will exist.	/
cancelPenalties/cancelDeadline	/	/	/	/
@offsetTimeDropType	enum	No	Enum: [ BeforeArrival ] An enumerated type indicates when the deadline drop time goes into effect.	/
@offsetTimeUnit	enum	No	Enum: [ D, H ]	/
@offsetTimeValue	number	No	The number of offset times with the time unit	/
@deadline	string	No	Local deadline times allowed for cancellation, like 4 PM, or 6 PM.	/
cancelPenalties/penaltyCharge	/	/	/	/
@chargeBase	enum	No	Enum: [ FullStay, NightBase ] if FullStay, it will be a percentage or amount, if NightBase, the nights are required.	/
@nights	number	No	It exists if the penalty charge is based on the night, like the first night.	/
@amount	number	No	It exists if the penalty charge is a flat charge, like USD 30.00.	/
@percent	number	No	It exists if the penalty charge is percent, like 15.5 means 15.5%	/
bookingChannel	string	No	Sub-distributor ID	/
productAddons	array[object]	No	/	/
@type	string	Yes	/	DisneyTicket
@code	string	Yes	/	/
@date	string	Yes	format with yyyy-MM-dd	2024-01-01
@quantity	integer	Yes	/	1
@officeId	string	No	specific distributor office	/
productAddons/rate	object	No	/	/
rate/ageQualifyingType	object	No	/	/
@type	enum	Yes	Enum: [Adult, Child]	Adult
@minAge	integer	Yes	/	18
@maxAge	integer	Yes	/	18
rate/currency	string	Yes	/	USD
rate/amountBeforeTax	number	No	/	123.23
rate/amountAfterTax	number	No	/	134.34
status	enum	Yes	Enum: [ Confirmed, Modified, Cancelled ] The latest status of the reservation Confirmed - New reservation Modified - Modification Reservation Cancelled - Cancellation Reservation Please combine the status and result fields to determine the reservation whether successful, combination examples are as follows: Confirmed + Successful = Booking is successful Confirmed + Failed = Booking is failed Modified + Successful = Modification is successful Modified + Failed = Modification is failed Cancelled + Successful = Cancellation is successful Cancelled + Failed = Cancellation is failed	/
cancellationId	string	No	Cancellation confirmation number in suppliers' system	C89389494
result	enum	Yes	Enum: [ Successful, Failed, Processing ] result of the reservation to send to the supplier	/
reservations/failCause	/	No	/	/
@errorCode	string	Yes	Error Code Appendix	/
@supplierErrorCode	string	No	Error code from the supply system	/
@errorMessage	string	Yes	Error message