Smoobu API AND TOOLS FOR DEVELOPERS

Integrate Smoobu functionality into virtually any system or application

Introduction and Overview

Our REST based APIs allow you to get access to your Smoobu Application. We have different APIs for different usecases. On this page we explain you a little bit more detailled what you need for your usecase as a host or as a channel. Please contact us before you start coding. We send you the necessary keys and all further information you need to know.

Tell us a few words about your ideas and plans. We are always happy to help our customers and our partners to build a perfect integrated and easy to use solution.

For hosts and Smoobu users

Smoobu users can request availabilities and send bookings to their Smoobu calendar. This enables the connection of your own PMS, your website, your booking engine with all the booking portals like Booking.com, Expedia, Airbnb…

The combination of the following two APIs is everything you need for an amazing booking engine on your website. You never get overbookings through you website when the booking engine checks the availability in all the connected booking portals in realtime. The host can maintain his prices and restrictions in the easy Smoobu frontend which is especially for non-technical users a big plus.

1. Availability API:

You can ask Smoobu if your properties are available or not. If not we deliver you also an answer what to change that a booking is possible. This API is perfect if your booking engine wants to check availabilities and prices for a specific period. If you have more than one property you get a list with all free rooms. If you maintain the prices in smoobu you get a calculated price for this period.

2. Booking API:

Send us your reservations into the Smoobu calendar. From there we block all other connected channels.

3. Get Reservations

Retrieve all bookings for a selected property including all details like contact information. With this API you can build your own individual PMS or connect your existing one.

For booking portals

If you are a booking portal you can easily offer your customers a channel manager integration. Never loose customers because they are unable to connect the big portals. You get the detailed documentation with all necessary authorization keys on request.

2. Booking API (modified):

When you get a booking for a Smoobu user you can send us this booking with all the relevant information into our system. The booking API is the same which the website of the host can use. The only difference is a  modification for your usecase as a channel. We don’t want to check again if all the restrictions are fulfilled. We accept every booking you send without any check. The restrictions like minimum lenght of stay etc. are already set up and controlled at your side. If there is another reservation – which should not be – our customer receive a notification from us.

4. Get Apartments:

The mapping of properties from different sources is our main business. We don’t want that you or we have a manual work during the setup process. For that we allow our customer to map the properties by his own because nobody knows the properties better. To map our ID with your ID we need a list of properties you list in your channel. It should be a unique ID and the name of the listing.

5. Change Availability:

Of course you can use our iCal-file for the existing availabilities of properties but this is slow. For a amazing user-experience and to avoid any overbookings it is necessary to update your availabilities in real time. With Change Availability we send you changes in your calendar in the moment we get them.

1: Smoobu Availability API

Partners and customers of smoobu can check their availability of properties and dates. For that you send a request with arrival and departure date and the property ID.

UPDATES: 2018-03-01: The API sends a detailled info why a property is not available. Possible reasons for example can be “minimum lenght of stay” or a not possible “arrival day”.
URL:             https://login.smoobu.com/booking/checkApartmentAvailability
Format:      JSON
Mandatory:

‘arrivalDate’,                        string in format: yyyy-mm-dd
‘departureDate’,                 string in format yyyy-mm-dd
‘apartments’,                       array with int values
‘customerId’,                       int (provided by Smoobu)
‘verificationHash’                string (provided by Smoobu)

 

Example: 

Post Request:

{
  “arrivalDate” : “2016-09-25”,
  “departureDate”:  “2016-09-29”,
  “apartments”: [162],
  “customerId”: 24,
  “verificationHash”: “xxxxx”
}

Response:

‘availableApartments’: array with int values
‘prices’: array with following format:
{
‘price’: float, ‘currency’: string (EUR,GBP,USD,CHF,AUD),
}

‘errorMessages’:
{
‘hotelId’: (float) :
{

Error Code Message Response to solve the error Example
400 ‘The number of guests exceeds the limit of the apartment.’ integer with the maximum occupancy [‘4’]
401 ‘The duration of the booking is too short.’ Integer with minimum lenght of stay [‘7’]
402 ‘The chosen day of arrival is not available’ String with possible arrival days [‘Sa’, ‘Su’]
403 ‘Arrival day is too short term.’ Integer with numbers of days [‘2’]

}
}

{
  "availableApartments":[2,3,14,15],
  "prices": {
    "2":{"price":200,"currency":"CHF"},
    "3":{"price":2424,"currency":"CHF"},
    "14":{"price":215,"currency":"CHF"}
  },
 "errorMessages": {
   "15": {
     "errorCode": 401,
     "message": "The duration of the booking is too short.",
     "minimumLengthOfStay": 5
  }
 }
}

In case of a wrong validation:

{
  "title": "Error occurred",
  "detail": "validation error"
}

2: Booking API

Partners and customers of Smoobu can send bookings to Smoobu. Our application receives them like a booking from a booking channel and synchronizes it into every other channel.

URL:       https://login.smoobu.com/api/apartment/{apartmentId}/booking
Format: JSON

For security issues you need a special API-Key. You find this API-Key in our application (Channel Manager – API – Edit). Please insert this Key into the header. If your API-Key is ABCDEFGH Your header should look like: ‘Api-Key: ABCDEFGH’

Replace {apartmentId} in the URL with the ID of your booked property. You also find this in your applicaton.

Example:

Request

Url: https://login.smoobu.com/api/apartment/123/booking

{
  “arrivalDate”: “01.09.2017”,
  “departureDate”: “03.09.2017”,
  “channelId”: 226
}

curl:

curl -X POST ‘https://login.smoobu.com/api/apartment/123/booking’ -H “Api-Key: ABCABCABC” –data-binary ‘{“arrivalDate”: “01.09.2017”, “departureDate”: “03.09.2017”, “channelId”: 226}’

Response

{
  “id”:4567
}

Request

Name Datatype Mandatory Description Example
channelId Int  x ID of the channel for which the booking should be entered. 120
arrivalDate String x Arrival day of the guest. Format has to be “dd.mm.YYYY”. 07.07.2019
departureDate String x Departure day. Format has to be “dd.mm.YYYY”. 09.07.2019
arrivalTime String Arrival time “HH:ii” 12:00
departureTime String Departure time “HH:ii” 15:00
firstName

lastName

String Guest’s Name Max Mustermann
guestEmail String Guest’s Email max@muster.de
guestPhone String Guest’s Phone 0177 12345678
notice String Notes. Text for every information you need. Breakfast, one dog
adults Int Number of adults 2
children Int Number of children 3
price Float Total price 150.00
priceStatus Int Current status of payment. Values can be:

1 – open/not payed

2 – partially paid

3 – complete payment

1
deposit Float Deposit 50.00
depositStatus Int Current status of payment. Values can be:

1 – open/not payed

2 – partially paid deposit

3 – complete paid deposit

1

Answer:

Our API answers with a code.

  • In case of success: Status-Code 200
{“id”: 4567}
  • In case of a wrong validation: Status-Code 400
{
  “status”: 400,
  “title”: “Bad Request”,
  “detail”: “Failed validation”,
  “validation_messages”: {
  “departureDate”: {
  “dateInvalidDate”: “The input does not appear to be a valid date”
}
}
}
  • In case of an unauthorized request: Status-Code 401
{
  “status”: 401,
  “title”: “Unauthorized”,
  “detail”: “Authentication required”
}
  • In case of a double booking: Status-Code 422
{
  “status”: 422,
  “title”: “Unprocessable Entity”,
  “detail”: “There exists already a reservation from 01.09.2017 to 03.09.2017
}

3: Get Reservations

Request

Method: GET
Format: JSON
Query paramter:
“from”: YYYY-mm-dd (default: today),
“to”: YYYY-mm-dd,
“created_from”: YYYY-mm-dd,
“created_to”: YYYY-mm-dd,
“showCancellation”: false”/”true (default “false”),
“page”: integer (default “1”)
URL: login.smoobu.com/api/apartment/:apartmentID/booking
Headers: API-Key (Api key provided by Smoobu)

Example:  login.smoobu.com/api/apartment/17/booking?from=2017-01-12&to=2019-01-13&created_from=2018-01-02&created_to=2018-01-08

Response

Format: JSON
Pagination: 
We send a maximum of 25 bookings per request. If you have more we split it into pages. At the beginning of the response you can see how many bookings you get and how many pages we have.

Example:

{
 "page_count": 1,
 "page_size": 25,
 "total_items": 3,
 "page": 1,
 "bookings": [
 {
  "id": 291,
  "type": "reservation",
  "arrival": "2018-01-10",
  "departure": "2018-01-12",
  "created-at": "2018-01-03 13:51",
  "apartment": {
   "id": 50017,
   "name": "Seaside apartment"
  },
  "channel": {
   "id": 465614,
   "name": "Booking.com"
  },
  "guest-name": "Harry Potter",
  "email": "HarryPotter@hogwarts.com",
  "phone": "+49123456789"
  "adults": 3,
  "children": 2,
  "check-in": "16:00",
  "check-out": "10:00",
  "notice": "",
  "price": 150,
  "price-paid": "Yes",
  "deposit": 0,
  "deposit-paid": "No"
 },
 {
  "id": 292,
  "type": "reservation",
  "arrival": "2018-01-22",
  "departure": "2018-01-25",
  "created-at": "2018-01-03 13:51",
  "apartment": {
   "id": 50017,
   "name": "Seaside apartment"
  },
  "channel": {
   "id": 465885,
   "name": "Airbnb"
  },
  "guest-name": "Hermine Granger",
  "email": "Hermine@hogwarts.com",
  "phone": "+49123456789",
  "adults": 1,
  "children": 0,
  "check-in": "18:00",
  "check-out": "",
  "notice": "she arrives by plane and is maybe a little bit late",
  "price": 200,
  "price-paid": "YES",
  "deposit": 0,
  "deposit-paid": "No"
  },
 ]
}

4: Get Apartments

Request

Method: GET
Format: JSON
Headers: API-Key (Api key configured for smoobu by yourself)

Example:  GET https://login.smoobu.com/api/apartment

Response

– apartments: list of apartments of this user

Structure for the apartment response:
– apartmentId: id of a single apartment
– name: Name of this apartment
– persons: Number of max guests
– currency: IsoCode of the currency (e.g. EUR)
– optionalInvoiceItems: list of all optional invoice items for the booking tool

Structure for the optional invoice item response:
– itemId: id of the item
– name: name of the item
– amount: amount of the item
– isUsePercentage: Boolean
– isOptional: Boolean
– calculationType: integer for calculation type
0: per booking
1: per person
2: per night
3: per person and night

Example:

{
    "apartments": [
        {
            "apartmentId": 43,
            "name": "Kaskadierung 1",
            "persons": 1,
            "currency": "EUR",
            "optionalInvoiceItems": []
        },
 ] 
}

5: Change Availability (under construction)

Request

Method: POST
Format: JSON
Headers: API-Key (Api key configured for smoobu by yourself)

Parameter:
– user_id: ID of the user in your system
– id: ID of the apartment in your system
– start_date: start date from which the availability should be changed
– end_date: end date until the availability should be changed
– available: is the apartment available in this date range

apartments: list of apartments of this user
– id: id of a single apartment
– name: Name of this apartment

Example:  set to unavailable

{
 "id": 122,
 "start_date": "2019-01-01",
 "end_date": "2019-01-04",
 "available": false
}

Example:  set to available

{
 "id": 122,
 "start_date": "2019-02-01",
 "end_date": "2019-02-09",
 "available": true
}

 

Response

Paramater:

– success: whether the update was successful or not
– error_message: the error message if the request failed e.g. because the apartment is already booked

Example:

{
 "success": true,
 "error_message": null
}

©2014 - 2018, Smoobu GmbH, Woennichstr. 68/70, 10317 Berlin, +44 1157070245