Create a reservation functionality is the core of the hotel booking process, enabling users to seamlessly book a room at their desired hotel. This use case allows guests to select the right hotel, room type, and stay duration while also providing options to personalize the stay with special requests. For the product, this is the pivotal step where users move from browsing to commitment, so it’s essential to ensure a smooth, frictionless experience. An intuitive booking flow, clear room descriptions, and a quick confirmation response enhance the user’s confidence in the platform. This process allows users to create a new reservation at a hotel, specifying details to secure a booking. The following attributes are required:
  • Guest Information: Includes full name, contact details (phone number, email), and address.
  • Room and Rate Details: Specifies the type of room, number of rooms, and occupancy (number of guests per room).
  • Stay Dates: Check-in and check-out dates for the reservation.
  • Payment Information: A valid payment method is required. Selfbok accepts 1 or 2 tokenized payment methods to facilitate payment. For more details on passing 2 payment tokens, refer to split payment.
The API processes these details to confirm and create a reservation, returning a unique reservation ID that the user can reference for future actions (retrieval, or cancellation).

​
Example

Example for a guest booking a 2-night stay at the Waldorf Astoria Hotel. 
{
  "check_in_date": "2025-01-01",
  "check_out_date": "2025-01-03",
  "guests": {
    "number_of_adults": 1,
    "number_of_children": 0,
    "primary": {
      "address": "123 Main St, Apt 152",
      "city": "Miami",
      "country": "US",
      "email": "guest@somedomain.com",
      "given_name": "John",
      "postal_code": "33123",
      "state": "FL",
      "surname": "Doe",
      "telephone_number": "+13055551234"
    }
  },
  "hotel": {
    "chain_code": "WA",
    "name": "Waldorf Astoria",
    "property_code": "C8639"
  },
  "payment": {
    "guest": {
      "amount": 400.22,
      "token": "1NEJtjOZ84AQM6jdleFdQAp"
    }
  },
  "rate": {
    "booking_code": "2QN57JU",
    "channel_code": "SBT1",
    "rate_type": "flexible_rate",
    "pcc": "KR5",
    "rate_name": "Flexible Rate",
    "room_name": "Accessible Deluxe Suite",
    "room_name_with_beds": "Accessible Deluxe Suite, One King Bed",
    "room_description": "Deluxe King 1 Bedroom Suite",
    "price": {
      "total_price": 400.22,
      "base_price": 350,
      "total_taxes": 50.22,
      "additional_fees": 0.0,
      "currency_code": "USD"
    },
    "terms": {
      "rate_payment_info": "PrePay",
      "guarantee_type": "DepositRequired",
      "refundable": true,
      "cancel_note": null,
      "cancel_penalties": [
        {
          "deadline_local": "2025-01-01T00:00-06:00",
          "cancel_short_description": "An estimated cancellation fee of 106.90 USD applies starting from 2025-01-01T00:00-06:00[America/Chicago].",
          "penalty": {
            "estimated_amount": true,
            "currency_amount": {
              "amount": 106.9,
              "currency": "USD"
            },
            "original_penalty_info": "100%"
          }
        }
      ]
    }
  }
}
Please refer to the Postman documentation for the Payment tokens conveyance step

​
Split Payment

Our API allows you to send 2 payment tokens. This capability is designed to enable reward or discount programs where a 2nd payment token can be used to reduce the amount charged to the guest’s payment method. See below for an example payment attribute from a create reservation request having both guest and partner payment attributes. 
{
 ...
  "payment": {
    "guest": {
      "amount": 400.22,
      "token": "1NEJtjOZ84AQM6jdleFdQAp"
    },
    "partner": {
      "amount": 400.22,
      "token": "1NEJtjOZ84AQM6jdleFdQAp"
    }
  }
  ...
}