JSON API - BOOK

Owned by Vincent Josset
Last updated: Jun 12, 2024 by Matthew Tompkins
6 min read

Creates a new reservation for the specified services and passenger details. Since these requests can potentially get very long, we recommend using a POST request instead of GET.

Input

  • transtype - Always BOOK

  • login - API user's username

  • password - API user's password

  • bookrequest - A JSON object string containing an array of bookcommand objects, an array of passenger objects, and an array of reference objects.

    • gateway - string - If booking air + land rates and services, make sure to include your origination gateway for the correct services and rates. If left blank or omitted, system will book land-only rates and services. If your Softrip provider doesn't offer different rates and services for air + land vs. land-only bookings, you can omit this member.

    • bookasfi - Boolean - Make the booking FI, booking the generic/base routing as PENDING air.

    • origin - string - The origin/book source of the booking to be made. Note: Must use the GUID that is saved in the Softrip system.

    • bookcommands - A JSON array of bookcommand objects, as described above in the SHOP response. Member fields and values will be returned by the SHOP request; just copy the bookcommand for selected services into this array. Note that if you are using a price/rate feed and are skipping the SHOP step, the bookcommand is one of the properties returned in the rate feed. Just replace placeholders for variable members (departuredate, duration, and mask). Services to be booked can be referenced by itemnumber and inclusionnumber, or by supplierid and serviceid. If a request includes all four parameters, the itemnumber and inclusionnumber will be used and the supplierid and serviceid will be ignored.

    • passengers - A JSON array of passenger objects, as described below in the GETRES response. Note that required fields for passengers will be different for each Softrip client. Check with your Softrip provider to determine which fields are required.

      • title - string - The passenger's title/salutation

      • lastname - string - The passenger's last name

      • firstname - string - The passenger's first name and middle name or initial

      • middlename - string - The passenger's middle name (Note: This is dependent on the setup of each client if they use the middle name separately from first name)

      • nomiddlename - Boolean - Pass True if the passenger does not have a middle name. False or null will be treated the same

      • gender - string - The passenger's gender. Must be either "F" (female) or "M" (male).

      • email - string - The passenger's email address

      • phone - string - The passenger's home/main phone number

      • mobilephone - string - The passenger's mobile phone number

      • fax - string - The passenger's fax number

      • HotelRequest - String - Free text field for hotel-related requests (smoking room, lower floor, disabled access etc.)

      • AirRequest - String - Free text field for air-related requests (Vegetarian meals, aisle/window seat etc.)

      • GeneralRequest - String - Free text field for all other passenger requests

        • If your front end does not have three distinct fields for these types of special requests, put them all in the "generalrequest" field

        • There is NO guarantee that any special requests will be met by suppliers. It is up to the third-party API consumer to notify their passengers that requests may not be met.

      • address - Address object for this passenger's address

        • address1 - string - The passenger's address' first line

        • address2 - string - The passenger's address' second line

        • city - string - The passenger's address' city

        • state - string - The passenger's address' state

        • zip - string - The passenger's address' zip/postal code

        • country - string - The passenger's address' country. Must be in international standard 2-letter format ("US" for United States, "FR" for France, "DE" for Germany etc.)

      • paxtype - string - The passenger type. "A" for adult, "C" for child

      • birthdate - date - The passenger's birth date (see above for date formats)

      • specialrequests - Special Requests object for this passenger's request (array)

        • id - integer - The preference ID that relates to the special request to save (This must be provided by Softrip for each type of request you want)

        • type - string - The type of request/preference that this is

        • value - string - The value entered by the passenger for the request

      • passengerforms - Passenger Form object for this passenger's request (array)

        • type - string - The type for the request (This must be provided by Softrip for each form and could be per brand)

        • description - string - The description/text to be saved against the form

        • formid - string - The Form ID that the contact/passenger filled out (This must be provided by Softrip for each form and could be per brand)

      • passportnumber - Passenger’s passport number

      • passportexpiration - Expiration date of the passenger’s passport (in yyyy-MM-dd format)

      • passportissuedate - Issue date of the passenger’s passport (in yyyy-MM-dd format)

      • nationality - The Nationality of the passenger (and their associated passport). Must be in international standard 2-letter format ("US" for United States, "FR" for France, "DE" for Germany etc.)

      • emergencycontact - Contact Name for emergencies for each passenger

      • emergencyphone - Phone Number for emergency contact. Expected format ###-###-#### for US & CAN. But the API will accept all formats.

    • references - A JSON array of references. Contact your Softrip provider to determine which reference questions are available.

      • keyid - string - A unique identifier for this reference question (e.g. "REFERENCENUMBER")

      • key - string - A description of this reference question (e.g. "Enter your reference number")

      • value - string - The value for this reference question (e.g. "1234")

    • promotions - A JSON array of promotion/coupon codes to be applied to the booking

      • promotionid - string - The promotion/coupon code to be applied

      • failifinvalid - boolean - Indicates whether the booking should fail if the promotion is invalid. If set to false, the booking will go through even if the promotion is inapplicable. If set to true, the booking will fail if the promotion is inapplicable.

    • discounts - A JSON array of discounts to be applied to the booking. Discounts are entered as manual services on the reservation, with the associated description. Note that a discount may not be for more than the total price of the reservation.

      • discount - integer - The value of the discount to be applied. This should be a positive amount (e.g. "50.00" for a $50 discount, not "-50.00"). This amount is per reservation.

      • description - string - The description of the discount to be applied. If left blank, the discount will be entered with the description "Discount".

    • resmemos - A JSON array of memos to be applied to the booking

      • memotext - string - The text of the memo to be applied

  • paymentamount - decimal - The amount that should be applied as payment to the booking (ONLY to be used if processing the payment through a 3rd party processor)

  • pnreference - string - The reference number provided by the payment processor

  • authcode - string - The authorization code provided by the payment processor

  • cardtype - string - The 2-letter card type of the card that was charged (VI=Visa,MC=MasterCard,AX=American Express, etc.)

Output

  • reservationscreated - integer - The number of reservations successfully created (one per distinct selling currency in the request)

  • [currency]rescreated - boolean - Indicates whether a reservation with the specified currency was created. When booking services in multiple currencies (e.g. CAD and USD), there will be one value for each currency (e.g. "cadrescreated = true, usdrescreated = true)

  • reservations - An array of reservation objects representing the reservations that were created by the BOOK request. See “GETRES" response below