Atlantes Booking API — Search & Booking API Documentation

1. Overview

This document specifies how API clients integrate with the Atlantes Booking API for:

Search APIs
Booking API

Scope is intentionally limited to Basic authentication connections.

2. Base URL & Versioning

Base URL (example): https://<your-domain>
API version prefix: /v1.0

All endpoints documented here are under /v1.0.

3. Authentication (Basic Only)

These APIs accept Basic auth via:

Authorization: Basic <base64(clientKeyId:clientKeySecret)>

3.1 How to build the header

Concatenate credentials as clientKeyId:clientKeySecret
Base64 encode the string
Send in Authorization header

Example (shell):


BASIC_TOKEN=$(printf "%s" "<clientKeyId>:<clientKeySecret>" | base64)
curl -H "Authorization: Basic ${BASIC_TOKEN}" ...

> Note: Client roles must include at least one allowed scope for these APIs (travel_advisor, client_regular, or client_admin).

4. Common Request/Response Conventions

Content type: application/json
Auth required: yes
Validation errors: HTTP 400
Unauthorized/invalid auth: HTTP 401
Forbidden enterprise/client constraints: HTTP 403
Not found resources (enterprise-scoped): HTTP 404
Sold-out/no longer available rates: HTTP 410
Provider/internal failure: HTTP 500

4.1 Error shape

Errors are Hapi/Boom-based. Clients should rely on HTTP status code and error message text.

5. Search APIs

5.1 Search destinations + hotel name suggestions

Endpoint

GET /v1.0/search

Query parameters

input (string, required)
skip (integer, optional, default 0)
limit (integer, optional, default 10)

cURL


curl -X GET "https://<your-domain>/v1.0/search?input=singapore&skip=0&limit=10" \
  -H "Authorization: Basic ${BASIC_TOKEN}"

Response (200)


{
  "meta": {
    "input": "singapore",
    "placesCount": 2,
    "count": 3
  },
  "data": {
    "places": [
      { "placeId": "ChIJ...", "description": "Singapore" }
    ],
    "hotels": [
      { "id": "65f0...", "name": "Sample Hotel" }
    ]
  }
}

5.2 Search hotels by place, hotel id(s), or geolocation

Endpoint

POST /v1.0/search/hotels

Query parameters

lazyLoad (boolean, optional, default false)
skip (integer, optional, default 0)
limit (integer, optional, default 20)

Body rules

Exactly one selector is required (xor):

placeId (string)
hotelId (24-char hex string)
hotelIds (array of 24-char hex strings)
geolocation object

Additional body fields:

dates (optional)

- checkIn (ISO date, default today) - checkOut (ISO date, min checkIn, default tomorrow)

occupancies (optional; default one room, 2 adults, 0 children)

Example request


{
  "placeId": "ChIJ...",
  "dates": {
    "checkIn": "2026-03-20",
    "checkOut": "2026-03-22"
  },
  "occupancies": [
    {
      "rooms": 1,
      "adults": 2,
      "children": 0
    }
  ]
}

cURL


curl -X POST "https://<your-domain>/v1.0/search/hotels?lazyLoad=false&skip=0&limit=20" \
  -H "Authorization: Basic ${BASIC_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "placeId":"ChIJ...",
    "dates":{"checkIn":"2026-03-20","checkOut":"2026-03-22"},
    "occupancies":[{"rooms":1,"adults":2,"children":0}]
  }'

Response (200)


{
  "meta": {
    "searchId": "67d...",
    "skip": 0,
    "limit": 20,
    "lazyLoad": false,
    "count": 1,
    "enterpriseId": "67a...",
    "token": "provider-token"
  },
  "data": {
    "hotels": [
      {
        "id": "65f...",
        "name": "Sample Hotel",
        "brandName": "Sample Brand",
        "address": {},
        "geolocation": {},
        "amenities": [],
        "loyaltyProgram": {},
        "rate": {
          "providerName": "zentrumhub",
          "numberOfDays": 2,
          "payAtHotel": false,
          "publishedBaseRate": 1000,
          "baseRate": 920,
          "taxes": 80,
          "totalRate": 1000,
          "publishedBaseRatePerNight": 500,
          "baseRatePerNight": 460
        },
        "isTargetHotel": false
      }
    ]
  }
}

5.3 Search rooms/rates for a hotel

Endpoint

POST /v1.0/search/hotels/{hotelId}/rooms

Path parameters

hotelId (24-char hex string, required)

Query parameters

provider (string, optional; filters output to one provider)

Body rules

Must provide exactly one of:

- searchId (24-char hex string from hotel search), OR - dates + occupancies

dates format:

checkIn ISO date (min now)
checkOut ISO date (min checkIn)

cURL (using previous searchId)


curl -X POST "https://<your-domain>/v1.0/search/hotels/<hotelId>/rooms" \
  -H "Authorization: Basic ${BASIC_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ "searchId": "67d..." }'

Response (200)


{
  "meta": {
    "searchId": "67e...",
    "count": 2,
    "hotelId": "65f...",
    "enterpriseId": "67a..."
  },
  "data": {
    "rooms": [
      {
        "name": "Deluxe Room",
        "type": "Double",
        "description": "City view",
        "beds": [],
        "numOfAdults": 2,
        "numOfChildren": 0,
        "maxGuestAllowed": 2,
        "size": { "value": 35, "unit": "squareMeter" },
        "views": [],
        "images": [],
        "rates": [
          {
            "id": "rate-1",
            "providerName": "zentrumhub",
            "baseRate": 460,
            "publishedRate": 500,
            "dailyRates": [],
            "totalRate": 1000,
            "taxes": 80,
            "refundability": "Refundable",
            "occupancies": [{ "numOfAdults": 2, "numOfChildren": 0 }],
            "numberOfDays": 2,
            "publishedRatePerNight": 500,
            "baseRatePerNight": 460,
            "currency": "USD",
            "boardBasis": {},
            "vipInclusions": []
          }
        ]
      }
    ]
  }
}

5.4 Check one or multiple rates

Endpoint

POST /v1.0/search/hotels/{hotelId}/check-rates

Path parameters

hotelId (24-char hex string, required)

Body rules

searchId (24-char hex, required)
Exactly one of:

- rateId (string) - rateIds (string[])

cURL


curl -X POST "https://<your-domain>/v1.0/search/hotels/<hotelId>/check-rates" \
  -H "Authorization: Basic ${BASIC_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"searchId":"67e...","rateId":"rate-1"}'

Response (200)


{
  "meta": {
    "searchId": "67e...",
    "hotelId": "65f...",
    "enterpriseId": "67a...",
    "count": 1
  },
  "data": {
    "rooms": [],
    "rates": [
      {
        "id": "rate-1",
        "providerName": "zentrumhub",
        "baseRate": 460,
        "publishedRate": 500,
        "dailyRates": [],
        "totalRate": 1000,
        "taxes": 80,
        "refundability": "Refundable",
        "occupancies": [{ "numOfAdults": 2, "numOfChildren": 0 }],
        "numberOfDays": 2,
        "publishedRatePerNight": 500,
        "baseRatePerNight": 460,
        "currency": "USD"
      }
    ]
  }
}

Common failures:

410 Gone: rate no longer available
400 Bad Request: invalid/sold-out search, invalid rate

6. Booking API

6.1 Create booking

Endpoint

POST /v1.0/bookings

Body


{
  "searchId": "67e...",
  "hotelId": "65f...",
  "room": {
    "rateId": "rate-1",
    "guests": [
      {
        "category": "primary",
        "type": "adult",
        "firstName": "Jane",
        "lastName": "Doe",
        "age": 30,
        "title": "Ms",
        "phone": "+6599999999",
        "email": "jane@example.com"
      },
      {
        "category": "secondary",
        "type": "adult",
        "firstName": "John",
        "lastName": "Doe",
        "age": 32
      }
    ]
  },
  "paymentToken": "tok_xxx"
}

Validation/business rules

searchId must be a valid rooms-search record in same enterprise
hotelId must belong to same enterprise
room.rateId must be valid after provider rate-check
Guest count must exactly match selected rate occupancy adults count
Provider credentials for client must exist

cURL


curl -X POST "https://<your-domain>/v1.0/bookings" \
  -H "Authorization: Basic ${BASIC_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "searchId":"67e...",
    "hotelId":"65f...",
    "room":{
      "rateId":"rate-1",
      "guests":[
        {"category":"primary","type":"adult","firstName":"Jane","lastName":"Doe","age":30},
        {"category":"secondary","type":"adult","firstName":"John","lastName":"Doe","age":32}
      ]
    },
    "paymentToken":"tok_xxx"
  }'

Response (201)


{
  "meta": {
    "mock": true
  },
  "data": {
    "booking": {
      "id": "67f...",
      "code": "BK-12345678-ABCD",
      "enterprise": "67a...",
      "account": "67b...",
      "search": "67e...",
      "hotel": "65f...",
      "rooms": [
        {
          "rateId": "rate-1",
          "guests": [],
          "room": {},
          "rate": {
            "id": "rate-1",
            "providerName": "zentrumhub",
            "baseRate": 460,
            "publishedRate": 500,
            "dailyRates": [],
            "totalRate": 1000,
            "taxes": 80,
            "numberOfDays": 2,
            "baseRatePerNight": 460,
            "publishedRatePerNight": 500
          }
        }
      ],
      "paymentToken": "tok_xxx",
      "dates": {
        "checkIn": "2026-03-20",
        "checkOut": "2026-03-22"
      },
      "status": "confirmed",
      "error": null,
      "createdAt": "2026-03-13T00:00:00.000Z",
      "modifiedAt": "2026-03-13T00:00:00.000Z"
    }
  }
}

Possible booking statuses in response object:

confirmed
failed
(internally starts as draft before provider response)

7. Recommended Client Flow (Search → Book)

Call POST /v1.0/search/hotels to obtain searchId, rates, and provider token context.
Call POST /v1.0/search/hotels/{hotelId}/rooms with searchId.
Call POST /v1.0/search/hotels/{hotelId}/check-rates before checkout.
Call POST /v1.0/bookings with selected rateId, guest list, and paymentToken.

8. Basic Auth-Only Integration Checklist

Store clientKeyId + clientKeySecret securely.
Generate and send Basic auth header for every call.
Handle auth failures (401) and role/enterprise access constraints (403, 404).
Re-check rates immediately before booking.
Treat 410 Gone as a stale/sold-out rate and restart search.

9. Endpoint Summary

GET /v1.0/search
POST /v1.0/search/hotels
POST /v1.0/search/hotels/{hotelId}/rooms
POST /v1.0/search/hotels/{hotelId}/check-rates
POST /v1.0/bookings