SpiderTT Hotel Booking API
Complete JSON API for hotel search, booking, and management. All requests are sent in the request body.
API Overview
The SpiderTT Hotel Booking API provides a complete solution for integrating hotel booking capabilities into your applications. All API requests use POST method with JSON data in the request body.
POST
/api/v1/hotelsearch
Search for available hotels based on criteria
POST
/api/v1/prebook
Add selected rooms to PreBook for final pricing
POST
/api/v1/makebook
Confirm booking with passenger details
POST
/api/v1/cancel
Cancel existing bookings
POST
/api/v1/bookdetail
Get booking details
POST
/api/v1/bookinglist
List bookings by date range
Important: All API requests are sent as POST requests with JSON data in the request body.
Standard Workflow
1
Search Hotels
Find available options
→
2
PreBook
Get final pricing
→
3
Make Book
Finalize reservation
→
4
Book Details
Optional
Price Changes: Always use the PreBook endpoint before confirming to get the final price. Prices may change between search and basket stages.
Creating a reservation: If the book response returns a successful result, the reservation was made without any problems.
Download Postman Collection
Get our ready-to-use Postman collection to start testing immediately.
Authentication
All API requests require authentication using credentials in the request body and Client ID in headers.
Request Headers
HTTP Headers
{
"Content-Type": "application/json",
"X-ClientId": "D96A2E1B-EC5B-4D35-8D5B-F462A5C2A721",
'Accept-Encoding': 'gzip'
}
Credentials in Request Body
All request bodies must include credentials object:
JSON
{
"credentials": {
"clientId": "D96A2E1B-EC5B-4D35-8D5B-F462A5C2A721",
"username": "testaccount@xmltest.com",
"password": "xmltest"
}
}
IP Whitelisting Required: You must provide your static IP addresses to SpiderTT for production environments.
Quick Start
Get started with the SpiderTT API in just a few steps.
1. Get Credentials
Contact SpiderTT to get your API credentials and Client ID for both test and production environments.
2. Set Up IP Whitelisting
Provide your static IP addresses to SpiderTT for whitelisting in live environments.
3. Test Integration
Use the test environment to verify your integration before going live.
Environments
Test Environment
Base URL:
Purpose: Development and testing integration
Requirements: test credentials
https://testxml.spidertt.com/api/v1
Purpose: Development and testing integration
Requirements: test credentials
Migration Process
- Complete integration testing in test environment
- Pass certification process with SpiderTT
- Provide production IP addresses for whitelisting
- Switch to production credentials and base URL
Search Hotels
POST/api/v1/hotelsearch
Search for available hotels based on criteria like dates, location, room requirements, and guest nationality.
JSON
{
"checkInDate": "20251216",
"checkOutDate": "20251218",
"hotelId": "72036,55517,308696,430364",
"nationalityCode": "DE",
"timeout": 3.2,
"paginationData": {
"pageNumber": 1,
"itemsPerPage": 50000
},
"roomCriteria": [
{
"adultCount": 1,
"roomCount": 1,
"childCount": 0,
"childAges": []
},
{
"adultCount": 2,
"roomCount": 1,
"childCount": 2,
"childAges": [3, 9]
}
],
"credentials": {
"clientId": "D96A2E1B-EC5B-4D35-8D5B-F462A5C2A721",
"username": "testaccount@xmltest.com",
"password": "xmltest"
}
}
JSON
{
"token": "123e33d3-36a2-4843-a61b-618a57782db3",
"paginationData": {
"pageNumber": 1,
"itemsPerPage": 50000
},
"errors": {},
"availableHotel": [
{
"availableHotelItem": [
{
"fromDate": "20251216",
"toDate": "20251218",
"availableHotelCount": 1,
"hotels": [
{
"isPromotion": 0,
"hotelCode": "72036",
"hotelName": "ATest This is not for sale",
"currency": "EUR",
"remark": " Please note that in some countries there is a local tax known as stay tax or tourist tax (city-tax) which must be paid directly by the guest at the hotel.",
"errors": {},
"status": "Search",
"supplierType": "One",
"availableRoom": [
{
"hotelOccupancy": {
"roomCount": 1,
"roomIndex": 0,
"roomGroupCode": "c97315ee-ec9a-4d23-941b-d05019a291f1",
"occupancy": {
"adultCount": 1,
"childCount": 0,
"childrenAges": "",
"passengers": []
}
},
"hotelRoom": [
{
"availCount": 1,
"isPackage": false,
"nonRefundable": true,
"cancellationPolicy": [
{
"amount": "210,00",
"dateTimeFrom": "20251119",
"penaltyType": "Amount",
"dateTimeTo": "20251119"
}
],
"hotelRoomUniqueNumber": {
"xmlServicesUniqueNumber": "08fb3291-9ed0-40fe-8c6d-ef5a96b0fc39|34f9f709-3a97-4f7a-b0c4-a73e9bded331|1|72036|1~0~0|1",
"spiderUniqueNumber": "8d663d3d-d680-49bc-9ad6-44ccfe8beb18",
"xmlServicesType": "One"
},
"board": {
"code": "63c52170-7e54-462f-97b4-11b52fc4e9ff",
"name": "All Inclusive"
},
"roomType": {
"characteristic": "Standard Room",
"code": "08fb3291-9ed0-40fe-8c6d-ef5a96b0fc39",
"name": "Standard Room Single Use"
},
"price": {
"amount": "210,00",
"currency": "EUR"
}
}
]
},
{
"hotelOccupancy": {
"roomCount": 1,
"roomIndex": 1,
"roomGroupCode": "c97315ee-ec9a-4d23-941b-d05019a291f1",
"occupancy": {
"adultCount": 2,
"childCount": 2,
"childrenAges": "3,9",
"passengers": []
}
},
"hotelRoom": [
{
"availCount": 1,
"isPackage": false,
"nonRefundable": true,
"cancellationPolicy": [
{
"amount": "277,20",
"dateTimeFrom": "20251119",
"penaltyType": "Amount",
"dateTimeTo": "20251119"
}
],
"hotelRoomUniqueNumber": {
"xmlServicesUniqueNumber": "6191999c-e889-4697-a733-d0f6b7db1057|34f9f709-3a97-4f7a-b0c4-a73e9bded331|2|72036|2~2~3~9|2",
"spiderUniqueNumber": "3496af30-49df-4446-9eb0-d3cd0e89158c",
"xmlServicesType": "One"
},
"board": {
"code": "63c52170-7e54-462f-97b4-11b52fc4e9ff",
"name": "All Inclusive"
},
"roomType": {
"characteristic": "Standard Room",
"code": "6191999c-e889-4697-a733-d0f6b7db1057",
"name": "Standard Room Unit Rate"
},
"price": {
"amount": "277,20",
"currency": "EUR"
}
}
]
}
]
}
]
}
]
}
]
}
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| checkInDate | string | Yes | Check-in date (YYYYMMDD) |
| checkOutDate | string | Yes | Check-out date (YYYYMMDD) |
| nationalityCode | string | Yes | 2-letter country code of guest nationality |
| roomCriteria | array | Yes | Array of room requirements |
| hotelId | string | Yes | Specific hotel IDs to search, HotelIds must be sent with ",". (Max: 300 - recommended: 200 codes) |
| timeout | number | No | Search timeout in seconds (Max:5 seconds) |
Multiple Room Parameters
Important: Understanding RoomIndex and RoomGroupCode is crucial for successful hotel searches and bookings.
RoomIndex
A simple sequential number (0, 1, 2, etc.) used to identify and reference each specific room within your search request.
Key Points:
- Received from search results
- Always starts from 0
- Must be sequential (0, 1, 2, ...)
- Used to reference specific rooms in subsequent API calls
- Maintains room order throughout the booking process
RoomGroupCode
A unique code that identifies a specific room type and configuration. This code is returned in the search response and must be used for booking.
Multi-Room Booking Rule: All rooms in a single booking request must have the same RoomGroupCode. You cannot book rooms with different RoomGroupCodes in the same reservation.
Key Points:
- Received from search results
- Identifies room type
- Must be identical for all rooms in multi-room bookings
RoomIndex and RoomGroupCode Validation Rules
Critical Validation: RoomIndex must be sequential and RoomGroupCode must be identical for all rooms in multi-room bookings.
Common Validation Errors
Error 1: Non-Sequential RoomIndex
Problem: RoomIndex values must be sequential starting from 0. Skipping numbers or using duplicates causes errors.
✓ Correct
JSON
{
"HotelRoomUniqueNumbers": [
{
// RoomIndex: 0
// RoomGroupCode: "8720d9b2-4489-43f0-a1ee-c3d00f40c110"
"SelectHotelRoomDTO": {
"HotelRoomUniqueNumbers": [
{
"HotelRoomUniqueNumberDTO": {
"XmlServicesUniqueNumber": "..."
}
}
]
}
},
{
// RoomIndex: 1
// RoomGroupCode: "8720d9b2-4489-43f0-a1ee-c3d00f40c110"
"SelectHotelRoomDTO": {
"HotelRoomUniqueNumbers": [
{
"HotelRoomUniqueNumberDTO": {
"XmlServicesUniqueNumber": "..."
}
}
]
}
},
{
// RoomIndex: 2
// RoomGroupCode: "8720d9b2-4489-43f0-a1ee-c3d00f40c110"
"SelectHotelRoomDTO": {
"HotelRoomUniqueNumbers": [
{
"HotelRoomUniqueNumberDTO": {
"XmlServicesUniqueNumber": "..."
}
}
]
}
}
]
}✗ Error
JSON
{
"HotelRoomUniqueNumbers": [
{
// RoomIndex: 0
"SelectHotelRoomDTO": {
"HotelRoomUniqueNumbers": [
{
"HotelRoomUniqueNumberDTO": {
"XmlServicesUniqueNumber": "..."
}
}
]
}
},
{
// RoomIndex: 1
"SelectHotelRoomDTO": {
"HotelRoomUniqueNumbers": [
{
"HotelRoomUniqueNumberDTO": {
"XmlServicesUniqueNumber": "..."
}
}
]
}
},
{
// RoomIndex: 1 - ERROR: Duplicate RoomIndex
"SelectHotelRoomDTO": {
"HotelRoomUniqueNumbers": [
{
"HotelRoomUniqueNumberDTO": {
"XmlServicesUniqueNumber": "..." // Should be RoomIndex 2
}
}
]
}
}
]
}
Solution: Ensure RoomIndex values are sequential (0, 1, 2, ...). The last number in XmlServicesUniqueNumber indicates the expected RoomIndex.
Error 2: Different RoomGroupCodes
Problem: All rooms in a multi-room booking must have the same RoomGroupCode. Mixing different room types is not allowed.
✓ Correct
JSON
{
"HotelRoomUniqueNumbers": [
{
// RoomIndex: 0
// RoomGroupCode: "8720d9b2-4489-43f0-a1ee-c3d00f40c110"
"SelectHotelRoomDTO": {
"HotelRoomUniqueNumbers": [
{
"HotelRoomUniqueNumberDTO": {
"XmlServicesUniqueNumber": "..."
}
}
]
}
},
{
// RoomIndex: 1
// RoomGroupCode: "8720d9b2-4489-43f0-a1ee-c3d00f40c110"
"SelectHotelRoomDTO": {
"HotelRoomUniqueNumbers": [
{
"HotelRoomUniqueNumberDTO": {
"XmlServicesUniqueNumber": "..."
}
}
]
}
},
{
// RoomIndex: 2
// RoomGroupCode: "8720d9b2-4489-43f0-a1ee-c3d00f40c110"
"SelectHotelRoomDTO": {
"HotelRoomUniqueNumbers": [
{
"HotelRoomUniqueNumberDTO": {
"XmlServicesUniqueNumber": "..."
}
}
]
}
}
]
}✗ Error
JSON
{
"HotelRoomUniqueNumbers": [
{
// RoomIndex: 0
// RoomGroupCode: "8720d9b2-4489-43f0-a1ee-c3d00f40c110"
"SelectHotelRoomDTO": {
"HotelRoomUniqueNumbers": [
{
"HotelRoomUniqueNumberDTO": {
"XmlServicesUniqueNumber": "..."
}
}
]
}
},
{
// RoomIndex: 1
// RoomGroupCode: "8720d9b2-4489-43f0-a1ee-c3d00f40c110"
"SelectHotelRoomDTO": {
"HotelRoomUniqueNumbers": [
{
"HotelRoomUniqueNumberDTO": {
"XmlServicesUniqueNumber": "..."
}
}
]
}
},
{
// RoomIndex: 2
// RoomGroupCode: "d61a6522-8758-42fc-9f51-f01eaca79d26" - ERROR: Different RoomGroupCode
"SelectHotelRoomDTO": {
"HotelRoomUniqueNumbers": [
{
"HotelRoomUniqueNumberDTO": {
"XmlServicesUniqueNumber": "..."
}
}
]
}
}
]
}
Solution: Use the same RoomGroupCode for all rooms in the booking. If you need different room types, make separate booking requests.
Validation Rules Summary
| Rule | Requirement | Error Example |
|---|---|---|
| RoomIndex Sequence | Must be sequential: 0, 1, 2, ... | 0, 1, 1 (duplicate) or 0, 2 (missing 1) |
| RoomGroupCode Consistency | All rooms must have identical RoomGroupCode | Different RoomGroupCodes in multi-room booking |
Best Practices
Validate RoomIndex Sequence: Always ensure RoomIndex values are sequential starting from 0
Check RoomGroupCode Consistency: Verify all rooms use the same RoomGroupCode before sending request
Best Practice: When booking multiple rooms, ensure all rooms use the same RoomGroupCode. If you need different room types, make separate booking requests.
PreBook Hotels
POST/api/v1/PreBook
Add selected rooms to PreBook to get final pricing and availability confirmation before booking.
Mandatory Step: This method must be called before Confirm to get the final price and availability. (30-Second Timeout:)
JSON
{
"Token": "123e33d3-36a2-4843-a61b-618a57782db3",
"HotelRoomUniqueNumbers": [
{
"HotelRoomUniqueNumbers": [
{
"xmlServicesUniqueNumber": "08fb3291-9ed0-40fe-8c6d-ef5a96b0fc39|34f9f709-3a97-4f7a-b0c4-a73e9bded331|1|72036|1~0~0|1",
"spiderUniqueNumber": "8d663d3d-d680-49bc-9ad6-44ccfe8beb18",
"xmlServicesType": "One"
}
]
},
{
"HotelRoomUniqueNumbers": [
{
"xmlServicesUniqueNumber": "6191999c-e889-4697-a733-d0f6b7db1057|34f9f709-3a97-4f7a-b0c4-a73e9bded331|2|72036|2~2~3~9|2",
"spiderUniqueNumber": "3496af30-49df-4446-9eb0-d3cd0e89158c",
"xmlServicesType": "One"
}
]
}
],
"credentials": {
"clientId": "D96A2E1B-EC5B-4D35-8D5B-F462A5C2A721",
"username": "testaccount@xmltest.com",
"password": "xmltest"
}
}
JSON
{
"token": "123e33d3-36a2-4843-a61b-618a57782db3",
"errors": {},
"hotelBasketItem": [
{
"fromDate": "20251216",
"toDate": "20251218",
"hotels": [
{
"purchaseToken": "123e33d3-36a2-4843-a61b-618a57782db3",
"isPromotion": 0,
"hotelCode": "72036",
"hotelName": "ATest This is not for sale",
"currency": "EUR",
"remark": "This is a test hotel! Please do not book!!!\nIf you make a booking for Test Hotel, your booking will be cancelled automatically. Please note that in some countries there is a local tax known as stay tax or tourist tax (city-tax) which must be paid directly by the guest at the hotel.",
"errors": {},
"status": "Basket",
"supplierType": "One",
"availableRoom": [
{
"hotelOccupancy": {
"roomCount": 1,
"occupancy": {
"adultCount": 1,
"childCount": 0,
"passengers": []
}
},
"hotelRoom": [
{
"availCount": 1,
"isPackage": false,
"nonRefundable": false,
"cancellationPolicy": [
{
"amount": "210,00",
"dateTimeFrom": "20251214",
"penaltyType": "Amount",
"dateTimeTo": "20251214"
}
],
"hotelRoomUniqueNumber": {
"xmlServicesUniqueNumber": "08fb3291-9ed0-40fe-8c6d-ef5a96b0fc39|34f9f709-3a97-4f7a-b0c4-a73e9bded331|1|72036|1~0~0|1",
"spiderUniqueNumber": "8d663d3d-d680-49bc-9ad6-44ccfe8beb18",
"xmlServicesType": "One"
},
"board": {
"code": "63c52170-7e54-462f-97b4-11b52fc4e9ff",
"name": "All Inclusive"
},
"roomType": {
"characteristic": "Standard Room",
"code": "08fb3291-9ed0-40fe-8c6d-ef5a96b0fc39",
"name": "Standard Room Single Use"
},
"price": {
"amount": "210,00",
"currency": "EUR"
}
}
]
},
{
"hotelOccupancy": {
"roomCount": 1,
"occupancy": {
"adultCount": 2,
"childCount": 2,
"passengers": []
}
},
"hotelRoom": [
{
"availCount": 1,
"isPackage": false,
"nonRefundable": false,
"cancellationPolicy": [
{
"amount": "277,20",
"dateTimeFrom": "20251214",
"penaltyType": "Amount",
"dateTimeTo": "20251214"
}
],
"hotelRoomUniqueNumber": {
"xmlServicesUniqueNumber": "6191999c-e889-4697-a733-d0f6b7db1057|34f9f709-3a97-4f7a-b0c4-a73e9bded331|2|72036|2~2~3~9|2",
"spiderUniqueNumber": "3496af30-49df-4446-9eb0-d3cd0e89158c",
"xmlServicesType": "One"
},
"board": {
"code": "63c52170-7e54-462f-97b4-11b52fc4e9ff",
"name": "All Inclusive"
},
"roomType": {
"characteristic": "Standard Room",
"code": "6191999c-e889-4697-a733-d0f6b7db1057",
"name": "Standard Room Unit Rate"
},
"price": {
"amount": "277,20",
"currency": "EUR"
}
}
]
}
]
}
]
}
]
}
Confirm Booking
POST/api/v1/MakeBook
Finalize the booking with passenger details and complete the reservation.
90-Second Timeout: Confirm operation has a 90-second response timeout. Ensure your system can handle this.
JSON
{
"ReferenceNumber": "Test1111",
"Token": "123e33d3-36a2-4843-a61b-618a57782db3",
"PurchaseToken": [
{
"ConfirmPassenger": [
{
"PurchaseToken": "123e33d3-36a2-4843-a61b-618a57782db3",
"Occupancy": {
"AdultCount": 2,
"ChildCount": 2,
"Passengers": [
{
"IsLeader": true,
"ID": "0",
"SalutationID": "66f1c75c-dff4-4305-99b7-19cdbdc9135a",
"Name": "Test2",
"LastName": "Test2",
"Age": 30,
"AgeSpecified": true,
"PassengerType": "Adult"
},
{
"IsLeader": false,
"ID": "1",
"SalutationID": "66f1c75c-dff4-4305-99b7-19cdbdc9135a",
"Name": "Test3",
"LastName": "Test3",
"Age": 30,
"AgeSpecified": true,
"PassengerType": "Adult"
},
{
"IsLeader": false,
"ID": "2",
"SalutationID": "66f1c75c-dff4-4305-99b7-19cdbdc9135a",
"Name": "CHD9",
"LastName": "CHD9",
"Age": 9,
"AgeSpecified": true,
"PassengerType": "Child"
},
{
"IsLeader": false,
"ID": "3",
"SalutationID": "66f1c75c-dff4-4305-99b7-19cdbdc9135a",
"Name": "CHD3",
"LastName": "CHD3",
"Age": 3,
"AgeSpecified": true,
"PassengerType": "Child"
}
]
},
"HotelRoomUniqueNumber": {
"xmlServicesUniqueNumber": "6191999c-e889-4697-a733-d0f6b7db1057|34f9f709-3a97-4f7a-b0c4-a73e9bded331|2|72036|2~2~3~9|2",
"spiderUniqueNumber": "3496af30-49df-4446-9eb0-d3cd0e89158c",
"xmlServicesType": "One"
}
},
{
"PurchaseToken": "123e33d3-36a2-4843-a61b-618a57782db3",
"Occupancy": {
"AdultCount": 1,
"ChildCount": 0,
"ChildrenAges": null,
"Passengers": [
{
"IsLeader": true,
"ID": "0",
"SalutationID": "66f1c75c-dff4-4305-99b7-19cdbdc9135a",
"Name": "Test1",
"LastName": "Test1",
"Age": 30,
"AgeSpecified": true,
"PassengerType": "Adult"
}
]
},
"HotelRoomUniqueNumber": {
"xmlServicesUniqueNumber": "08fb3291-9ed0-40fe-8c6d-ef5a96b0fc39|34f9f709-3a97-4f7a-b0c4-a73e9bded331|1|72036|1~0~0|1",
"spiderUniqueNumber": "8d663d3d-d680-49bc-9ad6-44ccfe8beb18",
"xmlServicesType": "One"
}
}
]
}
],
"credentials": {
"clientId": "D96A2E1B-EC5B-4D35-8D5B-F462A5C2A721",
"username": "testaccount@xmltest.com",
"password": "xmltest"
}
}
JSON
{
"fileNumber": "25011022",
"referenceNumber": "Test1111",
"token": "123e33d3-36a2-4843-a61b-618a57782db3",
"errors": {},
"confirmationItem": [
{
"confirmationItem": [
{
"fromDate": "20251216",
"toDate": "20251218",
"hotels": [
{
"isPromotion": 0,
"promotionCode": "",
"hotelCode": "72036",
"hotelName": "ATest This is not for sale",
"currency": "EUR",
"remark": "This is a test hotel! Please do not book!!!\nIf you make a booking for Test Hotel, your booking will be cancelled automatically. Please note that in some countries there is a local tax known as stay tax or tourist tax (city-tax) which must be paid directly by the guest at the hotel.",
"errors": {},
"status": "Confirmed",
"supplierType": "One",
"availableRoom": [
{
"hotelOccupancy": {
"roomCount": 1,
"occupancy": {
"adultCount": 1,
"childCount": 0,
"passengers": [
{
"isLeader": true,
"id": "0",
"salutationID": "66f1c75c-dff4-4305-99b7-19cdbdc9135a",
"name": "Test1",
"lastName": "Test1",
"age": 30,
"ageSpecified": true,
"passengerType": "Adult"
}
]
}
},
"hotelRoom": [
{
"availCount": 1,
"isPackage": false,
"cancellationPolicy": [
{
"amount": "210,00",
"dateTimeFrom": "20251214",
"penaltyType": "Amount",
"dateTimeTo": "20251214"
}
],
"hotelRoomUniqueNumber": {
"xmlServicesUniqueNumber": "08fb3291-9ed0-40fe-8c6d-ef5a96b0fc39|34f9f709-3a97-4f7a-b0c4-a73e9bded331|1|72036|1~0~0|1",
"spiderUniqueNumber": "8d663d3d-d680-49bc-9ad6-44ccfe8beb18",
"xmlServicesType": "One"
},
"board": {
"code": "63c52170-7e54-462f-97b4-11b52fc4e9ff",
"name": "All Inclusive"
},
"roomType": {
"characteristic": "Standard Room",
"code": "08fb3291-9ed0-40fe-8c6d-ef5a96b0fc39",
"name": "Standard Room Single Use"
},
"price": {
"amount": "210,00",
"currency": "EUR"
}
}
]
},
{
"hotelOccupancy": {
"roomCount": 1,
"occupancy": {
"adultCount": 2,
"childCount": 2,
"passengers": [
{
"isLeader": true,
"id": "0",
"salutationID": "66f1c75c-dff4-4305-99b7-19cdbdc9135a",
"name": "Test2",
"lastName": "Test2",
"age": 30,
"ageSpecified": true,
"passengerType": "Adult"
},
{
"isLeader": false,
"id": "1",
"salutationID": "66f1c75c-dff4-4305-99b7-19cdbdc9135a",
"name": "Test3",
"lastName": "Test3",
"age": 30,
"ageSpecified": true,
"passengerType": "Adult"
},
{
"isLeader": false,
"id": "2",
"salutationID": "66f1c75c-dff4-4305-99b7-19cdbdc9135a",
"name": "CHD9",
"lastName": "CHD9",
"age": 9,
"ageSpecified": true,
"passengerType": "Child"
},
{
"isLeader": false,
"id": "3",
"salutationID": "66f1c75c-dff4-4305-99b7-19cdbdc9135a",
"name": "CHD3",
"lastName": "CHD3",
"age": 3,
"ageSpecified": true,
"passengerType": "Child"
}
]
}
},
"hotelRoom": [
{
"availCount": 1,
"isPackage": false,
"cancellationPolicy": [
{
"amount": "277,20",
"dateTimeFrom": "20251214",
"penaltyType": "Amount",
"dateTimeTo": "20251214"
}
],
"hotelRoomUniqueNumber": {
"xmlServicesUniqueNumber": "6191999c-e889-4697-a733-d0f6b7db1057|34f9f709-3a97-4f7a-b0c4-a73e9bded331|2|72036|2~2~3~9|2",
"spiderUniqueNumber": "3496af30-49df-4446-9eb0-d3cd0e89158c",
"xmlServicesType": "One"
},
"board": {
"code": "63c52170-7e54-462f-97b4-11b52fc4e9ff",
"name": "All Inclusive"
},
"roomType": {
"characteristic": "Standard Room",
"code": "6191999c-e889-4697-a733-d0f6b7db1057",
"name": "Standard Room Unit Rate"
},
"price": {
"amount": "277,20",
"currency": "EUR"
}
}
]
}
]
}
]
}
]
}
]
}
Cancel Booking
POST/api/v1/cancel
Cancel an existing booking. This operation is only valid when the booking has a confirmed status.
JSON
{
"fileNumber": "232304441",
"credentials": {
"clientId": "D96A2E1B-EC5B-4D35-8D5B-F462A5C2A721",
"username": "testaccount@xmltest.com",
"password": "xmltest"
}
}
JSON
{
"fromDate": "16.12.2025",
"toDate": "18.12.2025",
"fileNumber": "25011022",
"referenceNumber": "Test1111",
"currency": "EUR",
"price": {
"amount": "0"
},
"errors": {},
"hotelCancelItem": [
{
"hotelCancelItem": [
{
"hotels": [
{
"hotelCode": "72036",
"hotelName": "ATest This is not for sale",
"status": "Cancel",
"supplierType": "One",
"availableRoom": [
{
"hotelOccupancy": {
"roomCount": 1,
"occupancy": {
"adultCount": 0,
"childCount": 0,
"passengers": [
{
"isLeader": false,
"salutationID": "3e1ae250-4d00-47b1-b9c0-a1c9ea07bf10",
"name": "CHD3 CHD3",
"lastName": "CHD3 CHD3",
"age": 3,
"ageSpecified": false,
"passengerType": "Child"
},
{
"isLeader": false,
"salutationID": "9aa5ef7b-2ad9-496c-8bb6-40bf936a9280",
"name": "TEST3 TEST3",
"lastName": "TEST3 TEST3",
"age": 0,
"ageSpecified": false,
"passengerType": "Adult"
},
{
"isLeader": false,
"salutationID": "7eff5a1a-f6cc-4ed4-a9cf-d9cfbd9a44f0",
"name": "CHD9 CHD9",
"lastName": "CHD9 CHD9",
"age": 9,
"ageSpecified": false,
"passengerType": "Child"
},
{
"isLeader": true,
"salutationID": "84de9a01-1f4d-4aa0-9574-cfe788c75a32",
"name": "TEST2 TEST2",
"lastName": "TEST2 TEST2",
"age": 0,
"ageSpecified": false,
"passengerType": "Adult"
}
]
}
},
"hotelRoom": [
{
"availCount": 1,
"cancellationPolicy": [
{
"amount": "277,20",
"dateTimeFrom": "2025-12-14",
"penaltyType": "Amount"
}
],
"board": {
"code": "AI-R",
"name": "All Inclusive"
},
"roomType": {
"characteristic": "Standard Room",
"name": "Standard Room"
}
}
]
},
{
"hotelOccupancy": {
"roomCount": 1,
"occupancy": {
"adultCount": 0,
"childCount": 0,
"passengers": [
{
"isLeader": true,
"salutationID": "4c8b583a-c228-4706-b41f-35cbef7c8b6c",
"name": "TEST1 TEST1",
"lastName": "TEST1 TEST1",
"age": 0,
"ageSpecified": false,
"passengerType": "Adult"
}
]
}
},
"hotelRoom": [
{
"availCount": 1,
"cancellationPolicy": [
{
"amount": "210,00",
"dateTimeFrom": "2025-12-14",
"penaltyType": "Amount"
}
],
"board": {
"code": "AI-R",
"name": "All Inclusive"
},
"roomType": {
"characteristic": "Standard Room",
"name": "Standard Room"
}
}
]
}
]
}
]
}
]
}
]
}
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| fileNumber | string | Yes | Unique booking identifier from confirmation |
Booking Details
POST/api/v1/bookdetail
Get detailed information about a specific confirmed booking.
JSON
{
"fileNumber": "25011022",
"credentials": {
"clientId": "D96A2E1B-EC5B-4D35-8D5B-F462A5C2A721",
"username": "testaccount@xmltest.com",
"password": "xmltest"
}
}
JSON
{
"fromDate": "2025-12-16",
"toDate": "2025-12-18",
"fileNumber": "25011022",
"referenceNumber": "Test1111",
"token": "EUR",
"currency": "EUR",
"price": {
"amount": "0"
},
"hotelDetailItem": [
{
"hotelDetailItem": [
{
"hotels": [
{
"hotelCode": "72036",
"hotelConfirmationNumber": "",
"hotelName": "ATest This is not for sale",
"status": "Cancel",
"supplierType": "One",
"availableRoom": [
{
"hotelOccupancy": {
"roomCount": 1,
"occupancy": {
"adultCount": 2,
"childCount": 2,
"passengers": [
{
"isLeader": false,
"salutationID": "66f1c75c-dff4-4305-99b7-19cdbdc9135a",
"name": "CHD3 CHD3",
"lastName": "CHD3 CHD3",
"age": 3,
"ageSpecified": false,
"passengerType": "Child"
},
{
"isLeader": false,
"salutationID": "66f1c75c-dff4-4305-99b7-19cdbdc9135a",
"name": "TEST3 TEST3",
"lastName": "TEST3 TEST3",
"age": 0,
"ageSpecified": false,
"passengerType": "Adult"
},
{
"isLeader": false,
"salutationID": "66f1c75c-dff4-4305-99b7-19cdbdc9135a",
"name": "CHD9 CHD9",
"lastName": "CHD9 CHD9",
"age": 9,
"ageSpecified": false,
"passengerType": "Child"
},
{
"isLeader": true,
"salutationID": "66f1c75c-dff4-4305-99b7-19cdbdc9135a",
"name": "TEST2 TEST2",
"lastName": "TEST2 TEST2",
"age": 0,
"ageSpecified": false,
"passengerType": "Adult"
}
]
}
},
"hotelRoom": [
{
"availCount": 1,
"cancellationPolicy": [
{
"amount": "277,20",
"dateTimeFrom": "20251214",
"penaltyType": "Percent"
}
],
"board": {
"code": "63c52170-7e54-462f-97b4-11b52fc4e9ff",
"name": "All Inclusive"
},
"roomType": {
"characteristic": "STANDARD ROOM",
"name": "STANDARD ROOM"
}
}
]
},
{
"hotelOccupancy": {
"roomCount": 1,
"occupancy": {
"adultCount": 1,
"childCount": 0,
"passengers": [
{
"isLeader": true,
"salutationID": "66f1c75c-dff4-4305-99b7-19cdbdc9135a",
"name": "TEST1 TEST1",
"lastName": "TEST1 TEST1",
"age": 0,
"ageSpecified": false,
"passengerType": "Adult"
}
]
}
},
"hotelRoom": [
{
"availCount": 1,
"cancellationPolicy": [
{
"amount": "277,20",
"dateTimeFrom": "20251214",
"penaltyType": "Percent"
}
],
"board": {
"code": "63c52170-7e54-462f-97b4-11b52fc4e9ff",
"name": "All Inclusive"
},
"roomType": {
"characteristic": "STANDARD ROOM",
"name": "STANDARD ROOM"
}
}
]
}
],
"remark": "This is a test hotel! Please do not book!!!\nIf you make a booking for Test Hotel, your booking will be cancelled automatically."
}
]
}
]
}
]
}
Booking List
POST/api/v1/bookinglist
Get a list of bookings within a specific date range.
JSON
{
"fromDate": "21.11.2025",
"toDate": "28.11.2025",
"credentials": {
"clientId": "D96A2E1B-EC5B-4D35-8D5B-F462A5C2A721",
"username": "testaccount@xmltest.com",
"password": "xmltest"
}
}
JSON
{
"errors": {},
"hotelDetailItem": [
{
"hotelDetailItem": [
{
"hotelsByDates": [
{
"hotelInformations": {
"hotelCode": "72036",
"hotelName": "ATest This is not for sale",
"address": "Taksim\r\n",
"phone": "+90 212 2121212",
"mail": "support@adonis.com",
"longitude": "456456",
"latitude": "45646",
"remark": "This is a test hotel! Please do not book!!!\nIf you make a booking for Test Hotel, your booking will be cancelled automatically."
},
"createdDate": "21.11.2025 10:01:55",
"fileNumber": "25011022",
"referenceNumber": "Test1111",
"fromDate": "20251216",
"toDate": "20251218",
"currency": "EUR",
"price": {
"amount": "0"
},
"errors": {},
"status": "Cancel",
"supplierType": "One",
"availableRoom": [
{
"hotelOccupancy": {
"roomCount": 1,
"occupancy": {
"adultCount": 2,
"childCount": 2,
"passengers": [
{
"isLeader": false,
"salutationID": "66f1c75c-dff4-4305-99b7-19cdbdc9135a",
"name": "CHD3 CHD3",
"lastName": "CHD3 CHD3",
"age": 3,
"ageSpecified": false,
"passengerType": "Child"
},
{
"isLeader": false,
"salutationID": "66f1c75c-dff4-4305-99b7-19cdbdc9135a",
"name": "TEST3 TEST3",
"lastName": "TEST3 TEST3",
"age": 0,
"ageSpecified": false,
"passengerType": "Adult"
},
{
"isLeader": false,
"salutationID": "66f1c75c-dff4-4305-99b7-19cdbdc9135a",
"name": "CHD9 CHD9",
"lastName": "CHD9 CHD9",
"age": 9,
"ageSpecified": false,
"passengerType": "Child"
},
{
"isLeader": true,
"salutationID": "66f1c75c-dff4-4305-99b7-19cdbdc9135a",
"name": "TEST2 TEST2",
"lastName": "TEST2 TEST2",
"age": 0,
"ageSpecified": false,
"passengerType": "Adult"
}
]
}
},
"hotelRoom": [
{
"availCount": 1,
"cancellationPolicy": [
{
"amount": "277,20",
"dateTimeFrom": "20251214",
"penaltyType": "Amount"
}
],
"board": {
"code": "AI-R",
"name": "All Inclusive"
},
"roomType": {
"characteristic": "(Standard Double or Twin Room ( Street )) Unit Rate",
"name": "Standard Double or Twin Room ( Street )"
}
}
]
},
{
"hotelOccupancy": {
"roomCount": 1,
"occupancy": {
"adultCount": 1,
"childCount": 0,
"passengers": [
{
"isLeader": true,
"salutationID": "66f1c75c-dff4-4305-99b7-19cdbdc9135a",
"name": "TEST1 TEST1",
"lastName": "TEST1 TEST1",
"age": 0,
"ageSpecified": false,
"passengerType": "Adult"
}
]
}
},
"hotelRoom": [
{
"availCount": 1,
"cancellationPolicy": [
{
"amount": "210,00",
"dateTimeFrom": "20251214",
"penaltyType": "Amount"
}
],
"board": {
"code": "AI-R",
"name": "All Inclusive"
},
"roomType": {
"characteristic": "(Standard Double or Twin Room ( Street )) Single Use",
"name": "Standard Double or Twin Room ( Street )"
}
}
]
}
]
}
]
}
]
}
]
}
Salutation Codes
Use these codes for passenger title/salutation in booking requests.
| Salutation | Code | Usage |
|---|---|---|
| Mr. | 66f1c75c-dff4-4305-99b7-19cdbdc9135a |
Adult male passengers |
| Mrs. | 67f1c75c-dff4-4305-99b7-19cdbdc9135a |
Adult female passengers (married) |
| Ms. | 68f1c75c-dff4-4305-99b7-19cdbdc9135a |
Adult female passengers (unmarried) |
Usage Example: Include the salutation code in passenger objects when confirming bookings.
JSON
{
"passengers": [
{
"isLeader": true,
"id": "1",
"salutationId": "66f1c75c-dff4-4305-99b7-19cdbdc9135a",
"name": "JOHN",
"lastName": "SMITH",
"passengerType": "Adult"
"Age": 30
"AgeSpecified": true
}
]
}
Board Type Codes
Meal plan codes used in room descriptions and pricing.
| Code | Name |
|---|---|
DE518B9F-CDB1-4047-BCA1-8BC97EE406AF
|
All Inclusive (Non-Refundable) |
63c52170-7e54-462f-97b4-11b52fc4e9ff
|
All Inclusive |
81ac9ca6-2207-4791-b37a-14a3cbe6e1be
|
Non Alcoholic All Inclusive (Refundable) |
e6c1590d-e486-452c-9fed-21b9a6ce2344
|
Room Only (Non-Refundable) |
7f382720-2ac1-4ec7-a79a-37bcc325c562
|
Full Board (Non-Refundable) |
c7613c99-6aa9-4194-9d1b-5af87c6d2e5f
|
Full Board |
bc7a1316-cae9-4286-996f-7f7e4c64a544
|
Room Only |
6958e34f-805c-4bdf-8bdb-93b08b0d7214
|
Half Board (Non-Refundable) |
a3fe0731-528c-4928-a326-9e0d65454756
|
Ultra All Inclusive |
d951aea7-4252-421e-bc96-b2b2822b8e35
|
Bed and Breakfast (Non-Refundable) |
1aa9e39b-51ae-41f9-964b-b94f22b6c643
|
Half Board |
4ba9e39b-51ae-41f9-964b-b94f22b6c643
|
Bed and Breakfast |
cdb8670a-368f-4653-879e-c02258e4341b
|
Ultra All Inclusive (Non-Refundable) |
5a95c58c-9d92-400c-ab6c-e490bb9a5164
|
Non Alcoholic All Inclusive(Non-Refundable) |
8dee34f0-daa6-46d0-a317-2979af616b93
|
Soft All Inclusive |
4ff0862d-6cb9-49ff-83df-fadbd8fa7ae2
|
Half Board Plus |
a66a9882-465f-4c16-a9de-e4d414fd5b81
|
Full Board Plus (Non Refundable) |
7fa55176-cb44-41c0-8b7b-65de4ad32582
|
Full Board Plus |
c1eca326-457c-4e5b-99cb-a8f1b7c3cefc
|
All Inclusive Plus (Non Refundable) |
72bad5ff-c248-45cb-9804-855e4a6e7a30
|
All Inclusive Plus |
Non-Refundable Rates: Bookings with non-refundable board types cannot be cancelled or modified.
Data Types
Common data structures used throughout the API.
Field Types Reference
| Field Type | Format | Example |
|---|---|---|
| Date | YYYYMMDD | "20231016" |
| Currency | 3-letter ISO code | "EUR", "USD", "TL" |
| Nationality Code | SpiderTT document | "DE", "US", "TR" |
| UUID | 8-4-4-4-12 hex format | "D96A2E1B-EC5B-4D35-8D5B-F462A5C2A721" |
| RoomCount | 1 Only | "1" |
| PassengerType | Adult,Child | "Adult" |
| Age | Adult (30) ,Child (child age) | "30" |
| IsLeader | There must be 1 adult leader for each room. | ""isLeader"" : true" |
| PenaltyType | Amount | ""penaltyType": "Amount"" |
| ReservationStatus | Search,Basket,Confirmed,NotConfirmed,Cancel,NotBasket | ""status": "Confirmed"" |
Price Object
JSON
{
"amount": 185.40,
"currency": "EUR"
}
Cancellation Policy Object
JSON
{
"amount": 92.70,
"dateTimeFrom": "2023-10-13",
"penaltyType": "Amount",
"dateTimeTo": "2023-10-13"
}
Passenger Object
JSON
{
"isLeader": true,
"id": "1",
"salutationId": "66f1c75c-dff4-4305-99b7-19cdbdc9135a",
"name": "CEM",
"lastName": "KONYA",
"age": 30,
"AgeSpecified": true,
"passengerType": "Adult"
}
Room Criteria Object
JSON
{
"adultCount": 2,
"roomCount": 1,
"childCount": 2,
"childAges": [3, 9]
}
Code Examples
Complete integration examples in different programming languages.
C# Search Hotels Request (Handling Gzip Response)
C#
using System.IO.Compression; using System.Text; var json = JsonSerializer.Serialize(searchData); var content = new StringContent(json, Encoding.UTF8, "application/json"); var client = new HttpClient(); client.DefaultRequestHeaders.Add("X-ClientId", "172247cb-6ce7-4be9-a2ac-86a8a577c931"); client.DefaultRequestHeaders.Add("Accept-Encoding", "gzip"); var response = await client.PostAsync("https://testxml.spidertt.com/api/v1/hotelsearch", content); if (response.Content.Headers.ContentEncoding.Contains("gzip")) { using var stream = await response.Content.ReadAsStreamAsync(); using var gzipStream = new GZipStream(stream, CompressionMode.Decompress); using var reader = new StreamReader(gzipStream); var result = await reader.ReadToEndAsync(); Console.WriteLine(result); } else { var result = await response.Content.ReadAsStringAsync(); Console.WriteLine(result); }
C# Gzip Response Helper Method
C#
public static async Task<string> ReadGzipResponse(HttpResponseMessage response) { if (response.Content.Headers.ContentEncoding.Contains("gzip")) { using var stream = await response.Content.ReadAsStreamAsync(); using var gzipStream = new GZipStream(stream, CompressionMode.Decompress); using var reader = new StreamReader(gzipStream); return await reader.ReadToEndAsync(); } else { return await response.Content.ReadAsStringAsync(); } } // Usage var client = new HttpClient(); client.DefaultRequestHeaders.Add("X-ClientId", "your-client-id"); client.DefaultRequestHeaders.Add("Accept-Encoding", "gzip"); var response = await client.PostAsync("https://testxml.spidertt.com/api/v1/hotelsearch", content); var result = await ReadGzipResponse(response);
C# HttpClient with Automatic Gzip Decompression
C#
var handler = new HttpClientHandler() { AutomaticDecompression = System.Net.DecompressionMethods.GZip }; var client = new HttpClient(handler); client.DefaultRequestHeaders.Add("X-ClientId", "172247cb-6ce7-4be9-a2ac-86a8a577c931"); var json = JsonSerializer.Serialize(searchData); var content = new StringContent(json, Encoding.UTF8, "application/json"); var response = await client.PostAsync("https://testxml.spidertt.com/api/v1/hotelsearch", content); var result = await response.Content.ReadAsStringAsync(); // Automatically decompressed
Python with Gzip Response Handling
Python
import requests import gzip import json search_data = { } headers = { 'Content-Type': 'application/json', 'X-ClientId': 'your-client-id', 'Accept-Encoding': 'gzip' } response = requests.post( 'https://testxml.spidertt.com/api/v1/hotelsearch', headers=headers, json=search_data ) if response.headers.get('Content-Encoding') == 'gzip': result = json.loads(gzip.decompress(response.content)) else: result = response.json()