OpenAPI Specification
openapi: 3.0.0
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.
Getting started is easy:
> **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).
> **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)
> **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.
Want 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 Bookings API
version: '1.003'
x-apisguru-categories:
- ecommerce
x-logo:
url: https://api.apis.guru/v2/cache/logo/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
servers:
- description: Hotel Booking API Sandbox
url: https://sandbox.impala.travel/v1
- description: Hotel Booking API Production
url: https://api.impala.travel/v1
security:
- API_Key_Authentication: []
tags:
- description: Making and managing bookings.
name: Bookings
paths:
/bookings:
get:
description: 'Returns a list of all the bookings you''ve made.
You 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`).
Example: 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.
You can specify the **sorting order** in which bookings are returned:
* This is done by using the `sortBy` query parameter.
* Results can be sorted by `createdAt` and `updatedAt`
* 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: '2021-12-20'
gt: '2021-12-20'
gte: '2021-12-20'
lt: '2021-12-20'
lte: '2021-12-20'
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: '2021-12-20'
gt: '2021-12-20'
gte: '2021-12-20'
lt: '2021-12-20'
lte: '2021-12-20'
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: '2020-11-04T15:56:37.000Z'
gt: '2020-11-04T15:56:37.000Z'
gte: '2020-11-04T15:56:37.000Z'
lt: '2020-11-04T15:56:37.000Z'
lte: '2020-11-04T15:56:37.000Z'
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: '2020-11-04T15:56:37.000Z'
gt: '2020-11-04T15:56:37.000Z'
gte: '2020-11-04T15:56:37.000Z'
lt: '2020-11-04T15:56:37.000Z'
lte: '2020-11-04T15:56:37.000Z'
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: '2020-12-17 23:59:59.999'
fee:
count: 100
price:
amount: 9500
currency:
code: EUR
type: PERCENTAGE
formatted: Non-refundable after October 19, 2021 00:00
start: '2020-12-15 23:59:59.999'
notes:
fromGuest: Please add an extra bed to this room
fromSeller: ''
rate:
cancellationPolicies:
- end: '2020-12-17 23:59:59.999'
fee:
count: 100
price:
amount: 9500
currency:
code: EUR
type: PERCENTAGE
formatted: Non-refundable after October 19, 2021 00:00
start: '2020-12-15 23:59:59.999'
components:
- formatted: Breakfast
includedInRate: true
type: BREAKFAST
end: '2021-11-23'
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: '2021-11-20'
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: '2020-10-20T12:38:22Z'
end: '2020-10-24'
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: '2020-10-21'
status: ACCEPTED
updatedAt: '2020-10-22T20:12:33Z'
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.
We recommend that you contact us at support@impala.travel with the x-correlation-id value contained
within 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.
You''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.
If 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.
* 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.
* 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.
* 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.
You 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)
<!-- theme: warning -->
> **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: '2019-08-24'
rooms:
- adults: 2
rateId: i8fIZ277SPDq4UohuxAft5Sr29UhMvyc0VypRxLiRFLoTk0XHmEbgSQ
start: '2019-08-24'
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.
We recommend that you contact us at support@impala.travel with the x-correlation-id value contained
within 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 -->
> Cancels the specified booking with immediate effect. This action might result in a cancellation charge being charged.
Submitting this request means we''ll notify the hotel of the cancellation and that they won''t expect your guest.
You 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.
If 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.
We recommend that you contact us at support@impala.travel with the x-correlation-id value contained
within 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.
We recommend that you contact us at support@impala.travel with the x-correlation-id value contained
within 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 -->
> Updates the specified booking with immediate effect. This action might result in a cancellation charge being charged.
> Please note that if you wish to change the contact details associated with a booking, you should use the [Change a B
# --- truncated at 32 KB (84 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/impala/refs/heads/main/openapi/impala-bookings-api-openapi.yml