Using the check-in API

This section describes all the possible actions related to retrieving guest registration data and providing room access instructions to guests through the online check-in API.

Check-in request object

Note

Only legaly required information will be available. Data will not be required from guests if not legally required to complete the check-in process in the property country.

Name Description Updated By[1] Required Type Default
firstname Guest's first name Booking No String empty
middlename Guest's middle name, only used on some countries (e.g. italy) Booking No String empty
lastname Guest's last name Booking No String empty
second_lastname Guest's second lastname (used in Spain for legal reasons) Booking No String empty
email Guest's email address Booking No String empty
status Status of the check-in request (see below) Both[2] No String empty
denial_reason Reason for denial when status is DENIED [3] Client App[1] No String empty
nationality Guest's country of nationality (in ISO 3166-1 alpha-2 format) Booking No String empty
gender Guest's gender (male / female / unknown) Booking No String empty
signature Guest's signature image in base64 data url format Booking No String empty
birthdate Guest's date of birth (YYYY-MM-DD) Booking No String empty
birth_city Guest's place of birth Booking No String empty
birth_country Guest's country of birth (ISO 3166-1 alpha-2) Booking No String empty
documents List of Guest's identity documents Booking No Object empty
expected_arrival_time Guest's expected time of arrival (in ISO8601 format). Booking No String empty
address Guest's address Booking No Object empty
room_access Room access object Client App Yes Object empty
room_access_usage Room access usage events Client App No Object empty
additional_guests List of Additional CheckinGuest for reservations having more that 1 guest Booking No Object empty

Possible status are: CREATED, DATA_REQUIRED, REQUESTED, SUCCESS and DENIED. You only ever have to update the status to either DATA_REQUIRED, SUCCESS or DENIED.

The signature is provided as an image in data url format, example:

data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+ip1sAAAAASUVORK5CYII=

[1] 'Client App' means that you're responsible to update/fill that information, when 'Booking' means that will be filled at the appropriate time by Booking.com based on guest provided information

[2] You and Booking.com are both responsible for changing the status of a check-in request, depending on the current request status. If the check-in request is in status CREATED or REQUESTED you are responsible for updating the status.

[3] Possible denial_reason are: UNKNOWN,DOMESTIC_ONLY, RESERVATION_CANCELLED.

documents object:

Name Description Required Type Default
type Identity document type Yes String empty
identifier Identity document number Yes String empty
issuer_authority Identity document issuer authority No String empty
issue_date Identity document expiration date (in ISO8601 format) No String empty
issue_city City in wich the document was issued No String empty
issue_country Country in wich the document was issued (ISO 3166-1 alpha-2) No String empty
expiration_date Identity document expiration date (in ISO8601 format) No String empty

Possible document types are: passport, national_id;

address object:

Name Description Required Type Default
line1 First line of address, street and house number No String empty
line2 Second line of addres No String empty
zipcode Zipcode of the address No String empty
city City No String empty
country Country (in ISO 3166-1 alpha-2 format) No String empty

room_access object:

Name Description Required Type Default
qrcode_content Content for a plain-text QR code to be shown to the guest Yes[1] String empty
premises_access_pin Plain-text access pin for a premise (e.g. building) to be shown to the guest No String empty
unit_access_pin Plain-text access pin for a unit (e.g. room) to be shown to the guest Yes[1] String empty
unit_lockbox_code Plain-text access code for a lockbox which contains the key(s) to a unit (e.g. room, apartment, villa) to be shown to the guest Yes[1] String empty
unit_label Unit label (e.g. room number) to be shown to the guest No String empty
additional_instructions Additional instructions on how to check-in to be shown to the guest No String empty
front_desk_key_pickup The guest will pick up the key at the front desk Yes[1] Bool empty

[1] Either qrcode_content or unit_access_pin or front_desk_key_pickup or unit_lockbox_code is required.

room_access_usage object:

Name Description Required Type Default
qr_first_scanned_at Timestamp for when the QR code was first scanned on the quiosk or front desk No ISO8601 empty
room_key_generated_at Timestmap for when the room key was generated at the quiosk No ISO8601 empty
key_collected_frontdesk_at Timestamp to when the guest collected the key at the frondesk (or locker) No ISO8601 empty
room_first_accessed_at Timestamp to when the key was first used No ISO8601 empty

Changes for multi guest integration

To get guest information for the additional guests (All guests other than primary guest), additional_guests key will be added in response of GET APIs when the checkin request is for reservation with more that one guest

  • additional_guests contains list of Check-in Guest objects

checkin guest object:

Name Description Updated By[1] Required Type Default
firstname Guest's first name Booking No String empty
middlename Guest's middle name, only used on some countries (e.g. italy) Booking No String empty
lastname Guest's last name Booking No String empty
second_lastname Guest's second lastname (used in Spain for legal reasons) Booking No String empty
email Guest's email address Booking No String empty
nationality Guest's country of nationality (in ISO 3166-1 alpha-2 format) Booking No String empty
gender Guest's gender (male / female / unknown) Booking No String empty
signature Guest's signature image in base64 data url format Booking No String empty
birthdate Guest's date of birth (YYYY-MM-DD) Booking No String empty
birth_city Guest's place of birth Booking No String empty
birth_country Guest's country of birth (ISO 3166-1 alpha-2) Booking No String empty
documents List of Guest's identity documents Booking No Object empty
address Guest's address Booking No Object empty

Get check-in request by id

GET https://hub-api.booking.com/v1.2/pms/hotels/{hotel_id}/checkin/{checkin_id}

Path parameters:

Name Description Type
hotel_id ID of the property String
checkin_id ID of the check-in request String

Sample response:

{
  "id": "ed3b64e81bc596b3eb9fbe4533300666",
  "channel_reservation_id": "channel-res-id",
  "room_reservation_id": "channel-room-reservation-id",
  "expected_arrival_time": "2022-06-01T01:00:00Z",
  "checkin_date": "2022-06-01",
  "checkout_date": "2022-06-02",
  "hotel_id": 1430720,
  "status": "SUCCESS",
  "firstname": "Alcocer",
  "lastname": "Gregg",
  "email": "galcocer@example.com",
  "gender": "male",
  "birthdate": "1990-08-19",
  "nationality": "in",
  "address": {
    "zipcode": "1234",
    "city": "Mumbai",
    "line1": "Fake street 123",
    "country": "in"
  },
  "documents": [
    {
      "type": "passport",
      "expiration_date": "2022-01-01",
      "issuer_authority": "in",
      "identifier": "AB 1234567"
    }
  ],
  "room_access": {
    "unit_label": "Room 550",
    "additional_instructions": "2nd floor, go straight to the end, then turn left and find your room number.",
    "qrcode_content": "This is plain text content to a QR code",
    "unit_access_pin": "12345",
    "premises_access_pin": "1234567890",
    "unit_lockbox_code" :"12345",

  },
  "updated_at": "2020-06-09T14:07:34Z",
  "created_at": "2020-06-09T14:07:34Z",
  "additional_guests": [
    {
      "gender": "male",
      "birthdate": "1990-08-19",
      "lastname": "Gregg",
      "firstname": "Alcocer Jr.",
      "nationality": "in",
      "email": "galcocerjr@example.com",
      "signature": "...",
      "documents": [...],
      "birth_city": null,
      "address": {
          "line2": "Line2 of address",
          "zipcode": "1234",
          "city": "Mumbai",
          "line1": "Fake street 123",
          "country": "in"
      },
      "birth_country": null,
      "id": "131a4432375f5bcb76053d55f47fec6b",
      "second_lastname": null
    },
    { ... }
  ]
}

List check-in requests for a property

GET https://hub-api.booking.com/v1.2/pms/hotels/{hotel_id}/checkin

Path parameters:

Name Description Type
hotel_id ID of the property String

Query parameters:

Name Description Required Type Default
page Which page of the results to fetch No Int 1
page_size Number of check-ins per page (request). Max is 100 No Int 50
status Status of the check-in request (see below) No String empty
reservation_id Booking.com Reservation Id No Int empty
id_type hard-code it to id_type=channelReservationId when using reservation_id No String empty

Possible status are: CREATED, REQUESTED, DATA_REQUIRED, SUCCESS and DENIED.

Sample response:

{
    "pagination": {
        "page_size": 50,
        "has_next": false,
        "total_records": 3,
        "page": 1
    },
    "checkins": [
        { ... },
        { ... },
        { ... }
    ]
}

Update check-in request

PUT https://hub-api.booking.com/v1.2/pms/hotels/{hotel_id}/checkin/{checkin_id}

Path parameters:

Name Description Type
hotel_id ID of the property String
checkin_id ID of the check-in request String

Sample request body:

{
  "status": "SUCCESS",
  "room_access": {
    "qrcode_content": "This is plain text content to a QR code",
    "premises_access_pin": "1234567890",
    "unit_access_pin": "12345",
    "unit_lockbox_code" :"12345",
    "premises_lockbox_code": "12345",
    "unit_label": "Room 550",
    "additional_instructions": "2nd floor, go straight to the end, then turn left and find your room number."
  }
}