NAV
shell ruby php javascript python

Introduction

Welcome to the Airhost Checkin API! YOu can use our API to access basic booking information and guest informations.

We have language bindings in Ruby! You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

Authentication

To generate proper authentication header, use this code:

# With shell, you can just pass the correct header with each request
curl "api_endpoint_here"
  -H "Authorization: Basic ZGVtbzpuaWt1bmlrdQ=="
  -H "APPID: APIKEY_FROM_AIRHOST"

require 'base64'
base64_encoded_string = Base64.encode64("username:password")

Base64.encode64("demo:nikuniku")
=> "ZGVtbzpuaWt1bmlrdQ=="

base64_encode("demo:nikuniku")
=> "ZGVtbzpuaWt1bmlrdQ=="

Buffer.from("demo:nikuniku").toString('base64')
#=> "ZGVtbzpuaWt1bmlrdQ=="

base64.b64decode("demo:nikuniku")
#=> "ZGVtbzpuaWt1bmlrdQ=="

Make sure to replace APIKEY_FROM_AIRHOST with your API key.

If you don't have one, please contact Airhost Support

Airhost expects for the API key plus the Authentication Key to be included in all API requests to the server in a header that looks like the following:

Authorization: Basic Base64(username:password)
APPID: APIKEY_FROM_AIRHOST

Base64(username:password) is host's username and password with the character ":" in the middle, then encode with base64 format.

House

Retrieve All Houses

curl "https://cloud.airhost.co/api/v1/houses"
  -H "Authorization: Basic Base64(username:password)"
  -H "APPID: APIKEY_FROM_AIRHOST"

JSON response:

{
    "data": [
        {
            "id": 409,
            "name": "AirHost Hotel No. 1",
            "house_photos": null,
            "address": null,
            "rooms": [
                {
                    "id": 421,
                    "name": "Double Bedroom"
                }
            ]
        },
        {
            "id": 401,
            "name": "AirHost Hotel No. 2",
            "house_photos": [
                "/uploads/house_picture/22/picture/1567674820-f07c678d-725f-59d3-be3a-30926e14ed98_636364134932167010.jpeg",
                "/uploads/house_picture/21/picture/1567674820-f07c678d-725f-59d3-be3a-30926e14ed98.jpeg"
            ],
            "address": "Address ABC, Street ABC, Japan",
            "rooms": [
                {
                    "id": 4241,
                    "name": "Single Bedroom"
                },
                {
                    "id": 401,
                    "name": "Double Bedroom"
                }
            ]
        }
    ],
    "meta": {
        "total_pages": 1,
        "total_count": 2
    }
}

This endpoint retrieves all the PMS connected houses with room information.

API Endpoint

GET https://cloud.airhost.co/api/v1/houses

Request Parameters

Parameter Description Mandatory
id House ID true
page Page number false

Response Properties

Parameter Description Mandatory
id Property ID true
name Property Name true
house_photos Array of Photo URLs true
address Address true
rooms Array of Rooms true
rooms[id] Room Type ID true
rooms[name] Room Type Name true

Booking

Retrieve Bookings

curl "https://cloud.airhost.co/api/v1/bookings"
  -H "Authorization: Basic Base64(username:password)"
  -H "APPID: APIKEY_FROM_AIRHOST"
  --date '{
  "house_id": 1,
  "updated_at": 11111111,
  "page": 2
    }

    updated_at = Time.zone.now.to_i

JSON response:

{
    "data": [
    {
        "id": 1358,
        "uid": "123456789",
        "guestnum": 3,
        "summary": "John Smith (123456789)",
        "dtstart": "2018-04-07T16:00:00.000+09:00",
        "dtend": "2018-04-11T11:00:00.000+09:00",
        "status": "confirmed",
        "checkin_type": "self_checkin",
        "checkin_status": "checked_in",
        "source": "airbnb",
        "created_at": "2018-01-07T16:00:00.000+09:00",
        "updated_at": "2018-01-11T11:00:00.000+09:00",
        "payment_status": "paid",
        "currency": "JPY",
        "reservation_site": "Booking.COM",
        "payment_method": "hotel_collect",
        "user": {
            "name": "John Smith",
            "email": "John@gmail.com",
            "language": "en",
            "phone": "1234567",
            "address": null,
            "country": "Spain",
            "postal_code": null
        },
        "room":
        {
            "id": 123,
            "name": "One Bedroom",
            "room_unit": "201"
        },
        "house":{
            "id": 1,
            "name": "Airhost Hotel"
        },
        "fees":[{
            "paid":false,
            "fee_type":"per_day",
            "amount":7700.0,
            "date":"2020-04-08",
            "description":"Standard Rate",
            "ota_collect":false,
            "included":false
            },
            {
                "fee_type": "channel_fee",
                "included": true,
                "amount": 1871
            },
            {
                "fee_type": "cleaning_fee",
                "included": true,
                "amount": 2000
            }],
        "booking_fees": [{
            "id":3,
            "fee_type":"transaction_fee",
            "description":"Stripe service fee",
            "dtdate":null,"amount":1008.0,
            "included":true,"currency":null,
            "paid":true,"per_night":false,
            "per_person":false,
            "percentage":0,
            "created_at":"2018-12-11T12:17:43.378+09:00",
            "updated_at":"2018-12-15T01:02:18.800+09:00"
        }],
        "cancellation_fee": 1008,
        "tasks": [{
            "type": "checkout",
            "date": "2019-07-22",
            "status": "pending"
        }],
        "checkin_code": 9760,
        "pre_checkin_url": "http://airhost/en/checkin/bookings/2b4e456f-abcd-efgh-ijkl-cfb76bb1bf1e",
        "checkin_information": null,
        "room_code": null,
        "key_doc_url": null,
        "checkin_completion_percentage": 80
    }],
    "meta":
    {
        "total_pages": 1,
        "total_count": 1
    }
}

This endpoint retrieves all bookings from one house.
Each request has a maximum of 10 results. If more than 10 results, use page 2 to get other results.

API Endpoint

GET https://cloud.airhost.co/api/v1/bookings

Request Parameters

Parameter Description Mandatory
house_id Search booking by House ID true
updated_at Bookings updated after this time (Epoch time in seconds) true
status Filter by booking status: default, all, pending, confirmed, cancelled, blocked, overlapped, closed, user_cancelled. Default will return confirmed + cancelled + user_cancelled bookings. false
page Page number false

Response Properties

Parameter Description Mandatory
id Booking ID in Airhost true
uid Booking ID from OTA true
guestnum Number of guests true
summary Booking's summary true
dtstart Checkin date true
dtend Checkout date true
status :pending, :confirmed, :cancelled, :blocked, :overlapped, :closed, :user_cancelled true
checkin_type self_checkin or operator_checkin false
checkin_status :before_checkin, :checked_in, :checked_out false
source OTA name true
created_at Time booking was created E.g. "2018-01-07T16:00:00.000+09:00" true
updated_at Time booking was last updated E.g. "2018-01-07T16:00:00.000+09:00" true
payment_status :not_paid, :paid, :partial_paid, :over_paid, :void true
currency Currency for this booking true
reservation_site Reservation source false
payment_method :ota_collect, :hotel_collect, :hotel_collect_credit, :hotel_collect_cash false
adultnum Num of adults for this booking false
childnum Num of children for this booking false
infantnum Num of infants for this booking false
description Booking's description or remark false
user Guest information true
room Room information true
house Property information true
fees Charges from OTA false
booking_fees Document any additional charges false
cancellation_fee Cancellation fees (For cancelled bookings) false
tasks Cleaning task details, if any false
checkin_code Same as Booking ID in Airhost false
pre_checkin_url Pre checkin URL false
checkin_information Checkin Information false
room_code Pin number of lock if IOT access is enabled false
key_doc_url Information for key for house false
checkin_completion_percentage Pre checkin guest information submission completion rate false

Create a Booking

curl -X POST "https://cloud.airhost.co/api/v1/bookings"
  -H "Authorization: Basic Base64(username:password)"
  -H "APPID: APIKEY_FROM_AIRHOST"
  -data '{
        "uid": "ABCDEFG",
        "guestnum": 3,
        "summary": "John Smith (ABCDEFG)",
        "description": "Need no smoking room",
        "dtstart": "2018-04-07T16:00:00.000+09:00",
        "dtend": "2018-04-11T11:00:00.000+09:00",
        "room_id": 123,
        "house_id": 1,
        "reservation_site": "your site name"
        "user":
        {
                    "name": "John Smith",
                    "email": "john_smith@gmail.com"
        }
    }'

JSON response:

{
    "id": 1358,
    "uid": "ABCDEFG",
    "guestnum": 3,
    "summary": "John Smith (ABCDEFG)",
    "description": "Need no smoking room",
    "dtstart": "2018-04-07T16:00:00.000+09:00",
    "dtend": "2018-04-11T11:00:00.000+09:00",
    "room":
    {
        "id": 123,
        "name": "One Bedroom"
    },
    "house":{
        "id": 1,
        "name": "Airhost Hotel"
    },
    "reservation_site": "your site name",
    "user":
    {
        "name": "John Smith",
        "email": "john_smith@gmail.com",
        "phone": "123456789",
        "language": "en",
        "country": "JP",
        "address": "123 test street"
    }
}

This endpoint add a guest into this booking

API Endpoint

POST http://cloud.airhost.co/api/v1/bookings

URL Parameters

Parameter Description Mandatory
uid Your unique ID for this booking true
guestnum Number of guests true
summary Reservation summary true
description Reservation details or guest remarks false
dtstart Checkin date in ISO 8601 format with timezone. true
dtend Checkout date in ISO 8601 format with timezone. true
room_id Room ID from airhost true
house_id House ID from airhost true
reservation_site Website name or company name or the OTA name false
user[name] Guest name true
user[email] Guest email address true
user[phone] Guest phone number true
user[language] Guest preferred language, two letters format. true
user[country] Guest country code false
user[address] Guest address false

Update a Booking

curl -X PUT "https://cloud.airhost.co/api/v1/bookings/:id"
  -H "Authorization: Basic Base64(username:password)"
  -H "APPID: APIKEY_FROM_AIRHOST"
  -data '{
    "uid": "ABCDEFG",
    "guestnum": 3,
    "summary": "John Smith (ABCDEFG)",
    "description": "Need no smoking room",
    "dtstart": "2018-04-07T16:00:00.000+09:00",
    "dtend": "2018-04-11T11:00:00.000+09:00",
    "status": "confirmed",
    "checkin_status": "checked_in",
    "reservation_site": "airbnb",
    "room_id": 123,
    "house_id": 1,
    "user":
    {
        "name": "John Smith",
        "email": "john_smith@gmail.com"
    }
}'

JSON response:

{
    "uid": "ABCDEFG",
    "guestnum": 3,
    "summary": "John Smith (ABCDEFG)",
    "dtstart": "2018-04-07T16:00:00.000+09:00",
    "dtend": "2018-04-11T11:00:00.000+09:00",
    "status": "confirmed",
    "checkin_status": "checked_in",
    "reservation_site": "airbnb",
    "room":
    {
        "id": 123,
        "name": "One Bedroom"
    },
    "house":{
        "id": 1,
        "name": "Airhost Hotel"
    },
    "user":
    {
        "name": "John Smith",
        "email": "john_smith@gmail.com"
    }
}

This endpoint add a guest into this booking

API Endpoint

PUT http://cloud.airhost.co/api/v1/bookings/:id

URL Parameters

Parameter Description Mandatory
id The Booking's ID true
status "confirmed" or "cancelled" true

3

Errors

The Airhost API uses the following error codes:

Error Code Description
400 Bad Request -- Your request is invalid (missing_required_paramter)
401 Unauthorized -- Your API key is wrong (invalid_api_key) or \n invalid_username_password: invalid username and password, please make sure they are base64 encoded.\n invalid_api_call: you are not authorized to use this API endpoint.
403 Forbidden -- The kitten requested is hidden for administrators only.
404 Not Found -- The specified record could not be found.
405 Method Not Allowed -- You tried to access a record with an invalid method.
406 Not Acceptable -- You requested a format that isn't json.
441 Not ready for checkin -- You cannot check in now, but need to wait till check-in time (not_ready_for_checkin)
442 Already checked in -- This reservation has already checked in (reservation_already_checked_in)
443 Already checked out -- This reservation has already checked out (reservation_already_checked_out)
429 Too Many Requests -- You're requesting too many kittens! Slow down!
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.
shell ruby php javascript python