Rooms and guests

Rooms are distributionsCopy Anchor Link

Each entry in distributions[] is one room. Inside it, persons[] lists everyone who sleeps in that room. Rooms in one booking can have different occupancy. Docs

• With two distributions, every combination in the Quote response has two entries in rooms[]. The platform pre-computes the room combinations for you.
• Prebook must repeat the Quote's rooms in the same order, with the same number of people in each room. Reordering rooms in your UI after the Quote produces an "order changed" error. Docs

Occupancy limitsCopy Anchor Link

Enforce these limits in your search form, before you call Quote. The room and people counts are rejected as soon as the request arrives. The child and adult rules are not: a room with no adult gets past the first check, so your form is the only thing that stops it early. Tested

Ages: Quote and PrebookCopy Anchor Link

Quote takes age. Prebook takes requestedAge. Both are the guest's age at the end of the stay, on the check-out date. A child who turns 6 during the stay is 6. Docs

• requestedAge is mandatory for every guest in Prebook, even when requiredField does not list it. Docs
• A child's requestedAge must equal the age you quoted, or Prebook fails with "Child age different from availability". This is why the Quote must also use the age at check-out, not the age today. Docs
• If you send birthDate, it must agree with requestedAge. Docs

/** Age on the check-out date. Send it as `age` in Quote and `requestedAge` in Prebook. */
export function ageAtCheckout(birthDate: string, checkOut: string): number {
  const [by, bm, bd] = birthDate.split('-').map(Number); // yyyy-MM-dd
  const [cy, cm, cd] = checkOut.split('-').map(Number);
  const birthdayStillAhead = cm < bm || (cm === bm && cd < bd);
  return cy - by - (birthdayStillAhead ? 1 : 0);
}

ageAtCheckout('2019-11-12', '2026-11-14'); // 7: the child turns 7 during the stay

Contact person and room holdersCopy Anchor Link

Confirm returns requiredField with three lists of RequiredPassengerData values. Spec Each list applies to a different position in distributions[].

• Put the adult who has an email address and a phone number first in room 1. That person becomes the contact person.
• Build the guest form from each Confirm response, not from a fixed template: the lists tell you exactly which data to collect.
• Prebook enforces the lists. A missing field gets 400 with one message per person and field, for example Missing the following required field of the contact person: Birthdate. Tested
• Suppliers differ. A test supplier asked for BIRTH_DATE for every guest, including the contact person. Tested
• The API receives the names you send for every room, but only mandatory data is forwarded to suppliers. Docs

Map requiredField to person fieldsCopy Anchor Link

Each requiredField value tells you which PersonVO field to fill in Prebook.

When DOCUMENT (not PASSPORT) is required, documentType is probably IDENTITY_CARD or NIE for a national document. This is not documented, so test it in your test account. Unverified

Validation rulesCopy Anchor Link

Field patternsCopy Anchor Link

The spec validates these PersonVO fields. A value that fails is rejected at Prebook. Spec

The platform checks phone numbers with Google's libphonenumber (com.google.i18n.phonenumbers). Validate them in your checkout with a port of the same library. Docs

Business rulesCopy Anchor Link

The API also checks the guests against each other and against the Quote. Docs

• Two guests with identical names in one booking are rejected. Add a suffix such as JR to tell a father and son apart.
• A documentType without a documentNumber is rejected.
• Two guests with the same document number are rejected.
• A passport that expires before the trip ends is rejected.
• birthDate must be consistent with requestedAge.
• A child's requestedAge must equal the quoted age, and the rooms must keep the Quote's order and person counts.

Validation errors the API returnsCopy Anchor Link

These are the passenger errors the API documents. Check each one before Prebook so guests fix their input in your form. Docs

The list does not include the field patterns above. Check those too.

// Mirrors the spec patterns for PersonVO. Java's \p{IsLatin} is \p{Script=Latin} in JavaScript (u flag).
const LATIN_NAME = /^[\p{Script=Latin} .'-]+$/u;
const PHONE = /^[0-9]+$/; // max 15
const PHONE_COUNTRY_CODE = /^\+[0-9]*$/; // 2 to 4 characters
const DOCUMENT_NUMBER = /^[A-Za-z0-9]+(?:-[A-Za-z0-9]+){0,2}$/; // max 20

export type GuestInput = {
  name?: string;
  lastName?: string;
  phoneCountryCode?: string;
  phone?: string;
  documentType?: 'IDENTITY_CARD' | 'NIE' | 'PASSPORT';
  documentNumber?: string;
};

export function validateGuest(p: GuestInput): string[] {
  const errors: string[] = [];
  for (const field of ['name', 'lastName'] as const) {
    const v = p[field];
    if (v !== undefined && !LATIN_NAME.test(v)) {
      errors.push(`${field}: Latin letters only. Transliterate other scripts.`);
    }
  }
  if (p.phone !== undefined && (!PHONE.test(p.phone) || p.phone.length > 15)) {
    errors.push('phone: digits only, at most 15.');
  }
  const cc = p.phoneCountryCode;
  if (cc !== undefined && (!PHONE_COUNTRY_CODE.test(cc) || cc.length < 2 || cc.length > 4)) {
    errors.push('phoneCountryCode: "+" followed by digits, for example +34.');
  }
  if (p.documentType && !p.documentNumber) {
    errors.push('documentNumber: required when documentType is set.');
  }
  const doc = p.documentNumber;
  if (doc !== undefined && (!DOCUMENT_NUMBER.test(doc) || doc.length > 20)) {
    errors.push('documentNumber: letters and digits, at most two hyphens, at most 20 characters.');
  }
  return errors;
}

/** Rules across the whole booking: one inner array per room, in Quote order. */
export function validateBooking(rooms: GuestInput[][]): string[] {
  const errors: string[] = [];
  const names = new Set<string>();
  const documents = new Set<string>();
  rooms.flat().forEach((p, i) => {
    const fullName = `${p.name ?? ''} ${p.lastName ?? ''}`.trim().toUpperCase(); // stricter than needed, on purpose
    if (fullName && names.has(fullName)) errors.push(`Guest ${i + 1}: duplicate name. Add a suffix such as JR.`);
    names.add(fullName);
    if (p.documentNumber) {
      const d = p.documentNumber.toUpperCase();
      if (documents.has(d)) errors.push(`Guest ${i + 1}: duplicate document number.`);
      documents.add(d);
    }
  });
  return errors;
}

persons or personCopy Anchor Link

The docs send the Prebook array as distributions[].persons, while the original OpenAPI definition names it person. Both work.

1. Send persons. It is the recommended name. Confirmed
2. person is accepted too: Prebook succeeds with either name. Tested
3. Responses name the array person: the Prebook echo, Book and booking detail. Tested Some documentation samples use persons and birthdate. Docs When you read responses, accept both person and persons, and both birthDate and birthdate.

const peopleIn = (room: any) => room.person ?? room.persons ?? [];
const birthDateOf = (p: any) => p.birthDate ?? p.birthdate;

Special requestsCopy Anchor Link

accommodation.commentToAccommodation in Prebook is the only way to pass a request to the hotel. It is free text forwarded to the hotel. Structured special requests are not supported, and bedding type cannot be sent. Docs

• Keep it short and plain, for example Late arrival around 23:00 or Adjoining rooms if possible.
• Booked services read from getBookings spell the field commentsToAccommodation (plural). Map both names. Spec

Worked example: two rooms with a childCopy Anchor Link

A family books two rooms from 2026-11-10 to 2026-11-14. Room 1: Ana Ruiz (35) and Luis Ruiz (33). Room 2: Omar Haddad (40) and his son Leo Haddad, who turns 7 on 12 November, during the stay. Leo is 7 in both Quote and Prebook. Certification asks for a two-room booking and a booking with children, so this makes a good test-account booking. Docs

1. Quote with two distributionsCopy Anchor Link

{
  "checkIn": "2026-11-10",
  "checkOut": "2026-11-14",
  "distributions": [
    { "persons": [{ "age": 35 }, { "age": 33 }] },
    { "persons": [{ "age": 40 }, { "age": 7 }] }
  ],
  "language": "EN",
  "sourceMarket": "AE",
  "tripType": "ONLY_HOTEL",
  "timeout": 8000,
  "filter": { "bestCombinations": true, "maxCombinations": 4 },
  "destinationId": "MAD"
}

Every combination in the response has two rooms in rooms[].

2. Confirm tells you what to collectCopy Anchor Link

{
  "auditData": {
    "authToken": "[REDACTED]",
    "traceId": "D4AE54C6-…"
  },
  "requiredField": {
    "contactPerson": ["FIRST_NAME", "LAST_NAME", "TITLE", "PHONE", "EMAIL"],
    "otherPersons": ["FIRST_NAME", "LAST_NAME", "TITLE"],
    "roomHolders": ["FIRST_NAME", "EMAIL"]
  }
}

3. Prebook with the same rooms in the same orderCopy Anchor Link

{
  "accommodation": {
    "combinationKey": "<key from Confirm>",
    "commentToAccommodation": "Adjoining rooms if possible"
  },
  "distributions": [
    {
      "persons": [
        {
          "name": "Ana",
          "lastName": "Ruiz",
          "requestedAge": 35,
          "courtesyTitle": "MRS",
          "email": "ana@example.com",
          "phoneCountryCode": "+34",
          "phone": "600000000"
        },
        { "name": "Luis", "lastName": "Ruiz", "requestedAge": 33, "courtesyTitle": "MISTER" }
      ]
    },
    {
      "persons": [
        {
          "name": "Omar",
          "lastName": "Haddad",
          "requestedAge": 40,
          "courtesyTitle": "MISTER",
          "email": "omar@example.com"
        },
        { "name": "Leo", "lastName": "Haddad", "requestedAge": 7, "courtesyTitle": "MISTER" }
      ]
    }
  ]
}

• Ana is the first person of room 1, so she is the contact person and carries the contactPerson fields: names, title, phone and email.
• Omar is the first person of room 2, so he is its room holder and carries the roomHolders fields (FIRST_NAME, EMAIL).
• Luis and Leo follow otherPersons (FIRST_NAME, LAST_NAME, TITLE). That is why the child also has a courtesyTitle.
• Leo's requestedAge (7) equals his quoted age (7).
• The array is persons, the recommended name. person works too (see persons or person).

RelatedCopy Anchor Link

• The booking flow
• Confirm and Prebook
• Limits
• Certification