openapi: 3.2.0 info: title: ZOE API by Bookit N Go Hotels API version: 1.0.0 license: name: Proprietary description: 'Versioned external API for deterministic ZOE sandbox flight, hotel, trip, and servicing workflows by Bookit N Go. Sandbox booking operations never execute live supplier or payment mutations.' security: - SandboxApiKey: [] tags: - name: Hotels description: Sandbox hotel search, validation, and booking operations paths: /recommendations/hotels: post: operationId: publicRankHotels summary: Deterministically rank hotel offers for a traveler tags: - Hotels description: Read-only hard-filter then weighted ranking. REQUIRED preferences are never traded away; missing fields are UNEVALUABLE. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RecommendationRequest' responses: '200': description: Ranked offers and durable receipt content: application/json: schema: $ref: '#/components/schemas/RecommendationResponse' /hotels/search: post: operationId: publicSearchHotels summary: Search sandbox hotel offers tags: - Hotels requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/HotelSearch' responses: '200': description: Normalized sandbox offers '400': $ref: '#/components/responses/Error' /hotels/{offerId}/revalidate: post: operationId: publicRevalidateHotel summary: Revalidate a sandbox hotel offer tags: - Hotels parameters: - $ref: '#/components/parameters/OfferId' responses: '200': description: Revalidation result '401': $ref: '#/components/responses/Error' /hotels/bookings: post: operationId: publicCreateHotelBooking summary: Create a sandbox hotel booking tags: - Hotels description: Creates a deterministic sandbox booking with durable duplicate protection. parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/HotelBookingInput' responses: '201': description: Sandbox booking created content: application/json: schema: $ref: '#/components/schemas/BookingResponse' '200': description: Idempotent replay '409': $ref: '#/components/responses/Error' /hotels/bookings/{bookingId}: get: operationId: publicGetHotelBooking summary: Retrieve a sandbox hotel booking tags: - Hotels parameters: - $ref: '#/components/parameters/BookingId' responses: '200': description: Sandbox hotel booking content: application/json: schema: $ref: '#/components/schemas/BookingResponse' '404': $ref: '#/components/responses/Error' components: schemas: Contact: type: object required: - email properties: email: type: string format: email phone: type: string countryCallingCode: type: string countryOfResidence: type: string BookingResponse: type: object required: - data properties: data: $ref: '#/components/schemas/Booking' Money: type: object required: - amount - currency properties: amount: type: number minimum: 0 currency: type: string minLength: 3 maxLength: 3 RecommendationResponse: type: object required: - data properties: data: type: object required: - receiptId - kind - results - receipt properties: receiptId: type: string kind: type: string enum: - FLIGHT - HOTEL results: type: array items: type: object required: - offer - score - evidence properties: offer: type: object score: type: number evidence: type: array items: $ref: '#/components/schemas/RecommendationEvidence' receipt: type: object RecommendationEvidence: type: object required: - category - status - strength - weight - freshness properties: preferenceId: type: string category: type: string value: {} status: type: string enum: - MATCHED - NOT_MATCHED - UNEVALUABLE - REQUIRED_VIOLATION strength: type: string enum: - REQUIRED - STRONG - PREFERRED - FLEXIBLE weight: type: number provenance: {} freshness: type: string context: $ref: '#/components/schemas/TravelContext' TravelContext: type: object additionalProperties: false properties: tripPurpose: type: string enum: - BUSINESS - LEISURE - BLEISURE - OTHER geography: type: string minLength: 1 season: type: string minLength: 1 companions: type: string enum: - SOLO - PARTNER - FAMILY - COLLEAGUES - GROUP HotelSearch: type: object required: - destination - checkIn - checkOut - rooms - adults properties: destination: type: string checkIn: type: string format: date checkOut: type: string format: date rooms: type: integer minimum: 1 adults: type: integer minimum: 1 children: type: integer minimum: 0 default: 0 currency: type: string default: CAD nationality: type: string default: CA occupancies: type: array minItems: 1 description: Room-level occupancy. Preserve one item per room and provide one age for each child. items: type: object required: - adults - children - childAges properties: adults: type: integer minimum: 1 children: type: integer minimum: 0 childAges: type: array items: type: integer minimum: 0 maximum: 17 ErrorResponse: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string message: type: string requestId: type: - string - 'null' details: {} Booking: type: object required: - id - type - status - offerId - environment - createdAt properties: id: type: string type: type: string enum: - flight_booking - hotel_booking status: type: string enum: - PENDING - CONFIRMED - FAILED offerId: type: string total: $ref: '#/components/schemas/Money' environment: type: string const: SANDBOX createdAt: type: string format: date-time RecommendationRequest: type: object additionalProperties: false required: - profileId - offerIds properties: profileId: type: string minLength: 1 offerIds: type: array minItems: 1 maxItems: 100 items: type: string context: $ref: '#/components/schemas/TravelContext' HotelBookingInput: type: object required: - offerId - holder - rooms - contact properties: offerId: type: string acceptedTotal: $ref: '#/components/schemas/Money' holder: type: object required: - name - surname properties: name: type: string surname: type: string contact: $ref: '#/components/schemas/Contact' rooms: type: array minItems: 1 items: type: object required: - guests properties: guests: type: array minItems: 1 items: type: object required: - type - name - surname properties: type: type: string enum: - AD - CH name: type: string surname: type: string age: type: integer parameters: OfferId: name: offerId in: path required: true schema: type: string BookingId: name: bookingId in: path required: true schema: type: string IdempotencyKey: name: Idempotency-Key in: header required: true schema: type: string minLength: 8 maxLength: 255 responses: Error: description: Public API error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' securitySchemes: SandboxApiKey: type: http scheme: bearer description: ZOE API sandbox credential (zoe_sandbox_ prefix). X-API-Key is also accepted.