openapi-directory
Version:
Building & bundling https://github.com/APIs-guru/openapi-directory for easy use from JS
1 lines • 219 kB
JSON
{"openapi":"3.0.0","servers":[{"description":"Hotel Booking API Sandbox","url":"https://sandbox.impala.travel/v1"},{"description":"Hotel Booking API Production","url":"https://api.impala.travel/v1"}],"info":{"contact":{"email":"support@impala.travel","name":"Impala Developer Support","url":"https://docs.impala.travel/"},"description":"Add room selling to your app with ease, or expand your existing hotel portfolio. Access all the marketing material you need to sell a room, from hotel amenities to images. Constantly updated, ever expanding and always correct. Impala allows you to start selling hotel rooms and earn a commission with every booking in hours.\n\nGetting started is easy:\n\n> **1. Sign-up within seconds**: Head to the [Impala website](https://impala.travel), enter your details and receive your sandbox API key immediately (no credit card needed).\n\n> **2. Start building within minutes**: Build against a sandbox API with realistic test data. Use a [step-by-step walkthrough](https://impala.travel) to see what's possible. Check for available hotels and their rates. Make and manage fake bookings without any risk. Add room booking to your existing website or app, or start an online travel agency from scratch. [](https://god.gw.postman.com/run-collection/11303451-9b241872-9961-424d-9ef4-9d949534567d?action=collection%2Ffork&collection-url=entityId%3D11303451-9b241872-9961-424d-9ef4-9d949534567d%26entityType%3Dcollection%26workspaceId%3D5ae55f12-332c-4e7d-8acc-3e75df3b2ee2)\n\n> **3. Go live within hours**: Once your app or integration is ready for prime time, move to production within your Impala dashboard and start making real hotel bookings for your customers right away.\n\nWant to see how it all works? Watch [a 5-minute walkthrough](https://www.youtube.com/watch?v=7B3evCL3nrY) of the two API requests you need to make a booking, and a demo of one of our customer's apps.","termsOfService":"https://impala.travel/terms-and-conditions/","title":"Impala Hotel Booking API","version":"1.003","x-apisguru-categories":["ecommerce"],"x-logo":{"url":"https://images.prismic.io/impala-v2/8d1fd8ad-ef74-46e6-99b8-a8dca8265c60_IM_LI_POST_LAUNCH.jpg"},"x-origin":[{"format":"openapi","url":"https://docs.impala.travel/api/v1/projects/impala/booking-api/nodes/spec/openapi.seller.yaml?branch=v1.003","version":"3.0"}],"x-providerName":"impala.travel","x-serviceName":"hotels"},"security":[{"API_Key_Authentication":[]}],"tags":[{"description":"Accessing hotel content, available rooms and rates.","name":"Hotels"},{"description":"Making and managing bookings.","name":"Bookings"},{"description":"Accessing deals you agreed with hotels for discounts and seller commission.","name":"Deals"},{"description":"Getting rates for future dates.","name":"Rate Calendar"},{"description":"Making and managing payments.","name":"Payments"}],"paths":{"/bookings":{"get":{"description":"Returns a list of all the bookings you've made.\n\nYou can filter the list based on when bookings were created or last updated, as well as their arrival (`start`) and departure (`end`). These date-based filters allow to narrow down the result with modifiers for less than (`lt`), greater than (`gt`), lower than or equal to (`lte`), greater than or equal to (`gte`) and equal to (`eq`).\n\nExample: Adding the query parameters `start[gt]=2021-05-20&updated[lte]=2020-11-20T11:11:00.000Z` would return bookings arriving after May 20th, 2020 that were updated before or on November 20th, 2020 at 11:11 am UTC.\n\nYou can specify the **sorting order** in which bookings are returned:\n* This is done by using the `sortBy` query parameter.\n* Results can be sorted by `createdAt` and `updatedAt`\n* The parameter allows for a comma-separated list of arguments with `:asc` (ascending, the default if no sorting is specified) and `:desc` (descending) modifiers.","operationId":"listBookings","parameters":[{"description":"Allows for filtering based on arrival date of the booking in ISO 8601 format (e.g. `2021-12-01`). Available modifiers include less than (`lt`), greater than (`gt`), lower than or equal to (`lte`), greater than or equal to (`gte`) and equal to (`eq`). Usage example: `?start[lte]=2021-12-20&start[gte]=2021-12-10`","example":{"eq":"2025-04-15T13:51:49.993Z","gt":"2025-04-15T13:51:49.993Z","gte":"2025-04-15T13:51:49.993Z","lt":"2025-04-15T13:51:49.993Z","lte":"2025-04-15T13:51:49.993Z"},"explode":true,"in":"query","name":"start","schema":{"type":"object"},"style":"deepObject"},{"description":"Allows for filtering based on departure date of the booking in ISO 8601 format (e.g. `2021-12-01`). Available modifiers include less than (`lt`), greater than (`gt`), lower than or equal to (`lte`), greater than or equal to (`gte`) and equal to (`eq`). Usage example: `?end[lte]=2021-12-25&end[gte]=2021-12-15`","example":{"eq":"2025-04-15T13:51:49.993Z","gt":"2025-04-15T13:51:49.993Z","gte":"2025-04-15T13:51:49.993Z","lt":"2025-04-15T13:51:49.993Z","lte":"2025-04-15T13:51:49.993Z"},"explode":true,"in":"query","name":"end","schema":{"type":"object"},"style":"deepObject"},{"description":"Allows for filtering based on creation date and time of the booking in ISO 8601 format (e.g. `2020-11-04T17:37:37Z`) and UTC timezone. Available modifiers include less than (`lt`), greater than (`gt`), lower than or equal to (`lte`), greater than or equal to (`gte`) and equal to (`eq`). Usage example: `?created[lte]=2020-11-04T19:37:37Z&created[gte]=2020-11-04T15:56:37.000Z`","example":{"eq":"2025-04-15T13:51:49.993Z","gt":"2025-04-15T13:51:49.993Z","gte":"2025-04-15T13:51:49.993Z","lt":"2025-04-15T13:51:49.993Z","lte":"2025-04-15T13:51:49.993Z"},"explode":true,"in":"query","name":"created","schema":{"type":"object"},"style":"deepObject"},{"description":"Allows for filtering based on the date and time the booking was last updated, in ISO 8601 format (e.g. `2020-11-04T17:37:37Z`) and UTC timezone. Available modifiers include less than (`lt`), greater than (`gt`), lower than or equal to (`lte`), greater than or equal to (`gte`) and equal to (`eq`). Usage example: `?updated[lte]=2020-11-04T19:37:37Z&updated[gte]=2020-11-04T15:56:37.000Z`","example":{"eq":"2025-04-15T13:51:49.993Z","gt":"2025-04-15T13:51:49.993Z","gte":"2025-04-15T13:51:49.993Z","lt":"2025-04-15T13:51:49.993Z","lte":"2025-04-15T13:51:49.993Z"},"explode":true,"in":"query","name":"updated","schema":{"type":"object"},"style":"deepObject"},{"description":"Pagination size. Defaults to 100 if omitted.","in":"query","name":"size","schema":{"default":100,"format":"int32","type":"number"}},{"description":"Pagination offset. Defaults to 0 if omitted.","in":"query","name":"offset","schema":{"default":0,"format":"int32","type":"number"}},{"description":"Order in which the results should be sorted. Currently allows you to sort by `createdAt` and `updatedAt`. Specify multiple paramaters by separating with commas","in":"query","name":"sortBy","schema":{"default":"createdAt:asc","example":"createdAt:desc,updatedAt:asc","type":"string"}}],"responses":{"200":{"content":{"application/json":{"examples":{"List of bookings":{"value":{"data":[{"bookedRooms":[{"adults":1,"cancellationPolicies":[{"end":"2025-04-15T13:51:49.993Z","fee":{"count":100,"price":{"amount":9500,"currency":{"code":"EUR"}},"type":"PERCENTAGE"},"formatted":"Non-refundable after October 19, 2021 00:00","start":"2025-04-15T13:51:49.993Z"}],"notes":{"fromGuest":"Please add an extra bed to this room","fromSeller":""},"rate":{"cancellationPolicies":[{"end":"2025-04-15T13:51:49.993Z","fee":{"count":100,"price":{"amount":9500,"currency":{"code":"EUR"}},"type":"PERCENTAGE"},"formatted":"Non-refundable after October 19, 2021 00:00","start":"2025-04-15T13:51:49.993Z"}],"components":[{"formatted":"Breakfast","includedInRate":true,"type":"BREAKFAST"}],"end":"2025-04-15T13:51:49.993Z","hotelAgreement":null,"maxOccupancy":2,"rateId":"i8fIZ277SPDq4UohuxAft5Sr29UhMvyc0VypRxLiRFLoTk0XHmEbgSQ","retailRate":{"taxesAndFees":{"includedInRate":[{"category":"VAT","charge":{"amount":9500,"currency":{"code":"EUR"}},"formatted":"10% VAT"}],"payAtHotel":[{"category":"VAT","charge":{"amount":9500,"currency":{"code":"EUR"}},"formatted":"10% VAT"}]},"total":{"amount":9500,"currency":{"code":"EUR"}}},"sellerCommissionPercentage":9.5,"start":"2025-04-15T13:51:49.993Z"},"roomType":{"name":"Penthouse Suite","roomTypeId":"d5b192ce-c45f-46da-abf5-3880b429b7cc"},"sellerToImpalaPayment":{"amount":9500,"currency":{"code":"EUR"}}}],"bookingId":"IM-0199-00000103","cancellation":{"fee":{"count":100,"price":{"amount":9500,"currency":{"code":"EUR"}},"type":"PERCENTAGE"}},"contact":{"contactId":"3c8aa2ff-5e5e-4f23-bcfc-9036ba818a84","email":"jocelin.carreon.crespo@example.com","firstName":"Jocelín","lastName":"Carreón Sample"},"createdAt":"2025-04-15T13:51:49.993Z","end":"2025-04-15T13:51:49.993Z","hotel":{"address":{"city":"Impalaland","country":"GBR","countryName":"United Kingdom","line1":"12 Sample Avenue","line2":"string","postalCode":"12345","region":"string"},"hotelId":"60a06628-2c71-44bf-9685-efbd2df4179e","href":"/v1/hotels/60a06628-2c71-44bf-9685-efbd2df4179e","images":[{"altText":"A photo of an object","height":4000,"url":"https://cdn.impala.travel/ckhlsuxbb000b3b666rr9ussq.jpg","width":4000}],"location":{"latitude":58.386186,"longitude":-9.952549},"name":"Impala Minimalist Palace","starRating":2.5},"hotelConfirmationCode":"04M3995","notes":{"fromGuest":"I am travelling with my family","fromSeller":""},"start":"2025-04-15T13:51:49.993Z","status":"ACCEPTED","updatedAt":"2025-04-15T13:51:49.993Z"}],"pagination":{"count":10,"next":"/v1/hotels?size=20&offset=120","prev":"/v1/hotels?size=20&offset=80","total":1500}}}},"schema":{"properties":{"data":{"items":{"$ref":"#/components/schemas/booking"},"type":"array"},"pagination":{"$ref":"#/components/schemas/pagination"}},"required":["data","pagination"],"type":"object"}}},"description":"Returns a paginated list of bookings (filtered based on your query parameters)."},"400":{"content":{"application/json":{"examples":{"Validation error":{"summary":"Bad request","value":{"code":"VALIDATION_ERROR","message":"\"start\" must be in YYYY-MM-DD format. \"foo\" is not allowed. \"lorem\" missing required peer \"ipsum\"","validations":[{"code":"DATE_FORMAT","message":"\"start\" must be in YYYY-MM-DD format","property":"start"},{"code":"OBJECT_UNKNOWN","message":"\"foo\" is not allowed","property":"foo"},{"code":"OBJECT_WITH","message":"\"lorem\" missing required peer \"ipsum\"","property":"lorem"}]}}},"schema":{"$ref":"#/components/schemas/validationError"}}},"description":"Your request wasn't formatted correctly and therefore couldn't be processed. This most frequently happens when query parameters or request body values are missing, incorrectly formatted or added where they don't exist (e.g. due to typos). We're including a list of `validations` to point out where things are going wrong and should be fixed."},"401":{"content":{"application/json":{"examples":{"API key invalid":{"value":{"message":"Invalid authentication credentials"}},"API key missing":{"value":{"message":"No API key found in request"}}},"schema":{"$ref":"#/components/schemas/genericError"}}},"description":"Your request was sent without or with an incorrect API key. This most frequently happens when the `x-api-key` header wasn't added or contains an incorrect value. This might also happen if you're trying to access the production API endpoints with a sandbox API key or vice versa."},"500":{"content":{"application/json":{"examples":{"Internal Server Error":{"summary":"Server has encountered an internal error.","value":{"message":"Internal Server Error"}}},"schema":{"$ref":"#/components/schemas/genericError"}}},"description":"An internal server error within the Impala platform has occurred. Our team will investigate the error.\nWe recommend that you contact us at support@impala.travel with the x-correlation-id value contained\nwithin the response headers. Sending us this value will allow us to identify the precise error you encountered."}},"summary":"List all bookings","tags":["Bookings"]},"post":{"description":"Creates a booking for for the rate and dates you specify in the request body.\n\nYou'll need a `roomTypes[].rates[].rateId` that's bookable for those dates, which you can find using the [Retrieve a hotel](https://docs.impala.travel/docs/booking-api/spec/openapi.seller.yaml/paths/~1hotels~1%7BhotelId%7D/get) endpoint.\n\nIf you have provided a credit card on the dashboard then **Impala will send the booking to the hotel immediately**. We'll ensure payment is taken care of before your guest arrives at the hotel.\n\n* Your guest needs to be **paying you** the rate specified in `retailRate` (as listed in the [Retrieve a hotel](https://docs.impala.travel/docs/booking-api/spec/openapi.seller.yaml/paths/~1hotels~1%7BhotelId%7D/get) response) before you submit this request.\n* Once your request is received and the booking is confirmed, **Impala will charge you** as the seller this `retailRate` minus the `sellerCommissionPercentage` (which is the affiliate commission you get to keep). We'll use the business credit card you've added to your account as payment method for this.\n* The difference between the amount you charge your guest (`retailRate`, e.g. 200 €) and what Impala charges you (`retailRate` minus `sellerCommissionPercentage`, e.g. 200 €) is your commission (in this example: 20 €) to keep.\n\nYou can find more information on how money flows between your guest and you, and you and Impala, [in this article](https://impala.stoplight.io/docs/booking-api/branches/v1.003/docs/good-to-know/payments-and-commissions.md)\n\n<!-- theme: warning -->\n\n> **This request might take up to 20 seconds to load.** While we work to return a response to your request within milliseconds in most cases, some bookings require us to re-verify current pricing in real-time and doing so might take up to 20 seconds. Please make sure your app handles this waiting state appropriately.","operationId":"createBooking","requestBody":{"content":{"application/json":{"examples":{"example-1":{"value":{"bookingContact":{"email":"jocelin.carreon.crespo@example.com","firstName":"Jocelín","lastName":"Carreón Sample"},"end":"2025-04-15T13:51:49.993Z","rooms":[{"adults":2,"rateId":"i8fIZ277SPDq4UohuxAft5Sr29UhMvyc0VypRxLiRFLoTk0XHmEbgSQ"}],"start":"2025-04-15T13:51:49.993Z"}}},"schema":{"$ref":"#/components/schemas/bookingRequest"}}},"description":"Specifies the room you want to book for your guest."},"responses":{"202":{"content":{"application/json":{"examples":{"Booking created (paid via guest)":{"$ref":"#/components/examples/BookingCreatedExampleWithPaymentBearerToken"},"Booking created (paid via you)":{"$ref":"#/components/examples/BookingCreatedExample"}},"schema":{"$ref":"#/components/schemas/booking"}}},"description":"We've created the booking and are returning some of its details in the response body."},"400":{"content":{"application/json":{"examples":{"Incorrect date range":{"value":{"code":"BAD_REQUEST","message":"There must be rate for each different day of the stay."}},"Invalid rate ID":{"value":{"code":"BAD_REQUEST","message":"Incorrect rate id provided. 47vP4lpKjW1giRX3ns6PSfoDwhccLqdzvRdMNNmCiaGaWK1DuFUm2qDvq is not a valid rate id"}},"No remaining allocations":{"value":{"code":"BAD_REQUEST","message":"No allocations remaining for dealId 'D123456'"}},"Room can't accommodate occupancy":{"value":{"code":"BAD_REQUEST","message":"The requested guest count exceeds the maximum occupancy for one or more rooms"}},"Validation error":{"summary":"Bad request","value":{"code":"VALIDATION_ERROR","message":"\"start\" must be in YYYY-MM-DD format. \"foo\" is not allowed. \"lorem\" missing required peer \"ipsum\"","validations":[{"code":"DATE_FORMAT","message":"\"start\" must be in YYYY-MM-DD format","property":"start"},{"code":"OBJECT_UNKNOWN","message":"\"foo\" is not allowed","property":"foo"},{"code":"OBJECT_WITH","message":"\"lorem\" missing required peer \"ipsum\"","property":"lorem"}]}}},"schema":{"$ref":"#/components/schemas/validationError"}}},"description":"Your request wasn't formatted correctly and therefore couldn't be processed. This most frequently happens when query parameters or request body values are missing, incorrectly formatted or added where they don't exist (e.g. due to typos). We're including a list of `validations` to point out where things are going wrong and should be fixed. "},"401":{"content":{"application/json":{"examples":{"API key invalid":{"value":{"message":"Invalid authentication credentials"}},"API key missing":{"value":{"message":"No API key found in request"}}},"schema":{"$ref":"#/components/schemas/genericError"}}},"description":"Your request was sent without or with an incorrect API key. This most frequently happens when the `x-api-key` header wasn't added or contains an incorrect value. This might also happen if you're trying to access the production API endpoints with a sandbox API key or vice versa."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/genericError"}}},"description":"You are not authorized to use this service. Please contact support@impala.travel to gain access."},"500":{"content":{"application/json":{"examples":{"Internal Server Error":{"summary":"Server has encountered an internal error.","value":{"message":"Internal Server Error"}}},"schema":{"$ref":"#/components/schemas/genericError"}}},"description":"An internal server error within the Impala platform has occurred. Our team will investigate the error.\nWe recommend that you contact us at support@impala.travel with the x-correlation-id value contained\nwithin the response headers. Sending us this value will allow us to identify the precise error you encountered."}},"summary":"Create a booking","tags":["Bookings"]}},"/bookings/{bookingId}":{"delete":{"description":"<!-- theme: danger -->\n\n> Cancels the specified booking with immediate effect. This action might result in a cancellation charge being charged.\n\nSubmitting this request means we'll notify the hotel of the cancellation and that they won't expect your guest.\n\nYou can use `GET /bookings/{bookingId}`to see the cancellation policies that apply to a booking at a given point in time. Please note that cancelling a booking will incur a cancellation fee according to the rules that apply at the time of cancellation. You can find the cancellation fee that has been charged in the response of this call in the `cancellation.fee` object.\n\nIf the booking you cancelled allows for a partial or full refund, we'll credit your Impala balance with the amount we charged you as the seller of this booking – meaning we'll deduct the amount the next time we're requesting payment for the sum of all the bookings you made.","operationId":"cancelBooking","parameters":[{"$ref":"#/components/parameters/bookingIdParam"}],"responses":{"200":{"content":{"application/json":{"examples":{"Cancelled booking":{"$ref":"#/components/examples/CancelledBooking"}},"schema":{"$ref":"#/components/schemas/booking"}}},"description":"Returns the cancelled booking. This includes the `cancellation.fee` object with details on the fee for this cancellation (most frequently this means either a zero fee, so the booking is fully refundable, or the full amount of the stay is due as a fee, meaning the booking was non-refundable)."},"400":{"content":{"application/json":{"examples":{"Validation error":{"summary":"Bad request","value":{"code":"VALIDATION_ERROR","message":"\"start\" must be in YYYY-MM-DD format. \"foo\" is not allowed. \"lorem\" missing required peer \"ipsum\"","validations":[{"code":"DATE_FORMAT","message":"\"start\" must be in YYYY-MM-DD format","property":"start"},{"code":"OBJECT_UNKNOWN","message":"\"foo\" is not allowed","property":"foo"},{"code":"OBJECT_WITH","message":"\"lorem\" missing required peer \"ipsum\"","property":"lorem"}]}}},"schema":{"$ref":"#/components/schemas/validationError"}}},"description":"Your request wasn't formatted correctly and therefore couldn't be processed. This most frequently happens when query parameters or request body values are missing, incorrectly formatted or added where they don't exist (e.g. due to typos). We're including a list of `validations` to point out where things are going wrong and should be fixed."},"401":{"content":{"application/json":{"examples":{"API key invalid":{"value":{"message":"Invalid authentication credentials"}},"API key missing":{"value":{"message":"No API key found in request"}}},"schema":{"$ref":"#/components/schemas/genericError"}}},"description":"Your request was sent without or with an incorrect API key. This most frequently happens when the `x-api-key` header wasn't added or contains an incorrect value. This might also happen if you're trying to access the production API endpoints with a sandbox API key or vice versa."},"403":{"content":{"application/json":{"examples":{"Booking started in the past":{"summary":"No access","value":{"code":"FORBIDDEN","message":"The booking's arrival date is in the past"}}},"schema":{"$ref":"#/components/schemas/genericError"}}},"description":"This booking can't be cancelled. This most frequently happens when you're trying to cancel a booking that has already started. Impala allows you to handle booking management up to a guest's arrival. Once the guest is staying or due arrival, please contact the hotel directly for questions around their current stay."},"404":{"content":{"application/json":{"examples":{"Booking not found":{"summary":"Not found","value":{"code":"NOT_FOUND","message":"Cannot find booking"}}},"schema":{"$ref":"#/components/schemas/genericError"}}},"description":"Not found"},"500":{"content":{"application/json":{"examples":{"Internal Server Error":{"summary":"Server has encountered an internal error.","value":{"message":"Internal Server Error"}}},"schema":{"$ref":"#/components/schemas/genericError"}}},"description":"An internal server error within the Impala platform has occurred. Our team will investigate the error.\nWe recommend that you contact us at support@impala.travel with the x-correlation-id value contained\nwithin the response headers. Sending us this value will allow us to identify the precise error you encountered."}},"summary":"Cancel a booking","tags":["Bookings"]},"get":{"description":"Returns all details for the specified booking.","operationId":"retrieveBooking","parameters":[{"$ref":"#/components/parameters/bookingIdParam"}],"responses":{"200":{"content":{"application/json":{"examples":{"Confirmed booking":{"$ref":"#/components/examples/BookingCreatedExample"}},"schema":{"$ref":"#/components/schemas/booking"}}},"description":"Returns the requested booking."},"400":{"content":{"application/json":{"examples":{"Validation error":{"summary":"Bad request","value":{"code":"VALIDATION_ERROR","message":"\"start\" must be in YYYY-MM-DD format. \"foo\" is not allowed. \"lorem\" missing required peer \"ipsum\"","validations":[{"code":"DATE_FORMAT","message":"\"start\" must be in YYYY-MM-DD format","property":"start"},{"code":"OBJECT_UNKNOWN","message":"\"foo\" is not allowed","property":"foo"},{"code":"OBJECT_WITH","message":"\"lorem\" missing required peer \"ipsum\"","property":"lorem"}]}}},"schema":{"$ref":"#/components/schemas/validationError"}}},"description":"Your request wasn't formatted correctly and therefore couldn't be processed. This most frequently happens when query parameters or request body values are missing, incorrectly formatted or added where they don't exist (e.g. due to typos). We're including a list of `validations` to point out where things are going wrong and should be fixed."},"401":{"content":{"application/json":{"examples":{"API key invalid":{"value":{"message":"Invalid authentication credentials"}},"API key missing":{"value":{"message":"No API key found in request"}}},"schema":{"$ref":"#/components/schemas/genericError"}}},"description":"Your request was sent without or with an incorrect API key. This most frequently happens when the `x-api-key` header wasn't added or contains an incorrect value. This might also happen if you're trying to access the production API endpoints with a sandbox API key or vice versa."},"404":{"content":{"application/json":{"examples":{"Booking not found":{"summary":"Not found","value":{"code":"NOT_FOUND","message":"Cannot find booking with reference IM-0576-00000000"}}},"schema":{"$ref":"#/components/schemas/genericError"}}},"description":"You've likely requested a booking that doesn't exist. This might be because of a typo in the booking ID. Impala booking IDs start with `IM-` for real-life bookings and `SANDBOX-` for all bookings created in our sandbox environment (e.g. `/bookings/IM-0576-00000601`)."},"500":{"content":{"application/json":{"examples":{"Internal Server Error":{"summary":"Server has encountered an internal error.","value":{"message":"Internal Server Error"}}},"schema":{"$ref":"#/components/schemas/genericError"}}},"description":"An internal server error within the Impala platform has occurred. Our team will investigate the error.\nWe recommend that you contact us at support@impala.travel with the x-correlation-id value contained\nwithin the response headers. Sending us this value will allow us to identify the precise error you encountered."}},"summary":"Retrieve a booking","tags":["Bookings"]},"put":{"description":"<!-- theme: danger -->\n\n> Updates the specified booking with immediate effect. This action might result in a cancellation charge being charged.\n\n> Please note that if you wish to change the contact details associated with a booking, you should use the [Change a Booking's Contact Details](https://docs.impala.travel/docs/booking-api/spec/openapi.seller.yaml/paths/~1bookings~1%7BbookingId%7D~1booking-contact/put) endpoint.\n\nChanges / updates a confirmed booking with the details you provide in the request body.\n\nWhen your guest needs to change their booking, you can use this endpoint to change any of the details you initially supplied when you [made their booking](https://docs.impala.travel/docs/booking-api/spec/openapi.seller.yaml/paths/~1bookings/post), e.g. you'll need to query for availability and use the `roomTypes[].rates[].rateId` that are available currently for their new stay dates. Any new rates selected must be for the same hotel as the original booking.\n\nA booking cannot be updated on or after the check in day of the original or new stay.\n\nIn addition, we require you do supply a `updateBookingVersionAtTimestamp` field with the `updatedAt` timestamp of the booking. You can find this value by looking up the booking via the [Retrieve a booking](https://docs.impala.travel/docs/booking-api/spec/openapi.seller.yaml/paths/~1bookings~1%7BbookingId%7D/get) endpoint. This is to avoid race conditions where another update might have happened since the last time you have checked for the current details of this booking.\n\nThe `status` of this booking will switch back to `PENDING` until we have submitted and confirmed the new details with the hotel.\n\n<!-- theme: warning -->\n\n> **This request might take up to 20 seconds to load.** While we work to return a response to your request within milliseconds in most cases, some bookings require us to re-verify current pricing in real-time and doing so might take up to 20 seconds. Please make sure your app handles this waiting state appropriately.","operationId":"updateBooking","parameters":[{"$ref":"#/components/parameters/bookingIdParam"}],"requestBody":{"content":{"application/json":{"examples":{"Example":{"value":{"bookingContact":{"email":"jocelin.carreon.crespo@example.com","firstName":"Jocelín","lastName":"Carreón Sample"},"end":"2025-04-15T13:51:49.993Z","rooms":[{"adults":2,"rateId":"i8fIZ277SPDq4UohuxAft5Sr29UhMvyc0VypRxLiRFLoTk0XHmEbgSQ"}],"start":"2025-04-15T13:51:49.993Z","updateBookingVersionAtTimestamp":"2025-04-15T13:51:49.993Z"}}},"schema":{"$ref":"#/components/schemas/updateBookingRequest"}}},"description":"Specifies the room you want to book for your guest."},"responses":{"200":{"content":{"application/json":{"examples":{"Booking created":{"$ref":"#/components/examples/BookingCreatedExample"}},"schema":{"$ref":"#/components/schemas/booking"}}},"description":"We've submitted the change to the hotel and are returning some of its details in the response body."},"400":{"content":{"application/json":{"examples":{"Incorrect date range":{"value":{"code":"BAD_REQUEST","message":"There must be rate for each different day of the stay."}},"Invalid rate ID":{"value":{"code":"BAD_REQUEST","message":"Incorrect rate id provided. 47vP4lpKjW1giRX3ns6PSfoDwhccLqdzvRdMNNmCiaGaWK1DuFUm2qDvq is not a valid rate id"}},"Requires guest payment":{"value":{"code":"BAD_REQUEST","message":"Cannot change a booking requires guest payment"}},"Room can't accommodate occupancy":{"value":{"code":"BAD_REQUEST","message":"The requested guest count exceeds the maximum occupancy for one or more rooms"}},"Validation error":{"summary":"Bad request","value":{"code":"VALIDATION_ERROR","message":"\"start\" must be in YYYY-MM-DD format. \"foo\" is not allowed. \"lorem\" missing required peer \"ipsum\"","validations":[{"code":"DATE_FORMAT","message":"\"start\" must be in YYYY-MM-DD format","property":"start"},{"code":"OBJECT_UNKNOWN","message":"\"foo\" is not allowed","property":"foo"},{"code":"OBJECT_WITH","message":"\"lorem\" missing required peer \"ipsum\"","property":"lorem"}]}}},"schema":{"$ref":"#/components/schemas/validationError"}}},"description":"Your request was invalid or wasn't formatted correctly and therefore couldn't be processed. This most frequently happens when query parameters or request body values are missing, incorrectly formatted or added where they don't exist (e.g. due to typos). We're including a list of `validations` to point out where things are going wrong and should be fixed. "},"401":{"content":{"application/json":{"examples":{"API key invalid":{"value":{"message":"Invalid authentication credentials"}},"API key missing":{"value":{"message":"No API key found in request"}}},"schema":{"$ref":"#/components/schemas/genericError"}}},"description":"Your request was sent without or with an incorrect API key. This most frequently happens when the `x-api-key` header wasn't added or contains an incorrect value. This might also happen if you're trying to access the production API endpoints with a sandbox API key or vice versa."},"404":{"content":{"application/json":{"examples":{"Booking not found":{"summary":"Not found","value":{"code":"NOT_FOUND","message":"Cannot find booking"}}},"schema":{"$ref":"#/components/schemas/genericError"}}},"description":"Not found"},"500":{"content":{"application/json":{"examples":{"Internal Server Error":{"summary":"Server has encountered an internal error.","value":{"message":"Internal Server Error"}}},"schema":{"$ref":"#/components/schemas/genericError"}}},"description":"An internal server error within the Impala platform has occurred. Our team will investigate the error.\nWe recommend that you contact us at support@impala.travel with the x-correlation-id value contained\nwithin the response headers. Sending us this value will allow us to identify the precise error you encountered."}},"summary":"Change a booking","tags":["Bookings"]}},"/bookings/{bookingId}/booking-contact":{"put":{"description":"Updates a confirmed booking with the booking contact details you provide in the request body.\n\nIn addition, we require you to supply a `updateBookingVersionAtTimestamp` field with the `updatedAt` timestamp of the booking. You can find this value by looking up the booking via the [Retrieve a booking](https://docs.impala.travel/docs/booking-api/spec/openapi.seller.yaml/paths/~1bookings~1%7BbookingId%7D/get) endpoint. This is to avoid race conditions where another update might have happened since the last time you have checked for the current details of this booking.","operationId":"updateBookingContact","parameters":[{"$ref":"#/components/parameters/bookingIdParam"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/updateBookingContactRequest"}}}},"responses":{"200":{"content":{"application/json":{"examples":{"Booking created":{"$ref":"#/components/examples/BookingCreatedExample"}},"schema":{"$ref":"#/components/schemas/booking"}}},"description":"We've submitted the change to the hotel and are returning the booking details in the response body."},"400":{"content":{"application/json":{"examples":{"Validation error":{"summary":"Bad request","value":{"code":"VALIDATION_ERROR","message":"\"start\" must be in YYYY-MM-DD format. \"foo\" is not allowed. \"lorem\" missing required peer \"ipsum\"","validations":[{"code":"OBJECT_UNKNOWN","message":"\"foo\" is not allowed","property":"foo"},{"code":"OBJECT_WITH","message":"\"lorem\" missing required peer \"ipsum\"","property":"lorem"}]}}},"schema":{"$ref":"#/components/schemas/validationError"}}},"description":"Your request was invalid or wasn't formatted correctly and therefore couldn't be processed. This most frequently happens when query parameters or request body values are missing, incorrectly formatted or added where they don't exist (e.g. due to typos). We're including a list of `validations` to point out where things are going wrong and should be fixed. "},"401":{"content":{"application/json":{"examples":{"API key invalid":{"value":{"message":"Invalid authentication credentials"}},"API key missing":{"value":{"message":"No API key found in request"}}},"schema":{"$ref":"#/components/schemas/genericError"}}},"description":"Your request was sent without or with an incorrect API key. This most frequently happens when the `x-api-key` header wasn't added or contains an incorrect value. This might also happen if you're trying to access the production API endpoints with a sandbox API key or vice versa."},"404":{"content":{"application/json":{"examples":{"Booking not found":{"summary":"Not found","value":{"code":"NOT_FOUND","message":"Cannot find booking"}}},"schema":{"$ref":"#/components/schemas/genericError"}}},"description":"Not found"},"500":{"content":{"application/json":{"examples":{"Internal Server Error":{"summary":"Server has encountered an internal error.","value":{"message":"Internal Server Error"}}},"schema":{"$ref":"#/components/schemas/genericError"}}},"description":"An internal server error within the Impala platform has occurred. Our team will investigate the error.\nWe recommend that you contact us at support@impala.travel with the x-correlation-id value contained\nwithin the response headers. Sending us this value will allow us to identify the precise error you encountered."}},"summary":"Change a booking contact","tags":["Bookings"]}},"/hotels":{"get":{"description":"Returns a list of all hotels worldwide that can be booked through Impala.\n\nYou can **filter** the results:\n\n* Adding `longitude`, `latitude` and a `radius` (in meters) query parameters will filter the results to hotels around this location.\n* Adding `start` and `end` dates (in ISO 8601 notation, e.g. `2021-12-31`) for the expected arrival and departure dates of your guests will limit the results to hotels that have at least one room bookable for this timeframe.\n* Adding `starRating`, `name` or `country` allows you to filter to hotels based on these values (e.g. `?starRating[gte]=4&name[like]=palace` for hotels with a rating of 4 or up with a name containing \"palace\")\n* Adding `hotelIds` allows you to limit the results to include only hotels with the ids listed. Its value should be a comma-separated list of hotel ids (e.g. `?hotelIds[]=hotelIdA,hotelIdB`)\n\n* Adding `contractable` allows you to filter to hotels that you can directly negotiate with through our [deals feature](https://docs.impala.travel/docs/booking-api/ZG9jOjcyNjgzMTA-contracting-with-hotels). (e.g `?contractable=true` or `?contractable=false`)\n\nYou can specify the **sorting order** in which hotels are returned:\n* This is done by using the `sortBy` query parameter.\n* Results can be sorted by `name` alphabetically, star `rating` and `distance_m` (in meters from the specified latitude/longitude location).\n* The parameter allows for a comma-separated list of arguments with optional `:asc` (ascending, the default if the modifier is omitted) and `:desc` (descending) modifiers.\n\nIf no hotels match your filter criteria, an empty array will be returned.","operationId":"listHotels","parameters":[{"description":"Allows for filtering based on the property name. Available modifiers include equal to (`eq`) or case insensitive search (`like`). Usage example: `?name[like]=palace`","example":{"eq":"Minimalist Palace","like":"palace"},"explode":true,"in":"query","name":"name","schema":{"type":"object"},"style":"deepObject"},{"description":"Allows for filtering based on the starRating of a property. Available modifiers include less than (`lt`), greater than (`gt`), less than or equal to (`lte`), greater than or equal to (`gte`) and equal to (`eq`). Usage example: `?starRating[gt]=3&starRating[lt]=5`","example":{"eq":4,"gt":3,"gte":4,"lt":4,"lte":3},"explode":true,"in":"query","name":"starRating","schema":{"type":"object"},"style":"deepObject"},{"description":"Allows for filtering based on the country of a property. The only available modifier for this parameter is equal to (`eq`). Usage example: `?country[eq]=GBR`","example":{"eq":"GBR"},"explode":true,"in":"query","name":"country","schema":{"type":"object"},"style":"deepObject"},{"description":"The arrival day of the desired stay range in ISO 8601 format (`YYYY-MM-DD`).","in":"query","name":"start","schema":{"example":"2025-04-15T13:51:49.993Z","type":"string"}},{"description":"The departure day of the desired stay range in ISO 8601 format (`YYYY-MM-DD`).","in":"query","name":"end","schema":{"example":"2025-04-15T13:51:49.993Z","type":"string"}},{"description":"The WGS 84 latitude of the location to search around (e.g. `58.386186`).","in":"query","name":"latitude","schema":{"example":58.386186,"format":"double","maximum":90,"minimum":-90,"type":"number"}},{"description":"The WGS 84 longitude of the location to search around (e.g. `-9.952549`).","in":"query","name":"longitude","schema":{"example":-9.952549,"format":"double","maximum":180,"minimum":-180,"type":"number"}},{"description":"The distance (in meters) to search around the specified location (e.g. `10000` for 10 km).","in":"query","name":"radius","schema":{"example":25000,"format":"int32","minimum":0,"type":"integer"}},{"description":"A comma-separated list of hotel ids you wish to filter by (e.g. `60a06628-2c71-44bf-9685-efbd2df4179e,60a06628-2c71-44bf-9685-efbd2df4179e`).","explode":false,"in":"query","name":"hotelIds","schema":{"example":["0e25533a-2db2-4894-9db1-4c1ff92d798c,77c272b6-18e6-4036-b9c3-7fc5454e3f6a"],"items":{"example":"8a39290a-bcd0-461e-92c6-38e71a06d2f7","type":"string"},"type":"array"},"style":"form"},{"description":"Allows for filtering based on the date and time when this hotel was first added to the Impala platform, in ISO 8601 format (e.g. `2020-11-04T17:37:37Z`) and UTC timezone. Available modifiers include less than (`lt`), greater than (`gt`), lower than or equal to (`lte`), greater than or equal to (`gte`) and equal to (`eq`). Usage example: `?created[lte]=2020-11-04T19:37:37Z&created[gte]=2020-11-04T15:56:37.000Z`","example":{"eq":"2025-04-15T13:51:49.994Z","gt":"2025-04-15T13:51:49.994Z","gte":"2025-04-15T13:51:49.994Z","lt":"2025-04-15T13:51:49.994Z","lte":"2025-04-15T13:51:49.994Z"},"explode":true,"in":"query","name":"created","schema":{"type":"object"},"style":"deepObject"},{"description":"Allows for filtering based on the date and time the content of this hotel was last updated, in ISO 8601 format (e.g. `2020-11-04T17:37:37Z`) and UTC timezone. Available modifiers include less than (`lt`), greater than (`gt`), lower than or equal to (`lte`), greater than or equal to (`gte`) and equal to (`eq`). Usage example: `?updated[lte]=2020-11-04T19:37:37Z&updated[gte]=2020-11-04T15:56:37.000Z`","example":{"eq":"2025-04-15T13:51:49.994Z","gt":"2025-04-15T13:51:49.994Z","gte":"2025-04-15T13:51:49.994Z","lt":"2025-04-15T13:51:49.994Z","lte":"2025-04-15T13:51:49.994Z"},"explode":true,"in":"query","name":"updated","schema":{"type":"object"},"style":"deepObject"},{"description":"Number of hotels returned on a given page (pagination).","in":"query","name":"size","schema":{"default":25,"example":40,"format":"int32","maximum":300,"minimum":1,"type":"number"}},{"description":"Offset from the first hotel in the result (for pagination).","in":"query","name":"offset","schema":{"default":0,"example":25,"format":"int32","type":"number"}},{"description":"Order in which the results should be sorted. Currently allows you to sort by `name` (alphabetical), star `rating`, and `distance_m` in meters from the specified latitude/longitude. Allows for a comma-separated list of of arguments with modifiers for `:asc` (ascending) and `:desc` (descending) ordering.","in":"query","name":"sortBy","schema":{"default":"createdAt:desc","example":"name:asc,distance_m:desc","type":"string"}}],"responses":{"200":{"content":{"application/json":{"examples":{"List of available hotels":{"$ref":"#/components/examples/ExampleHotels"},"No hotels available":{"$ref":"#/components/examples/NoHotelsAvailable"}},"schema":{"properties":{"data":{"items":{"$ref":"#/components/schemas/hotelFullDetail"},"type":"array"},"pagination":{"$ref":"#/components/schemas/pagination"}},"type":"object"}}},"description":"Returns a paginated list of hotels."},"400":{"content":{"application/json":{"examples":{"Validation error":{"summary":"Bad request","value":{"code":"VALIDATION_ERROR","message":"\"start\" must be in YYYY-MM-DD format. \"foo\" is not allowed. \"lorem\" missing required peer \"ipsum\"","validations":[{"code":"DATE_FORMAT","message":"\"start\" must be in YYYY-MM-DD format","property":"start"},{"code":"OBJECT_UNKNOWN","message":"\"foo\" is not allowed","property":"foo"},{"code":"OBJECT_WITH","message":"\"lorem\" missing required peer \"ipsum\"","property":"lorem"}]}}},"schema":{"$ref":"#/components/schemas/validationError"}}},"description":"Your request wasn't formatted correctly and therefore couldn't be processed. This most frequently happens when query parameters or request body values are missing, incorrectly formatted or added where they don't exist (e.g. due to typos). We're including a list of `validations` to point out where things are going wrong and should be fixed."},"401":{"content":{"application/json":{"examples":{"API key invalid":{"value":{"message":"Invalid authentication credentials"}},"API key missing":{"value":{"message":"No API key found in request"}}},"schema":{"$ref":"#/components/schemas/genericError"}}},"description":"Your request was sent without or with an incorrect API key. This most frequently happens when the `x-api-key` header wasn't added or contains an incorrect value. This might also happen if you're trying to access the production API endpoints with a sandbox API key or vice versa."},"500":{"content":{"application/json":{"examples":{"Internal Server Error":{"summary":"Server has encountered an internal error.","value":{"message":"InternalServerError"}}},"schema":{"$ref":"#/components/schemas/genericError"}}},"description":"An internal server error within the Impala platform has occurred. Our team will investigate the error.\nWe recommend that you contact us at support@impala.travel with the x-correlation-id value contained\nwithin the response headers. Sending us this value will allow us to identify the precise error you encountered."}},"summary":"List all hotels","tags":["Hotels"]}},"/hotels/{hotelId}":{"get":{"description":"Returns the full content, room types and rates for the specified hotel.\n\nWhen querying the hotels API you can query with or without dates. Where querying with dates requires providing valid values for the `start` and `end` parameters. Requests without these values will be considered a query without dates.\n\n**Querying without dates:**\n\nWhen you query without dates, the search result will include all properties that match your request. Including all content that is associated with those properties. However you will find that the `rates` attribute for each room will always be empty.\n\n**Querying with dates:**\n\nWhen you query with dates, the search result will include all properties that match your request, including all content that is associated with those properties. Rooms which do not have available prices for the provided dates will appear with an empty `rates` array.\n\nFor rooms where there are available prices the `rates` array will include both the public rates of the hotel, along with prices that come from deals in which you are participating. This would include private deals which you have negotiated with a hotel, along with Impala deals which you have been verified for.\n\nUsing the `rateId` of any of those rates, you can use the [Create a booking](https://docs.impala.travel/docs/booking-api/spec/openapi.seller.yaml/paths/~1bookings/post) endpoint to make a booking.","operationId":"retrieveHotel","parameters":[{"description":"The unique identifier of this hotel on the Impala platform.","in":"path","name":"hotelId","required":true,"schema":{"format":"uuid","type":"string"}},{"description":"The arrival day of the desired stay range in ISO 8601 format (`YYYY-MM-DD`).","in":"query","name":"start","schema":{"example":"2025-04-15T13:51:49.994Z","type":"string"}},{"description":"The departure day of the desired stay range in ISO 8601 format (`YYYY-MM-DD`).","in":"query","name":"end","schema":{"example":"2025-04-15T13:51:49.994Z","type":"string"}}],"responses":{"200":{"content":{"application/json":{"examples":{"List Single Hotel":{"$ref":"#/components/examples/ExampleHotel"}},"schema":{"$ref":"#/components/schemas/hotelFullDetail"}}},"description":"Returns the requested hotel."},"400":{"content":{"application/json":{"examples":{"Validation error":{"summary":"Bad request","value":{"code":"VALIDATION_ERROR","message":"\"start\" must be in YYYY-MM-DD format. \"foo\" is not allowed. \"lorem\" missing required peer \"ipsum\"","validations":[{"code":"DATE_FORMAT","message":"\"start\" must be in YYYY-MM-DD format","property":"start"},{"code":"OBJECT_UNKNOWN","message":"\"foo\" is not allowed","property":"foo"},{"code":"OBJECT_WITH","message":"\"lorem\" missing required peer \"ipsum\"","property":"lorem"}]}}},"schema":{"$ref":"#/components/schemas/validationError"}}},"description":"Your request wasn't formatted correctly and therefore couldn't be processed. This most frequently happens when query parameters or request body values are missing, incorrectly formatted or added where they don't exist (e.g. due to typos). We're including a list of `validations` to point out where things are going wrong and should be fixed."},"401":{"content":{"application/json":{"examples":{"API key invalid":{"value":{"message":"Invalid authentication credentials"}},"API key missing":{"value":{"message":"No API key found in request"}}},"schema":{"$ref":"#/components/schemas/genericError"}}},"description":"Your request was sent without or with an incorrect API key. This most frequently happens when the `x-api-key` header wasn't added or contains an incorrect value. This might also happen if you're trying to access the production API endpoints with a sandbox API key or vice versa."},"403":{"content":{"application/json":{"examples":{"fail":{"summary":"No access","value":{"message":"Forbidden resource"}}},"schema":{"$ref":"#/components/schemas/genericError"}}},"description":"Forbidden"},"500":{"content":{"application/json":{"examples":{"Internal Server Error":{"summary":"Server has encountered an internal error.","value":{"message":"Internal Server Error"}}},"schema":{"$ref":"#/components/schemas/genericError"}}},"description":"An internal server error within the Impala platform has occurred. Our team will investigate the error.\nWe recommend that you contact us at support@impala.travel with the x-correlation-id value contained\nwithin the response headers. Sending us this value will allow us to identify the precise error you encountered."}},"summary":"Retrieve a hotel","tags":["Hotels"]}},"/hotels/{hotelId}/rate-plans":{"get":{"description":"Returns a list of all rate plans available for you for a hotel.\n\nRate plans are products the hotel is offering. They typically consist of a combination of restrictiveness in case of cancellations or changes, the time they're bookable, minimum or maximum length of stay restrictions (e.g. week-long bookings), included components like breakfast or dinner and/or the conditions under which the room can be sold (e.g. private rates that can only be offered and sold to a closed user group behind login).\n\nExamples of rate plans:\n\n* Non-refundable room rate that includes breakfast\n* Room-only rate with free cancellation up to 14 days before arrival\n\nFor each such rate plan this endpoint returns the room types it's available for, alongside prices for each date and occupancy that can be sold – or the information that the room isn't available (closed) for a certain date.\n\nFor the vast majority of our customers, availability searches using the [List all hotels](https://docs.impala.travel/docs/booking-api/spec/openapi.seller.yaml/paths/~1hotels/get) endpoint are the best choice. It accepts the dates your guest is looking for and provides the rates to display.\n\nThis endpoint can help augment this for two additional use cases:\n\nThis endpoint allows you to query rate prices for all future dates in one go, making it a great choice to feed availability information and prices into your own system or displaying a rate calender to guide your guests to gain an overview of future availability and prices.","operationId":"listRatePlansForHotel","responses