{ "openapi": "3.0.3", "info": { "title": "Idea Holiday Partner API", "version": "1.0.0", "description": "Hotels, flights and FD fares for approved travel agents, paid from the Idea Holiday wallet. Guides: hotels-v1, flights-v1, fd-fare-v1. Every response uses the Envelope. API fees (per room-night, per passenger, plus GST) are non-refundable." }, "servers": [ { "url": "https://b2b.ideaholiday.com/api/v1/partner", "description": "Production (ih_live_ keys) and sandbox (ih_test_ keys)" } ], "security": [ { "apiKey": [] } ], "tags": [ { "name": "Account" }, { "name": "Hotels" }, { "name": "Flights" }, { "name": "FD" } ], "paths": { "/wallet": { "get": { "summary": "Wallet balance, credit limit and available funds", "tags": [ "Account" ], "responses": { "200": { "description": "Wallet", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Wallet" } } } ] } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } } } }, "/hotels/search": { "post": { "summary": "Search hotels", "tags": [ "Hotels" ], "responses": { "200": { "description": "Hotels", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/HotelSearchResult" } } } ] } } } }, "502": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HotelSearchRequest" } } } } } }, "/hotels/search/{search_id}": { "get": { "summary": "Next page of a search (no new supplier call)", "tags": [ "Hotels" ], "responses": { "200": { "description": "Hotels", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/HotelSearchResult" } } } ] } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } }, "parameters": [ { "name": "search_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "From search" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Page" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Up to 50" } ] } }, "/hotels/{hotel_id}": { "get": { "summary": "Hotel details and all rates", "tags": [ "Hotels" ], "responses": { "200": { "description": "Hotel details", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" } ] } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } }, "parameters": [ { "name": "hotel_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Hotel" }, { "name": "search_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "From search" } ] } }, "/hotels/prebook": { "post": { "summary": "Confirm the live price and hold the rate", "tags": [ "Hotels" ], "responses": { "200": { "description": "Prebooked", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/HotelPrebook" } } } ] } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HotelPrebookRequest" } } } } } }, "/hotels/bookings": { "post": { "summary": "Book a prebooked hotel from the wallet", "tags": [ "Hotels" ], "responses": { "201": { "description": "Confirmed", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/HotelBooking" } } } ] } } } }, "202": { "description": "Pending or unknown", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/HotelBooking" } } } ] } } } }, "402": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "409": { "description": "Failed (refunded)", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/HotelBooking" } } } ] } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HotelBookRequest" } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique per booking attempt, 8-128 of A-Z a-z 0-9 _ . : -. A repeat with the same key and body returns the first answer.", "schema": { "type": "string", "minLength": 8, "maxLength": 128 } } ] } }, "/hotels/bookings/{booking_id}": { "get": { "summary": "Hotel booking status", "tags": [ "Hotels" ], "responses": { "200": { "description": "Booking", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/HotelBooking" } } } ] } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } }, "parameters": [ { "name": "booking_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Booking" } ] } }, "/hotels/bookings/{booking_id}/cancel": { "post": { "summary": "Request cancellation of a confirmed hotel", "tags": [ "Hotels" ], "responses": { "202": { "description": "Cancelling", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/HotelBooking" } } } ] } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelRequest" } } } }, "parameters": [ { "name": "booking_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Booking" } ] } }, "/hotels/bookings/{booking_id}/cancellation": { "get": { "summary": "Cancellation result and refund", "tags": [ "Hotels" ], "responses": { "200": { "description": "Booking", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/HotelBooking" } } } ] } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } }, "parameters": [ { "name": "booking_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Booking" } ] } }, "/flights/search": { "post": { "summary": "Search flights (TBO)", "tags": [ "Flights" ], "responses": { "200": { "description": "Flights", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/FlightSearchResult" } } } ] } } } }, "502": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FlightSearchRequest" } } } } } }, "/flights/fare-quote": { "post": { "summary": "Confirm the live fare", "tags": [ "Flights" ], "responses": { "200": { "description": "Quote", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/FareQuote" } } } ] } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FareQuoteRequest" } } } } } }, "/flights/bookings": { "post": { "summary": "Book (and ticket LCC fares) from the wallet", "tags": [ "Flights" ], "responses": { "201": { "description": "Ticketed", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/FlightBooking" } } } ] } } } }, "202": { "description": "Booked or unknown", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/FlightBooking" } } } ] } } } }, "402": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "409": { "description": "Failed (refunded)", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/FlightBooking" } } } ] } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FlightBookRequest" } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique per booking attempt, 8-128 of A-Z a-z 0-9 _ . : -. A repeat with the same key and body returns the first answer.", "schema": { "type": "string", "minLength": 8, "maxLength": 128 } } ], "description": "Live keys only." } }, "/flights/bookings/{booking_id}": { "get": { "summary": "Flight booking status", "tags": [ "Flights" ], "responses": { "200": { "description": "Booking", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/FlightBooking" } } } ] } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } }, "parameters": [ { "name": "booking_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Booking" } ] } }, "/flights/bookings/{booking_id}/ticket": { "post": { "summary": "Ticket a BOOKED flight", "tags": [ "Flights" ], "responses": { "200": { "description": "Ticketed", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/FlightBooking" } } } ] } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "502": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } }, "parameters": [ { "name": "booking_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Booking" } ] } }, "/fd/availability": { "post": { "summary": "FD Fare availability (FD Fare v1 body)", "tags": [ "FD" ], "responses": { "200": { "description": "As FD Fare v1" }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FdPassthrough" } } } } } }, "/fd/search": { "post": { "summary": "FD Fare search (FD Fare v1 body)", "tags": [ "FD" ], "responses": { "200": { "description": "As FD Fare v1" }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FdPassthrough" } } } } } }, "/fd/bookings": { "post": { "summary": "FD Fare confirm (FD Fare v1 body); adds data.api_fee", "tags": [ "FD" ], "responses": { "200": { "description": "As FD Fare v1" }, "402": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "422": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FdPassthrough" } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique per booking attempt, 8-128 of A-Z a-z 0-9 _ . : -. A repeat with the same key and body returns the first answer.", "schema": { "type": "string", "minLength": 8, "maxLength": 128 } } ], "description": "Live keys only." } }, "/fd/bookings/{reference}": { "get": { "summary": "FD Fare booking status", "tags": [ "FD" ], "responses": { "200": { "description": "As FD Fare v1" }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } }, "parameters": [ { "name": "reference", "in": "path", "required": true, "schema": { "type": "string" }, "description": "booking_reference" } ] } }, "/fd/bookings/{reference}/cancel": { "post": { "summary": "FD Fare cancellation request", "tags": [ "FD" ], "responses": { "200": { "description": "As FD Fare v1" }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelRequest" } } } }, "parameters": [ { "name": "reference", "in": "path", "required": true, "schema": { "type": "string" }, "description": "booking_reference" } ] } }, "/flights/bookings/{booking_id}/cancellation-charges": { "get": { "summary": "Cancellation charges if cancelled now", "tags": [ "Flights" ], "parameters": [ { "name": "booking_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Booking" } ], "responses": { "200": { "description": "Charges", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/FlightCancellationCharges" } } } ] } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "502": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } } } }, "/flights/bookings/{booking_id}/cancel": { "post": { "summary": "Cancel a booked or ticketed flight", "tags": [ "Flights" ], "description": "Releases a held PNR (full refund) or sends the cancellation to the airline. The booking becomes CANCELLING, then CANCELLED with the refund in the wallet. Some airlines take hours; check GET /cancellation or wait for the booking.cancelled webhook. The API fee is not refunded.", "parameters": [ { "name": "booking_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Booking" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelRequest" } } } }, "responses": { "202": { "description": "Cancellation started or done", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/FlightBooking" } } } ] } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "502": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } } } }, "/flights/bookings/{booking_id}/cancellation": { "get": { "summary": "Cancellation result and refund", "tags": [ "Flights" ], "parameters": [ { "name": "booking_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Booking" } ], "responses": { "200": { "description": "Booking with its cancellation", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/FlightBooking" } } } ] } } } }, "404": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "409": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "502": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "403": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "x-api-key" } }, "schemas": { "Envelope": { "type": "object", "required": [ "request_id", "status", "data", "errors", "meta" ], "properties": { "request_id": { "type": "string" }, "status": { "type": "string", "enum": [ "ok", "error" ] }, "data": { "nullable": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } }, "meta": { "type": "object", "properties": { "currency": { "type": "string" }, "sandbox": { "type": "boolean" } } } } }, "Wallet": { "type": "object", "properties": { "balance": { "type": "number", "description": "INR" }, "credit_limit": { "type": "number", "description": "INR" }, "available": { "type": "number", "description": "INR" } } }, "HotelSearchRequest": { "type": "object", "required": [ "city_code", "check_in", "check_out", "rooms" ], "properties": { "city_code": { "type": "string" }, "check_in": { "type": "string", "format": "date" }, "check_out": { "type": "string", "format": "date", "description": "1 to 30 nights" }, "rooms": { "type": "array", "minItems": 1, "maxItems": 6, "items": { "type": "object", "required": [ "adults" ], "properties": { "adults": { "type": "integer", "minimum": 1, "maximum": 8 }, "child_ages": { "type": "array", "maxItems": 4, "items": { "type": "integer", "minimum": 0, "maximum": 17 } } } } }, "nationality": { "type": "string", "default": "IN" }, "page": { "type": "integer", "default": 1 }, "limit": { "type": "integer", "default": 20, "maximum": 50 } } }, "HotelRate": { "type": "object", "properties": { "booking_code": { "type": "string" }, "room_name": { "type": "string" }, "meal_plan": { "type": "string" }, "total_price": { "type": "number", "description": "INR" }, "refundable": { "type": "boolean" } } }, "Hotel": { "type": "object", "properties": { "hotel_id": { "type": "string" }, "name": { "type": "string" }, "star_rating": { "type": "number" }, "address": { "type": "string" }, "city": { "type": "string" }, "image_url": { "type": "string" }, "currency": { "type": "string" }, "lowest_price": { "type": "number", "description": "INR" }, "rates": { "type": "array", "items": { "$ref": "#/components/schemas/HotelRate" } } } }, "HotelSearchResult": { "type": "object", "properties": { "search_id": { "type": "string" }, "nights": { "type": "integer" }, "total": { "type": "integer" }, "page": { "type": "integer" }, "limit": { "type": "integer" }, "hotels": { "type": "array", "items": { "$ref": "#/components/schemas/Hotel" } } } }, "HotelPrebookRequest": { "type": "object", "required": [ "search_id", "hotel_id", "booking_codes" ], "properties": { "search_id": { "type": "string" }, "hotel_id": { "type": "string" }, "booking_codes": { "type": "array", "minItems": 1, "items": { "type": "string" } } } }, "HotelPrebook": { "type": "object", "properties": { "booking_id": { "type": "string" }, "booking_ref": { "type": "string" }, "status": { "type": "string" }, "hotel_id": { "type": "string" }, "hotel_name": { "type": "string" }, "check_in": { "type": "string" }, "check_out": { "type": "string" }, "rooms": { "type": "integer" }, "total_payable": { "type": "number", "description": "INR" }, "api_fee": { "type": "object", "description": "Idea Holiday API fee, non-refundable", "properties": { "base": { "type": "number", "description": "INR" }, "gst": { "type": "number", "description": "INR" }, "total": { "type": "number", "description": "INR" } } }, "expires_at": { "type": "string", "nullable": true }, "cancellation_policy": { "nullable": true }, "pan_required": { "type": "boolean" }, "passport_required": { "type": "boolean" }, "rate_conditions": { "type": "array", "items": { "type": "string" } } } }, "HotelGuest": { "type": "object", "required": [ "room_index", "title", "first_name", "last_name" ], "properties": { "room_index": { "type": "integer", "minimum": 0 }, "type": { "type": "string", "enum": [ "ADULT", "CHILD" ], "default": "ADULT" }, "title": { "type": "string", "enum": [ "Mr", "Mrs", "Ms", "Miss" ] }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "age": { "type": "integer", "description": "Required for CHILD" }, "pan": { "type": "string" }, "lead": { "type": "boolean" } } }, "Contact": { "type": "object", "required": [ "email", "phone" ], "properties": { "email": { "type": "string", "format": "email" }, "phone": { "type": "string" } } }, "HotelBookRequest": { "type": "object", "required": [ "booking_id", "guests", "contact" ], "properties": { "booking_id": { "type": "string" }, "guests": { "type": "array", "items": { "$ref": "#/components/schemas/HotelGuest" } }, "contact": { "$ref": "#/components/schemas/Contact" } } }, "HotelBooking": { "type": "object", "properties": { "booking_id": { "type": "string" }, "booking_ref": { "type": "string" }, "status": { "type": "string", "enum": [ "PREBOOKED", "BOOKING", "PENDING", "CONFIRMED", "UNKNOWN", "FAILED", "CANCELLING", "CANCELLED" ] }, "confirmation_no": { "type": "string", "nullable": true }, "hotel_id": { "type": "string" }, "hotel_name": { "type": "string" }, "check_in": { "type": "string", "nullable": true }, "check_out": { "type": "string", "nullable": true }, "rooms": { "type": "integer" }, "total_payable": { "type": "number", "description": "INR" }, "paid_amount": { "type": "number", "description": "INR" }, "currency": { "type": "string" }, "refund": { "nullable": true }, "last_error": { "type": "string", "nullable": true } } }, "CancelRequest": { "type": "object", "properties": { "reason": { "type": "string", "maxLength": 300 } } }, "FlightSearchRequest": { "type": "object", "required": [ "origin", "destination", "departure_date" ], "properties": { "origin": { "type": "string", "pattern": "^[A-Z]{3}$" }, "destination": { "type": "string", "pattern": "^[A-Z]{3}$" }, "departure_date": { "type": "string", "format": "date" }, "return_date": { "type": "string", "format": "date" }, "adults": { "type": "integer", "minimum": 1, "default": 1 }, "children": { "type": "integer", "minimum": 0, "default": 0 }, "infants": { "type": "integer", "minimum": 0, "default": 0 }, "cabin": { "type": "string", "enum": [ "ECONOMY", "PREMIUM_ECONOMY", "BUSINESS", "PREMIUM_BUSINESS", "FIRST" ], "default": "ECONOMY" } } }, "FlightSegment": { "type": "object", "properties": { "airline_code": { "type": "string" }, "airline_name": { "type": "string" }, "flight_number": { "type": "string" }, "fare_class": { "type": "string" }, "origin": { "type": "string" }, "origin_terminal": { "type": "string" }, "departure_time": { "type": "string" }, "destination": { "type": "string" }, "destination_terminal": { "type": "string" }, "arrival_time": { "type": "string" }, "baggage": { "type": "string" }, "cabin_baggage": { "type": "string" }, "duration_minutes": { "type": "integer" } } }, "FlightOption": { "type": "object", "properties": { "result_index": { "type": "string" }, "direction": { "type": "string", "enum": [ "OUTBOUND", "INBOUND" ] }, "is_lcc": { "type": "boolean" }, "refundable": { "type": "boolean" }, "validating_airline": { "type": "string" }, "fare": { "type": "object", "properties": { "currency": { "type": "string" }, "base": { "type": "number", "description": "INR" }, "tax": { "type": "number", "description": "INR" }, "total": { "type": "number", "description": "INR" } } }, "journeys": { "type": "array", "items": { "type": "object", "properties": { "segments": { "type": "array", "items": { "$ref": "#/components/schemas/FlightSegment" } } } } }, "last_ticket_date": { "type": "string", "nullable": true } } }, "FlightSearchResult": { "type": "object", "properties": { "search_id": { "type": "string" }, "trip_type": { "type": "string", "enum": [ "ONE_WAY", "ROUND_TRIP" ] }, "outbound": { "type": "array", "items": { "$ref": "#/components/schemas/FlightOption" } }, "inbound": { "type": "array", "items": { "$ref": "#/components/schemas/FlightOption" } }, "message": { "type": "string", "nullable": true } } }, "FareQuoteRequest": { "type": "object", "required": [ "search_id", "result_index" ], "properties": { "search_id": { "type": "string" }, "result_index": { "type": "string" }, "return_result_index": { "type": "string", "description": "Domestic round trips: the chosen inbound option" } } }, "FareQuote": { "type": "object", "properties": { "quote_id": { "type": "string" }, "search_id": { "type": "string" }, "result_index": { "type": "string" }, "return_result_index": { "type": "string", "nullable": true }, "passengers": { "type": "object", "properties": { "adults": { "type": "integer" }, "children": { "type": "integer" }, "infants": { "type": "integer" } } }, "is_lcc": { "type": "boolean" }, "fare": { "type": "object", "properties": { "currency": { "type": "string" }, "base": { "type": "number", "description": "INR" }, "tax": { "type": "number", "description": "INR" }, "total": { "type": "number", "description": "INR" } } }, "api_fee": { "type": "object", "description": "Idea Holiday API fee, non-refundable", "properties": { "base": { "type": "number", "description": "INR" }, "gst": { "type": "number", "description": "INR" }, "total": { "type": "number", "description": "INR" } } }, "fare_rules": { "type": "array", "items": { "type": "string" } }, "valid_until": { "type": "string", "nullable": true } } }, "FlightPassenger": { "type": "object", "required": [ "type", "title", "first_name", "last_name", "date_of_birth" ], "properties": { "type": { "type": "string", "enum": [ "ADULT", "CHILD", "INFANT" ] }, "title": { "type": "string", "enum": [ "Mr", "Mrs", "Ms", "Mstr", "Miss" ], "description": "Mr, Mrs, Ms for adults; Mstr, Miss for children and infants" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "date_of_birth": { "type": "string", "format": "date" }, "nationality": { "type": "string", "default": "IN" }, "passport_number": { "type": "string" }, "passport_expiry": { "type": "string", "format": "date" }, "passport_issue_country": { "type": "string" } } }, "FlightBookRequest": { "type": "object", "required": [ "quote_id", "passengers", "contact" ], "properties": { "quote_id": { "type": "string" }, "passengers": { "type": "array", "items": { "$ref": "#/components/schemas/FlightPassenger" }, "description": "First passenger is the lead adult; counts must match the search" }, "contact": { "$ref": "#/components/schemas/Contact" } } }, "FlightBooking": { "type": "object", "properties": { "booking_id": { "type": "string" }, "booking_ref": { "type": "string" }, "status": { "type": "string", "enum": [ "CREATED", "BOOKED", "TICKETED", "UNKNOWN", "FAILED", "CANCELLING", "CANCELLED" ] }, "pnr": { "type": "string", "nullable": true }, "ticket_number": { "type": "string", "nullable": true }, "origin": { "type": "string", "nullable": true }, "destination": { "type": "string", "nullable": true }, "departure_date": { "type": "string", "nullable": true }, "return_date": { "type": "string", "nullable": true }, "passengers": { "type": "array", "items": { "type": "object" } }, "total_payable": { "type": "number", "description": "INR" }, "currency": { "type": "string" }, "refund": { "nullable": true }, "last_error": { "type": "string", "nullable": true }, "cancellation": { "nullable": true, "type": "object", "properties": { "state": { "type": "string", "enum": [ "REQUESTED", "PENDING", "CANCELLED", "REVIEW", "REJECTED", "FAILED" ] }, "reason": { "type": "string", "nullable": true }, "requested_at": { "type": "string" }, "refund_amount": { "type": "number", "nullable": true, "description": "INR credited to the wallet, once CANCELLED" }, "cancellation_charge": { "type": "number", "nullable": true }, "settled_at": { "type": "string", "nullable": true }, "last_error": { "type": "string", "nullable": true } } } } }, "FdPassthrough": { "type": "object", "description": "Same request and response bodies as FD Fare v1 (/openapi/fd-fare-v1.json)", "additionalProperties": true }, "FlightCancellationCharges": { "type": "object", "properties": { "booking_id": { "type": "string" }, "mode": { "type": "string", "enum": [ "RELEASE", "CANCEL" ], "description": "RELEASE: the ticket was not issued, the held PNR is released with a full refund. CANCEL: the ticket is cancelled with the airline." }, "paid": { "type": "number", "description": "INR paid for the booking" }, "refund_amount": { "type": "number", "description": "INR credited to the wallet if cancelled now (estimate from the airline; the final amount comes with the cancellation)" }, "cancellation_charge": { "type": "number" }, "currency": { "type": "string" }, "remarks": { "type": "array", "items": { "type": "string" } } } }, "WebhookEvent": { "type": "object", "description": "Body of a webhook POST to the URL set under Help > API Access > Webhook. Headers: X-IH-Event, X-IH-Delivery, X-IH-Signature (t=,v1=HMAC-SHA256 of '.' with your signing secret). Retried after 1, 5, 30, 120 and 720 minutes until a 2xx answer.", "required": [ "id", "event", "sandbox", "createdAt", "data" ], "properties": { "id": { "type": "string", "description": "Delivery ID; use it to drop duplicates." }, "event": { "type": "string", "enum": [ "booking.confirmed", "booking.ticketed", "booking.failed", "booking.cancelled", "booking.pnr_changed", "wallet.low", "webhook.test" ] }, "sandbox": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "data": { "type": "object", "description": "Booking events: product (HOTEL, FLIGHT or FD) and booking (same fields as the booking status). booking.pnr_changed also has previousPnr and pnrChangedAt. wallet.low (at most once a day, below the threshold you set, default Rs.10,000): availableFunds, walletBalance, threshold, currency.", "properties": { "product": { "type": "string", "enum": [ "HOTEL", "FLIGHT", "FD" ] }, "booking": { "type": "object", "additionalProperties": true }, "previousPnr": { "type": "string", "nullable": true }, "pnrChangedAt": { "type": "string", "format": "date-time" }, "availableFunds": { "type": "number" }, "walletBalance": { "type": "number" }, "threshold": { "type": "number" }, "currency": { "type": "string", "example": "INR" } } } } } } } }