{
  "openapi": "3.0.3",
  "info": {
    "title": "Idea Holiday Partner API — FD Fare",
    "version": "1.0.0",
    "description": "Authenticated FD Fare availability, search, confirmation, status, and cancellation APIs for approved travel partners. Use the Idea Holiday Partner API for the complete booking lifecycle."
  },
  "servers": [{ "url": "https://b2b.ideaholiday.com/api/v1/fly", "description": "Production" }],
  "security": [{ "partnerAccessToken": [] }, { "partnerApiKey": [] }],
  "paths": {
    "/availability": {
      "post": { "summary": "List available FD Fare dates", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AvailabilityRequest" } } } }, "responses": { "200": { "description": "Available dates" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "503": { "$ref": "#/components/responses/Unavailable" } } }
    },
    "/search": {
      "post": { "summary": "Search FD fares", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchRequest" } } } }, "responses": { "200": { "description": "FD fares and expiry time" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "503": { "$ref": "#/components/responses/Unavailable" } } }
    },
    "/confirm": {
      "post": { "summary": "Confirm an FD Fare booking", "description": "A confirmation can have a supplier-side effect. If the response is unknown, look up status before retrying.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmRequest" } } } }, "responses": { "200": { "description": "Booking confirmed or pending ticket issue" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "description": "Fare or seat is no longer available" }, "503": { "$ref": "#/components/responses/Unavailable" } } }
    },
    "/status/{booking_reference}": {
      "get": { "summary": "Get booking status", "parameters": [{ "in": "path", "name": "booking_reference", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "Latest booking status" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Booking not found" } } }
    },
    "/cancel-request": {
      "post": { "summary": "Request booking cancellation", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelRequest" } } } }, "responses": { "200": { "description": "Cancellation request accepted" }, "202": { "description": "Supplier review required" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Booking not found" } } }
    }
  },
  "components": {
    "securitySchemes": { "partnerAccessToken": { "type": "http", "scheme": "bearer", "bearerFormat": "Partner access token", "description": "Issued for an approved Idea Holiday partner account." }, "partnerApiKey": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Administrator-issued ih_test_ (availability/search only) or ih_live_ partner API key." } },
    "responses": {
      "BadRequest": { "description": "Invalid request" },
      "Unauthorized": { "description": "Missing, expired, or invalid partner token" },
      "Unavailable": { "description": "Supplier temporarily unavailable" }
    },
    "schemas": {
      "AvailabilityRequest": { "type": "object", "required": ["from_airport", "to_airport"], "properties": { "from_airport": { "$ref": "#/components/schemas/IataAirport" }, "to_airport": { "$ref": "#/components/schemas/IataAirport" }, "supplier": { "$ref": "#/components/schemas/Supplier" } } },
      "SearchRequest": { "type": "object", "required": ["from_airport", "to_airport", "departure_date", "adults"], "properties": { "from_airport": { "$ref": "#/components/schemas/IataAirport" }, "to_airport": { "$ref": "#/components/schemas/IataAirport" }, "departure_date": { "type": "string", "format": "date" }, "return_date": { "type": "string", "format": "date" }, "adults": { "type": "integer", "minimum": 1, "maximum": 9 }, "children": { "type": "integer", "minimum": 0, "default": 0 }, "infants": { "type": "integer", "minimum": 0, "default": 0 }, "trip_type": { "type": "string", "enum": ["oneway", "roundtrip"], "default": "oneway" }, "supplier": { "$ref": "#/components/schemas/Supplier" } } },
      "ConfirmRequest": { "type": "object", "required": ["flight_id", "search_params", "selected_flight", "passengers", "contact_email", "contact_phone"], "properties": { "flight_id": { "type": "string" }, "supplier": { "type": "string", "description": "Optional routing value returned by the preceding search. Send it unchanged when present." }, "search_id": { "type": "string" }, "selected_flight": { "type": "object", "additionalProperties": true }, "search_params": { "$ref": "#/components/schemas/SearchRequest" }, "contact_email": { "type": "string", "format": "email" }, "contact_phone": { "type": "string", "example": "919876543210" }, "passengers": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/Passenger" } } } },
      "Passenger": { "type": "object", "required": ["title", "first_name", "last_name", "passenger_type", "email", "phone"], "properties": { "title": { "type": "string", "enum": ["MR", "MS", "MRS", "MSTR", "MISS"] }, "first_name": { "type": "string", "minLength": 2 }, "last_name": { "type": "string", "minLength": 2 }, "passenger_type": { "type": "string", "enum": ["ADULT", "CHILD", "INFANT"] }, "date_of_birth": { "type": "string", "format": "date" }, "email": { "type": "string", "format": "email" }, "phone": { "type": "string" }, "passport_number": { "type": "string" }, "passport_expirydate": { "type": "string", "format": "date" }, "passport_issuing_country_code": { "type": "string", "minLength": 2, "maxLength": 2 }, "nationality": { "type": "string", "minLength": 2 } } },
      "CancelRequest": { "type": "object", "required": ["booking_reference", "reason"], "properties": { "booking_reference": { "type": "string" }, "reason": { "type": "string", "minLength": 1 } } },
      "IataAirport": { "type": "string", "pattern": "^[A-Z]{3}$", "example": "DEL" },
      "Supplier": { "type": "string", "default": "all", "description": "Optional Idea Holiday search routing preference. Omit this field or use all for the standard search." }
    }
  }
}