Shared schemas
Objects that appear across many endpoints, such as auditData, money, meal plans, cancellation policies, pagination, rooms and passengers. Field names, types and validation patterns come from the OpenAPI spec.
These objects appear in many responses and requests. Each endpoint page links here instead of repeating them. Types follow the OpenAPI spec.
AuditResponseVO
Most response objects carry auditData. Its traceId identifies your token's calls for support, and it echoes your live token. Some responses have none: see the list.
{
"timestamp": "2022-11-15 09:05:14",
"processTime": 18099,
"authToken": "[REDACTED]",
"traceId": "D4AE54C6-FAED-40D8-9B9F-1B8555459610",
"availabilityId": 188,
"server": "…"
}export function redact<T extends { auditData?: { authToken?: string } }>(body: T): T {
if (body?.auditData?.authToken) body.auditData.authToken = '[REDACTED]';
return body;
}MoneyVO
An amount with its currency.
- Prices in the booking flow are always in your microsite currency. You can't request another currency per call, so convert for display yourself.
- Supplier-side amounts on booked services, such as
providerNetPrice, can be in the supplier's currency even when the customer paid in yours. Support every currency there, or use the.operatorlegs of MoneyAmountVO.
MoneyAmountVO
The same amount in two currencies. It appears in cancellation policies (policyAmount) and in the price breakdowns of booked trips.
For single-currency accounting, the .operator legs are the safer choice: they are already converted, so supplier currencies don't leak into your books. Pick your legs deliberately and document the choice. See Reading bookings.
MealPlanVO
The meal plan of a combination in Quote, Confirm, Prebook and Book.
{
"id": "BH",
"type": "HALF_BOARD",
"description": "1 BED AND BREAKFAST + 1 HALF BOARD",
"providerDescription": "1 bed and breakfast + 1 half board"
}Booked hotels read through getBookings carry mealPlan as a plain string, not a MealPlanVO.
CancellationPolicyVO
One step of a cancellation policy. A policy is a list of cumulative steps: each step says "from this date on, cancelling costs this much".
[
{ "date": "2024-10-09", "amount": { "amount": 0.0, "currency": "EUR" } },
{ "date": "2025-06-23", "amount": { "amount": 444.46, "currency": "EUR" } },
{ "date": "2025-06-26", "amount": { "amount": 808.04, "currency": "EUR" } }
]Read it as:
| Cancel on | Penalty |
|---|---|
| Up to 2025-06-22 | 0.00 EUR (free) |
| 2025-06-23 to 2025-06-25 | 444.46 EUR |
| From 2025-06-26 | 808.04 EUR, the full price |
- Policies in Quote are informational. Confirm returns the authoritative ones.
- Booked hotel services read through
getBookingscarry the policy undercancelPolicy. - We have seen the service-level
cancelPolicydates serialised in UTC while the booking-levelcancellationPoliciesdates are in operator local time, so near midnight they differ by a day. Show the booking-level date to people. - Suppliers apply deadlines in hotel local time, so tell guests "cancel before" the date rather than "on" it.
CancellationTypeVO
A one-line summary of a combination's cancellation policy, returned as currentCancellationType. It is only present in quote responses.
{ "deadline": "2025-06-23", "type": "REFUNDABLE" }Booked hotels have no service-level currentCancellationType. Read the steps in cancelPolicy instead.
GeolocationVO
{ "latitude": 39.887368, "longitude": 4.265355 }PaginationVO
Returned by paged lists such as the accommodation list.
{ "firstResult": 0, "pageResults": 1, "totalResults": 86768 }Stop paging when firstResult + pageResults reaches totalResults, or a page comes back empty.
DistributionVO
One room and the people in it. In Quote, each distributions[] entry is one room.
{
"id": "TST-1464-0",
"person": [
{ "id": "TST-1464-0-0", "name": "Ana", "lastName": "Ruiz", "requestedAge": 34 },
{ "id": "TST-1464-0-1", "name": "Luis", "lastName": "Ruiz", "requestedAge": 36 }
]
}After Book, person ids follow <booking reference>-<room index>-<person index>. Use person.id as the passenger identity in your own systems.
PersonVO
A guest. Prebook sends it, and booking responses return it. Only requestedAge is required by the spec; Confirm's requiredField tells you which other fields a booking needs.
Validation patterns
Pre-validate these before Prebook, so guests can fix their input first.
| Field | Pattern or rule |
|---|---|
name, lastName | ^[\p{IsLatin} .'-]+$: Latin script only. Transliterate Arabic, Cyrillic, Greek or CJK names, and keep the original script in your own records. |
phone | [0-9]+, max 15 digits |
phoneCountryCode | \+[0-9]*$, 2 to 4 characters |
documentNumber | ^[A-Za-z0-9]+(?:-[A-Za-z0-9]+){0,2}$, max 20 |
email | Email format |
The API also rejects duplicate passenger names, duplicate document numbers, a birth date that doesn't match requestedAge, and a passport that expires before the trip ends. See Rooms and guests for the full list.
{
"name": "Ana",
"lastName": "Ruiz",
"requestedAge": 34,
"courtesyTitle": "MRS",
"email": "ana@example.com",
"phoneCountryCode": "+34",
"phone": "600000000"
}When you read passengers, name is the first name and lastName the surname, so join them for display. Some payloads use firstName or fullName, so accept those too.
Related
Provider configurations
List the supplier connections configured on your microsite. Check it first when a destination or a hotel search returns nothing.
Enums
Every enumeration the hotel API uses, from booking statuses and meal plan types to hotel categories, languages and passenger data fields, with the rules for handling values you don't recognise.