HolaOlas Agent & Integrator Booking API

Machine-readable spec — excursion / activity / default

{
  "urlPattern": "https://holaolas.app/{locale}/p/{providerSlug}/e/{experienceSlug}",
  "experienceTypes": [
    "excursion",
    "activity"
  ],
  "experienceTypesNote": "Any loaded experience whose type is not hotel uses BookingFormExcursion and this parser (including activity and default branch).",
  "parser": "parseExcursionPrefillFromSearchParams",
  "sourceFile": "src/utils/booking-prefill-url.ts",
  "internalDoc": "docs/booking-prefill-vs-formulaires.md section 3.A",
  "dateFormat": "YYYY-MM-DD",
  "precedence": [
    "If categoryCounts (or pricingCategories) yields at least one valid row after filtering, it replaces adults/children/childrenAges prefill for that load.",
    "payment is parsed before deposit; if both are set, payment wins when it maps to full or deposit.",
    "options is parsed before selectedOptions; categoryCounts before pricingCategories.",
    "specialRequests: first non-empty among specialRequests, notes, remarks (then trim, max 8000 chars)."
  ],
  "paymentAndDepositSynonyms": {
    "mapsToFull": [
      "full",
      "total",
      "100"
    ],
    "mapsToDeposit": [
      "deposit",
      "depot",
      "partial"
    ],
    "caseInsensitive": true,
    "params": [
      "payment",
      "deposit"
    ]
  },
  "queryParams": {
    "date": "Single-day YYYY-MM-DD (regex). Multi-day uses startDate+endDate when both valid and experience supportsMultiDay.",
    "startDate": "Multi-day start. Alias: dateFrom.",
    "endDate": "Multi-day end. Alias: dateTo.",
    "slot": "Slot id or time 11:00 / 11h00. Alias: timeSlotId (slot read first).",
    "categoryCounts": "URL-encoded JSON: array [{ categoryId or category_id, count }] or object { categoryId: count }. Alias param name: pricingCategories (categoryCounts read first). Counts 0–99; form keeps count>0 and known category ids + auto-adult + free-children.",
    "adults": "Integer 1–99. Omitted if not in URL. Ignored when categoryCounts prefill applies.",
    "children": "Integer 0–99. Omitted if not in URL. Ignored when categoryCounts prefill applies.",
    "childrenAges": "Comma or semicolon separated ages 0–120. Alias: childAges.",
    "options": "URL-encoded JSON object { optionId: quantity }; quantities 0–999. Alias: selectedOptions (options read first).",
    "payment": "See paymentAndDepositSynonyms.",
    "deposit": "Same parser as payment; lower precedence if payment also set.",
    "specialRequests": "Aliases: notes, remarks. Max 8000 chars after trim.",
    "firstName": "Alias: prenom.",
    "lastName": "Alias: nom.",
    "email": "string",
    "phone": "Alias: tel.",
    "phoneCountry": "e.g. FR, MX, CA"
  },
  "notParsedOnExcursionParser": [
    "checkin",
    "checkout"
  ]
}

Machine-readable spec — hotel

{
  "urlPattern": "https://holaolas.app/{locale}/p/{providerSlug}/e/{experienceSlug}",
  "experienceTypes": [
    "hotel"
  ],
  "parser": "parseHotelPrefillFromSearchParams",
  "sourceFile": "src/utils/booking-prefill-url.ts",
  "internalDoc": "docs/booking-prefill-vs-formulaires.md section 3.B",
  "dateFormat": "YYYY-MM-DD",
  "routing": "The public experience page picks this parser only when the loaded experience type is hotel; otherwise the excursion spec applies.",
  "precedence": [
    "Valid unitId matching config.units[].id plus categoryCounts (after filter to that unit’s pricing categories and auto-adult/free-children) overrides adults/children/childrenAges for that load.",
    "Valid unitId plus adults and/or children: merge into initializeCategoryCounts for that unit; unit-change category reset is skipped once (skipInitAfterPrefillRef).",
    "Without valid unitId: adults, children, childrenAges, categoryCounts from URL are not applied; checkin/checkout, contact, options, payment, specialRequests, and extras booleans still apply when present.",
    "payment before deposit; options before selectedOptions; categoryCounts before pricingCategories.",
    "specialRequests: first non-empty among specialRequests, notes, remarks (trim, max 8000 chars)."
  ],
  "paymentAndDepositSynonyms": {
    "mapsToFull": [
      "full",
      "total",
      "100"
    ],
    "mapsToDeposit": [
      "deposit",
      "depot",
      "partial"
    ],
    "caseInsensitive": true,
    "params": [
      "payment",
      "deposit"
    ]
  },
  "booleanQueryValues": {
    "true": [
      "1",
      "true",
      "yes",
      "on"
    ],
    "false": [
      "0",
      "false",
      "no",
      "off"
    ],
    "note": "For extraBed, withPet, earlyCheckin, lateCheckout: true applies only if the matching hotelSettings flag is enabled; false always clears the checkbox."
  },
  "queryParams": {
    "checkin": "YYYY-MM-DD. Aliases: checkIn, dateFrom (on hotel pages dateFrom means check-in, not excursion multi-day).",
    "checkout": "YYYY-MM-DD. Aliases: checkOut, dateTo.",
    "unitId": "Room/unit id from experience config. Aliases: unit, room (read in that order).",
    "adults": "Integer 1–99. Ignored without valid unitId; ignored when categoryCounts prefill applies.",
    "children": "Integer 0–99. Same constraints as adults.",
    "childrenAges": "Comma or semicolon separated 0–120. Alias: childAges.",
    "categoryCounts": "URL-encoded JSON array [{ categoryId or category_id, count }] or object. Alias: pricingCategories. Filtered to selected unit’s categories.",
    "options": "URL-encoded JSON { optionId: quantity }. Alias: selectedOptions (options first).",
    "payment": "See paymentAndDepositSynonyms.",
    "deposit": "Same as payment; lower precedence if payment also set.",
    "specialRequests": "Aliases: notes, remarks. Max 8000 chars after trim.",
    "firstName": "Alias: prenom.",
    "lastName": "Alias: nom.",
    "email": "string",
    "phone": "Alias: tel.",
    "phoneCountry": "e.g. FR, MX, CA",
    "extraBed": "boolean query; requires hotelSettings.extraBed.enabled for true to stick.",
    "withPet": "boolean; requires hotelSettings.petFee.enabled for true.",
    "earlyCheckin": "boolean. Alias: early_checkin. Requires hotelSettings.earlyCheckin.enabled for true.",
    "lateCheckout": "boolean. Alias: late_checkout. Requires hotelSettings.lateCheckout.enabled for true."
  },
  "collisionNote": "dateFrom/dateTo mean checkin/checkout on hotel pages only; on excursion pages the excursion parser uses them as startDate/endDate aliases."
}

Human-readable list — excursion / activity

• Core: date, adults, children, slot or timeSlotId, firstName (or prenom), lastName (or nom), email, phone (or tel), phoneCountry
• Multi-day (only if the experience has multi-day enabled): startDate + endDate, or dateFrom + dateTo (both YYYY-MM-DD)
• childrenAges or childAges — comma/semicolon-separated (e.g. 5,8,12)
• categoryCounts or pricingCategories — URL-encoded JSON: array [{"categoryId":"…","count":n}] or object {"categoryId":n} (ids from experience config). Overrides adults / children / childrenAges when present.
• options or selectedOptions — URL-encoded JSON {"optionId":quantity}
• payment or deposit: full or deposit
• specialRequests, notes, or remarks
• Not read by the excursion parser: checkin, checkout (use the hotel spec on hotel experiences).

Human-readable list — hotel

• Dates: checkin + checkout (aliases checkIn/checkOut, or dateFrom/dateTo for arrival/departure — not the excursion multi-day meaning).
• Room: unitId (aliases unit, room) must match config.units[].id. Without a valid id, adults, children, childrenAges, and categoryCounts from the URL are ignored; other params still apply.
• Same as excursion where shared: childrenAges/childAges, categoryCounts/pricingCategories, options/selectedOptions, payment/deposit, contact fields, specialRequests/notes/remarks.
• Extras (boolean: 1/true/yes/on vs 0/false/no/off): extraBed, withPet, earlyCheckin (or early_checkin), lateCheckout (or late_checkout). true only sticks if enabled in hotel settings.

Example — excursion (minimal)

https://holaolas.app/en/p/adorablesailing/e/el-colectivo-shared-sailing-excursion-on-the-bacalar-lagoon-bacalar?date=2026-03-10&adults=3&children=0&slot=11:00&firstName=Jean&lastName=Dupont&email=jean@example.com&phone=0612345678

Example — excursion (ages + options JSON — encode the JSON for the URL)

In code: options=%7B%22snorkel-kit%22%3A2%7D

https://holaolas.app/fr/p/adorablesailing/e/example-slug?date=2026-04-13&adults=2&children=2&childrenAges=6,9&slot=11:00&firstName=Marie&lastName=Faubert&options=%7B%22snorkel-kit%22%3A1%7D&payment=deposit

Example — hotel (replace unit UUID and slugs)

https://holaolas.app/fr/p/myprovider/e/my-hotel-slug?checkin=2026-06-01&checkout=2026-06-05&unitId=YOUR-UNIT-UUID-FROM-CONFIG&adults=2&children=1&payment=deposit&extraBed=1