Introduction
Welcome to the Hubwayz API! You can use our API to access Hubwayz’s various API endpoints.
This document is meant for developers with at least some experience in API developments.
For any question, credentials, or request, please contact your account manager at Hubwayz.
Authentication
There are basically 3 different methods you can choose to use for authentication.
- Persistent Authentication - This method is used when you need a session that expires.
To use this method you send a “login” call with the user details, and get the LoginToken in the response.
This token is your session ID and you can send it instead of sending the account/agent/password on each call, and once it expires you simply get a new session code. - One-off Authentication - This method is used when you don’t need a session, and have the login credentials handy. to use it, you simply send the account/agent/password combination on each call.
- Token Based Authentication - This method is used for searching and booking content on Mishor, but can also be used for all other services.
To use this method you simply save a unique login token for each agent/account combination.
Persistent Authentication
The Persistent authentication method is used to establish a “session” and avoid having to send all the authentication details on each call to the API.
The first phase is to send a login call with the specific agent login details, and then used to received token to conduct all other calls.
GET https://example.com/login/agent/
Login
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://example.com/login/agent/",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => array(
"aether-application-key: [app-key]",
"aether-account: [account]",
"aether-agent: [agent]",
"aether-customization: [customization]",
"aether-password: [password]",
"cache-control: no-cache"
),
));
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
curl \
-H "aether-application-key: [app-key]" \
-H "aether-account: [account]" \
-H "aether-agent: [agent]" \
-H "aether-customization: [customization]" \
-H "aether-password: [password]" \
-H "cache-control: no-cache" \
https://example.com/login/agent/
| Header | Mandatory | Description |
|---|---|---|
| aether-application-key | Yes | Your unique application key issued by your account manager |
| aether-account | Yes | The account that is making the request |
| aether-agent | Yes | The agent that is making the request |
| aether-password | Yes | The agent that is making the request |
| aether-customization | No | The whitelabel domain that is making the request. This is used in cases that require some customization like setting logos or emails, etc. |
The login request returns JSON structured like this:
{
"content": {
"LoginToken": "example12345",
"UserName": "example",
"FirstName": "example",
"LastName": "example",
"AccountID": 12345,
"AgentID": 12345,
"Permissions": {
"12345": {
"PermissionID": 12345,
"PermissionValue": "enabled"
}
},
"AccountLoginName": "example",
"AccountCompanyName": "example",
"AccountCurrencies": {
"EUR": {
"IsDefault": 1,
"Currency": "EUR"
},
"USD": {
"IsDefault": 0,
"Currency": "USD"
}
},
"AgentMeta": {
"AgentID": 1
},
"AccountMeta": {
"AccountID": 1
},
"OnAccounts": [
{
"AccessToken": "$6h$14$.gAH439wmRjrwAVXD98HNOgsNpDczlqm3Jq7KnEd1rVAGv3Fykk1a",
"AccountID": 1,
"LoginName": "example",
"CompanyName": "example",
"Type": "test",
"Status": "enabled",
"Market": "EU",
"Country": "DE",
"City": "Berlin",
"Address": "Some street"
}
],
"ProfileVersion": "dcc81048a744a12345a33bf6728550f700"
},
"status": "done"
}
Then, Once you have the LoginToken you can send it instead of the full credentials on each call.
Example of using the LoginToken to authenticate
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "[API endpoint]",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => array(
"aether-application-key: [application-key]",
"aether-customization: [customization]",
"aether-login-token: [login-token]
"cache-control: no-cache"
),
));
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
curl \
-H "aether-application-key: [app-key]" \
-H "aether-customization: [customization]" \
-H "aether-login-token: [login-token]" \
-H "cache-control: no-cache" \
[API endpoint]
Make sure to replace all items in
square brackets []with the requests’ details.
One-off Authentication
These headers must be sent with every call:
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "[API endpoint]",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => array(
"aether-application-key: [app-key]",
"aether-account: [account]",
"aether-agent: [agent]",
"aether-customization: [customization]",
"aether-password: [password]",
"cache-control: no-cache"
),
));
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
curl \
-H "aether-application-key: [app-key]" \
-H "aether-account: [account]" \
-H "aether-agent: [agent]" \
-H "aether-customization: [customization]" \
-H "aether-password: [password]" \
-H "cache-control: no-cache" \
[API endpoint]
Make sure to replace all items in
square brackets []with the requests’ details.
The One-Off authentication method is used in cases you do not want to keep a “session”.
The API expects for all of the above headers to be included in all API requests to the server in a header that looks like the example on the right:
| Header | Mandatory | Description |
|---|---|---|
| aether-application-key | Yes | Your unique application key issued by your account manager |
| aether-account | Yes | The account that is making the request |
| aether-agent | Yes | The agent that is making the request |
| aether-password | Yes | The agent that is making the request |
| aether-customization | No | The whitelabel domain that is making the request. This is used in cases that require some customization like setting logos or emails, etc. |
Token based authentication
The Token authentication method is a combination of the 2 previous methods, and is mainly used for searching and booking content through Mishor. However, you can use this method for all of your authentication needs, it’ll work either way.
curl \
-H "aether-application-key: [app-key]" \
-H "aether-access-token: [account]" \
-H "aether-customization: [customization]" \
-H "cache-control: no-cache" \
[API endpoint]
Make sure to replace all items in
square brackets []with the requests’ details.
The aether-access-token can be retrieved through the login method above, and saved locally for all future use. it will not change until you actively change it through the back-office, although Hubwayz may initiate a rotation of all tokens once every period for security purposes.
Remote login to the Hubwayz UI
In order to perform a silent login from your UI to the Hubwayz UI so that your users will not need to enter their credentials, you can use the following method.
Basically, you need to hold the credentials of your agents or users, and send them to the Hubwayz API.
After we get the data from JSON, we’ll try to login with received credentials. If an attempt fails, we register a new user.
For registration we need all the fields. For login it can be only “email” and “password”. But we recommend sending the whole record each time.
Request
POST https://yourWhitelabelDomain.com/api/remote/login
Remote login request:
{
"firstName": "testName",
"lastName": "testLastName",
"email": "some@email.com",
"phone": "+44 123 456 789"
"password": "test"
}
| Attribute | Description |
|---|---|
| firstName | First name of the agent, required for registration |
| lastName | Last name of the agent, required for registration |
| email of the agent, required always | |
| password | The password of the agent, which is performing the login, required always |
| phone | optional |
Response
Remote login response:
{
"auth_key": "$2y$10$GgE9IqVAt9BhRtjKADliWusRknKj0JlLWUZBAnT/OlQM5M0ykv03q",
"url": "http://{WLURL}?auth_key=$2y$10$GgE9IqVAt9BhRtjKADliWusRknKj0JlLWUZBAnT/OlQM5M0ykv03q"
}
In response you are getting an URL and auth_key. You should redirect your user to this URL:
http://{WLURL}?auth_key=$2y$10$GgE9IqVAt9BhRtjKADliWusRknKj0JlLWUZBAnT/OlQM5M0ykv03q
| Attribute | Description |
|---|---|
| auth_key | should be send to url for authorisation |
| url | the url to send your user’s browser to. |
Errors
There are two kinds of errors that can be received as a response:
You are trying to login with wrong password or register with existing e-mail:
{
"status": "error",
"errorMessage": "Account with the email first@last.email already exists.",
"errorCode": 500
}
Other errors:
{
"status": "error",
"errorMessage": "The operation was unsuccessful [#205].",
"errorCode": 500
}
Aether
Aether is the full fledged back office system that allows management of the bookings, accounting, setting of accounts and agents, and all other entities in the system.
Currency rates
Request
curl \
-H "aether-application-key: [app-key]" \
-H "aether-account: [account]" \
-H "aether-agent: [agent]" \
-H "aether-customization: [customization]" \
-H "aether-password: [password]" \
-H "cache-control: no-cache" \
https://example.com/currency-rates/get/USD,EUR
Response
{
"content": {
"Status": "done",
"Message": [
{
"FromCurrency": "EUR",
"ToCurrency": "USD",
"Rate": 1.24607
},
{
"FromCurrency": "USD",
"ToCurrency": "EUR",
"Rate": 0.802523
}
],
"ProfileVersion": "xxx"
},
"status": "done"
}
GET https://example.com/currency-rates/get/[comma separated currencies]
| Attribute | Description |
|---|---|
| FromCurrency | 3 letter ISO 4217 currency code |
| ToCurrency | 3 letter ISO 4217 currency code |
| Rate | Float, value of the currency pair |
Accounting
In order to use the accounting, you will need to use the same authentication methods described above.
Documents
Get Document
Request
curl \
-H "aether-application-key: [app-key]" \
-H "aether-account: [account]" \
-H "aether-agent: [agent]" \
-H "aether-customization: [customization]" \
-H "aether-password: [password]" \
-H "cache-control: no-cache" \
-d '{"ID":22}' \
-X POST
https://example.com/accounting/document/get
Response
{
"content": {
"Accounting": {
"Balance": 30,
"Currency": "USD",
"GrossAmount": 30,
"NetAmount": 30,
"PaymentMethod": "cash",
"Tax": 0
},
"ActionPermissions": {
"AddLine": true,
"Cancel": true,
"Finalize": true,
"Pay": true
},
"Booking": ["35"],
"Covered": [],
"CreateDate": "2018-02-05 15:10:49",
"CreateType": "manual",
"DisplayName": "Sales Order",
"DocumentID": 48,
"DueDate": "2018-02-06 10:20:58",
"From": {
"AccountAlias": "test travel",
"AccountID": 101,
"AccountType": "Account",
"ContactAddress": "test",
"ContactCity": "test",
"ContactEmail": "stest@mail.com",
"ContactName": "testy mctestington"
},
"IssueDate": "2018-02-06 10:20:58",
"LeadName": "TEST TEST",
"LineSubTotals": {
"hotels": 30
},
"Lines": [
{
"Accounting": {
"Amount": 15,
"Conversion": 15,
"Currency": "EUR"
},
"BookingItem": {
"BookingID": "35",
"BookingItemID": 1,
"EndDate": "2018-01-15",
"LeadName": "TEST TEST",
"ServiceType": "hotels",
"StartDate": "2018-01-09"
},
"Details": {
"ItemDescription": "A TEST ROOM IN A FAKE HOTEL",
"ItemName": "hotels Booking",
"LineType": "hotels",
"ProductID": 1,
"Quantity": 1
},
"DocumentID": 48,
"LineID": 42
},
{
"Accounting": {
"Amount": 15,
"Conversion": 15,
"Currency": "EUR"
},
"BookingItem": {
"BookingID": "35",
"BookingItemID": 2,
"EndDate": "2018-01-15",
"LeadName": "TEST TEST",
"ServiceType": "hotels",
"StartDate": "2018-01-09"
},
"Details": {
"ItemDescription": "A TEST ROOM IN A FAKE HOTEL",
"ItemName": "hotels Booking",
"LineType": "hotels",
"ProductID": 2,
"Quantity": 1
},
"DocumentID": 48,
"LineID": 43
}
],
"PaymentDetails": null,
"Payments": [],
"ProfileVersion": "1108c82ffac3914820eee3c4b227299e909e1cd5",
"Reference": "s51",
"Status": "open",
"To": {
"AccountAlias": "jeff travel",
"AccountID": 3,
"AccountType": "Account",
"ContactAddress": "test",
"ContactCity": "test",
"ContactEmail": "N/A",
"ContactName": "N/A"
},
"ToProvider": false,
"Type": "invoice"
},
"status": "done"
}
POST https://example.com/accounting/document/get
| Attribute | Description |
|---|---|
| DocumentID | The ID of this document |
| CreateDate | The timestamp of the document creation |
| CreateType | How was this document created. possible values are: manual, custom, scenario |
| IssueDate | The deciding timestamp of when the document was issue, can be different than the actual creation timestamp |
| DueDate | The timestamp stating when the document is due to be covered |
| Type | Whether the document is an invoice or a payment. possible values are: invoice, payment |
| DisplayName | The category name that the condition of this document falls under. Can be one of the following (Sales Order, Invoice, Receipt, Credit, Refund, Purchase Order, Provider Invoice, Provider Receipt, Provider Credit, Provider Payout, Provider Payment, Provider Refund) |
| Status | The status of the document. possible values are: open, finalized, cancelled |
| Reference | The reference number generated for this document |
| ToProvider | Boolean, indicates the direction of the document. if false it means it’s a client facing document, otherwise it’s provider facing |
| LeadName | Name of the lead Pax the document refers to |
| From | The Contact element which is issuing the document, see details below |
| To | The Contact element which is receiving the document, see details below |
| Accounting.NetAmount | The net amount of the document |
| Accounting.GrossAmount | The gross amount of the document |
| Accounting.Currency | The currency of the document |
| Accounting.Tax | Tax value included in the document |
| Accounting.Balance | The remaining balance for the document |
| ActionsPermissions | See ActionsPermissions section below |
| Lines | See the “Get lines” section for details |
| LineSubTotals | An array/object of sub-totals regarding the lines, grouped by line type |
| Payments | Array of payments that covers this document |
| Covered | Array of documents this document covers |
| PaymentDetails | See PaymentDetails section below |
Contact element
Note that the contact can be of a Customer or of an account.
| Attribute | Description |
|---|---|
| ContactName | The name of the Customer and/or the account holder |
| ContactAddress | The address of the Customer and/or the account holder |
| ContactCity | The city of the Customer and/or the account holder |
| ContactEmail | The email of the Customer and/or the account holder |
| AccountID | The ID of the contact |
| AccountType | Whether it’s an “Account” or a “Customer” |
| AccountAlias | Name of the account |
ActionsPermissions element
| Attribute | Description |
|---|---|
| Pay | Indicates that a payment can be made to this document |
| AddLine | Indicates whether a line could be added to this document |
| Finalize | Indicates whether this document is open and can be finalized |
| Cancel | Indicates whether this document can be cancelled |
PaymentDetails element
The PaymentDetails can be one of the following:
- Bank Transfer
- Credit Card
- VCC
- Cash
- Cheque
Each of these elements have different structure, and is shown on the “Type” attribute:
Bank Transfer
| Attribute | Description |
|---|---|
| Date | Date of the payment, structure YYYY-MM-DD HH:MM:SS |
| Sum | Value of the payment |
| Comment | Free text comment |
| Type | always “Bank Transfer” |
| Reference | Transaction reference, free text |
Credit Card
| Attribute | Description |
|---|---|
| Date | Date of the payment, structure YYYY-MM-DD HH:MM:SS |
| Sum | Value of the payment |
| Comment | Free text comment |
| CardType | the card type used for payment. Free text. |
| Last4Digits | last 4 digits of the credit card used for the payment |
VCC
| Attribute | Description |
|---|---|
| Date | Date of the payment, structure YYYY-MM-DD HH:MM:SS |
| Sum | Value of the payment |
| Comment | Free text comment |
| CardType | the card type used for payment. Free text. |
| Last4Digits | last 4 digits of the credit card used for the payment |
Cash
| Attribute | Description |
|---|---|
| Date | Date of the payment, structure YYYY-MM-DD HH:MM:SS |
| Sum | Value of the payment |
| Comment | Free text comment |
| Details | Free text |
Cheque
| Attribute | Description |
|---|---|
| Date | Date of the payment, structure YYYY-MM-DD HH:MM:SS |
| Sum | Value of the payment |
| Comment | Free text comment |
| AccountNumber | Number of the account used for payment |
| ChequeNumber | Identifier of the Cheque used for payment |
Get Line
Request
curl \
-H "aether-application-key: [app-key]" \
-H "aether-account: [account]" \
-H "aether-agent: [agent]" \
-H "aether-customization: [customization]" \
-H "aether-password: [password]" \
-H "cache-control: no-cache" \
-d '{"ID":44}' \
-X POST
https://example.com/accounting/line/get
Response
{
"content": {
"ActionPermissions": {
"Edit": true,
"Remove": true
},
"ProfileVersion": "347...",
"LineID": 9,
"DocumentID": 6,
"Details": {
"LineType": "Product",
"ProductID": 1,
"ItemName": "dinner",
"ItemDescription": "super awesome delux dinner for 2",
"Quantity": 1
},
"BookingItem": {
"BookingID": null,
"BookingItemID": null,
"ServiceType": null,
"LeadName": null,
"StartDate": null,
"EndDate": null
},
"Accounting": {
"Amount": 100,
"Currency": "EUR",
"Conversion": 125
}
},
"status": "done"
}
This method retrieves document lines.
| Attribute | Description |
|---|---|
| LineID | The ID of the line |
| DocumentID | The ID of the document the line belongs to |
| ActionPermissions | What can be done with this line, see below |
| Details | Line details, see below |
| BookingItem | The booking item the line covers, see below |
| Accounting | Accounting aspects of the line, see below |
ActionPermissions
| Attribute | Description |
|---|---|
| Edit | boolean, can the line be edited |
| Remove | boolean, can the line be removed |
Details
| Attribute | Description |
|---|---|
| LineType | The type of item the line refers to, possible values are: Product, Tax, but it can also be anything the user defines when setting the line. |
| ProductID | The product id for the line. Note that this can be any product and not necessarily the booking item id. |
| ItemName | The name of the Item the line refers to, free text. |
| ItemDescription | Free text description of the item. |
| Quantity | How many products does this line covers |
BookingItem
| Attribute | Description |
|---|---|
| BookingID | The booking ID the line covers |
| BookingItemID | The booking item ID the line covers |
| ServiceType | The service type the line covers |
| LeadName | Lead name of the booking |
| StartDate | Start date of the booking |
| EndDate | End date of the booking |
Accounting
| Attribute | Description |
|---|---|
| Amount | Value of the line |
| Currency | Currency of the line |
| Conversion | The value of this line converted into the documents default currency |
List Documents
Request
curl \
-H "aether-application-key: [app-key]" \
-H "aether-account: [account]" \
-H "aether-agent: [agent]" \
-H "aether-customization: [customization]" \
-H "aether-password: [password]" \
-H "cache-control: no-cache" \
-d '{"filters":{"FromID": 1},"resultsPerPage": 10,"currentPage": 1}' \
-X POST
https://example.com/accounting/document/list
This method retrieves documents based of filters and pagination.
| Attribute | Description |
|---|---|
| resultsPerPage | Number of results to return per page, max is 50 |
| currentPage | Current page |
| filters | available filters object, optional, see below for details |
(optional) Request Filters
you can include multiple filters on the request to narrow your search. all filters are optional
| Attribute | Description |
|---|---|
| DocumentIDs | array of document IDs |
| FromIDs | array of account IDs the document was issued from |
| ToIDs | array of account IDs the document was issued to |
| BookingIDs | array of booking IDs the document was issued for |
| AgentIDs | array of booking IDs the document was issued by |
| CreatedAfter_value | Timestamp, get bookings created after this date, format is: YYYY-MM-DD HH:MM:SS |
| CreatedBefore_value | Timestamp, get bookings created before this date, format is: YYYY-MM-DD HH:MM:SS |
| IssuedAfter_value | Timestamp, get bookings issued after this date, format is: YYYY-MM-DD HH:MM:SS |
| IssuedBefore_value | Timestamp, get bookings issued before this date, format is: YYYY-MM-DD HH:MM:SS |
| DueAfter_value | Timestamp, get bookings due after this date, format is: YYYY-MM-DD HH:MM:SS |
| DueBefore_value | Timestamp, get bookings due before this date, format is: YYYY-MM-DD HH:MM:SS |
| Types | array, possible values are invoice, payment |
| PaymentMethods | array, see PaymentDetails for possible values |
| Statuses | array, possible values are open, finalized, cancelled |
| Currencies | array, list of currencies |
| References | array, list of document references |
| DisplayNames | array, possible values Sales Order, Invoice, Receipt, Credit, Refund, Purchase Order, Provider Invoice, Provider Receipt, Provider Credit, Provider Payout, Provider Payment, Provider Refund |
| Direction | string, possible values Account, Provider, Both |
Response
{
"content": {
"currentPage": 1,
"totalResults": 86,
"resultsPerPage": 10,
"records": [
/*...documents...*/
],
"ProfileVersion": "7efd..."
},
"status": "done"
}
POST https://example.com/accounting/document/list
| Attribute | Description |
|---|---|
| records | a list of document objects as described in the /accounting/document/get method |
Mishor
Introduction
Mishor is an API switch for multiple travel content providers.
Products
Hotels
Flow
The common case usage is quite simple:
- Initiate a search
- Poll to get results
- [optional] poll the same search to get better results providing timestamp of the last poll
- [optional] get the cancellation policy, if it’s not returned as part of the search/poll results
- run a pre-book call
- book
Please note - changing any method of the API requires a new fresh certification.
Search
Request
curl \
-H "aether-application-key: [app-key]" \
-X POST
-d @request-file.json
https://example.com/hotels/search
Request content
{
"client": {
"ip": "1.2.3.4",
"userAgent": "Example User Agent"
},
"currencies": ["USD"],
"customerCountry": "IL",
"customFields": [],
"dates": {
"from": "2018-09-20",
"to": "2018-09-22"
},
"destinations": [
{
"id": 5252,
"type": "location"
}
],
"filters": [],
"pax": [
{
"adults": 2
}
],
"service": "hotels"
}
Request
POST https://example.com/hotels/search
| Attribute | Description |
|---|---|
| client | Information about the client who is running the search. This node is optional, but sending it may provide special rates, for example for mobile users. |
| .client/ip | The IP of the end-client |
| .client/userAgent | The user agent of the end-client |
| currencies | A list of currencies you wish to get your results in. The first currency on the list will be the default currency of the search |
| customerCountry | 2 letter ISO code of the customer country running the search. Note: that the same customer country must be used on the booking, and giving a wrong or inaccurate customer country may result in the hotel not honoring the booking. |
| customFields | See below |
| dates | The from and to dates, format: YYYY-MM-DD |
| destinations | The search destinations array |
| .destinations/[item]/type | can be either hotel or location |
| .destinations/[item]/id | the entity id based on the type |
| filters | See below |
| pax | See below |
Filters
In order to better fit your needs, the API allows sending filters to include additional content.
All the filters are optional.
Example of a filter in the request
{
"name": "payAtTheHotel",
"value": true
},
{
"name":"showWhenCheckinDateWithin",
"value":8
},
{
"name":"hideWhenCancellationDeadlineWithin",
"value":18
}
| Filter | Type | Description |
|---|---|---|
| payAtTheHotel | bool | Include post-pay content |
| onRequest | bool | Include on-request content, which is not immediately confirmed |
| showSpecialDeals | bool | Include the special deals offers and descriptions in the response |
| getPackageRates | bool | Include rates which mustn’t be sold as-is, but only as part of a package. This feature must be enabled on your account by your account manager |
| showRoomDescriptions | bool | Whether to show the rooms descriptions where available |
| showRoomBedding | bool | Whether to show the bedding setup for the room |
| showRoomCategories | bool | Whether to show the category of the room |
| showWhenCheckinDateWithin | int | Show all results regardless of the free cancellation deadline if the arrival date is within the days specified in the filter |
| hideWhenCancellationDeadlineWithin | int | Hide results if the deadline for free cancellation is within the days specified in the filter |
Custom Fields
This part is relevant for deep-integrations only, where you have your own suppliers connected via this API and need to pass parameters to specific providers.
An example of such a use-case is a B2B system that wants the agents using the system to collect loyalty points from a specific directly-contracted provider. In order to achieve that, you need to pass the agent credentials for that specific provider during search, and these credentials will be used to contact the provider.
Example of custom fields in the request
{
"customFields": {
"agentId": 1,
"whatever": "shalgon"
}
}
Pax
The pax array specifies the desired room configuration.
Each room is an object and each object consists of adults and children, where the children element is an array with their ages.
For example: in order to search for a room with 1 adult and 2 children ages 12 and 14, you need to create an object that looks like this:
{
“adults”: 1,
“children”: [12,14]
}
Note that different hotels and different channels treat “child” differently, so even if you send a child aged 15, some properties may treat it as an adult while others as a child.
Example of pax in the request
{
"pax": [
{
"adults": 2
},
{
"adults": 1,
"children": [12, 14]
}
]
}
Response
The response will return the results received until the search was completed.
Response
{
"results": [
{
"items": [
{
"name": "Classic Double",
"category": "standard",
"bedding": "double",
"board": "BB",
"hotelId": 3090,
"pax": {
"adults": 2,
"children": []
},
"quantity": {
"min": 1,
"max": 1
}
},
{
"name": "Classic Double",
"category": "standard",
"bedding": "double",
"board": "BB",
"hotelId": 3090,
"pax": {
"adults": 2,
"children": []
},
"quantity": {
"min": 1,
"max": 1
}
}
],
"code": "3090:::BB:5aeffedce7c86:qPo",
"price": {
"amount": 1096.62,
"currency": "USD"
},
"netPrice": {
"amount": 722.25,
"currency": "EUR"
},
"barRate": {
"amount": 631.8,
"currency": "EUR"
},
"confirmation": "immediate",
"payment": "pre",
"packageRate": false,
"commissionable": true,
"cancellation": {
"type": "non-refundable"
}
}
],
"sessionId": "1234",
"status": "done",
"timestamp": 1533640316,
"requestTime": "2018-08-07 14:11:56",
"completed": 100,
"processTime": 530
}
The response is an array of results, each result consists of these attributes:
| Attribute | Description |
|---|---|
| items | An array of items the result id holds. The booking will be made on the result including all the items in it. The prices are only on the result level. |
| .item/name | The name of the offered room |
| .item/category | The category of the room |
| .item/bedding | the bedding type available for this room |
| .item/board | the available board for this offer, available list of boards exists in the lookups section |
| .item/hotelId | The hotel id, taken from the static data |
| .item/pax | the corresponding pax from your search which this result is suitable to |
| .item/quantity | min/max availability. how many items of this result can be booked. If the min value is larger than 1, it means you must book at least the minimum quantity of results. Note that the price element in any case is the total price of the minimum quantity of items offered. |
| barRate | Price (amount/currency) of the BAR, the price which you are not allowed to sell below on B2C platforms. |
| cancellation | See below |
| code | The result code, use this for the next steps |
| commissionable | boolean, indicates whether you can apply a commission on top of the price or not |
| confirmation | immediate or on-request |
| netPrice | The net price (amount/currency) of this result |
| packageRate | boolean, indicates whether this result can be sold as a stand-alone offer or if it requires to be sold as part of a package |
| payment | pre or post, indicates whether this is a pre-paid result or a pay-at-the-hotel result |
| price | The gross price of the result |
In addition, there are several other attributes that are of interest:
| Attribute | Description |
|---|---|
| sessionId | The session ID of the search |
| status | The status of the search, whether it is done, working, or failed |
| timestamp | The server timestamp of the response. this can be used to poll by delta |
| requestTime | The request date time in Human readable format |
| completed | Integer, percentage of the progress. 0 means no tasks were completed, 100 means all tasks were completed, everything in between in “in process”. Please note this attribute is for Hubwayz’s internal use only. To check if the search was completed or not please refer only to the status property. |
| processTime | Processing time in milliseconds. |
In case of post-payment results, you might get a transaction node in the response. This node will be returned in case you defined a “transaction fee” markup for this purpose.
This is being used in case the user has to pay a gross amount directly to the hotel, but you still want to collect something for the booking.
Example of a transaction fee in the response
"transactionFee": {
"amount": 25.7,
"currency": "EUR"
}
Cancellation Policy
The cancellation policy is build from frames.
Each frame has a start date (from), end date(to), and a penalty.
These frames tells you exactly what will be the penalty on each date starting from the booking date until the check-in date.
After the check-in date the cancellation penalty should be assumed as 100%.
Poll
Request
curl \
-H "aether-application-key: [app-key]" \
-X POST
-d @request-file.json
https://example.com/hotels/poll[/timestamp]
Request content
{
"client": {
"ip": "1.2.3.4",
"userAgent": "Example User Agent"
},
"currencies": ["USD"],
"customerCountry": "IL",
"customFields": [],
"dates": {
"from": "2018-09-20",
"to": "2018-09-22"
},
"destinations": [
{
"id": 5252,
"type": "location"
}
],
"filters": [],
"pax": [
{
"adults": 2
}
]
}
Request
POST https://example.com/hotels/poll[/timestamp]
The poll request & response are identical to the search request & response with the exception of the endpoint.
You can send as many polls as you like until the status in the response is working. Once it finishes, the status changes to done and this means no new results will show up in your next poll.
Check out the Flow chapter in the beginning to get a better understanding of this method.
You can add an optional timestamp to the URL, the timestamp must be the one returned in the previous search/poll response in order to get the details.
If you do not send the timestamp in the URL, you will get ALL results every time.
Note that the search and poll requests must be identical.
Progress
Request
curl \
-H "aether-application-key: [app-key]" \
-X POST
-d @request-file.json
https://example.com/hotels/progress
Request content
{
"client": {
"ip": "1.2.3.4",
"userAgent": "Example User Agent"
},
"currencies": ["USD"],
"customerCountry": "IL",
"customFields": [],
"dates": {
"from": "2018-09-20",
"to": "2018-09-22"
},
"destinations": [
{
"id": 5252,
"type": "location"
}
],
"filters": [],
"pax": [
{
"adults": 2
}
]
}
Request
POST https://example.com/hotels/progress
The progress request & response are identical to the search request & response with the exception of the endpoint. This call doesn’t return any results, but status of the search.
You can send as many progress calls as you like until the status in the response is working. Once it finishes, the status changes to done and this means you can now use poll request to grab all of the results.
Check out the Flow chapter in the beginning to get a better understanding of this method.
Note that the search and progress requests much be identical.
Get cancellation policy
Request content
{
"client": {
"ip": "1.2.3.4",
"userAgent": "Example User Agent"
},
"currencies": ["USD"],
"customerCountry": "IL",
"customFields": [],
"dates": {
"from": "2018-09-20",
"to": "2018-09-22"
},
"destinations": [
{
"id": 5252,
"type": "location"
}
],
"filters": [],
"pax": [
{
"adults": 2
}
]
}
Request
POST http://example.com/hotels/cancellation/[room code]
The request consists of the desired room code (in the url) and the original search (in the request body).
Response
The response is exactly the same as the poll response, but with the cancellation frames in place.
Note that if you searched for multiple rooms and received multiple room codes for a single result, you MUST send multiple calls in order to get the cancellation policy for each separate code.
Pre-Book
Request content
{
"services": [
{
"searchCodes": [
{
"code": "17512:standard:double:BB:5c06a3747437b$118h120U",
"pax": [
{
"adults": 2,
"children": []
}
]
},
{
"code": "17512:standard:double:BB:5c06a378bbb90$118h120U",
"pax": [
{
"adults": 1,
"children": []
}
]
}
],
"searchRequest": {
"currencies": ["USD"],
"customerCountry": "IL",
"dates": {
"from": "2018-05-04",
"to": "2018-05-05"
},
"destinations": [
{
"id": 5252,
"type": "location"
}
],
"filters": [
{
"name": "payAtTheHotel",
"value": true
}
],
"pax": [
{
"adults": 2
},
{
"adults": 1
}
],
"service": "hotels"
}
}
]
}
Request
POST http://example-booking.com/pre-book
Note that this request is being send to a different domain than the one used for searching
| Element | Description |
|---|---|
| searchCodes | The result codes you are planning to book. you can send as many search codes as you like in this array. |
| .code | the code from the result |
| .pax | the pax related to the specific code |
| searchRequest | the original, unchanged, search request |
Response
Response content
{
"content": {
"PaymentMethods": [
{
"methodDescription": "",
"methodName": "account_credit",
"paymentSettings": {
"creditCardForm": false,
"requiredFields": []
},
"status": "disabled"
},
{
"methodDescription": "",
"methodName": "enett",
"paymentSettings": {
"creditCardForm": false,
"requiredFields": [
{
"enettId": "test"
}
]
},
"status": "enabled"
},
{
"methodDescription": "",
"methodName": "credit_card",
"paymentSettings": {
"creditCardForm": true,
"requiredFields": []
},
"status": "enabled"
}
],
"Services": {
"hotels": [
{
"barRate": {
"amount": 690,
"currency": "EUR"
},
"cancellation": {
"frames": [
{
"from": "2018-05-21",
"penalty": {
"amount": 0,
"currency": "USD"
},
"to": "2018-06-18"
},
{
"from": "2018-06-18",
"penalty": {
"amount": 247.71,
"currency": "EUR"
},
"to": "2018-06-21"
}
],
"type": "fully-refundable"
},
"code": "33823:standard:double:BB:5afd296a87736$33823:standard:double:BB:5afd296a87775$qPo",
"commissionable": true,
"confirmation": "immediate",
"items": [
{
"bedding": "double",
"board": "BB",
"boardName": "Breakfast Continental",
"category": "standard",
"hotel": {
"address": "Via Marghera 15/17",
"city": "Rome",
"fax": null,
"latitude": "41.90224110705",
"longitude": "12.503670528531",
"name": "Hotel Corot",
"phone": "+39644700900",
"rating": "3",
"zip": "00185"
},
"hotelId": 33823,
"name": "Standard Double or Twin Room",
"pax": {
"adults": 2,
"children": []
},
"quantity": {
"max": 1,
"min": 1
},
"remarks": {
"general": "this is a remark that should be shown to the customer"
}
},
{
"bedding": "double",
"board": "BB",
"boardName": "Breakfast Continental",
"category": "standard",
"hotel": {
"address": "Via Marghera 15/17",
"city": "Rome",
"fax": null,
"latitude": "41.90224110705",
"longitude": "12.503670528531",
"name": "Hotel Corot",
"phone": "+39644700900",
"rating": "3",
"zip": "00185"
},
"hotelId": 33823,
"name": "Standard Double or Twin Room",
"pax": {
"adults": 2,
"children": []
},
"quantity": {
"max": 1,
"min": 1
},
"remarks": {
"general": "this is a remark that should be shown to the customer <b>including HTML</b>"
}
}
],
"netPrice": {
"amount": 788.77,
"currency": "EUR"
},
"packageRate": false,
"paymentMethod": "direct",
"price": {
"amount": 1196.4,
"currency": "USD"
},
"surcharges": [
{
"price": {
"amount": 20,
"currency": "USD"
},
"payment": "excluded",
"title": "City tax",
"mandatory": true,
"description": ""
},
{
"price": {
"amount": 8.3,
"currency": "USD"
},
"payment": "included",
"title": "Occupancy tax",
"mandatory": true,
"description": ""
}
],
"requestCode": "319229:standard:double:RO:4bf3d2665b474$119yo",
"token": "65DDBED2"
}
]
}
},
"status": "done"
}
| Element | Description |
|---|---|
| PaymentMethods | The acceptable payment methods for this booking |
| .methodName | the name of the payment method. a standard integration will use account_credit or credit_card. |
| .methodDescription | additional description of the method, for example if the method is a saved credit card token on the account, the description can say something like “Credit card ending with 1234” |
| .status | whether this option is enabled for this booking |
| .paymentSettings | specific settings for the payment method |
| ..creditCardForm | boolean, specifies if you need to show the credit card form to the user |
| ..requiredFields | key/value array of objects, consists of required fields to request from the user. for example the enett agent id in case of enett payment integration |
| Services | The services that are about to be booked |
| .hotels | an array of hotel rooms that are about to be booked |
| ..barRate | The minimum price (amount/currency) that can be shown on B2C website |
| ..cancellation | The cancellation policies, see the search response for details |
| ..code | The room code |
| ..commissionable | Whether or not you can add commission to the final price |
| ..confirmation | immediate or on-request |
| ..items | a collection of items |
| ..item.bedding | The offered bedding configuration |
| ..item.board | The offered board code |
| ..item.board | The offered board name |
| ..item.category | The offered room category |
| ..item.hotel | The hotel information. Note that it is mandatory to show the hotel information received in this response to the user prior to them making the booking, and use this information on the voucher issued to the user. It is NOT allowed to use the information from the static data. |
| ..item.hotelId | The booked hotel ID |
| ..item.name | The booked room name. Note that it is mandatory to show the room name received in this response to the user prior to them making the booking, and show this information on the voucher issued to the user. It is NOT allowed to use the information from the search response. |
| ..item.pax | The pax suitable for this room |
| ..item.quantity | See the search response for details |
| ..item.remarks | object that includes keys and free text remarks received from the hotel. the default key is called general, and additional keys may be included in certain cases. Note that is is mandatory to show these remarks to the user before the booking and it is also mandatory to put them on the voucher. |
| ..netPrice | The net price (amount/currency) of the booking, i.e. the amount that you need to pay the provider |
| ..packageRate | if true, this offer cannot be sold as a stand-alone booking, and the price must never be shown to the user without it being bundled as a package with other products. |
| ..payment | pre or post |
| ..price | The gross price (amount/currency) of the booking, i.e. the amount you charge your customer |
| ..surcharges | if there are any additional surcharges applied to the price |
| ..surcharges.price | The price (amount/currency) of the surcharge |
| ..surcharges.payment | included or excluded or direct |
| ..surcharges.title | The name of the surcharge |
| ..surcharges.mandatory | true or false |
| ..surcharges.description | The description of the surcharge |
| ..requestCode | the code you sent in the request. this is used in case the result changed due to price or availability. it is for your use only and should not be sent in further requests. |
| ..token | the booking token you will have to send in order to make the actual booking |
| ..warnings | optional node, returned only in case of price or availability change |
"warnings": [
{
"code": 2100,
"message": "Your item is not available under the originally requested price, please review the selected alternative or go back to select another result."
}
]
Book
Request
POST http://example-booking.com/book
Note that this request is being send to a different domain than the one used for searching
{
"creditCard": {
"cardNumber": "4111 1111 1111 1111",
"cvc": "555",
"expiry": {
"month": "12",
"year": "2019"
},
"name": {
"first": "Yogi",
"last": "Berra"
}
},
"customer": {
"birthDate": "1975-09-14",
"contact": {
"address": "housington 66",
"city": "cityngton",
"country": "NL",
"email": "test@example.com",
"phone": "555-4433222",
"state": "N/A",
"zip": "88776"
},
"name": {
"first": "Yogi",
"last": "Berra"
},
"title": "M"
},
"paymentMethod": {
"methodName": "account_credit"
},
"reference": {
"agency": "my agency reference",
"voucherEmail": "test@example.com"
},
"services": [
{
"specialRequests":[
{
"arrival":"late"
},
{
"additional_information":"This is a test booking"
}
],
"bookingRequest": [
{
"code": "3742:::RO:5acb6bcf725bf:qPo",
"pax": [
{
"adults": [
{
"contact": {
"address": "housington 66",
"city": "cityngton",
"country": "NL",
"email": "test@example.com",
"phone": "555-4433222",
"state": "N/A",
"zip": "88776"
},
"lead": true,
"name": {
"first": "Yogi",
"last": "Berra"
},
"title": "M"
},
{
"name": {
"first": "Mona",
"last": "Lisa"
},
"title": "F"
}
]
}
],
"token": "1515BEE8"
}
],
"searchRequest": {
"currencies": ["USD"],
"customerCountry": "NL",
"dates": {
"from": "2018-05-04",
"to": "2018-05-05"
},
"destinations": [
{
"id": 5252,
"type": "location"
}
],
"filters": [
{
"name": "payAtTheHotel",
"value": true
}
],
"pax": [
{
"adults": 2,
"children": []
}
],
"service": "hotels"
}
}
]
}
| Element | Description |
|---|---|
| creditCard | In case you are paying with a credit card, you need to send all relevant details |
| customer | The customer details of the customer that is making the booking. It doesn’t have to be the same details as the travelers |
| payment | how are you going to pay for the booking. this value must be one of the options returned in the pre-book |
| .method | one of: “credit_card”, “account_credit”, or “enett” |
| .securePaymentUrl | in case the payment method is credit_card, you need to supply a URL where to send the user after the payment process. |
| reference | your references |
| .agency | free text of your agency reference, i.e. your internal booking id |
| .voucherEmail | an email address to send the voucher to |
| services | this array of elements consists of the desired items you want to book. Each element contains 2 sub-elements: the original search request, and the booking request. |
| .searchRequest | the original search request |
| .specialRequests | the special request |
| .bookingRequest | this element will contain the guest information and the payment details. |
| ..code | The result code you wish to book, this code comes from the search/poll response |
| ..token | the token from the pre-book call |
| ..pax | The pax configuration array for the booked properties. Each element in the array is a booked room |
| …adults | the details of the adults in the room |
| ….name | first/last names of the guest |
| ….title | M for male, F for female (for children - see below) |
| ….lead | boolean, set to true if this is the lead pax. each booking must have one lead. do not set this flag on more than one. |
| ….contact | contact details of the lead pax, can be different than the customer on the booking. |
In case you want to send a booking request for children, the child element must include another attribute called “birthDate” with a date value in the format YYYY-MM-DD. It is important to note that the age of the children is calculated based on the booking date.
Example of a children node:
“children”: [
{
”birthDate”: “2014-04-20”
”name”: {
”first”: “test”,
”last”: “test”
},
”title”: “C”
}
]
Please ensure the “birthDate” attribute is present and correctly formatted to prevent any issues during the booking process.
Response
Response content
{
"content": {
"bookingID": "1000255",
"customer": {
"birthDate": "1985-01-01",
"contact": {
"address": "housington 66",
"city": "cityington",
"country": "NL",
"email": "test@example.com",
"phone": "555-4433222",
"state": "N/A",
"zip": "88776"
},
"name": {
"first": "Yogi",
"last": "Berra"
},
"title": "M"
},
"netPrice": {
"amount": 55.2,
"currency": "EUR"
},
"payment": {
"method": "account_credit",
"clearingState": null,
"paymentStatus": "unpaid"
},
"price": {
"amount": 60.72,
"currency": "EUR"
},
"services": [
{
"cancellation": {
"frames": [
{
"from": "2018-05-13",
"penalty": {
"amount": 60.72,
"currency": "EUR"
},
"to": "2018-07-17"
}
],
"type": "refundable"
},
"code": "10666:standard:double:BB:5af95d6668163:qPo",
"hotel": {
"address": "Via San Lino Papa 35",
"city": "Rome",
"fax": null,
"latitude": "41.919755493726",
"longitude": "12.420943826437",
"name": "Hotel Pineta Palace",
"phone": "+3963013800",
"rating": "4",
"room": {
"bedding": "double",
"board": "BB",
"boardName": null,
"category": "standard",
"name": "Economy Double or Twin Room",
"token": "9179F6DB"
},
"zip": "00167"
},
"itemId": 1,
"netPrice": {
"amount": 55.2,
"currency": "EUR"
},
"pax": [
{
"adults": [
{
"birthDate": "1985-01-01",
"contact": {
"address": "housington 66",
"city": "cityington",
"country": "NL",
"email": "test@example.com",
"phone": "555-4433222",
"state": "N/A",
"zip": "88776"
},
"lead": true,
"name": {
"first": "Yogi",
"last": "Berra"
},
"title": "M"
},
{
"birthDate": "1985-01-01",
"lead": false,
"name": {
"first": "Mona",
"last": "Lisa"
},
"title": "F"
}
],
"children": []
}
],
"price": {
"amount": 60.72,
"currency": "EUR"
},
"quantity": 1,
"remarks": "<br>\r\n. 1 double bed, 2 single beds. Economy Double or Twin Room. <p><b>Know Before You Go</b> <br /><ul> <li>All guests, including children, must be present at check-in and show their government-issued photo ID card or passport.</li> <li>Cash transactions at this property cannot exceed EUR 2999.99, due to national regulations. For further details, please contact the property using information in the booking confirmation. </li> <li>One child 3 years old or younger stays free when occupying the parent or guardian's room, using existing bedding. </li> </ul></p><p><b>Fees</b> <br /><p>The following fees and deposits are charged by the property at time of service, check-in, or check-out. </p> <ul> <li>Self parking fee: EUR 8 per day</li> </ul> <p>The above list may not be comprehensive. Fees and deposits may not include tax and are subject to change. </p></p><p><b>Mandatory Fees and Taxes</b> <br /><p>You'll be asked to pay the following charges at the property:</p> <ul><li>A tax is imposed by the city: EUR 6 per person, per night, up to 10 nights. This tax does not apply to children under 10 years of age. </li></ul> <p>We have included all charges provided to us by the property. However, charges can vary, for example, based on length of stay or the room you book. </p></p>. -This booking is non-amendable, If you need to make an amendment, please cancel and re-book for the new dates or room type.. Breakfast Buffet. 1 double bed, 2 single beds. Economy Double or Twin Room. <p><b>Know Before You Go</b> <br /><ul> <li>All guests, including children, must be present at check-in and show their government-issued photo ID card or passport.</li> <li>Cash transactions at this property cannot exceed EUR 2999.99, due to national regulations. For further details, please contact the property using information in the booking confirmation. </li> <li>One child 3 years old or younger stays free when occupying the parent or guardian's room, using existing bedding. </li> </ul></p><p><b>Fees</b> <br /><p>The following fees and deposits are charged by the property at time of service, check-in, or check-out. </p> <ul> <li>Self parking fee: EUR 8 per day</li> </ul> <p>The above list may not be comprehensive. Fees and deposits may not include tax and are subject to change. </p></p><p><b>Mandatory Fees and Taxes</b> <br /><p>You'll be asked to pay the following charges at the property:</p> <ul><li>A tax is imposed by the city: EUR 6 per person, per night, up to 10 nights. This tax does not apply to children under 10 years of age. </li></ul> <p>We have included all charges provided to us by the property. However, charges can vary, for example, based on length of stay or the room you book. </p></p>. -This booking is non-amendable, If you need to make an amendment, please cancel and re-book for the new dates or room type.. Breakfast Buffet",
"service": "hotels",
"status": "confirmed",
"supplier": {
"reference": "BG66666GZSPL"
}
}
],
"status": "confirmed"
},
"status": "done"
}
Most of the details are a reflection of the data sent by you. the following details are of notice:
| Element | Description |
|---|---|
| bookingID | The Innstant system booking ID |
| payment | The payment options used in the booking |
| .method | The payment method used |
| .clearingState | In case a credit card was used, the clearing state tells you if the booking was charged or just authorized. possible values are enrollment, authorization, payment and pre-payment |
| .paymentStatus | paid or unpaid |
| services.supplier.reference | the supplier reference that should appear on the voucher |
Understanding the different statuses on the bookings response
We return 3 status attributes as part of the book response, each of them has a different purpose.
In order to know if a specific service within the booking was confirmed - you must check the individual statuses on each service in the booking.
| Element | Description |
|---|---|
| status | message status - tells you if there was a communication error |
| content.status | the booking status |
| content.services.status | status of each service in the booking |
Possible status values
| Element | Description |
|---|---|
| confirmed | The booking/item was confirmed |
| initialized | The booking/item started the booking process |
| partially_confirmed | The booking was only partially confirmed, you must check each item to make sure which one was not confirmed |
| failed | The booking/item failed to confirm |
| error | There was an error during the booking process |
| cancelled | The booking/item was cancelled |
| pending_cancellation | The booking/item was not cancelled yet but is waiting to be cancelled |
| on_request | The booking/item is pending the provider approval or rejection |
| rejected | The booking/item was rejected |
| unknown | ¯_(ツ)_/¯ |
Recoverable errors
In some cases you’ll get a “recoverable error”. This can happen if there is already a booking on that hotel for the same guest, if the price changed, or if the processing commission is too high (if you’re using the processing feature).
The response will have the error code a70x or a21xx (i.e. a702, a2100, etc) and it can be recovered by calling the endpoint: /complete-booking/ with the content:
{"completeCode":"a702","paymentSettings":{"paymentAmount":"net","paymentDate":"billing-terms","transactionFeeCharge":true},"bookingID":xx1234}
| Element | Description |
|---|---|
| completeCode | The recoverable error code you received in the initial booking response |
| paymentSettings | the same paymentSettings node you sent in the booking request |
| bookingID | the booking ID from the initial booking response |
Cancel
Request content
{
"BookingID": 1234,
"CancelReason": "The dog is sick",
"Force": false,
"IsManual": false
}
Request
POST https://example.com/booking-cancel
| Attribute | Description |
|---|---|
| BookingID | The booking ID you would like to cancel |
| CancelReason | The reason for the cancellation, can be left blank |
| Force | Should the booking be cancelled in any case, without calling the provider - USE FALSE UNLESS YOU KNOW WHAT YOU ARE DOING |
| IsManual | Is the booking being cancelled by a human request or by an automated process |
Response
Response content
{
"content": {
"Status": "done",
"Warnings": []
},
"status": "done"
}
| Attribute | Description |
|---|---|
| content.Status | Was the cancellation successful (done) or unsuccessful (error) |
| content.Warnings | This array will be returned only if force cancellation was used |
Booking Details
Request
GET https://example.com/booking-details/[booking-id]
| Attribute | Description |
|---|---|
| BookingID | The booking ID you would like to get details for |
Response
The response is the same as booking response
Events
Overview
The Events API provides access to bookable events such as tours, excursions, attractions, tickets, and other experiences.
Domain Model
An Event represents the experience or product offered to the customer. It contains general information about the event, such as its name, description, images, categories, duration, locations, and available features.
An Event can have one or more Modalities. A modality represents a specific variant of the event, such as a different ticket type, package, duration, or set of included services.
In the API response, the Event name is provided in the name field and the Modality name is provided in the subtitle field.
A Rate represents a specific bookable offer for an Event and Modality. A rate contains commercial and booking information such as price, currency, cancellation policy, confirmation type, payment type, and the rate code.
The domain model can therefore be represented as:
Event
└── Modality
└── Rate
├── Price
├── Cancellation policy
├── Operation dates
├── Sessions (when applicable)
└── Languages (when applicable)
Search Results
Each element of the results array represents a Rate that can be selected for booking.
The rate contains the commercial information for a particular Event and Modality, while the items object contains the information describing the Event.
The main domain concepts are:
- Event — the product or experience being offered. It is identified by
eventId. - Modality — a specific variant of an Event. Its display name is provided in the
subtitlefield. - Rate — a specific bookable offer for an Event and Modality. It is identified by the
codefield of the search result. - Operation Date — the date on which the Event takes place.
- Session — a specific time slot or scheduled session, when applicable.
- Language — the language in which the Event or service is provided, when applicable.
Flow
The common case usage is quite simple:
- Initiate a search for location
- Poll to get results
- Initiate a search for selected event
- Get details for the selected event
- Run a pre-book call for the selected modality
- Book
The flow uses two searches. The first search is run by city (destination.type = location) and returns the available Events in that destination, with a single Rate per Event (the lowest-priced modality). The second search is run for a specific Event (destination.type = event) and returns all of its modalities, together with the full event information such as featureGroups, location and routes.
When building the booking request, use the values returned by the Search API. In particular, the selected Rate code, Operation Date, and — when required — Session and Language should be taken from the availability returned by the API.
Search
Request
curl \
-H "aether-application-key: [app-key]" \
-X POST
-d @request-file.json
https://example.com/events/search
Request content
{
"currencies": ["EUR"],
"customerCountry": "IL",
"dates": {
"from": "2026-10-01",
"to": "2026-10-31"
},
"destinations": [
{
"id": 610,
"type": "location"
}
],
"pax": [
{
"adults": 1,
"children":[]
}
],
"service": "events"
}
Request
POST https://example.com/events/search
| Attribute | Description |
|---|---|
| currencies | List of currencies you wish to get your results in. The first currency on the list will be the default currency of the search |
| customerCountry | 2 letter ISO code of the customer country running the search. Note: that the same customer country must be used on the booking, and giving a wrong or inaccurate customer country may result in the venue not honoring the booking. |
| dates | The from and to dates, format: YYYY-MM-DD |
| destinations | The search destinations array |
| .destinations/id | The entity ID based on the type |
| .destinations/type | Type of destination, can be location or event |
| pax | See below |
Pax
The pax specifies the desired room configuration.
Each room is an object and each object consists of adults and children, where the children element is an array with their ages.
For example: in order to search for a room with 1 adult and 2 children ages 12 and 14, you need to create an object that looks like this:
{
“adults”: 1,
“children”: [12,14]
}
Note: that different suppliers and different channels treat “child” differently, so even if you send a child aged 15, some properties may treat it as an adult while others as a child.
Example of pax in the request
{
"pax": [
{
"adults": 2
},
{
"adults": 1,
"children": [12, 14]
}
]
}
Response
The response will return special fields. If “status” is working the search is correct. You should run next step for to receiving results.
Response
{
"timestamp": 1786991816,
"requestTime": "2026-08-17 18:36:56",
"status": "working",
"completed": 0,
"sessionId": "t:111:2:2026-10-01:2026-10-31:IL:1+:EUR:610:location:b2b",
"processTime": 11947,
"expireAt": "2026-08-17 19:07:02"
}
| Attribute | Description |
|---|---|
| timestamp | The server timestamp of the response. this can be used to poll by delta |
| requestTime | The request date time in Human readable format |
| status | The status of the search, whether it is done, working, or failed |
| completed | Integer, percentage of the progress. 0 means no tasks were completed, 100 means all tasks were completed, everything in between in “in process”. Please note this attribute is for Hubwayz’s internal use only. To check if the search was completed or not please refer only to the status property. |
| sessionId | The session ID of the search |
| processTime | Processing time in milliseconds. |
| expireAt | The date time of session lifetime |
Poll
Request
curl \
-H "aether-application-key: [app-key]" \
-X POST
-d @request-file.json
https://example.com/events/poll[/timestamp]
Request content
{
"currencies": ["EUR"],
"customerCountry": "IL",
"dates": {
"from": "2026-10-01",
"to": "2026-10-31"
},
"destinations": [
{
"id": 610,
"type": "location"
}
],
"pax": [
{
"adults": 1,
"children":[]
}
],
"service": "events"
}
Request
POST https://example.com/events/poll[/timestamp]
You can send as many polls as you like until the status in the response is working. Once it finishes, the status changes to done and this means no new results will show up in your next poll.
You can add an optional timestamp to the URL, the timestamp must be the one returned in the previous search/poll response in order to get the details.
If you do not send the timestamp in the URL, you will get ALL results every time.
Note that the search and poll requests must be identical.
Response
The response will return the results received until the search was completed.
Response
{
"timestamp": 1786991898,
"requestTime": "2026-08-17 18:38:18",
"status": "done",
"completed": 100,
"sessionId": "t:111:2:2026-10-01:2026-10-31:IL:1+:EUR:610:location:b2b",
"processTime": 5570,
"expireAt": "2026-08-17 19:07:02",
"results": [
{
"price": {
"amount": 428.57,
"currency": "EUR"
},
"netPrice": {
"amount": 428.57,
"currency": "EUR"
},
"barRate": null,
"confirmation": "immediate",
"paymentType": "pre",
"packageRate": false,
"commissionable": true,
"providers": [
{
"id": "12345",
"name": "example"
}
],
"specialOffers": [],
"items": [
{
"eventId": "E-E10-25AINC0029",
"name": "Private Cava and Vineyards Half-Day Tour with Hotel pick-up from Barcelona (HD)",
"categories": [
{
"id": 8,
"name": "Day Trips & Excursions"
}
],
"pax": {
"adults": 1,
"children": []
},
"images": ["https://example.com/directory/image.jpg"],
"thumbnail": "https://example.com/directory/thumbnail.jpg",
"locations": [
"Private Cava and Vineyards Half-Day Tour with Hotel pick-up from Barcelona (HD)"
],
"duration": "1 DAYS",
"description": "<p>Round-trip hotel pick-up & drop-off included.</p>",
"subtitle": "tour",
"operationDates": [
{
"from": "2026-10-01",
"to": "2026-10-01"
},
{
"from": "2026-10-02",
"to": "2026-10-02"
}
],
"sessions": [
{
"code": "08:30",
"name": "08:30"
}
],
"languages": [
{
"code": "en",
"description": "English"
}
],
"featureGroups": [
{
"groupCode": "DRINKS",
"included": [
{
"featureType": "DRINKSINCL",
"description": "Tasting of 3 cavas ."
}
],
"excluded": []
},
{
"groupCode": "MEAL",
"included": [
{
"featureType": "FOODINCL",
"description": "Traditional cheese and deli meats. "
}
],
"excluded": []
},
{
"groupCode": "UNKNOWN",
"included": [
{
"featureType": "OTHERINCL",
"description": "Guide"
}
],
"excluded": [
{
"featureType": "OTHERNOT",
"description": "Gratuities"
}
]
},
{
"groupCode": "TRANSPORT",
"included": [
{
"featureType": "TRANSPORTINCL",
"description": "Hotel pick-up and drop-off"
}
],
"excluded": []
}
],
"location": {
"startingPoints" : [
{
"type": "HOTEL_PICKUP",
"description": "",
"meetingPoint": {
"type": "ADDRESS",
"description": "Private Cava and Vineyards Half-Day Tour with Hotel pick-up from Barcelona (HD)",
"address": "",
"city": "",
"zip": "",
"geolocation": null,
"country": {
"code": "ES",
"name": "Spain"
},
"area": null
},
"pickupInstructions": [
{
"code": "",
"description": ""
}
]
}
],
"endPoints" : [
{
"type": "Same",
"description": "Same as Starting Point",
"meetingPoint": null,
"pickupInstructions": []
}
]
},
"routes": [
{
"description": "Stop offs (Blue Line)",
"timeFrom": "08:30:00",
"timeTo": "21:00:00",
"duration": {
"value": 80,
"metric": "MINUTES"
},
"frequency": {
"minimum": {
"value": 40,
"metric": "MINUTES"
},
"maximum": {
"value": 40,
"metric": "MINUTES"
}
},
"points": [
{
"type": "POI",
"order": 1,
"stop": false,
"description": "",
"timeFrom": "",
"timeTo": "",
"stopTime": null,
"pointOfInterest": {
"type": "ADDRESS",
"description": "Prado Museum",
"address": "Paseo del Prado, s/n, 28014 Barcelona",
"city": "Barcelona",
"zip": "-",
"geolocation": {
"latitude": 40.413782,
"longitude": -3.692127400000004
},
"country": {
"code": "ES",
"name": ""
}
}
}
]
}
]
}
],
"cancellation": {
"type": "fully-refundable"
},
"code": "a03819c9$1108E973G",
"languages": []
}
]
}
The response is list of results, each result consists of these attributes:
| Attribute | Description |
|---|---|
| price | The gross price {amount, currency} of the result |
| netPrice | The net price {amount, currency} of this result |
| barRate | Price {amount, currency} of the BAR, the price which you are not allowed to sell below on B2C platforms. |
| confirmation | immediate or on-request |
| paymentType | pre or post, indicates whether this is a pre-paid result or a pay-at-the-venue result |
| packageRate | true or false, indicates whether this result can be sold as a stand-alone offer or if it requires to be sold as part of a package |
| commissionable | true or false, indicates whether you can apply a commission on top of the price or not |
| providers | List of the providers {id, name} that returned this result |
| specialOffers | List of special offers if they are |
| items | List of items the result id holds. The booking will be made on the result including all the items in it. The prices are only on the result level. |
| .item/eventId | Id of the event |
| .item/name | The name of the offered event |
| .item/categories | The categories {id, name} of the events |
| .item/pax | The corresponding pax from your search which this result is suitable to |
| .item/images | List of images for the event, including URLs and display properties |
| .item/thumbnail | Thumbnail image of the event |
| .item/locations | Short information about start point of the event |
| .item/duration | Duration of the event |
| .item/description | Description of the event |
| .item/subtitle | The modality name of the event |
| .item/operationDates | List of {from, to} date ranges during which the event operates |
| .item/sessions | List of {code, name} objects, the available sessions for this item |
| .item/languages | List of {code, description} objects, the languages available for this item |
| .item/featureGroups | List of grouped features, such as included or excluded services |
| ..featureGroup/groupCode | Code identifying the group (e.g., TRANSPORT, MATERIAL) |
| ..featureGroup/excluded | List of excluded features in this group |
| …excluded/featureType | Type of the excluded feature |
| …excluded/description | Description of the excluded feature |
| ..featureGroup/included | List of included features in this group |
| …included/featureType | Type of the included feature |
| …included/description | Description of the included feature |
| .item/location | Location details including start and end points |
| ..location/startingPoints | List of object, each describing {type, description, meeting points, pickup instructions} |
| ..location/endPoints | List of object, each describing {type, description, meeting points, pickup instructions} |
| .item/routes | List of available tour routes |
| ..route/description | Description of the route (e.g., East/Green route) |
| ..route/timeFrom | Starting time of the route |
| ..route/timeTo | End time of the route |
| ..route/duration | Object with value and metric of duration (e.g., 2.0 HOURS) |
| ..route/frequency | Object indicating minimum and maximum frequency of departures |
| ..route/points | List of points describing the route |
| cancellation | See below |
| code | The result code, use this for the next steps |
| languages | List of {code, name} objects, the languages this result (as opposed to a specific item, see .item/languages above) is available in |
Cancellation Policy
The cancellation policy is build from frames.
Each frame has a start date (from), end date(to), and a penalty.
These frames tells you exactly what will be the penalty on each date starting from the booking date until the check-in date.
After the check-in date the cancellation penalty should be assumed as 100%.
Details
Request
curl \
-H "aether-application-key: [app-key]" \
-X POST
-d @request-file.json
https://example.com/events/details/[eventId]
Request
The request consists of the desired eventId (in the url) and the original search by event (in the request body).
Response
{
"timestamp": 1786992700,
"requestTime": "2026-08-17 18:51:40",
"status": "done",
"completed": 100,
"sessionId": "t:111:2:2026-10-01:2026-10-31:IL:1+:EUR:610:location:b2b",
"processTime": 564,
"expireAt": "2026-08-17 19:07:02",
"results": [
{
"price": {
"amount": 428.57,
"currency": "EUR"
},
"netPrice": {
"amount": 428.57,
"currency": "EUR"
},
"barRate": null,
"confirmation": "immediate",
"paymentType": "pre",
"packageRate": false,
"commissionable": true,
"providers": [
{
"id": "12345",
"name": "example"
}
],
"specialOffers": [],
"items": [
{
"eventId": "E-E10-25AINC0029",
"name": "Private Cava and Vineyards Half-Day Tour with Hotel pick-up from Barcelona (HD)",
"categories": [
{
"id": 8,
"name": "Day Trips & Excursions"
}
],
"pax": {
"adults": 1,
"children": []
},
"images": ["https://example.com/directory/image.jpg"],
"thumbnail": "https://example.com/directory/thumbnail.jpg",
"locations": [
"Private Cava and Vineyards Half-Day Tour with Hotel pick-up from Barcelona (HD)"
],
"duration": "1 DAYS",
"description": "<p>Round-trip hotel pick-up & drop-off included.</p>",
"subtitle": "tour",
"operationDates": [
{
"from": "2026-10-01",
"to": "2026-10-01"
},
{
"from": "2026-10-02",
"to": "2026-10-02"
}
],
"sessions": [
{
"code": "08:30",
"name": "08:30"
}
],
"languages": [
{
"code": "en",
"description": "English"
}
],
"featureGroups": [
{
"groupCode": "DRINKS",
"included": [
{
"featureType": "DRINKSINCL",
"description": "Tasting of 3 cavas ."
}
],
"excluded": []
},
{
"groupCode": "MEAL",
"included": [
{
"featureType": "FOODINCL",
"description": "Traditional cheese and deli meats. "
}
],
"excluded": []
},
{
"groupCode": "UNKNOWN",
"included": [
{
"featureType": "OTHERINCL",
"description": "Guide"
}
],
"excluded": [
{
"featureType": "OTHERNOT",
"description": "Gratuities"
}
]
},
{
"groupCode": "TRANSPORT",
"included": [
{
"featureType": "TRANSPORTINCL",
"description": "Hotel pick-up and drop-off"
}
],
"excluded": []
}
],
"location": {
"startingPoints" : [
{
"type": "HOTEL_PICKUP",
"description": "",
"meetingPoint": {
"type": "ADDRESS",
"description": "Private Cava and Vineyards Half-Day Tour with Hotel pick-up from Barcelona (HD)",
"address": "",
"city": "",
"zip": "",
"geolocation": null,
"country": {
"code": "ES",
"name": "Spain"
},
"area": null
},
"pickupInstructions": [
{
"code": "",
"description": ""
}
]
}
],
"endPoints" : [
{
"type": "Same",
"description": "Same as Starting Point",
"meetingPoint": null,
"pickupInstructions": []
}
]
},
"routes": [
{
"description": "Stop offs (Blue Line)",
"timeFrom": "08:30:00",
"timeTo": "21:00:00",
"duration": {
"value": 80,
"metric": "MINUTES"
},
"frequency": {
"minimum": {
"value": 40,
"metric": "MINUTES"
},
"maximum": {
"value": 40,
"metric": "MINUTES"
}
},
"points": [
{
"type": "POI",
"order": 1,
"stop": false,
"description": "",
"timeFrom": "",
"timeTo": "",
"stopTime": null,
"pointOfInterest": {
"type": "ADDRESS",
"description": "Prado Museum",
"address": "Paseo del Prado, s/n, 28014 Barcelona",
"city": "Barcelona",
"zip": "-",
"geolocation": {
"latitude": 40.413782,
"longitude": -3.692127400000004
},
"country": {
"code": "ES",
"name": ""
}
}
}
]
}
]
}
],
"cancellation": {
"type": "fully-refundable"
},
"code": "a03819c9$1108E973G",
"languages": []
}
]
}
The response is the result for the event, you can see describing of fields in the response for method Poll
Pre-Book
curl \
-H "aether-application-key: [app-key]" \
-X POST
-d @request-file.json
https://example-booking.com/pre-book
Request content
{
"services": [
{
"searchRequest": {
"currencies": ["EUR"],
"customerCountry": "IL",
"dates": {
"from": "2026-10-01",
"to": "2026-10-31"
},
"destinations": [
{
"id": 610,
"type": "location"
}
],
"pax": [
{
"adults": 1,
"children":[]
}
],
"customFields":
[
{
"name": "source",
"value": "b2b.travel"
}
],
"filters": [],
"service": "events"
},
"searchCodes": [
{
"code": "a03819c9$1108E973G",
"quantity": 1,
"pax": [
{
"adults": 1,
"children":[]
}
],
"options": [
{
"name": "date",
"value":
{
"name": "date",
"code": "2026-10-02",
"from": "2026-10-02",
"to": "2026-10-02"
}
},
{
"name": "name",
"value": "Activities"
},
{
"name": "modality",
"value":
{
"code": "c33e7510$1108E973G",
"eventId": "E-E10-25AINC0029",
"name": "Private Cava and Vineyards Half-Day Tour with Hotel pick-up from Barcelona (HD)",
"subtitle": "tour",
"dates":
[
"2026-10-01",
"2026-10-02"
],
"price":
{
"amount": "428.57",
"currency": "EUR"
},
"token": null
}
},
{
"name": "category",
"value":
{
"id": 8,
"name": "Day Trips & Excursions"
}
},
{
"name": "language",
"value":
{
"code": "en",
"name": "English"
}
},
{
"name": "session",
"value":
{
"code": "08:30",
"name": "08:30"
}
}
]
}
],
"specialRequests": null,
"bookingRequest": [],
"login": null
}
]
}
Request
POST https://example-booking.com/pre-book
Note that this request is being sent to a different domain than the one used for searching_
| Element | Description |
|---|---|
| services | List of elements consists of the desired items you want to book |
| .service/searchRequest | The original, unchanged, search request |
| .service/searchCodes | List of codes you are planning to book |
| ..searchCode/code | The code from the result |
| ..searchCode/quantity | Quantity of tickets |
| ..searchCode/pax | The pax related to the specific code |
| ..searchCode/options | Details for your booking |
| .service/specialRequests | The special request if it is |
| .service/bookingRequest | The booking request if it is |
| .service/login | The special fields |
Custom Fields
This part is relevant for deep-integrations only, where you have your own suppliers connected via this API and need to pass parameters to specific providers.
An example of such a use-case is a B2B system that wants the agents using the system to collect loyalty points from a specific directly-contracted provider. In order to achieve that, you need to pass the agent credentials for that specific provider during search, and these credentials will be used to contact the provider.
Example of custom fields in the request
{
"customFields": {
"name": "source",
"value": "b2b.travel"
}
}
Response
Response content
{
"content": {
"Services": {
"events": [
{
"price": {
"amount": 428.57,
"currency": "EUR"
},
"priceWithoutTax": {
"amount": 428.57,
"currency": "EUR"
},
"netPrice": {
"amount": 428.57,
"currency": "EUR"
},
"taxAmount": {
"amount": 0,
"currency": "EUR"
},
"transactionFee": {
"amount": 0,
"currency": "EUR"
},
"netPriceInClientCurrency": {
"amount": 428.57,
"currency": "EUR"
},
"barRate": {
"amount": 0,
"currency": "EUR"
},
"confirmation": "immediate",
"paymentMethod": "pre",
"packageRate": false,
"commissionable": true,
"code": "a03819c9$1108E973G",
"cancellation": {
"type": "fully-refundable",
"frames": [
{
"from": "2026-08-17 00:00:00",
"to": "2026-09-29 23:59:59",
"penalty": {
"amount": 0,
"currency": "EUR"
}
},
{
"from": "2026-09-30 00:00:00",
"to": "2026-10-01 23:59:59",
"penalty": {
"amount": 428.57,
"currency": "EUR"
}
}
]
},
"token": "8FFE576A",
"items": [
{
"name": "Private Cava and Vineyards Half-Day Tour with Hotel pick-up from Barcelona (HD)",
"categories": [
{
"id": 8,
"name": "Day Trips & Excursions"
}
],
"images": [
"https://example.com/directory/image.jpg"
],
"thumbnail": "https://example.com/directory/thumbnail.jpg",
"locations": [
"Private Cava and Vineyards Half-Day Tour with Hotel pick-up from Barcelona (HD)"
],
"duration": "1 DAYS",
"description": "<p>Round-trip hotel pick-up & drop-off included.</p>",
"remarks":
{
"returnDetails": "",
"inclusions": "",
"exclusions": "",
"general": "Take a short drive around 45 minutes from all major resorts with our air-conditioned car to go to Bali Zoo where the tour takes place. Having breakfast with the adorable orangutan can be your once-in-a-lifetime experience. The trip also includes the zoo admission and animal show.<br />\n<br />\nPick up at around 06.45 am and take around 45 minutes to drive from all major tourist resorts to the Bali zoo. Start your day to see the amazing orangutan while having breakfast. See how they play cheerfully, and take a picture with them as it will definitely be your unforgettable experience. Look around to see the Bali zoo animal collections and witness how your visit helps them all to have a safe, warm and peaceful place to live.",
"termsAndConditions": "",
"importantInfo": "Please make sure you answer all the mandatory questions during the booking process.</br>",
"info": ""
},
"questions": [
{
"id": "EMAIL",
"message": "Please provide an email address",
"type": "free text",
"required": true,
"title": "",
"subTitle": "",
"options": []
},
{
"id": "HOTEL",
"message": "Please provide the name of your hotel",
"type": "free text",
"required": true,
"title": "",
"subTitle": "",
"options": []
},
{
"id": "PHONENUMBER",
"message": "Guests telephone with international code required",
"type": "free text",
"required": true,
"title": "",
"subTitle": "",
"options": [],
"pattern": "^\\+?[0-9\\s\\-\\(\\)]{7,20}$",
"placeholder": "+1 234 567 8900"
}
],
"pax": [
{
"adults": 1,
"children":[]
}
],
"eventId": "E-E10-25AINC0029",
"location": {
"startingPoints" : [
{
"type": "HOTEL_PICKUP",
"description": "",
"meetingPoint": {
"type": "ADDRESS",
"description": "Private Cava and Vineyards Half-Day Tour with Hotel pick-up from Barcelona (HD)",
"address": "",
"city": "",
"zip": "",
"geolocation": null,
"country": {
"code": "ES",
"name": "Spain"
},
"area": null
},
"pickupInstructions": [
{
"code": "",
"description": ""
}
]
}
],
"endPoints" : [
{
"type": "Same",
"description": "Same as Starting Point",
"meetingPoint": null,
"pickupInstructions": []
}
]
},
"featureGroups": [
{
"groupCode": "DRINKS",
"included": [
{
"featureType": "DRINKSINCL",
"description": "Tasting of 3 cavas ."
}
],
"excluded": []
},
{
"groupCode": "MEAL",
"included": [
{
"featureType": "FOODINCL",
"description": "Traditional cheese and deli meats. "
}
],
"excluded": []
},
{
"groupCode": "UNKNOWN",
"included": [
{
"featureType": "OTHERINCL",
"description": "Guide"
}
],
"excluded": [
{
"featureType": "OTHERNOT",
"description": "Gratuities"
}
]
},
{
"groupCode": "TRANSPORT",
"included": [
{
"featureType": "TRANSPORTINCL",
"description": "Hotel pick-up and drop-off"
}
],
"excluded": []
}
],
"languages": [
{
"code": "en",
"description": "English",
"name": null
}
],
"vouchers": [
{
"code" : "1234567",
"language" : "EN",
"url" : "https://voucher-service/voucher/111",
"mimeType" : "text/html",
"dateFrom" : "2026-10-02",
"dateTo" : "2026-10-02"
}
]
}
],
"surcharges": [
{
"price": {
"amount": 20,
"currency": "EUR"
},
"payment": "excluded",
"title": "City tax",
"mandatory": true,
"description": ""
},
{
"price": {
"amount": 8.3,
"currency": "EUR"
},
"payment": "included",
"title": "Occupancy tax",
"mandatory": true,
"description": ""
}
],
"requestCode": "a03819c9$1108E973G",
"providers": [
{
"id": "12345",
"name": "example"
}
],
"languages": [
{
"code": "en",
"description": "English"
}
]
}
]
},
"PaymentMethods": [
{
"methodName": "account_credit",
"methodDescription": "",
"paymentSettings": {
"creditCardForm": false,
"requiredFields": [],
"processingFee": 0
},
"status": "enabled",
"title": "account_credit"
},
{
"methodName": "credit_card",
"methodDescription": "",
"paymentSettings": {
"creditCardForm": true,
"requiredFields": [],
"processingFee": "0.023"
},
"status": "enabled",
"title": "credit_card"
}
],
"ImmediateCharge": true,
"PaymentDueDate": "2026-10-02",
"LoyaltyPoints": [
{
"points": 38,
"expectedAmount": {
"amount": 0.38,
"currency": "EUR"
},
"expiryDays": 360
}
],
"AvailablePoints": [
{
"codes": [
"a03819c9$1108E973G"
],
"points": 533,
"pointsToAmount": {
"amount": 5.33,
"currency": "EUR"
}
}
],
"AutoCancellation": true
},
"status": "done"
}
The response is list of events, each event consists of these attributes:
| Element | Description |
|---|---|
| Services | The result for booking |
| .events | List of events for booking |
| ..price | The gross price {amount, currency} of the booking |
| ..priceWithoutTax | The gross price {amount, currency} minus the tax amount |
| ..netPrice | The net price {amount, currency} of the booking |
| ..taxAmount | The amount of the tax {amount, currency}, if applicable |
| ..transactionFee | Any additional fee {amount, currency} that may apply for the cost of processing the transaction |
| ..netPriceInClientCurrency | Normalized amount {amount, currency} to the currency you requested |
| ..barRate | The minimum price {amount, currency} that can be shown on B2C website |
| ..confirmation | immediate or on-request |
| ..paymentMethod | pre or post |
| ..packageRate | true or false, indicates whether this result can be sold as a stand-alone offer or if it requires to be sold as part of a package |
| ..commissionable | true or false, indicates whether you can apply a commission on top of the price or not |
| ..code | The event code |
| ..cancellation | The cancellation policies, see the search response for details |
| ..token | The booking token you will have to send in order to make the actual booking |
| ..items | List of items the result id holds |
| …item/name | The event name |
| …item/categories | The categories {id, name} of the events |
| …item/images | List of images for the event, including URLs and display properties |
| …item/thumbnail | Thumbnail image of the event |
| …item/locations | Short information about start point of the event |
| …item/duration | Duration of the event |
| …item/description | Description of the event |
| …item/remarks | List of remarks |
| …item/questions | List of questions |
| ….question/id | Code of question |
| ….question/message | The question text |
| ….question/type | Type of question. Can be free text |
| ….question/required | Mandatory of answer true or false |
| ….question/title | Title of the question |
| ….question/subTitle | Subtitle of the question |
| ….question/options | List of option for question |
| ….question/placeholder | Placeholder for question |
| ….question/pattern | Pattern for question |
| ….question/field_type | Type of field for question |
| …item/pax | The corresponding pax from your search which this result is suitable to |
| …item/eventId | The eventid |
| …item/location | Location details including start and end points |
| ….location/startingPoints | List of object, each describing {type, description, meeting points, pickup instructions} |
| ….location/endPoints | List of object, each describing {type, description, meeting points, pickup instructions} |
| …item/featureGroups | List of grouped features, such as included or excluded services |
| ….featureGroup/groupCode | Code identifying the group (e.g., TRANSPORT, MATERIAL) |
| ….featureGroup/excluded | List of excluded features in this group |
| …..excluded/featureType | Type of the excluded feature |
| …..excluded/description | Description of the excluded feature |
| ….featureGroup/included | List of included features in this group |
| …..included/featureType | Type of the included feature |
| …..included/description | Description of the included feature |
| …item/languages | List of {code, description} objects, the languages available for this item |
| …item/vouchers | List of vouchers for the event |
| ….voucher/code | Code of voucher |
| ….voucher/language | Language of voucher |
| ….voucher/url | URL for the voucher |
| ….voucher/mimeType | Type of voucher |
| ….voucher/dateFrom | Date of start for bookings |
| ….voucher/dateTo | Date of end for bookings |
| ..surcharges | Any additional surcharges applied to the price |
| …surcharges/price | The price {amount, currency} of the surcharge |
| …surcharges/payment | included or excluded or direct |
| …surcharges/title | The name of the surcharge |
| …surcharges/mandatory | true or false |
| …surcharges/description | The description of the surcharge |
| ..requestCode | The code you sent in the request |
| ..providers | List of the providers {id, name} that returned this result |
| ..languages | List of {code, name} objects, the languages this result (as opposed to a specific item, see .item/languages above) is available in |
| PaymentMethods | List of payment methods for this booking |
| .paymentMethod/methodName | The name of the payment method. a standard integration will use account_credit or credit_card. |
| .paymentMethod/methodDescription | Description of the method, for example if the method is a saved credit card token on the account, the description can say something like “Credit card ending with 1234” |
| .paymentMethod/paymentSettings | Specific settings for the payment method |
| .paymentMethod/status | Whether this option is enabled for this booking |
| .paymentMethod/title | The short name of the payment method |
| ImmediateCharge | true or false |
| PaymentDueDate | Date of payment |
| LoyaltyPoints | List of loyalty points |
| AvailablePoints | List of available points |
| AutoCancellation | true or false |
| status | Status of response |
Book
Request
POST https://example-booking.com/book
Note that this request is being sent to a different domain than the one used for searching
{
"reference":
{
"agency": "my agency reference",
"voucherEmail": "test@example.com"
},
"customer":
{
"title": "MR",
"name":
{
"first": "Testa",
"last": "Test"
},
"birthDate": "1990-01-01",
"contact":
{
"country": "IL",
"city": "N/A",
"state": "N/A",
"address": "N/A",
"phone": "N/A",
"zip": "N/A",
"email": "testa@example.com",
"passportNumber": ""
}
},
"paymentMethod":
{
"methodName": "account_credit",
"securePaymentUrl": "https://b2b.travel/111"
},
"paymentSettings":
{
"paymentAmount": "net",
"paymentDate": "billing-terms",
"transactionFeeCharge": true
},
"services": [
{
"searchRequest": {
"currencies": ["EUR"],
"customerCountry": "IL",
"dates": {
"from": "2026-10-01",
"to": "2026-10-31"
},
"destinations": [
{
"id": 610,
"type": "location"
}
],
"pax": [
{
"adults": 1,
"children":[]
}
],
"customFields":
[
{
"name": "source",
"value": "b2b.travel"
}
],
"filters": [],
"service": "events"
},
"bookingRequest": [
{
"code": "a03819c9$1108E973G",
"token": "12409BCC",
"pax": [
{
"adults": [
{
"name": {
"first": "Testa",
"last": "Test"
},
"title": "MR",
"birthDate": "1990-01-01",
"lead": 1,
"contact":
{
"country": "IL",
"state": "N/A",
"address": "N/A",
"phone": "N/A",
"zip": "N/A",
"city": "N/A",
"email": "testa@example.com"
}
}
]
}
],
"options": [
{
"name": "date",
"value":
{
"name": "date",
"code": "2026-10-02",
"from": "2026-10-02",
"to": "2026-10-02"
}
},
{
"name": "name",
"value": "Activities"
},
{
"name": "modality",
"value":
{
"code": "c33e7510$1108E973G",
"eventId": "E-E10-25AINC0029",
"name": "Private Cava and Vineyards Half-Day Tour with Hotel pick-up from Barcelona (HD)",
"subtitle": "tour",
"dates":
[
"2026-10-01",
"2026-10-02"
],
"price":
{
"amount": "428.57",
"currency": "EUR"
},
"token": null
}
},
{
"name": "category",
"value":
{
"id": 8,
"name": "Day Trips & Excursions"
}
},
{
"name": "language",
"value":
{
"code": "en",
"name": "English"
}
},
{
"name": "session",
"value":
{
"code": "08:30",
"name": "08:30"
}
},
{
"name": "questions",
"value": [
{
"id": "EMAIL",
"value": "testa@example.com"
},
{
"id": "HOTEL",
"value": "Hotel name"
},
{
"id": "PHONENUMBER",
"value": "+1 (604) 897-7291"
}
]
}
]
}
]
}
]
}
| Element | Description |
|---|---|
| reference | The references {agency, voucherEmail} |
| customer | The customer details of the customer that is making the booking. |
| paymentMethod | List of payment methods for this booking |
| .paymentMethod/methodName | The name of the payment method. a standard integration will use account_credit or credit_card. |
| .paymentMethod/securePaymentUrl | URL for the payment method |
| paymentSettings | Details for payment methods {paymentAmount, paymentDate, transactionFeeCharge} |
| services | List of elements consists of the desired items you want to book |
| .service/searchRequest | The original, unchanged, search request |
| .service/specialRequests | The special request if it is |
| .service/bookingRequest | List of booking details |
| ..bookingRequest/code | The code for booking |
| ..bookingRequest/token | the token from the pre-book call |
| ..bookingRequest/pax | The pax with information about passengers |
| ..bookingRequest/options | Details for your booking |
In case you want to send a booking request for children, the child element must include another attribute called “birthDate” with a date value in the format YYYY-MM-DD.
Example of a children node:
“children”: [
{
”birthDate”: “2014-04-20”
”name”: {
”first”: “test”,
”last”: “test”
},
”title”: “C”
}
]
Response
Response content
{
"content": {
"bookingID": 123456,
"bookingDate": "2019-07-16",
"status": "confirmed",
"customer": {
"title": "MR",
"name": {
"first": "Testa",
"last": "Test"
},
"birthDate": "1990-01-01",
"contact": {
"country": "IL",
"city": "N/A",
"state": "N/A",
"address": "N/A",
"phone": "N/A",
"zip": "N/A",
"email": "testa@example.com",
"passportNumber": ""
},
"create": false
},
"price": {
"amount": 428.57,
"currency": "EUR"
},
"netPrice": {
"amount": 428.57,
"currency": "EUR"
},
"taxAmount": null,
"commissionAmount": null,
"services": [
{
"event": {
"name": "Private Cava and Vineyards Half-Day Tour with Hotel pick-up from Barcelona (HD)",
"categories": [
{
"id": 8,
"name": "Day Trips & Excursions"
}
],
"images": [
"https://example.com/directory/image.jpg"
],
"thumbnail": "https://example.com/directory/thumbnail.jpg",
"locations": [
"Private Cava and Vineyards Half-Day Tour with Hotel pick-up from Barcelona (HD)"
],
"duration": "1 DAYS",
"description": "<p>Round-trip hotel pick-up & drop-off included.</p>",
"eventId": 0,
"options": [
{
"name": "date",
"value": {
"name": "date",
"code": "2026-10-02",
"from": "2026-10-02",
"to": "2026-10-02"
},
"code": null
},
{
"name": "name",
"value": "Activities",
"code": null
},
{
"name": "modality",
"value": {
"code": "c33e7510$1108E973G",
"eventId": "E-E10-25AINC0029",
"name": "Private Cava and Vineyards Half-Day Tour with Hotel pick-up from Barcelona (HD)",
"subtitle": "tour",
"dates": [
"2026-10-01",
"2026-10-02"
],
"price": {
"amount": "428.57",
"currency": "EUR"
},
"token": null
},
"code": null
},
{
"name": "category",
"value": {
"id": 8,
"name": "Day Trips & Excursions"
},
"code": null
},
{
"name": "language",
"value": {
"code": "en",
"name": "English"
},
"code": null
},
{
"name": "session",
"value": {
"code": "08:30",
"name": "08:30"
},
"code": null
},
{
"name": "questions",
"value": [
{
"id": "EMAIL",
"value": "testa@example.com"
},
{
"id": "HOTEL",
"value": "Hotel name"
},
{
"id": "PHONENUMBER",
"value": "+1 (604) 897-7291"
}
],
"code": null
}
]
},
"answers":
[
{
"id": "EMAIL",
"title": "",
"value": "testa@example.com"
},
{
"id": "HOTEL",
"title": "",
"value": "Hotel name"
},
{
"id": "PHONENUMBER",
"title": "",
"value": "+1 (604) 897-7291"
}
],
"extendedOptions":
{
"options": null,
"lead": null,
"location": {
"startingPoints" : [
{
"type": "HOTEL_PICKUP",
"description": "",
"meetingPoint": {
"type": "ADDRESS",
"description": "Private Cava and Vineyards Half-Day Tour with Hotel pick-up from Barcelona (HD)",
"address": "",
"city": "",
"zip": "",
"geolocation": null,
"country": {
"code": "ES",
"name": "Spain"
},
"area": null
},
"pickupInstructions": [
{
"code": "",
"description": ""
}
]
}
],
"endPoints" : [
{
"type": "Same",
"description": "Same as Starting Point",
"meetingPoint": null,
"pickupInstructions": []
}
]
},
"featureGroups": [
{
"groupCode": "DRINKS",
"included": [
{
"featureType": "DRINKSINCL",
"description": "Tasting of 3 cavas ."
}
],
"excluded": []
},
{
"groupCode": "MEAL",
"included": [
{
"featureType": "FOODINCL",
"description": "Traditional cheese and deli meats. "
}
],
"excluded": []
},
{
"groupCode": "UNKNOWN",
"included": [
{
"featureType": "OTHERINCL",
"description": "Guide"
}
],
"excluded": [
{
"featureType": "OTHERNOT",
"description": "Gratuities"
}
]
},
{
"groupCode": "TRANSPORT",
"included": [
{
"featureType": "TRANSPORTINCL",
"description": "Hotel pick-up and drop-off"
}
],
"excluded": []
}
],
"languages": [
{
"code": "en",
"description": "English",
"name": null
}
]
},
"vouchers" : [
{
"code" : "1234567",
"language" : "EN",
"url" : "https://voucher-service/voucher/111",
"mimeType" : "text/html",
"dateFrom" : "2026-10-02",
"dateTo" : "2026-10-02"
}
],
"itemId": 1,
"service": "events",
"startDate": "2026-10-02",
"endDate": "2026-10-02",
"paymentType": "pre",
"quantity": 1,
"code": "a03819c9$1108E973G",
"status": "confirmed",
"supplier": {
"reference": "111-12345"
},
"price": {
"amount": 428.57,
"currency": "EUR"
},
"taxAmount": null,
"netPrice": {
"amount": 428.57,
"currency": "EUR"
},
"cancellation": {
"type": "fully-refundable",
"frames": [
{
"from": "2026-08-17 00:00:00",
"to": "2026-09-29 23:59:59",
"penalty": {
"amount": 0,
"currency": "EUR"
}
},
{
"from": "2026-09-30 00:00:00",
"to": "2026-10-01 23:59:59",
"penalty": {
"amount": 428.57,
"currency": "EUR"
}
}
]
},
"pax": [
{
"adults": [
{
"name": {
"first": "Testa",
"last": "Test"
},
"title": "MR",
"birthDate": "1990-01-01",
"lead": 1,
"contact":
{
"country": "IL",
"state": "N/A",
"address": "N/A",
"phone": "N/A",
"zip": "N/A",
"city": "N/A",
"email": "testa@example.com"
}
}
]
}
],
"surcharges": [
{
"price": {
"amount": 20,
"currency": "EUR"
},
"payment": "excluded",
"title": "City tax",
"mandatory": true,
"description": ""
},
{
"price": {
"amount": 8.3,
"currency": "EUR"
},
"payment": "included",
"title": "Occupancy tax",
"mandatory": true,
"description": ""
}
],
"remarks": {
"returnDetails": "",
"general": "<p>A private tour that gives you the opportunity to discover the flavours and colours of the enchanting <strong>Chianti wine region between Florence and Siena</strong>!</p><p>An unforgettable full day chauffeur-driven tour in the heart of Chianti, far from the hustle and bustle of Florence.</p><p> </p><p>Let your personal chauffeur do all the work and take you on a journey through the spellbinding countryside of Chianti, a region known for its scenic beauty, picturesque villages and pure air. Your chauffeur will pick you up from your hotel and take you for a 30-minute drive through beautiful rolling hills, verdant vineyards and olive trees; he will be more than happy to stop along the road and let you take some wonderful pictures whenever you see something that catches your eye. Relax and enjoy the scenery, the first stop on the tour is just around the corner!</p><p> </p><p>The Chianti wine region needs no introduction, and its marvelous landscape is literally dotted with picture postcard tiny villages and magnificent castles dominating sunny rolling hills. Don't forget to visit <strong>Greve in Chianti, Panzano in Chianti or Montefioralle</strong>, some of the most beautiful and authentic Chianti villages: tiny squares, delicious patios decorated with flowers, small artisans' shops and local wineries where you can taste the world renowned <strong>Chianti Classico red wine (if option selected)</strong>. </p><p> </p><p>Your personal driver will be at your complete disposal for the whole day, so you can choose whether to express to him your preferences or to let him take you on an unforgettable journey in <strong>the heart of Tuscany</strong>!</p><p> </p><p>A private tour that gives you the opportunity to discover the flavors and colors of the enchanting Chianti wine region between Florence and Siena!</p>",
"importantInfo": "Please make sure you answer all the mandatory questions during the booking process. "
},
"reference": null,
"providers": [
{
"id": "12345",
"name": "example"
}
]
}
],
"payment": {
"method": "account_credit",
"clearingState": null,
"paymentStatus": "unpaid"
},
"options": {
"emails": []
},
"reference": {
"agency": "my agency reference",
"voucherEmail": "test@example.com"
},
"behalf": null
},
"status": "done"
}
Most of the details are a reflection of the data sent by you. the following details are of notice:
| Element | Description |
|---|---|
| bookingID | The Innstant system booking ID |
| bookingDate | Date of bookin |
| status | Status of booking can be confirmed or cancelled or failed |
| customer | The customer details of the customer that is making the booking. |
| price | The gross price {amount, currency} of the booking |
| netPrice | The net price {amount, currency} of the booking |
| taxAmount | The amount of the tax {amount, currency}, if applicable |
| commissionAmount | The amount of the commission {amount, currency} |
| services | List of bookings details |
| .service/event | Objec event |
| ..event/name | The event name |
| ..event/categories | The categories {id, name} of the events |
| ..event/images | List of images for the event, including URLs and display properties |
| ..event/thumbnail | Thumbnail image of the event |
| ..event/locations | Short information about start point of the event |
| ..event/duration | Duration of the event |
| ..event/description | Description of the event |
| ..event/options | Details for your booking |
| .service/answers | Answers for question |
| .service/extendedOptions | Additional details for your booking |
| ..extendedOption/location | Location details including start and end points |
| …location/startingPoints | List of object, each describing {type, description, meeting points, pickup instructions} |
| …location/endPoints | List of object, each describing {type, description, meeting points, pickup instructions} |
| ..extendedOption/featureGroups | List of grouped features, such as included or excluded services |
| …featureGroup/groupCode | Code identifying the group (e.g., TRANSPORT, MATERIAL) |
| …featureGroup/excluded | List of excluded features in this group |
| ….excluded/featureType | Type of the excluded feature |
| ….excluded/description | Description of the excluded feature |
| …featureGroup/included | List of included features in this group |
| ….included/featureType | Type of the included feature |
| ….included/description | Description of the included feature |
| ..extendedOption/languages | List of {code, description} objects, the languages available for this item |
| .service/vouchers | List of vouchers for the event |
| ..voucher/code | Code of voucher |
| ..voucher/language | Language of voucher |
| ..voucher/url | URL for the voucher |
| ..voucher/mimeType | Type of voucher |
| ..voucher/dateFrom | Date of start for bookings |
| ..voucher/dateTo | Date of end for bookings |
| .service/itemId | Number of event |
| .service/sevice | Type of service |
| .service/startDate | Date of start for bookings |
| .service/endDate | Date of end for bookings |
| .service/paymentMethod | pre or post |
| .service/quantity | Quantity of event |
| .service/code | The event code |
| .service/status | Status of booking |
| .service/supplier | Supplier reference |
| .service/price | The gross price {amount, currency} of the booking |
| .service/taxAmount | The amount of the tax {amount, currency}, if applicable |
| .service/netPrice | The net price {amount, currency} of the booking |
| .service/cancellation | The cancellation policies, see the search response for details |
| .service/pax | The corresponding pax from your search which this result is suitable to |
| .service/surcharges | List of surcharges applied to the price |
| ..surcharges/price | The price {amount, currency} of the surcharge |
| ..surcharges/payment | included or excluded or direct |
| ..surcharges/title | The name of the surcharge |
| ..surcharges/mandatory | true or false |
| ..surcharges/description | The description of the surcharge |
| .service/remarks | List of remarks |
| .service/providers | List of the providers {id, name} for this booking |
| payment | Object payment methods for this booking |
| .payment/method | The name of the payment method. a standard integration will use account_credit or credit_card. |
| .payment/paymentStatus | Whether this option is enabled for this booking |
| reference | The references {agency, voucherEmail} |
| status | Status of response |
Cancel
Request content
{
"BookingID": 123456,
"CancelReason": "The dog is sick",
"Force": false,
"IsManual": true
}
Request
POST https://example.com/booking-cancel
| Attribute | Description |
|---|---|
| BookingID | The booking ID you would like to cancel |
| CancelReason | The reason for the cancellation, can be left blank |
| Force | Should the booking be cancelled in any case, without calling the provider - USE FALSE UNLESS YOU KNOW WHAT YOU ARE DOING |
| IsManual | Is the booking being cancelled by a human request or by an automated process |
Respone
Response content
{
"content": {
"BookingID": 123456,
"BookingTime": "2026-09-01 11:27:41",
"TechnicalStatus": "confirmed"
},
"status": "done"
}
| Attribute | Description |
|---|---|
| BookingID | The booking ID |
| BookingTime | Datetime when the booking was cancelled |
| TechnicalStatus | Status for method cancel. confirmed if the booking was cancelled successfully |
| status | Status of response |
Booking Details
Request
GET https://example.com/booking-details/[booking-id]
| Attribute | Description |
|---|---|
| BookingID | The booking ID you would like to get details for |
Response
The response is the same as booking response
Transfers
Flow
The common case usage is quite simple:
- Initiate a search
- Poll to get results
- run a pre-book call
- book
Search
Request
curl \
-H "aether-application-key: [app-key]" \
-X POST
-d @request-file.json
https://example.com/transfers/search
Request content
{
"currencies": ["USD"],
"customerCountry": "IL",
"customFields": [],
"pickupDateTime": "2026-01-25 11:45:00Z",
"pickupDateTimeReturn": "2026-01-29 10:14:00Z",
"vehicleType": [],
"pickupLocation": {
"id": 2188,
"type": "terminal"
},
"dropoffLocation": {
"id": 141836,
"type": "hotel"
},
"pax": [
{
"adults": 2,
"children": []
}
],
"checkedLuggage": 2,
"carryOnLuggage": 2,
"service": "transfers"
}
Request
POST https://example.com/transfers/search
| Attribute | Description |
|---|---|
| currencies | A list of currencies you wish to get your results in. The first currency on the list will be the default currency of the search |
| customerCountry | 2 letter ISO code of the customer country running the search. Note: that the same customer country must be used on the booking, and giving a wrong or inaccurate customer country may result in the hotel not honoring the booking |
| customFields | See below |
| pickupDateTime | The date and time of the start of the direct trip, format: YYYY-MM-DDTHH:MM:SSZ |
| pickupDateTimeReturn | The date and time of the start of return trip, format: YYYY-MM-DDTHH:MM:SSZ. Note If you have one way trip you shouldn’t include this field in the request |
| vehicleType | See below |
| pickupLocation | The departure point for the trip |
| .id | The entity id of the type |
| .type | The type, can be either hotel or terminal or seaport or railway |
| dropoffLocation | The destination for the trip |
| .id | The entity id of the type |
| .type | The type, can be either hotel or terminal or seaport or railway |
| pax | See below |
| checkedLuggage | Number of pieces of luggage |
| carryOnLuggage | Number of pieces of carryOnLuggage |
Important!
Date and time must be in local time of the pickup location.
One of the location must be a hotel. Therefore, it is not possible to book a trip between two airports or an airport and a seaport.
custom fields
This part is relevant for deep-integrations only, where you have your own suppliers connected via this API and need to pass parameters to specific providers.
An example of such a use-case is a B2B system that wants the agents using the system to collect loyalty points from a specific directly-contracted provider. In order to achieve that, you need to pass the agent credentials for that specific provider during search, and these credentials will be used to contact the provider.
Example of custom fields in the request
{
"customFields": {
"agentId": 1,
"whatever": "shalgon"
}
}
vehicleType
The following vehicle categories are available.
| Type | VehicleType |
|---|---|
| Private vehicle categories | SEDAN, STATIONWAGON, SUV, MINIVAN, BUSINESS_SEDAN, STRETCH_LIMOUSINE, MINIBUS, STANDARD_ELECTRIC_CAR, EXCLUSIVE_MINIVAN, LUXURY_SEDAN, HIGH_END_ELECTRIC_CAR, ECONOMY_SEDAN, HELICOPTER, VAN, BUS, MPV, COACH |
| Shared vehicle categories | SHUTTLE, SPEEDY_SHUTTLE, EVENT_SHUTTLE, DIRECT_SHUTTLE |
For example, to find a transfer of the required type, you need to create an object of the following type:
“vehicleType”: [“SEDAN”, “SUV”, “MINIVAN”]
Please note - if you do not specify any vehicle in this field, the search will be performed across all types of vehicles.
Example of vehicleType in the request
{
"vehicleType": ["SEDAN", "SUV", "MINIVAN"]
}
pax
The pax defines the desired trip participant configuration.
It is an object consisting of the adults and children elements, where the children element is an array specifying ages.
For example, to find a transfer for 1 adult and 2 children, ages 12 and 14, you would create an object like this:
{
“adults”: 1,
“children”: [12,14]
}
Example of pax in the request
{
"pax": [
{
"adults": 1,
"children": [12, 14]
}
]
}
Response
The response will return the results received until the search was completed.
Response
{
"timestamp": 1764160052,
"requestTime": "2025-11-27 16:01:24",
"status": "done",
"completed": 100,
"sessionId": "tr:50641:2:2026-01-25_11:45:00:2026-01-29_10:14:00:IL:2+:USD:d41d8cd98f00b204e9800998ecf8427e:2188:terminal:141836:hotel:2:2:b2b",
"processTime": 367,
"expireAt": "2025-11-27 16:16:29",
"results": [
{
"price": {
"amount": 160.2,
"currency": "USD"
},
"netPrice": {
"amount": 160.2,
"currency": "USD"
},
"barRate": {
"amount": 160.2,
"currency": "USD"
},
"confirmation": "immediate",
"paymentType": "pre",
"packageRate": false,
"commissionable": true,
"providers": [
{
"id": 123,
"name": "Name of providers"
}
],
"specialOffers": [],
"items": [
{
"transferId": "4190828522",
"pax": {
"adults": 2,
"children": []
},
"images": ["https://example.com/economy-sedan.jpg"],
"waitingTime": 45,
"expires": "2025-11-27 17:16:32+00:00",
"passengerCapacity": 3,
"luggageCapacity": 3,
"VehicleCategory": "ECONOMY_SEDAN",
"vehicleModels": "Buick GL8, Toyota Allion, Toyota Prius Plus, Nissan Versa, Volkswagen Touran",
"addons": [
{
"id": 22003755618,
"name": "SPECIAL_LUGGAGE",
"price": {
"amount": 6,
"currency": "USD"
},
"maxAllowed": 1
},
{
"id": 22003755626,
"name": "BABY_SEAT",
"price": {
"amount": 6,
"currency": "USD"
},
"maxAllowed": 1
},
{
"id": 22003755667,
"name": "MEET_GREET",
"price": {
"amount": 0,
"currency": "USD"
},
"maxAllowed": 1
}
],
"forwardDirection": true,
"freeCancellationUntil": "2026-01-24 11:44:52+00:00"
},
{
"transferId": "4190828369",
"pax": {
"adults": 2,
"children": []
},
"images": ["https://example.com/economy-sedan.jpg"],
"waitingTime": 15,
"expires": "2025-11-27 17:16:31+00:00",
"passengerCapacity": 3,
"luggageCapacity": 3,
"VehicleCategory": "ECONOMY_SEDAN",
"vehicleModels": "Buick GL8, Toyota Allion, Toyota Prius Plus, Nissan Versa, Volkswagen Touran",
"addons": [
{
"id": 22003754742,
"name": "SPECIAL_LUGGAGE",
"price": {
"amount": 6,
"currency": "USD"
},
"maxAllowed": 1
},
{
"id": 22003754752,
"name": "BABY_SEAT",
"price": {
"amount": 6,
"currency": "USD"
},
"maxAllowed": 1
}
],
"forwardDirection": false,
"freeCancellationUntil": "2026-01-28 10:14:00+00:00"
}
],
"cancellation": {
"type": "fully-refundable",
"frames": [
{
"from": "2025-11-27 15:46:32",
"to": "2026-01-24 11:44:51",
"penalty": {
"amount": 0,
"currency": "USD"
}
},
{
"from": "2026-01-24 11:44:52",
"to": "2026-01-25 11:44:44",
"penalty": {
"amount": 160.2,
"currency": "USD"
}
}
]
},
"code": "4190828522_4190828369$1086E973G",
"languages": [],
"origin": {
"bookerEnteredAddress": "Dubai Airport (DXB), Dubai, Dubai, United Arab Emirates",
"resolvedAddress": "Dubai Airport (DXB), Dubai, Dubai, United Arab Emirates",
"fullResolvedAddress": {
"streetName": "",
"streetNumber": "",
"city": "Dubai",
"postalCode": "",
"region": "Dubai",
"countryCode": "AE",
"establishment": "Dubai Airport"
},
"latitude": 25.248665,
"longitude": 55.352917,
"iataCode": "DXB",
"type": "terminal"
},
"destination": {
"bookerEnteredAddress": "Sofitel Abu Dhabi Corniche, Corniche Road East Capital Plaza Complex, PO Box 44966, Abu Dhabi, AE",
"resolvedAddress": "Sofitel Abu Dhabi Corniche, Capital Plaza Complex - Corniche Rd E - Al Danah - E9-01 - Abu Dhabi - United Arab Emirates",
"fullResolvedAddress": {
"streetName": "Corniche Road East",
"streetNumber": "",
"city": "Abu Dhabi",
"postalCode": "",
"region": "Abu Dhabi",
"countryCode": "AE",
"establishment": "Sofitel Abu Dhabi Corniche"
},
"latitude": 24.4991793,
"longitude": 54.3678277,
"iataCode": "",
"type": "hotel"
}
}
]
}
The response is an array of results and some common attributes.
Common attributes:
| Attribute | Description |
|---|---|
| sessionId | The session ID of the search |
| status | The status of the search, whether it is done, working, or failed |
| timestamp | The server timestamp of the response. this can be used to poll by delta |
| requestTime | The request date time in Human readable format |
| completed | Integer, percentage of the progress. 0 means no tasks were completed, 100 means all tasks were completed, everything in between in “in process”. Please note this attribute is for Hubwayz’s internal use only. To check if the search was completed or not please refer only to the status property. |
| processTime | Processing time in milliseconds. |
Attributes for array of results:
| Attribute | Description |
|---|---|
| price | The gross price (amount/currency) of the result |
| netPrice | The net price (amount/currency) of this result |
| barRate | Price (amount/currency) of the BAR, the price which you are not allowed to sell below. |
| confirmation | immediate or on-request |
| paymentType | pre or post |
| packageRate | boolean, indicates whether this result can be sold as a stand-alone offer or if it requires to be sold as part of a package |
| commissionable | boolean, indicates whether you can apply a commission on top of the price or not |
| providers | Provider code and name |
| specialOffers | Special offers |
| items | An array of items the result id holds. The booking will be made on the result including all the items in it. The prices are only on the result level. |
| .transferId | The entity id of transfer |
| .pax | the corresponding pax from your search which this result is suitable to |
| .images | Array of the vehicle images |
| .waitingTime | Waiting time |
| .expires | Date and time of vehicle search |
| .passengerCapacity | Maximum number of passengers |
| .luggageCapacity | Maximum number of luggage |
| .VehicleCategory | Vehicle category |
| .vehicleModels | Vehicle models |
| .addons | Additional amenities |
| ..id | The entity id of addon |
| ..name | The name of addon |
| ..price | The price of addon (amount/currency) |
| ..maxAllowed | Max number of this addon |
| .forwardDirection | true or false |
| .freeCancellationUntil | Free cancellation |
| cancellation | See below |
| code | The result code, use this for the next steps |
| languages | An array of languages |
| origin | Place of departure of the trip |
| .bookerEnteredAddress | The address of departure |
| .resolvedAddress | The address of departure |
| .fullResolvedAddress | The full address of departure |
| .latitude | Coordinates of departure |
| .longitude | Coordinates of departure |
| .iataCode | Code of country |
| .type | The type of departure |
| destination | Place of destination of the trip |
| .bookerEnteredAddress | The address of destination |
| .resolvedAddress | The address of destination |
| .fullResolvedAddress | The full address of destination |
| .latitude | Coordinates of destination |
| .longitude | Coordinates of destination |
| .iataCode | Code of country |
| .type | The type of destination |
Cancellation Policy
The cancellation policy is build from frames.
Each frame has a start date (from), end date(to), and a penalty.
These frames tells you exactly what will be the penalty on each date starting from the booking date until the check-in date.
After the check-in date the cancellation penalty should be assumed as 100%.
Poll
Request
curl \
-H "aether-application-key: [app-key]" \
-X POST
-d @request-file.json
https://example.com/transfers/poll
Request content
{
"currencies": ["USD"],
"customerCountry": "IL",
"customFields": [],
"pickupDateTime": "2026-01-25 11:45:00Z",
"pickupDateTimeReturn": "2026-01-29 10:14:00Z",
"vehicleType": [],
"pickupLocation": {
"id": 2188,
"type": "terminal"
},
"dropoffLocation": {
"id": 141836,
"type": "hotel"
},
"pax": [
{
"adults": 2,
"children": []
}
],
"checkedLuggage": 2,
"carryOnLuggage": 2,
"service": "transfers"
}
Request
POST https://example.com/transfers/poll
The poll request & response are identical to the search request & response with the exception of the endpoint.
You can send as many polls as you like until the status in the response is working. Once it finishes, the status changes to done and this means no new results will show up in your next poll.
Check out the Flow chapter in the beginning to get a better understanding of this method.
Note that the search and poll requests must be identical.
Pre-Book
Request content
{
"services": [
{
"searchRequest": {
"currencies": ["USD"],
"customerCountry": "IL",
"customFields": [],
"pickupDateTime": "2026-01-25 11:45:00Z",
"pickupDateTimeReturn": "2026-01-29 10:14:00Z",
"vehicleType": [],
"pickupLocation": {
"id": 2188,
"type": "terminal"
},
"dropoffLocation": {
"id": 141836,
"type": "hotel"
},
"pax": [
{
"adults": 2,
"children": []
}
],
"checkedLuggage": 2,
"carryOnLuggage": 2,
"service": "transfers"
},
"searchCodes": [
{
"code": "4190828522_4190828369$1086E973G",
"quantity": 1,
"pax": [
{
"adults": 2,
"children": []
}
]
}
]
}
]
}
Request
POST http://example-booking.com/pre-book
Note that this request is being sent to a different domain than the one used for searching
| Attribute | Description |
|---|---|
| searchRequest | The original, unchanged, search request |
| searchCodes | The result codes you are planning to book. you can send as many search codes as you like in this array. |
| .code | The code from the result |
| .quantity | Number of request |
| .pax | the pax related to the specific code |
Response
Response content
{
"content": {
"Services": {
"transfers": [
{
"price": {
"amount": 160.2,
"currency": "USD"
},
"priceWithoutTax": {
"amount": 160.2,
"currency": "USD"
},
"netPrice": {
"amount": 160.2,
"currency": "USD"
},
"taxAmount": {
"amount": 0,
"currency": "USD"
},
"transactionFee": {
"amount": 0,
"currency": "USD"
},
"netPriceInClientCurrency": {
"amount": 160.2,
"currency": "USD"
},
"barRate": {
"amount": 160.2,
"currency": "USD"
},
"confirmation": "immediate",
"paymentMethod": null,
"packageRate": false,
"commissionable": true,
"code": "4190828522_4190828369$1086E973G",
"cancellation": {
"type": "fully-refundable",
"frames": [
{
"from": "2025-11-27 15:46:32",
"to": "2026-01-24 11:44:51",
"penalty": {
"amount": 0,
"currency": "USD"
}
},
{
"from": "2026-01-24 11:44:52",
"to": "2026-01-25 11:44:44",
"penalty": {
"amount": 160.2,
"currency": "USD"
}
}
]
},
"token": "AC94DA30",
"items": [
{
"transferId": "4190828522",
"name": null,
"supplier": {
"id": "123",
"relation": "345",
"reference": null
},
"pax": {
"adults": 2,
"children": []
},
"addons": [
{
"name": "SPECIAL_LUGGAGE",
"quantity": null,
"price": {
"amount": 6,
"currency": "USD"
}
},
{
"name": "BABY_SEAT",
"quantity": null,
"price": {
"amount": 6,
"currency": "USD"
}
},
{
"name": "MEET_GREET",
"quantity": null,
"price": {
"amount": 0,
"currency": "USD"
},
"maxAllowed": 1
}
],
"status": null,
"reference": null,
"remarks": null
},
{
"transferId": "4190828369",
"name": null,
"supplier": {
"id": "123",
"relation": "345",
"reference": null
},
"pax": {
"adults": 2,
"children": []
},
"addons": [
{
"id": 22003754742,
"name": "SPECIAL_LUGGAGE",
"price": {
"amount": 6,
"currency": "USD"
},
"maxAllowed": 1
},
{
"id": 22003754752,
"name": "BABY_SEAT",
"price": {
"amount": 6,
"currency": "USD"
},
"maxAllowed": 1
}
],
"status": null,
"reference": null,
"remarks": null
}
],
"surcharges": [],
"requestCode": "4190828522_4190828369$1086E973G",
"providers": [
{
"id": 789,
"name": "Name of provider"
}
],
"languages": [],
"priceFlow": []
}
]
},
"PaymentMethods": [
{
"methodName": "account_credit",
"methodDescription": "",
"paymentSettings": {
"creditCardForm": false,
"requiredFields": [],
"processingFee": 0
},
"status": "enabled",
"title": "account_credit"
},
{
"methodName": "credit_card",
"methodDescription": "",
"paymentSettings":
{
"creditCardForm": true,
"requiredFields":
[],
"processingFee": "0.023"
},
"status": "enabled",
"title": "credit_card"
}
]
},
"status": "done"
}
Common attributes:
| Attribute | Description |
|---|---|
| status | The status of the pre-book, whether it is done, working, or failed |
Attributes for result:
| Attribute | Description |
|---|---|
| Services | The services that are about to be booked |
| .transfers | An array of transfers that are about to be booked |
| ..price | The gross price (amount/currency) of the booking, i.e. the amount you charge your customer |
| ..priceWithoutTax | The gross price (amount/currency) of the booking without tax |
| ..netPrice | The net price (amount/currency) of the booking, i.e. the amount that you need to pay the provider |
| ..taxAmount | The tax (amount/currency) |
| ..transactionFee | The fee (amount/currency) of the booking |
| ..netPriceInClientCurrency | The net price (amount/currency) of the booking in client currency |
| ..barRate | The minimum price (amount/currency) that can be shown |
| ..confirmation | immediate or on-request |
| ..paymentMethod | pre or post |
| ..packageRate | If true, this offer cannot be sold as a stand-alone booking, and the price must never be shown to the user without it being bundled as a package with other products. |
| ..commissionable | Whether or not you can add commission to the final price |
| ..code | The transfer code |
| ..cancellation | The cancellation policies, see the search response for details |
| ..token | The booking token you will have to send in order to make the actual booking |
| ..items | An array of transfers |
| …transferId | The entity id of transfer |
| …name | The name of transfer |
| …supplier | Information about supplier |
| …pax | the corresponding pax from your search which this result is suitable to |
| …addons | Additional amenities |
| ….name | The name of addon |
| ….quantity | The quantity of addon |
| ….price | The price of addon (amount/currency) |
| …status | Status of transfer |
| …reference | The reference of transfer |
| …remarks | The remark of transfer |
| ..surcharges | If there are any additional surcharges applied to the price |
| …price | The price (amount/currency) of the surcharge |
| …payment | included or excluded or direct |
| …title | The name of the surcharge |
| …mandatory | true or false |
| …description | The description of the surcharge |
| ..requestCode | The code you sent in the request. This is used in case the result changed due to price or availability. It is for your use only and should not be sent in further requests. |
| ..providers | Information about provider |
| ..languages | An array of languages |
| PaymentMethods | The acceptable payment methods for this booking |
| .methodName | The name of the payment method. a standard integration will use account_credit or credit_card. |
| .methodDescription | Additional description of the method, for example if the method is a saved credit card token on the account, the description can say something like “Credit card ending with 1234” |
| .paymentSettings | Specific settings for the payment method |
| .status | Whether this option is enabled for this booking |
| .title | The title of the payment method |
"warnings": [
{
"code": 2100,
"message": "Your item is not available under the originally requested price, please review the selected alternative or go back to select another result."
}
]
Book
Request
POST http://example-booking.com/book
Note that this request is being sent to a different domain than the one used for searching
{
"creditCard": {
"cardNumber": "4111 1111 1111 1111",
"cvc": "555",
"expiry": {
"month": "12",
"year": "2019"
},
"name": {
"first": "Yogi",
"last": "Berra"
}
},
"reference": {
"agency": "my agency reference",
"voucherEmail": "test@example.com"
},
"customer": {
"title": "M",
"name": {
"first": "Yogi",
"last": "Berra"
},
"birthDate": "1975-09-14",
"contact": {
"address": "housington 66",
"city": "cityngton",
"country": "IL",
"email": "test@example.com",
"phone": "555-4433222",
"state": "N/A",
"zip": "88776"
}
},
"paymentMethod": {
"methodName": "account_credit",
"securePaymentUrl": "https://example.com"
},
"paymentSettings":
{
"paymentAmount": "net",
"paymentDate": "billing-terms",
"transactionFeeCharge": true
},
"services": [
{
"searchRequest": {
"currencies": ["USD"],
"customerCountry": "IL",
"customFields": [],
"pickupDateTime": "2026-01-25 11:45:00Z",
"pickupDateTimeReturn": "2026-01-29 10:14:00Z",
"vehicleType": [],
"pickupLocation": {
"id": 2188,
"type": "terminal"
},
"dropoffLocation": {
"id": 141836,
"type": "hotel"
},
"pax": [
{
"adults": 2,
"children": []
}
],
"checkedLuggage": 2,
"carryOnLuggage": 2,
"service": "transfers"
},
"specialRequests": null,
"bookingRequest": [
{
"code": "4190828522_4190828369$1086E973G",
"pax": [
{
"adults": [
{
"name": {
"first": "Yogi",
"last": "Berra"
},
"title": "M",
"birthDate": "1975-09-14",
"lead": 1,
"contact": {
"address": "housington 66",
"city": "cityngton",
"country": "IL",
"email": "test@example.com",
"phone": "555-4433222",
"state": "N/A",
"zip": "88776"
}
}
]
}
],
"options": [
{
"name": "addons",
"value": [
{
"name": "SPECIAL_LUGGAGE",
"quantity": "0",
"price": "6",
"currency": "USD"
},
{
"name": "BABY_SEAT",
"quantity": "0",
"price": "6",
"currency": "USD"
},
{
"name": "MEET_GREET",
"quantity": "1",
"price": {
"amount": 0,
"currency": "USD"
}
}
]
},
{
"name": "flightNumber",
"value": "1234"
},
{
"name": "flightNumberReturn",
"value": "5678"
},
{
"name": "phone",
"value": "+12 3456 789012"
},
{
"name": "carType",
"value": "ECONOMY_SEDAN"
},
{
"name": "transferType",
"value": "private"
},
{
"name": "pickupName",
"value": "Dubai Airport (DXB), Dubai, Dubai, United Arab Emirates"
},
{
"name": "dropOffName",
"value": "Sofitel Abu Dhabi Corniche, Capital Plaza Complex - Corniche Rd E - Al Danah - E9-01 - Abu Dhabi - United Arab Emirates"
},
{
"name": "greetSignText",
"value": "Yogi Berra"
}
]
}
]
}
]
}
| Attribute | Description |
|---|---|
| creditCard | In case you are paying with a credit card, you need to send all relevant details |
| reference | Your references |
| .agency | Free text of your agency reference, i.e. your internal booking id |
| .voucherEmail | An email address to send the voucher to |
| customer | The customer details of the customer that is making the booking. It doesn’t have to be the same details as the travelers |
| paymentMethod | The payment method for the booking |
| .methodName | The payment method, can be either credit_card or account_credit |
| .securePaymentUrl | URL for the customer after the payment process. |
| paymentSettings | Settings for payment |
| services | This array of elements consists of the desired items you want to book. Each element contains 2 sub-elements: the original search request, and the booking request. |
| .searchRequest | The original search request |
| .specialRequests | The special request |
| .bookingRequest | This element will contain the guest information and the payment details. |
| ..code | The result code you wish to book, this code comes from the search/poll response |
| ..pax | Information about one adult |
| ..options | Additional options |
| ….name | The name of option |
| ….value | The value of option. If name is addons then value are array |
Response
Response content
{
"content": {
"bookingID": "1234567",
"bookingDate": "2025-11-27",
"status": "confirmed",
"customer": {
"title": "M",
"name": {
"first": "Yogi",
"last": "Berra"
},
"birthDate": "1975-09-14",
"contact": {
"address": "housington 66",
"city": "cityngton",
"country": "NL",
"email": "test@example.com",
"phone": "555-4433222",
"state": "N/A",
"zip": "88776"
},
"create": false
},
"price":
{
"amount": 160.2,
"currency": "USD"
},
"netPrice":
{
"amount": 160.2,
"currency": "USD"
},
"taxAmount": null,
"commissionAmount": null,
"services": [
{
"transfer": {
"PickupID": "terminal-2188",
"DropOffID": "hotel-141836",
"FlightNumber": "1234",
"FlightNumberReturn": "5678",
"GreetSignText": "Yogi Berra",
"DriverComments": "N/A",
"CarType": "ECONOMY_SEDAN",
"TransferType": "private",
"PickupName": "Dubai Airport (DXB), Dubai, Dubai, United Arab Emirates",
"DropOffName": "Sofitel Abu Dhabi Corniche, Capital Plaza Complex - Corniche Rd E - Al Danah - E9-01 - Abu Dhabi - United Arab Emirates",
"PickupDateTime": "2026-01-25 11:45:00Z",
"PickupDateTimeReturn": "2026-01-29 10:14:00Z",
"Addons": [
{
"name": "MEET_GREET",
"quantity": "1",
"price": {
"amount": 0,
"currency": "USD"
}
}
],
"CheckedLuggage": 2,
"CarryOnLuggage": 2,
"RoundTrip": false,
"Pax": [
{
"adults": 2,
"children": []
}
],
"origin": {
"bookerEnteredAddress": "Dubai Airport (DXB), Dubai, Dubai, United Arab Emirates",
"resolvedAddress": "Dubai Airport (DXB), Dubai, Dubai, United Arab Emirates",
"fullResolvedAddress": {
"streetName": "",
"streetNumber": "",
"city": "Dubai",
"postalCode": "",
"region": "Dubai",
"countryCode": "AE",
"establishment": "Dubai Airport"
},
"latitude": "25.248665",
"longitude": "55.352917",
"iataCode": "DXB",
"type": "terminal"
},
"destination": {
"bookerEnteredAddress": "Sofitel Abu Dhabi Corniche, Corniche Road East, Capital Plaza Complex, Abu Dhabi, AE",
"resolvedAddress": "Sofitel Abu Dhabi Corniche, Capital Plaza Complex - Corniche Rd E - Al Danah - E9-01 - Abu Dhabi - United Arab Emirates",
"fullResolvedAddress": {
"streetName": "Corniche Road East",
"streetNumber": "",
"city": "Abu Dhabi",
"postalCode": "",
"region": "Abu Dhabi",
"countryCode": "AE",
"establishment": "Sofitel Abu Dhabi Corniche"
},
"latitude": "24.4991793",
"longitude": "54.3678277",
"iataCode": "",
"type": "hotel"
}
},
"transferInfo": {
"PickupID": "terminal-2188",
"DropOffID": "hotel-141836",
"FlightNumber": "1234",
"FlightNumberReturn": "5678",
"GreetSignText": "Yogi Berra",
"DriverComments": "N/A",
"CarType": "ECONOMY_SEDAN",
"TransferType": "private",
"PickupName": "Dubai Airport (DXB), Dubai, Dubai, United Arab Emirates",
"DropOffName": "Sofitel Abu Dhabi Corniche, Capital Plaza Complex - Corniche Rd E - Al Danah - E9-01 - Abu Dhabi - United Arab Emirates",
"PickupDateTime": "2026-01-25 11:45:00Z",
"PickupDateTimeReturn": "2026-01-29 10:14:00Z",
"Addons": [
{
"name": "MEET_GREET",
"quantity": "1",
"price": {
"amount": 0,
"currency": "USD"
}
}
],
"CheckedLuggage": 2,
"CarryOnLuggage": 2,
"RoundTrip": false,
"Pax": [
{
"adults": 2,
"children": []
}
],
"origin": {
"bookerEnteredAddress": "Dubai Airport (DXB), Dubai, Dubai, United Arab Emirates",
"resolvedAddress": "Dubai Airport (DXB), Dubai, Dubai, United Arab Emirates",
"fullResolvedAddress": {
"streetName": "",
"streetNumber": "",
"city": "Dubai",
"postalCode": "",
"region": "Dubai",
"countryCode": "AE",
"establishment": "Dubai Airport"
},
"latitude": "25.248665",
"longitude": "55.352917",
"iataCode": "DXB",
"type": "terminal"
},
"destination": {
"bookerEnteredAddress": "Sofitel Abu Dhabi Corniche, Corniche Road East, Capital Plaza Complex, Abu Dhabi, AE",
"resolvedAddress": "Sofitel Abu Dhabi Corniche, Capital Plaza Complex - Corniche Rd E - Al Danah - E9-01 - Abu Dhabi - United Arab Emirates",
"fullResolvedAddress": {
"streetName": "Corniche Road East",
"streetNumber": "",
"city": "Abu Dhabi",
"postalCode": "",
"region": "Abu Dhabi",
"countryCode": "AE",
"establishment": "Sofitel Abu Dhabi Corniche"
},
"latitude": "24.4991793",
"longitude": "54.3678277",
"iataCode": "",
"type": "hotel"
}
},
"meetingPoint": [
{
"id": 4048,
"type": "TRANSFER_COMPANY",
"name": "Host Pick Up (DXB)",
"description": "Important note: Due to known delays at the airport, your Representative will start waiting for you 70 minutes after the flight's arrival for 45 minutes. \n\n1. Switch on your phone and connect to the Wi-Fi.\n\n2. Collect your luggage and head to the Arrivals Hall. \nDepending on your arrival gate, please go to the correct meeting point:\n- Terminal 1 Arrival: Waiting area near Spinneys or at your Service\n- Terminal 2 Arrival: Waiting area next to Costa Coffee\n- Terminal 3 Arrival: Waiting area near the VIP limousine Parking. Video will be sent to you to reach to your representative, please also see walking map picture for terminal 3. (Note: Paging is prohibited at terminal 3 by airport authorities)\n\n3. If you are unable to find them please contact +971559318323 / +97142411004",
"lat": "25.256806157624",
"lng": "55.364227294922",
"files": [
{
"id": 4411793,
"fileType": "MAP",
"url": "https://example.com/1"
},
{
"id": 4411792,
"fileType": "MAP",
"url": "https://example.com/2"
}
],
"forwardDirection": true
}
],
"transferCompany": [
{
"id": 3279,
"name": "Name of company",
"phoneNumber": "+12345678901",
"forwardDirection": true
}
],
"transferItems": {
"items": [
{
"pax": {
"adults": 2,
"children": []
},
"vehicleModels": "Toyota Prius Plus",
"passengerCapacity": 3,
"travellerAppUrl": "",
"duration": "01:29",
"pickupTime": "2026-01-25 11:45:00Z",
"waitingTime": 45,
"distance": 154.312,
"distanceUnit": "KILOMETER",
"forwardDirection": true,
"freeCancellationUntil": "2026-01-24 11:44:52+00:00",
"luggageCapacity": 3,
"VehicleCategory": "ECONOMY_SEDAN",
"transferId": "4190828522",
"name": null,
"supplier": {
"id": "123",
"relation": "456",
"reference": null
},
"addons": [
{
"name": "MEET_GREET",
"quantity": null,
"price": null
}
],
"status": "confirmed",
"reference": "J546G7-1",
"remarks": null
},
{
"pax": {
"adults": 2,
"children": []
},
"vehicleModels": "Toyota Prius Plus",
"passengerCapacity": 3,
"travellerAppUrl": "",
"duration": "01:29",
"pickupTime": "2026-01-29 10:14:00Z",
"waitingTime": 15,
"distance": 154.312,
"distanceUnit": "KILOMETER",
"forwardDirection": false,
"freeCancellationUntil": "2026-01-28 10:14:00+00:00",
"luggageCapacity": 3,
"VehicleCategory": "ECONOMY_SEDAN",
"transferId": "4190828369",
"name": null,
"supplier": {
"id": "123",
"relation": "456",
"reference": null
},
"addons": [
{
"name": "MEET_GREET",
"quantity": null,
"price": null
}
],
"status": "confirmed",
"reference": "J546G7-2",
"remarks": null
}
],
"status": "confirmed",
"customer": null,
"price": {
"amount": 160.2,
"currency": "USD"
},
"netPrice": {
"amount": 160.2,
"currency": "USD"
},
"cancellation": {
"type": "fully-refundable",
"frames": [
{
"from": "2025-11-27 15:46:32",
"to": "2026-01-24 11:44:51",
"penalty": {
"amount": 0,
"currency": "USD"
}
},
{
"from": "2026-01-24 11:44:52",
"to": "2026-01-25 11:44:44",
"penalty": {
"amount": 160.2,
"currency": "USD"
}
}
]
},
"specialRequests": null,
"priceFlow": [],
"extraData": [
{
"name": "bookingId",
"value": 1234567
},
{
"name": "forwardJorney",
"value": 4169682
},
{
"name": "returnJorney",
"value": 4193719
}
]
},
"itemId": 1,
"service": "transfers",
"startDate": "2026-01-25",
"endDate": "2026-01-29",
"paymentType": "pre",
"quantity": 1,
"code": "4190828522_4190828369$1086E973G",
"status": "confirmed",
"supplier": {
"reference": "J546G7-1; J546G7-2"
},
"price": {
"amount": 160.2,
"currency": "USD"
},
"taxAmount": null,
"netPrice": {
"amount": 160.2,
"currency": "USD"
},
"cancellation": {
"type": "fully-refundable",
"frames": [
{
"from": "2025-11-27 15:46:32",
"to": "2026-01-24 11:44:51",
"penalty": {
"amount": 0,
"currency": "USD"
}
},
{
"from": "2026-01-24 11:44:52",
"to": "2026-01-25 11:44:44",
"penalty": {
"amount": 160.2,
"currency": "USD"
}
}
]
},
"pax": [
{
"adults": [
{
"lead": true,
"title": "M",
"name": {
"first": "Yogi",
"last": "Berra"
},
"birthDate": "1975-09-14",
"contact": {
"address": "housington 66",
"city": "cityngton",
"country": "NL",
"email": "test@example.com",
"phone": "555-4433222",
"state": "N/A",
"zip": "88776"
}
}
],
"children": []
}
],
"surcharges": null,
"remarks": [],
"reference": null,
"providers": [
{
"id": 789,
"name": "Name of provider"
}
]
}
],
"payment":
{
"method": "account_credit",
"clearingState": null,
"paymentStatus": "unpaid"
},
"options":
{
"emails":
[]
},
"reference":
{
"agency": "my agency reference",
"voucherEmail": "test@example.com"
}
},
"status": "done"
}
Common attributes:
| Attribute | Description |
|---|---|
| status | The status of the pre-book, whether it is done, working, or failed |
Attributes for result:
| Attribute | Description |
|---|---|
| bookingID | The booking ID |
| bookingDate | Date of booking |
| status | The booking status |
| customer | Information about the customer |
| price | The gross price (amount/currency) of the booking, i.e. the amount you charge your customer |
| netPrice | The net price (amount/currency) of the booking, i.e. the amount that you need to pay the provider |
| taxAmount | The tax (amount/currency) |
| commissionAmount | Whether or not you can add commission to the final price |
| services | The services that are about to be booked |
| .transfer | An array of transfers |
| ..PickupID | The point ID for start of the trip |
| ..DropOffID | The point ID for finish of the trip |
| ..FlightNumber | The flight before the trip |
| ..FlightNumberReturn | The flight after the trip |
| ..GreetSignText | Name of the customer |
| ..DriverComments | Comments of the driver |
| ..CarType | Type of the car |
| ..TransferType | Type of transfer |
| ..PickupName | The point name for start of the trip |
| ..DropOffName | The point name for finish of the trip |
| ..PickupDateTime | Date for start of the trip |
| ..PickupDateTimeReturn | Date for finish of the trip |
| ..Addons | Additional amenities |
| ..CheckedLuggage | Number of pieces of luggage |
| ..CarryOnLuggage | Number of pieces of carryOnLuggage |
| ..RoundTrip | Type of the trip |
| ..pax | the corresponding pax from your search which this result is suitable to |
| ..origin | Place of departure of the trip |
| …bookerEnteredAddress | The address of departure |
| …resolvedAddress | The address of departure |
| …fullResolvedAddress | The full address of departure |
| …latitude | Coordinates of departure |
| …longitude | Coordinates of departure |
| …iataCode | Code of country |
| …type | The type of departure |
| ..destination | Place of destination of the trip |
| …bookerEnteredAddress | The address of destination |
| …resolvedAddress | The address of destination |
| …fullResolvedAddress | The full address of destination |
| …latitude | Coordinates of destination |
| …longitude | Coordinates of destination |
| …iataCode | Code of country |
| …type | The type of destination |
| .transferInfo | Information about transfers |
| ..PickupID | The point ID for start of the trip |
| ..DropOffID | The point ID for finish of the trip |
| ..FlightNumber | The flight before the trip |
| ..FlightNumberReturn | The flight after the trip |
| ..GreetSignText | Name of the customer |
| ..DriverComments | Comments of the driver |
| ..CarType | Type of the car |
| ..TransferType | Type of transfer |
| ..PickupName | The point name for start of the trip |
| ..DropOffName | The point name for finish of the trip |
| ..PickupDateTime | Date for start of the trip |
| ..PickupDateTimeReturn | Date for finish of the trip |
| ..Addons | Additional amenities |
| ..CheckedLuggage | Number of pieces of luggage |
| ..CarryOnLuggage | Number of pieces of carryOnLuggage |
| ..RoundTrip | Type of the trip |
| ..pax | the corresponding pax from your search which this result is suitable to |
| ..origin | Place of departure of the trip |
| …bookerEnteredAddress | The address of departure |
| …resolvedAddress | The address of departure |
| …fullResolvedAddress | The full address of departure |
| …latitude | Coordinates of departure |
| …longitude | Coordinates of departure |
| …iataCode | Code of country |
| …type | The type of departure |
| ..destination | Place of destination of the trip |
| …bookerEnteredAddress | The address of destination |
| …resolvedAddress | The address of destination |
| …fullResolvedAddress | The full address of destination |
| …latitude | Coordinates of destination |
| …longitude | Coordinates of destination |
| …iataCode | Code of country |
| …type | The type of destination |
| .meetingPoint | Information about point of meeting |
| .transferCompany | Information about transfer company |
| .transferItems | Information about transfers |
| .itemId | Code of transfer |
| .service | Information about services that are about to be booked |
| .startDate | The date of start the trip |
| .endDate | The date of finish the trip |
| .paymentType | pre or post |
| .quantity | The quantity |
| .code | The transfer code |
| .status | The booking status |
| .supplier | Information about supplier |
| .price | The gross price (amount/currency) of the booking, i.e. the amount you charge your customer |
| .taxAmount | The tax (amount/currency) |
| .netPrice | The net price (amount/currency) of the booking, i.e. the amount that you need to pay the provider |
| ..cancellation | The cancellation policies, see the search response for details |
| ..pax | Information about one adult |
| .surcharges | If there are any additional surcharges applied to the price |
| ..price | The price (amount/currency) of the surcharge |
| ..payment | included or excluded or direct |
| ..title | The name of the surcharge |
| ..mandatory | true or false |
| ..description | The description of the surcharge |
| .remarks | The remark of transfer |
| .reference | The reference of transfer |
| .providers | Information about provider |
| payment | The acceptable payment methods for this booking |
| .method | The name of the payment method. a standard integration will use account_credit or credit_card |
| .paymentStatus | Whether this option is enabled for this booking |
| options | The options |
| reference | Your references |
| .agency | Free text of your agency reference, i.e. your internal booking id |
| .voucherEmail | An email address to send the voucher to |
Possible status values
| Status | Description |
|---|---|
| confirmed | A transfer company has accepted the offer and has been assigned to the journey. The transfer company details and personalized travel voucher are available at this point |
| on request | The journey has been offered to the associated transfer companies, but have not yet been accepted |
| cancelled | The journey was cancelled |
| failed | The booking/item failed to confirm |
Cancel
Request content
{
"BookingID": 1234,
"CancelReason": "The dog is sick",
"Force": false,
"IsManual": false
}
Request
POST https://example.com/booking-cancel
| Attribute | Description |
|---|---|
| BookingID | The booking ID you would like to cancel |
| CancelReason | The reason for the cancellation, can be left blank |
| Force | Should the booking be cancelled in any case, without calling the provider - USE FALSE UNLESS YOU KNOW WHAT YOU ARE DOING |
| IsManual | Is the booking being cancelled by a human request or by an automated process |
Response
Response content
{
"content": {
"Status": "done",
"Warnings": []
},
"status": "done"
}
| Attribute | Description |
|---|---|
| content.Status | Was the cancellation successful (done) or unsuccessful (error) |
| content.Warnings | This array will be returned only if force cancellation was used |
Booking Details
Request
GET https://example.com/booking-details/[booking-id]
| Attribute | Description |
|---|---|
| BookingID | The booking ID you would like to get details for |
Response
The response is the same as booking response
Sports
Flow
The common case usage is quite simple:
- Initiate events search by location, event type, etc.;
- Poll to get results;
- Initiate a ticket search by event;
- Poll to get results;
- Run a pre-book call;
- Book;
Search
Request
curl \
-H "aether-application-key: [app-key]" \
-H "Content-Type: application/json" \
-X POST \
-d @request-file.json \
https://example.com/sports/search
Request content
{
"currencies": ["EUR"],
"customerCountry": "IL",
"dates": {
"from": "2027-01-11",
"to": "2027-01-31"
},
"destinations": [
{
"id": 1000,
"type": "event-type"
}
],
"service": "sports"
}
Request
POST https://example.com/sports/search
You can search for events by eventTypeId or for a specific event by eventId.
| Attribute | Description |
|---|---|
| currencies | List of currencies you wish to get your results in. The first currency on the list will be the default currency of the search |
| customerCountry | Two-letter ISO code of the customer country running the search. Note: the same customer country must be used on the booking, and an incorrect customer country may result in the venue not honoring the booking. |
| dates | The from and to dates in YYYY-MM-DD format |
| destinations | The search destinations array |
| .destinations/id | The entity ID based on the type |
| .destinations/type | Type of destination: location, participant, venue, tournament, event-type, or event |
Here is a small list of some popular IDs of our sports.
| ID | Description of event type |
|---|---|
| 1000 | Football |
| 1001 | Tennis |
| 1002 | Basketball |
| 1003 | Car Racing |
| 1005 | Baseball |
| 1006 | US Football |
| 1007 | Motorbike Racing |
| 1008 | Bicycle Racing |
| 1009 | Athletics |
| 1010 | Ice Hockey |
| 1012 | Handball |
| 1014 | Boxing |
| 1017 | Multiple Sports |
| 1020 | Rugby |
| 1021 | Ski |
| 1023 | Concerts |
| 1024 | Volleyball |
Response
The response contains the search status. When status is working, the search has been accepted and is still processing. Poll the search to receive results.
Response
{
"timestamp": 1791300931,
"requestTime": "2026-10-06 15:35:31",
"status": "working",
"completed": 0,
"sessionId": "s:50641:2:2027-01-11:2027-01-31:IL:EUR:1000:event-type:b2b",
"processTime": 5857,
"expireAt": "2026-10-06 16:05:36"
}
| Attribute | Description |
|---|---|
| timestamp | The server timestamp of the response |
| requestTime | The request date and time in human-readable format |
| status | The status of the search, whether it is done, working, or failed |
| completed | Integer, percentage of the progress. 0 means no tasks were completed, 100 means all tasks were completed, everything in between in “in process”. Please note this attribute is for Hubwayz’s internal use only. To check if the search was completed or not please refer only to the status property. |
| sessionId | The session ID of the search |
| processTime | Processing time in milliseconds. |
| expireAt | The date and time when the session expires |
Poll
Request
curl \
-H "aether-application-key: [app-key]" \
-H "Content-Type: application/json" \
-X POST \
-d @request-file.json \
https://example.com/sports/poll
Request content
{
"currencies": ["EUR"],
"customerCountry": "IL",
"dates": {
"from": "2027-01-11",
"to": "2027-01-31"
},
"destinations": [
{
"id": 1000,
"type": "event-type"
}
],
"service": "sports"
}
Request
POST https://example.com/sports/poll
Continue polling while the status is working. When the status changes to done, no new results will be returned by subsequent polls.
Note that the search and poll requests must be identical.
Response
The response will return the results received until the search was completed.
Response
{
"timestamp": 1791301114,
"requestTime": "2026-10-06 15:38:34",
"status": "done",
"completed": 100,
"sessionId": "s:50641:2:2027-01-11:2027-01-31:IL:EUR:1000:event-type:b2b",
"processTime": 218,
"expireAt": "2026-10-06 16:05:36",
"results": [
{
"price": {
"amount": 82,
"currency": "EUR"
},
"netPrice": {
"amount": 82,
"currency": "EUR"
},
"barRate": null,
"confirmation": "immediate",
"paymentType": "pre",
"commissionable": true,
"providers": [
{
"id": 12345,
"name": "Sports365"
}
],
"specialOffers": [],
"items": [],
"cancellation": {
"type": "non-refundable",
"frames": [
{
"from": "2026-10-06 00:00:00",
"to": "2027-01-12 23:59:59",
"penalty": {
"amount": 82,
"currency": "EUR"
}
}
]
},
"eventId": 392295,
"eventTypeId": 1000,
"name": "RC Strasbourg vs Le Mans",
"address": "12 rue de l'Extenwoerth,\r\n67100 Strasbourg",
"eventDateTime": "2027-01-16 15:00:00",
"finalDate": false,
"finalTime": false,
"dateTimeBoundaries": "Event will not start before Friday at 20:30 and not after Sunday at 21:00",
"tournamentId": 13,
"venueId": 2077,
"venueName": "Stade de la Meinau",
"mapUrl": "https://example.com/venues/thumbs/1_allianzarena.jpg",
"participants": [
2555,
1198
],
"languages": [],
"code": "27748497$1103Q973G"
}
]
}
The response contains a list of results. The meaning of each result depends on destinations.type:
- For
location,participant,venue,tournament, andevent-type, each result represents an event. - For
event, each result represents a ticket for the selected event. The event information is included in the result, while the ticket information is available in theitems[]array. In the current implementation, this array contains one element,items[0].
Each result has the following attributes:
| Attribute | Description |
|---|---|
| price | The gross price {amount, currency} of the result |
| netPrice | The net price {amount, currency} of this result |
| barRate | Price {amount, currency} of the BAR, the price which you are not allowed to sell below on B2C platforms. |
| confirmation | immediate or on-request |
| paymentType | pre or post, indicates whether this is a pre-paid result or a pay-at-the-venue result |
| commissionable | true or false, indicates whether you can apply a commission on top of the price or not |
| providers | List of the providers {id, name} that returned this result |
| specialOffers | List of special offers, if any |
| items | Ticket data for the result. This array is empty for searches by location, participant, venue, tournament, or event-type; see below |
| cancellation | See below |
| eventId | Event ID |
| eventTypeId | Event type ID |
| name | The name of the event |
| address | The address of the event |
| eventDateTime | The date and time of the event |
| finalDate | Indicates whether the event date is confirmed. When the date is confirmed but the time is not, the zone boundaries represent the earliest and latest hours during which the event may begin on that day. When the date is not confirmed, the zone boundaries represent the range of days during which the event may take place. |
| finalTime | Indicates whether the event start time is confirmed. When false, the zone boundaries represent the earliest and latest hours during which the event may begin on the event day. |
| dateTimeBoundaries | Time boundaries (dateTimeBoundaries) are a textual description displayed when the event date is not final, specifying the range of days or hours during which the event may take place. |
| tournamentId | Tournament ID of the event |
| venueId | Venue ID of the event |
| venueName | Venue name of the event |
| mapUrl | URL of the venue map |
| participants | List of participant or team IDs |
| languages | List of {code, name} objects |
| code | The result code to use in the next steps |
Cancellation Policy
The cancellation policy is built from frames.
Each frame has a start date (from), an end date (to), and a penalty.
These frames tell you exactly what the penalty will be on each date from the booking date until the event date.
After the event date, assume a cancellation penalty of 100%.
{
"items": [
{
"ticketId": "27748497",
"name": "Short Side",
"description": "All Together",
"availableSellingQuantity": [
1,
2,
3
],
"categoryRestrictions": [],
"deliveries": [
{
"id": 1006,
"name": "E-Ticket",
"description": "",
"price": {
"amount": 5,
"currency": "EUR"
},
"deliveryFields": []
}
],
"remarks": {
"ConfirmationText": "Online stock - Confirmation is guaranteed, the tickets\r\nare delivered 24-72 hours prior to the event",
"ImportantNotes": "",
"PurchaseAlert": "",
"PriceComments": ""
},
"splittedCategoryName": {
"main": "Short Side",
"secondary": "",
"packageDetails": "",
"description": ""
},
"isVipPackage": false
}
]
}
Items (tickets)
For searches by location, participant, venue, tournament, or event-type, each result represents an event and the items array is empty. For searches by event, each result represents a ticket, and the ticket details are in the first and currently only element of the items[] array: items[0].
| Attribute | Description |
|---|---|
| items | Ticket data held by the result code |
| items[0].ticketId | The ticket ID |
| items[0].name | The name of the ticket category |
| items[0].description | The description of the ticket category |
| items[0].availableSellingQuantity | Available selling quantities |
| items[0].categoryRestrictions | Each category can have multiple restrictions that should be displayed to the end client. |
| items[0].deliveries | List of the deliveries {id, name, description, price, deliveryFields} returned for this ticket |
| items[0].remarks | List of remarks {ConfirmationText, ImportantNotes, PurchaseAlert, PriceComments} returned for this ticket |
| items[0].splittedCategoryName | Ticket category name split into {main, secondary, packageDetails, description} |
| items[0].isVipPackage | Indicates whether this ticket category is designated as a VIP package |
Search by event
After selecting an event from the first search, run a second search with the event ID to retrieve its ticket categories.
Request
POST https://example.com/sports/search
{
"currencies": ["EUR"],
"customerCountry": "IL",
"dates": {
"from": "2027-01-11",
"to": "2027-01-31"
},
"destinations": [
{
"id": 392295,
"type": "event"
}
],
"service": "sports"
}
Poll this search using POST https://example.com/sports/poll. The poll request must be identical to this search request.
Pre-Book
curl \
-H "aether-application-key: [app-key]" \
-H "Content-Type: application/json" \
-X POST \
-d @request-file.json \
https://example-booking.com/pre-book
Request content
{
"services": [
{
"searchRequest": {
"currencies": ["EUR"],
"customerCountry": "IL",
"dates": {
"from": "2027-01-11",
"to": "2027-01-31"
},
"destinations": [
{
"id": 392295,
"type": "event"
}
],
"service": "sports"
},
"searchCodes": [
{
"code": "27748497$1103Q973G",
"quantity": 1,
"pax": [
{
"adults": 1,
"children":[]
}
],
"options": [
{
"name": "eventId",
"value": 392295
}
]
}
],
"specialRequests": null,
"bookingRequest": [],
"login": null
}
]
}
Request
POST https://example-booking.com/pre-book
Note: this request is sent to a different domain than the one used for searching.
| Element | Description |
|---|---|
| services | List of services to book |
| .service/searchRequest | The original, unchanged, search request |
| .service/searchCodes | List of codes you plan to book |
| ..searchCode/code | The code from the result |
| ..searchCode/quantity | Quantity of tickets |
| ..searchCode/pax | The pax related to the specific code |
| ..searchCode/options | Details for your booking |
| .service/specialRequests | Special requests, if any |
| .service/bookingRequest | Booking details, if any |
| .service/login | Login details, if any |
Custom Fields
This part is relevant for deep integrations where you have your own suppliers connected through this API and need to pass parameters to specific providers.
For example, a B2B system may need to pass agent credentials during the search. If custom fields are used, include them unchanged in the corresponding Pre-Book and Book search requests.
Example of custom fields in the request
{
"customFields": [
{
"name": "source",
"value": "b2b.travel"
}
]
}
Response
Response content
{
"content": {
"Services": {
"sports": [
{
"eventDateTime": "2027-01-16 15:00:00",
"eventId": 392295,
"eventTypeId": 1000,
"name": "RC Strasbourg vs Le Mans",
"address": "12 rue de l'Extenwoerth,\r\n67100 Strasbourg",
"tournamentId": 13,
"venueId": 2077,
"venueName": "Stade de la Meinau",
"mapUrl": "https://example.com/venues/thumbs/3_stamford-bridge.jpg",
"participants": [
2555,
1198
],
"items": [
{
"ticketId": "27748497",
"name": "Short Side",
"description": "All Together",
"availableSellingQuantity": [
1,
2,
3
],
"categoryRestrictions": null,
"deliveries": [
{
"id": 1006,
"name": "E-Ticket",
"description": "",
"price": {
"amount": 5,
"currency": "EUR"
},
"deliveryFields": []
}
],
"remarks": {
"Confirmation text": "Online stock - Confirmation is guaranteed, the tickets\r\nare delivered 24-72 hours prior to the event",
"ImportantNotes": "",
"PurchaseAlert": "",
"PriceComments": ""
},
"supplier": {
"id": "12345",
"relation": "876543",
"reference": null
},
"purchaseFields": [
{
"name": "fullName",
"required": true
},
{
"name": "birthDate",
"required": false
},
{
"name": "nationalityCountryId",
"required": true
},
{
"name": "passportNumber",
"required": false
},
{
"name": "cityOfBirth",
"required": true
}
],
"pax": null,
"splittedCategoryName": {
"main": "Rose & Ball East Upper seats",
"secondary": "",
"packageDetails": "▪ East upper, long side seating Block - EU7\r\n▪ Pre-match 3-course hot & cold bowl food and drinks ( beer, wine soft drinks )\r\n▪ Post-match drinks and savoury snacks ( 1 hr after match )\r\n▪ Official matchday programme and visit from former first team player",
"description": ""
},
"isVipPackage": false,
"status": null,
"reference": null
}
],
"code": "27748497$1103Q973G",
"cancellation": {
"type": "non-refundable",
"frames": [
{
"from": "2026-10-06 00:00:00",
"to": "2027-01-12 23:59:59",
"penalty": {
"amount": 82,
"currency": "EUR"
}
}
]
},
"price": {
"amount": 82,
"currency": "EUR"
},
"netPrice": {
"amount": 82,
"currency": "EUR"
},
"transactionFee": null,
"confirmation": "immediate",
"paymentMethod": null,
"paymentType": "pre",
"sessionId": "s:50641:2:2027-01-11:2027-01-31:IL:EUR:392295:event:b2b",
"surcharges": [
{
"price": {
"amount": 8.3,
"currency": "EUR"
},
"payment": "included",
"title": "Occupancy tax",
"mandatory": true,
"description": ""
}
],
"startDate": "2027-01-16 15:00:00",
"endDate": "2027-01-16 15:00:00",
"expectedCode": "27748497$1103Q973G",
"warnings": [],
"barRate": null,
"packageRate": null,
"commissionable": true,
"token": "71FC23AB",
"providers": [
{
"id": 12345,
"name": "Sports365"
}
]
}
]
},
"PaymentMethods": [
{
"methodName": "account_credit",
"methodDescription": "",
"paymentSettings": {
"creditCardForm": false,
"requiredFields": [],
"processingFee": 0
},
"status": "enabled",
"title": "account_credit"
},
{
"methodName": "credit_card",
"methodDescription": "",
"paymentSettings": {
"creditCardForm": true,
"requiredFields": [],
"processingFee": 0.001
},
"status": "enabled",
"title": "credit_card"
}
],
"ImmediateCharge": true,
"PaymentDueDate": "2026-10-06",
"LoyaltyPoints": [],
"AvailablePoints": [
{
"codes": [
"27722532$1103Q118B1076E"
],
"points": 1140,
"pointsToAmount": {
"amount": 11.4,
"currency": "EUR"
}
}
],
"AutoCancellation": false,
"ProfileVersion": "7e283bc33072493e5df970474dba7c73344ad52a"
},
"status": "done"
}
The response contains the events and ticket details used for booking:
| Element | Description |
|---|---|
| Services/sports | List of results for booking |
| .sport/eventDateTime | The date and time of the event |
| .sport/eventId | Event ID |
| .sport/eventTypeId | Event type ID |
| .sport/name | The name of the event |
| .sport/address | The address of the event |
| .sport/tournamentId | Tournament ID of the event |
| .sport/venueId | Venue ID of the event |
| .sport/venueName | Venue name of the event |
| .sport/mapUrl | URL of the venue map |
| .sport/participants | List of participant or team IDs |
| .sport/items | List of items held by the result code |
| ..item/ticketId | The ticket ID |
| ..item/name | The name of the ticket category |
| ..item/description | The description of the ticket category |
| ..item/availableSellingQuantity | Available selling quantities |
| ..item/categoryRestrictions | Each category can have multiple restrictions that should be displayed to the end client. |
| ..item/deliveries | List of the deliveries {id, name, description, price, deliveryFields} that returned this result |
| ..item/remarks | List of remarks {ConfirmationText, ImportantNotes, PurchaseAlert, PriceComments} that returned this result |
| ..item/supplier | The supplier {id, relation, reference} that returned this result |
| ..item/purchaseFields | List of purchase fields {name, required} that returned this result |
| ..item/pax | The pax from the provider |
| ..item/splittedCategoryName | List of the ticket category name split into separate components {main, secondary, packageDetails, description} that returned this result |
| ..item/isVipPackage | Indicates whether this ticket category is designated as a VIP package |
| ..item/status | Status of item |
| ..item/reference | Reference of item |
| .sport/code | The event code |
| .sport/cancellation | The cancellation policies, see the search response for details |
| .sport/price | The gross price {amount, currency} of the booking |
| .sport/netPrice | The net price {amount, currency} of the booking |
| .sport/transactionFee | Any additional fee {amount, currency} that may apply for the cost of processing the transaction |
| .sport/confirmation | immediate or on-request |
| .sport/paymentMethod | Payment method, if provided |
| .sport/paymentType | pre or post, indicates whether this is a pre-paid result or a pay-at-the-venue result |
| .sport/sessionId | The session ID of the search |
| .sport/surcharges | Any additional surcharges applied to the price |
| ..surcharge/price | The price {amount, currency} of the surcharge |
| ..surcharge/payment | included or excluded or direct |
| ..surcharge/title | The name of the surcharge |
| ..surcharge/mandatory | true or false |
| ..surcharge/description | The description of the surcharge |
| .sport/startDate | Start date of the event |
| .sport/endDate | End date of the event |
| .sport/expectedCode | The code you sent in the request |
| .sport/barRate | The minimum price {amount, currency} that can be shown on a B2C website |
| .sport/packageRate | true or false, indicates whether this result can be sold as a stand-alone offer or if it requires to be sold as part of a package |
| .sport/commissionable | true or false, indicates whether you can apply a commission on top of the price or not |
| .sport/token | The booking token you will have to send in order to make the actual booking |
| .sport/providers | List of the providers {id, name} that returned this result |
| PaymentMethods | List of payment methods for this booking |
| .paymentMethod/methodName | The name of the payment method. A standard integration will use account_credit or credit_card. |
| .paymentMethod/methodDescription | Description of the method, for example if the method is a saved credit card token on the account, the description can say something like “Credit card ending with 1234” |
| .paymentMethod/paymentSettings | Specific settings for the payment method |
| .paymentMethod/status | Whether this option is enabled for this booking |
| .paymentMethod/title | The short name of the payment method |
| ImmediateCharge | true or false |
| PaymentDueDate | Date of payment |
| LoyaltyPoints | List of loyalty points |
| AvailablePoints | List of available points |
| AutoCancellation | true or false |
| status | Status of response |
Book
Request
POST https://example-booking.com/book
Note that this request is being sent to a different domain than the one used for searching
{
"reference": {
"agency": "my agency reference",
"voucherEmail": "test@example.com"
},
"customer": {
"title": "MR",
"name": {
"first": "Testa",
"last": "Test"
},
"birthDate": "1990-01-01",
"contact": {
"country": "IL",
"city": "N/A",
"state": "N/A",
"address": "N/A",
"phone": "N/A",
"zip": "N/A",
"email": "testa@example.com",
"passportNumber": ""
}
},
"paymentMethod": {
"methodName": "account_credit",
"securePaymentUrl": "https://b2b.travel/111"
},
"paymentSettings": {
"paymentAmount": "net",
"paymentDate": "billing-terms",
"transactionFeeCharge": true
},
"services": [
{
"searchRequest": {
"currencies": ["EUR"],
"customerCountry": "IL",
"dates": {
"from": "2027-01-11",
"to": "2027-01-31"
},
"destinations": [
{
"id": 392295,
"type": "event"
}
],
"service": "sports"
},
"bookingRequest": [
{
"code": "27748497$1103Q973G",
"token": "71FC23AB",
"pax": [
{
"adults": [
{
"name": {
"first": "Testa",
"last": "Test"
},
"title": "MR",
"birthDate": "1990-01-01",
"lead": 1,
"contact": {
"country": "IL",
"state": "N/A",
"address": "N/A",
"phone": "N/A",
"zip": "N/A",
"city": "N/A",
"email": "testa@example.com"
}
}
]
}
],
"options": {
"0": {
"id": "",
"count": "1"
},
"sports": {
"27748497$1103Q973G": [
{
"adults": [
{
"title": "MR",
"name": {
"first": "Testa",
"last": "Test"
},
"contact": {
"email": "testa@example.com",
"phone": "555-4433222",
"country": "IL",
"city": "N/A"
}
}
]
}
]
},
"pax": {
"name": "pax",
"value": {
"0": {
"title": "MR",
"name": {
"first": "Testa",
"last": "Test"
},
"contact": {
"email": "testa@example.com",
"phone": "555-4433222",
"country": "IL",
"city": "N/A"
}
}
}
},
"delivery": {
"name": "delivery",
"value": {
"id": "1006",
"name": "E-Ticket"
}
},
"staticData": {
"name": "staticData",
"value": {
"eventType": {
"id": 1000,
"name": "Football (Soccer)",
"category": null
},
"participants": [
{
"id": 2555,
"name": "RC Strasbourg",
"eventTypeId": 1000,
"logo": "https://example.com/logos/competitors/2555.png"
},
{
"id": 1198,
"name": "Le Mans",
"eventTypeId": 1000,
"logo": "https://example.com/logos/competitors/1198.png"
}
],
"tournaments": {
"id": 13,
"name": "French Ligue 1",
"logo": "https://example.com/logos/tournaments/13.png",
"eventTypeId": 1000
},
"venue": {
"id": 2077,
"name": "Stade de la Meinau",
"address": "",
"zip": null,
"phone": null,
"fax": null,
"latitude": "48.5601",
"longitude": "7.75497",
"description": null,
"destination": {
"id": 1204,
"name": "Strasbourg",
"country": "FR"
},
"translations": [],
"images": []
}
}
}
}
}
]
}
]
}
| Element | Description |
|---|---|
| reference | The references {agency, voucherEmail} |
| customer | The customer details of the customer that is making the booking. |
| paymentMethod | List of payment methods for this booking |
| .paymentMethod/methodName | The name of the payment method. a standard integration will use account_credit or credit_card. |
| .paymentMethod/securePaymentUrl | URL for the payment method |
| paymentSettings | Details for payment methods {paymentAmount, paymentDate, transactionFeeCharge} |
| services | List of elements consists of the desired items you want to book |
| .service/searchRequest | The original, unchanged, search request |
| .service/bookingRequest | List of booking details |
| ..bookingRequest/code | The code for booking |
| ..bookingRequest/token | the token from the pre-book call |
| ..bookingRequest/pax | The pax with information about pax details |
| ..bookingRequest/options | Details for your booking |
| …option/0 | The number of tickets {id, count} |
| …option/sports | The pax information for the event |
| …option/pax | The pax information about passengers |
| …option/delivery | List of the deliveries {id, name, description, price, deliveryFields} that returned this result |
| …option/staticData | Static data information about the event |
| ….staticData/name | Name of static data information |
| ….staticData/value | Value of static data information |
| …..value/eventType | Type of event {id, name, category} |
| …..value/participants | List of participants {id, name, eventTypeId, logo} |
| …..value/tournaments | List of tournaments {id, name, eventTypeId, logo} |
| …..value/venue | List of venue {id, name, address, zip, phone, fax, latitude, longitude, description, destination, translations, images} |
If you send a booking request for children, each child must include a birthDate in YYYY-MM-DD format.
For example:
{
"children": [
{
"birthDate": "2014-04-20",
"name": {
"first": "test",
"last": "test"
},
"title": "C"
}
]
}
Each pax element must contain the fields marked as required in the PurchaseFields array. Otherwise, the booking process will fail.
Response
Response content
{
"content": {
"bookingID": 1234567,
"bookingDate": "2026-10-06",
"status": "confirmed",
"customer": {
"title": "MR",
"name": {
"first": "Testa",
"last": "Test"
},
"birthDate": "1993-01-01",
"contact": {
"country": "IL",
"state": "N/A",
"address": "N/A",
"city": "N/A",
"phone": "555-4433222",
"zip": "N/A",
"email": "testa@example.com",
"passportNumber": ""
},
"create": false
},
"price": {
"amount": 82,
"currency": "EUR"
},
"netPrice": {
"amount": 82,
"currency": "EUR"
},
"taxAmount": null,
"commissionAmount": null,
"services": [
{
"sports": {
"name": "RC Strasbourg vs Le Mans",
"eventDateTime": "2027-01-16 15:00:00",
"eventId": 392295,
"eventTypeId": 1000,
"address": "12 rue de l'Extenwoerth,\r\n67100 Strasbourg",
"tournamentId": 13,
"venueId": 2077,
"venueName": "Stade de la Meinau",
"mapUrl": "https://example.com/venues/thumbs/stade.jpg",
"description": null,
"availableSellingQuantity": null,
"categoryRestrictions": null,
"delivery": {
"id": "1006",
"name": "E-Ticket"
},
"pax": {
"0": {
"title": "MR",
"name": {
"first": "Testa",
"last": "Test"
},
"contact": {
"email": "testa@example.com",
"phone": "555-4433222",
"country": "IL",
"city": "N/A"
}
}
},
"staticData": {
"eventType": {
"id": 1000,
"name": "Football (Soccer)",
"category": null
},
"participants": [
{
"id": 2555,
"name": "RC Strasbourg",
"eventTypeId": 1000,
"logo": "https://example.com/logos/competitors/2555.png"
},
{
"id": 1198,
"name": "Le Mans",
"eventTypeId": 1000,
"logo": "https://example.com/logos/competitors/1198.png"
}
],
"tournaments": {
"id": 13,
"name": "French Ligue 1",
"logo": "https://example.com/logos/tournaments/13.png",
"eventTypeId": 1000
},
"venue": {
"id": 2077,
"name": "Stade de la Meinau",
"address": "",
"zip": null,
"phone": null,
"fax": null,
"latitude": "48.5601",
"longitude": "7.75497",
"description": null,
"destination": {
"id": 1204,
"name": "Strasbourg",
"country": "FR"
},
"translations": [],
"images": []
}
}
},
"itemId": 1,
"service": "sports",
"startDate": "2027-01-16",
"endDate": "2027-01-16",
"paymentType": "pre",
"quantity": 1,
"code": "27748497$1103Q973G",
"status": "confirmed",
"supplier": {
"reference": "288909"
},
"price": {
"amount": 82,
"currency": "EUR"
},
"taxAmount": null,
"netPrice": {
"amount": 82,
"currency": "EUR"
},
"cancellation": {
"type": "non-refundable",
"frames": [
{
"from": "2026-10-06 00:00:00",
"to": "2027-01-12 23:59:59",
"penalty": {
"amount": 82,
"currency": "EUR"
}
}
]
},
"surcharges": [
{
"price": {
"amount": 8.3,
"currency": "EUR"
},
"payment": "included",
"title": "Occupancy tax",
"mandatory": true,
"description": ""
}
],
"remarks": [
{
"Confirmation text": "Online stock - Confirmation is guaranteed, the tickets\r\nare delivered 24-72 hours prior to the event",
"ImportantNotes": "",
"PurchaseAlert": "",
"PriceComments": ""
}
],
"reference": null,
"providers": [
{
"id": 12345,
"name": "Sports365"
}
]
}
],
"payment": {
"method": "account_credit",
"clearingState": null,
"paymentStatus": "unpaid"
},
"options": {
"emails": [
"on_request_booking"
]
},
"reference": {
"agency": "TTAS-00870900",
"voucherEmail": "burcin@jetoffholidays.com"
},
"behalf": null,
"ProfileVersion": "7e283bc33072493e5df970474dba7c73344ad52a"
},
"status": "done"
}
Most fields reflect data sent by you. The following fields require special attention:
| Element | Description |
|---|---|
| bookingID | The Hubwayz system booking ID |
| bookingDate | Date of booking |
| status | Status of booking can be confirmed or cancelled or failed |
| customer | The customer details for the booking. |
| price | The gross price {amount, currency} of the booking |
| netPrice | The net price {amount, currency} of the booking |
| taxAmount | The amount of the tax {amount, currency}, if applicable |
| commissionAmount | The amount of the commission {amount, currency} |
| services | List of booking details |
| .service/sports | Event details |
| ..sport/name | The name of the event |
| ..sport/eventDateTime | The date and time of the event |
| ..sport/eventId | Event ID |
| ..sport/eventTypeId | Event type ID |
| ..sport/address | The address of the event |
| ..sport/tournamentId | Tournament ID of the event |
| ..sport/venueId | Venue ID of the event |
| ..sport/venueName | Venue name of the event |
| ..sport/mapUrl | URL of the venue map |
| ..sport/description | The description of the event |
| ..sport/availableSellingQuantity | Available selling quantities |
| ..sport/categoryRestrictions | Each category can have multiple restrictions that should be displayed to the end client. |
| ..sport/delivery | Delivery information {id, name} |
| ..sport/pax | The pax from the provider |
| ..sport/staticData | Static data information about the event |
| ..staticData/eventType | Type of event {id, name, category} |
| ..staticData/participants | List of participants {id, name, eventTypeId, logo} |
| ..staticData/tournaments | List of tournaments {id, name, eventTypeId, logo} |
| ..staticData/venue | Venue information |
| .service/itemId | Item ID |
| .service/service | Type of service |
| .service/startDate | Start date of the booking |
| .service/endDate | End date of the booking |
| .service/paymentType | pre or post |
| .service/quantity | Quantity of tickets |
| .service/code | The event code |
| .service/status | Status of booking |
| .service/supplier | Supplier reference |
| .service/price | The gross price {amount, currency} of the booking |
| .service/taxAmount | The amount of the tax {amount, currency}, if applicable |
| .service/netPrice | The net price {amount, currency} of the booking |
| .service/cancellation | The cancellation policies, see the search response for details |
| .service/surcharges | List of surcharges applied to the price |
| ..surcharge/price | The price {amount, currency} of the surcharge |
| ..surcharge/payment | included or excluded or direct |
| ..surcharge/title | The name of the surcharge |
| ..surcharge/mandatory | true or false |
| ..surcharge/description | The description of the surcharge |
| .service/remarks | List of remarks |
| .service/reference | The reference |
| .service/providers | List of the providers {id, name} for this booking |
| payment | Object payment methods for this booking |
| .payment/method | The name of the payment method. A standard integration will use account_credit or credit_card. |
| .payment/paymentStatus | Whether this option is enabled for this booking |
| options | Options for booking |
| reference | The references {agency, voucherEmail} |
| status | Status of response |
Booking Details
Request
GET https://example.com/booking-details/[booking-id]
| Attribute | Description |
|---|---|
| BookingID | The booking ID you would like to get details for |
Response
The response is the same as booking response
Lookups
Board Codes
| Board Code | Description |
|---|---|
| RO | Room Only |
| BB | Breakfast |
| HB | Half Board |
| FB | Full Board |
| AI | All Inclusive |
FAQ
Q: How many adults and children can accommodate a single room?
A: 1-6 adults, 0-4 children
Q: Which ages are considered as children?
A: Each provider treats it differently, but usually guests are counted as children if their ages are between 0 and 16
Q: What is the min/max length of stay (in nights) allowed in a search request?
A: 1 to 30 nights
Q: Is it possible to send more than one hotel code in the same request?
A: Yes, this feature is supported. You can send max 250 hotel codes per request
Q: Is it possible to send more than one destination code in the same request?
A: No, this feature will be supported in the future
Q: I get an error in the search response: “”Invalid Request! Make sure it’s a valid JSON and has allowed values as described in documentation””
A: Make sure you included the header Content-Type: application/json, and that your search dates are in the future.
Q: I get a status: “working” in search response, but no results
A: You need to send at least one Poll request in order to get results.
Q: How many polls do I have to send in order to get all the results?
A: Depends on your preferred timeout. We work with many providers, some are faster than others and return results in a few seconds, while the slower ones require more time.
The polling mechanism allows you to decide how much time you want to keep polling. The first results will be received in 3 to 5 seconds, and you’ll be able to get new ones by keeping polling every 3 seconds until you decide to stop.
Q: When searching for multiple rooms, can I select which items I want to book from the different results?
A: No. Each of the result objects in the results array has the exact number of rooms to match your search criteria, and should be booked as a whole, using the result code.
Q: For how long are the search results bookable?
A: Every search session is valid for 30 minutes. If more than 30 minutes have passed, the results are no longer bookable, and you’ll have to run a new search.
Q: I get an error message in pre-book/book response
A: Make sure that you try to book the search results within 30 minutes from initial search. In addition, verify that your booking matches your search criteria exactly: same nationality, number of guests, number of rooms, children ages, etc.
Q: Are all the fields in the customer object mandatory?
A: Yes. And without a proper country code that matches the one in search request, the booking will probably fail. As for the other fields, if you don’t have the customer’s phone number or zip, for example, you can send “N/A”, but the fields must be included.
Q: Why do I get an “on_request” booking status even though I’ve excluded on-request in my search filters?
A: Even though the result you got has not been classified as “on request” when you first initiated the search, its status may change on the provider end by the time you make the booking. In such cases, it is mandatory to run the booking-details request to verify it’s status at least once a day until the status is changed to either confirmed or rejected. If the status does not change after 3 working days (72 hours), it is mandatory to contact customer support and verify the status manually.
Q: I get empty results when the second request with the same parameters is sent
A: To avoid this please make sure that you send the first poll request without a timestamp. The timestamp should be used only in the second poll.
Q: Do you have passenger name restrictions?
A: Yes. First and last name should contain alphabetic characters only and be at least one character. Empty names, no white space or special characters allowed. Please only use the letters a-z, A-Z (Latin alphabet).
Static Data
Introduction
The static data is accessible via a web service or by downloading data in a CSV file. The data is updated constantly, so make sure to update it at least once a week.
In order to access the static data, you will need to send a valid application key in the request header.
Please note: It is not permitted to use static data dynamically. This means you must download the static data and keep it updated on your side.
Methods
Countries
Request
curl \
-H "aether-application-key: [app-key]" \
https://example.com/countries
Response
[
{
"continent": "Europe",
"id": "AD",
"name": "Andorra",
"region": "Southern Europe",
"regions": [
{
"code": "AN",
"name": "Andorra la Vella"
},
{
"code": "EE",
"name": "Escaldes-Engordany"
}
]
},
{
"continent": "Europe",
"id": "AL",
"name": "Albania",
"region": "Southern Europe",
"regions": [
{
"code": "TR",
"name": "Tirane"
}
]
},
...
]
GET https://example.com/countries
| Attribute | Description |
|---|---|
| id | ISO Alpha-2 country code |
| name | The name of the country |
| continent | Name of the continent |
| region | The region within the continent |
| regions | a collection of provinces or regions within the country |
Destinations
Request
curl \
-H "aether-application-key: [app-key]" \
https://example.com/destinations/AL
Response
[
{
"countryid": "AL",
"id": "6069",
"lat": "41.3275459",
"lon": "19.8186982",
"name": "Tirana",
"seoname": "tirana",
"type": "city"
},
...
]
GET https://example.com/destinations/[country code]
| Attribute | Description |
|---|---|
| countryid | ISO Alpha-2 country code |
| id | a numeric value, the id of the specific location |
| name | The name of the destination |
| type | the type of the destination, whether it’s a city, a region, etc. |
| seoname | a url-safe slug of the destination name |
| lat | Latitude of the destination |
| lon | Longitude of the destination |
Hotels by IDs
Request
curl \
-H "aether-application-key: [app-key]" \
https://example.com/hotels/1,2,3
Response
[
{
"id":"1111",
"name":"Example Hotel",
"address":"123 main street",
"status":"1",
"zip":"12345",
"phone":"+66 666 666666",
"fax":"+66 666 666667",
"lat":"66.6666",
"lon":"77.777",
"seoname":"example-hotel",
"stars":"4",
"destinations":[
{
"destinationId":"666",
"type": "city"
},
{
"destinationId":"84533",
"type": "zone"
}
],
"mainImageId":"666",
"images":[
{
"id":"666",
"width":"375",
"height":"250",
"title":"External View",
"url":"0\/0\/666.png"
},
...
],
"description":"The Example is a superbly decorated 4 star place setting new standards. Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat."
},
...
]
GET https://example.com/hotels/[hotels id list]
The hotel ids should be separated by a comma, and the limit is up to 500 hotel ids per request.
| Attribute | Description |
|---|---|
| id | a numeric value, the id of the specific hotel |
| name | The name of the hotel |
| seoname | a url-safe slug of the destination name |
| lat | Latitude of the destination |
| lon | Longitude of the destination |
| status | The status of the hotel, 0 means disabled, all other positive values means active. |
| address | the physical address of the hotel |
| zip | zip code |
| phone | phone number |
| fax | fax number |
| stars | the number of stars |
| description | free text description. for translations, see translations |
| destinations | a collection of destination ids and types the hotel belongs to. see destinations |
| images | see the images section |
| mainImageId | the main image id of the hotel. the image details will be part of the images collection. |
Hotels Diff Since
Request
curl \
-H "aether-application-key: [app-key]" \
https://example.com/hotels-diff/2018-01-01
Response
[
"1142",
"30087",
...
]
GET https://example.com/hotels-diff/[timestamp]
This method returns the hotel ids of only hotels that changed since the timestamp in the request.
Currencies
Request
curl \
-H "aether-application-key: [app-key]" \
https://example.com/currencies
Response
[
{
"currencyId": "EUR",
"name": "Euro",
"sign": "€",
"active": "1"
},
{
"currencyId": "USD",
"name": "United States Dollars",
"sign": "$",
"active": "1"
}
]
GET https://example.com/currencies
| Attribute | Description |
|---|---|
| currencyId | 3 letter ISO 4217 currency code |
| name | The name of the currency |
| sign | Sign, if any |
| active | boolean, 1 is active, 0 is disabled |
Markets
Request
curl \
-H "aether-application-key: [app-key]" \
https://example.com/markets
Response
[
{
"marketId":"26",
"title":"Western Europe",
"countries":[
"AT",
"BE",
"CH",
"DE",
"FR",
"LI",
"LU",
"MC",
"NL"
]
},
...
]
GET https://example.com/markets
| Attribute | Description |
|---|---|
| marketId | numeric id |
| title | The name of the market |
| countries | ISO Alpha-2 country code collection of countries participating in this market |
Airlines
Request
curl \
-H "aether-application-key: [app-key]" \
https://example.com/airlines
Response
[
{
"iata": "BD",
"name": "bmi",
"alt_name": "bmi British Midland",
"icao": "BMA",
"country": "United Kingdom"
},
...
]
GET https://example.com/airlines
| Attribute | Description |
|---|---|
| iata | iata code (2 letter code) |
| name | The name of the airline |
| alt_name | alternative name, more descriptive |
| icao | icao code of the airline (3 letter code) |
| country | Country of origin |
Facilities
24h reception
accessibility
air condition
babysitting
bar
beach
beauty salon
concierge
conference room
gym
hair dryer
internet
kids pool
laundry services
minibar
nightclub
no smoking
outdoor pool
parking lot
pets friendly
radio
refrigerator
restaurant
room service
safe
sauna
solarium
spa
tv
tv channels (satellite)
bikes
bath
free newspaper
coffee/tea
currency exchange
water sports
bidet
free internet
iron
surcharge airport shuttle
surcharge baby friendly
surcharge babysitting
heated pool
indoor pool
pool
baby friendly
ball sport
diving
free street parking
game room
gift shop
golf course
kitchen
library
newspaper
ping pong
pool bar
squash
tennis court
winter sport
airport shuttle
free bikes
kids club
water park
free airport shuttle
hot tub
surcharge bikes
onsite parking lot
surcharge laundry services
surcharge room service
coffee shop
free shuttle to beach
free kids club
video games
iron services
surcharge shuttle to casino
free baby friendly
mini market
pool table
casino
surcharge valet parking
tv channels (cable)
valet parking
atm
surcharge internet
surcharge street parking
surcharge newspaper
free coffee/tea
free long term parking
free truck parking
surcharge shuttle to train
tv channels (digital)
shared bathroom
free near gym
surcharge pets friendly
surcharge parking lot
surcharge shuttle to beach
truck parking
near gym
bbq
surcharge beach
shared lounge
free minibar
fireplace
surcharge kids club
surcharge shuttle to shopping
free gym
free safe
surcharge spa
board games
electric vehicle charge station
surcharge safe
bowling
surcharge truck parking
onsite atm
surcharge coffee/tea
boating
surfing
street parking
surcharge shuttle to ferry
karaoke
free onsite parking lot
free shuttle to train
beach bar
free valet parking
free babysitting
free conference room
free parking lot
surcharge beauty salon
surcharge long term parking
surcharge shuttle to theme park
surcharge shuttle to cruise
scenic view
onsite beach
free beauty salon
free solarium
onsite golf course
free shuttle to theme park
free shuttle to cruise
free shuttle to ferry
onsite spa
free shuttle to casino
adults only
surcharge shuttle to ski
surcharge minibar
free pets friendly
onsite mini market
onsite water sports
free shuttle to shopping
near nightclub
free water park
lockers
free shuttle to ski
onsite tennis court
shared kitchen
shuttle to ski
surcharge conference room
surcharge pool
surcharge gym
free spa
onsite video games
surcharge solarium
surcharge golf course
shared bath
surcharge water park
halal
free laundry services
near golf course
shuttle to beach
kosher
surcharge sauna
free currency exchange
near beach
near spa
free sauna
near tennis court
onsite winter sport
sea view
near water sports
surcharge air condition
free pool
surcharge onsite parking lot
surcharge tennis court
surcharge pool table
free accessibility
long term parking
surcharge tv channels (cable)
free beach
near restaurant
onsite conference room
surcharge iron
free game room
netflix
surcharge winter sport
surcharge hair dryer
surcharge refrigerator
onsite diving
surcharge video games
onsite restaurant
surcharge ping pong
onsite bikes
surcharge tv channels (satellite)
surcharge accessibility
surcharge iron services
onsite bbq
surcharge kitchen
surcharge bath
surcharge tv
near beauty salon
onsite coffee/tea
free air condition
near atm
near outdoor pool
near casino
surcharge radio
near surfing
free heated pool
free refrigerator
near parking lot
free no smoking
near winter sport
near diving
near bbq
surcharge near parking lot
halal food
kosher food
onsite boating
near boating
Static Data Download
There is an option to download a CSV file with the static data instead of using API.
To download static data in CSV file please use the following endpoint:
https://static-data-console.innstant-servers.com/static-files/download
Images
{
"images":[
{
"id":"100511",
"width":"500",
"height":"500",
"title":"Double Bed",
"url":"0\/100\/100511.png"
},
...
]
}
| Attribute | Description |
|---|---|
| id | a numeric value, the id of the specific image |
| width | width in pixels |
| height | height in pixels |
| title | textual title for the image. Note that it can be empty. |
| url | the url of the image |
To create the full URI, use the following structure:
https://cdn-images.innstant-servers.com/[max-width]x[max-height]/[image-url]
For example:
https://cdn-images.innstant-servers.com/500x500/0/100/100511.jpg
Errors
Search Errors
| Code | Description |
|---|---|
| m400 | Bad Request – Your request sucks |
| m401 | Unauthorized – Your API key is wrong |
| m404 | Required service and/or method not found. Refer to documentation to see available endpoints |
| m405 | Method not allowed! Refer to documentation to see allowed methods |
| m777 | Unexpected infrastructure failure! Please contact us at api@innstant.com |
| m1001 | Invalid Request! Make sure it’s a valid JSON and has allowed values as described in documentation |
| m1003 | Entity id and/or type is wrong! Please contact us at api@innstant.com |
| m1004 | Unexpected internal error occurred. Please contact us at api@innstant.com |
| m1010 | Unexpected internal error occurred. Please contact us at api@innstant.com |
| m1011 | Unexpected internal error occurred. Please contact us at api@innstant.com |
| m1012 | Unexpected internal error occurred. Please contact us at api@innstant.com |
| m1013 | Unexpected internal error occurred. Please contact us at api@innstant.com |
| m1014 | Unexpected internal error occurred. Please contact us at api@innstant.com |
| m1015 | Unexpected internal error occurred. Please contact us at api@innstant.com |
| m1016 | Unexpected internal error occurred. Please contact us at api@innstant.com |
| m1020 | Unexpected internal error occurred. Please contact us at api@innstant.com |
| m1021 | Unexpected internal error occurred. Please contact us at api@innstant.com |
| m1100 | Wrong account setup. Please contact your account manager for more details |
| m1101 | Wrong account setup. Please contact your account manager for more details |
| m1200 | No data found for requested plugin. Please check your spelling |
| m1201 | Account does not exist. Please contact your account manager |
| m1202 | Supplier does not exist. Please contact your account manager |
| m1203 | Agent does not exist. Please contact your account manager |
| m1210 | Unexpected internal error occurred. Please contact us at api@innstant.com |
| m2000 | Unexpected supplier response. Please contact us at api@innstant.com |
| m2001 | Unexpected supplier response. Please contact us at api@innstant.com |
| m2100 | Unexpected supplier response. Please contact us at api@innstant.com |
| m2101 | Unexpected supplier response. Please contact us at api@innstant.com |
| m2102 | Unexpected supplier response. Please contact us at api@innstant.com |
Login errors
| Code | Description |
|---|---|
| a0 | Uncategorized error |
| a100 | Missing login details |
| a101 | Invalid login information |
| a102 | Invalid password |
| a103 | Invalid account status |
| a104 | Invalid agent status |
| a105 | Account disabled |
| a106 | Agent disabled |
| a107 | Invalid login details |
| a108 | Invalid API key |
| a109 | Missing API key |
| a110 | API key disabled |
| a111 | Bad agent configuration |
| a112 | Missing access token |
System errors
| Code | Description |
|---|---|
| a201 | Missing account ID |
| a202 | Missing agent ID |
| a203 | Invalid parameter |
| a204 | Invalid account setup |
| a205 | General error |
| a206 | Missing whitelabel ID |
| a208 | Access storage error |
Permission error
| Code | Description |
|---|---|
| a300 | Permission error |
Booking errors
| Code | Description |
|---|---|
| a400 | Missing booking item |
| a401 | Booking not found |
| a402 | Payment method not supported |
| a403 | Account balance error |
| a404 | Provider failure |
| a405 | Booking expired |
| a406 | Invalid 3D secure token |
| a407 | Invalid markup |
| a408 | Cancellation failed |
| a409 | Broad on request |
| a410 | Missing customer email |
| a414 | Room is unavailable |
Processing errors
| Code | Description |
|---|---|
| a500 | Missing processing credentials |
| a501 | No processing account set |
Accounting errors
| Code | Description |
|---|---|
| a600 | Duplicate document |
| a601 | Document save error |
Payment errors
| Code | Description |
|---|---|
| a700 | Payment authorize is not supported for this interface |
| a701 | Missing amount |
| a702 | Booking already exists (recoverable) |
Warnings
| Code | Description |
|---|---|
| a2100 | Price change (recoverable) |
| a2101 | Board change (recoverable) |
| a2102 | Cancellation policy change (recoverable) |
| a2103 | Result code change (recoverable) |