Managing check-in requests¶

This section describes all the possible actions related to check-in requests using the Online Check-in API. A check-in request is created after a guest makes a reservation, which becomes usable via the API 48 hours before the check-in date.

Onboarding properties¶

POST
https://supply-xml.booking.com/online-checkin-api/connections

The POST online-checkin-api/connections endpoint enables you to add one or more properties to the online check-in flow. This means that you must onboard properties via this endpoint to enable them to provide the online check-in service to their guests.

Body parameters¶

The following table describes what elements you can add as query parameters:

Request body example¶

The following is a request body example:

{
    "connections": [
      {
        "property_id": 6867480,
        "status": 0
      }
    ]
  }

Response body example¶

The following is a successful response body example:

{
    "data": {
    },
    "warnings": [],
    "errors": [],
    "meta": {
        "ruid": "UmFuZG9tSVYkc2RlIyh9YY8pNP28YnjFYiCLGDctX2VdpaCrD2ekmKJeDlscod1V6ffje/e7RlMOXp1XuxdSdaTwUn7VvORk"
    }
}

Response body parameters¶

The following table describes the response elements:

The API returns the following error response when you try to connect property which is a live property and you are not certified to use Online check-in API.
"Error code= BAD_REQUEST" ShortText="1 non-test hotel[s] found. Provider is not certified to use Online check-in API for live properties."....
To resolve the error, you can either connect only test properties, or you'll need a Online Check-in API certification from us to connect to live properties. To obtain this, please contact Connectivity Support team.

Retrieving properties that can use the online check-in API (onboarded properties)¶

GET
https://supply-xml.booking.com/online-checkin-api/connections

The GET online-checkin-api/connections endpoint enables you to retrieve all of your properties that are onboarded and can use the online check-in flow.

Query parameters¶

The following table describes what elements you can add as query parameters:

Response body example¶

The following is a successful response body example:

{
    "data": {
        "connections": [
            {
                "property_id": 6796563,
                "status": 1,
                "created_at": "2021-02-23 21:57:25",
                "updated_at": "2021-06-16 12:23:45"
            },
            {
                "property_id": 7344263,
                "status": 1,
                "created_at": "2021-06-01 10:54:04",
                "updated_at": "2021-06-16 12:23:45"
            },
            {
                "property_id": 7344457,
                "status": 1,
                "created_at": "2021-06-01 10:54:04",
                "updated_at": "2021-06-16 12:23:45"
            }
        ],
        "next_page": null
    },
    "warnings": [],
    "errors": [],
    "meta": {
        "ruid": "UmFuZG9tSVYkc2RlIyh9YRQ7gbXAPki2nCInyYXmc+4Hddp+Y/GHKKhwruGUP4DfPiv9Rncl4n+9B1ugY8Ahhbc1xzpgheYb"
    }

Response body parameters¶

The following table describes the response elements:

Using the online check-in API¶

The check-in request journey starts when a guest's reservation is within 48 hours before the check-in date. Depending on your properties' needs (you can use only one flow per machine account), you can use one of the following two flows:

• Control flow: The property can decide which guests (reservations) are eligible to do an online check-in. For example, property wants to only enable guests with pre-paid reservations to check in online.
• Automated flow: The property automates the check-in flow by enabling all guests with a reservation to do an online check-in. If needed, the property can still reject an online check-in.

The automated flow is the default flow. If you want to change to the control flow, contact the Connectivity support team.

Control flow¶

To understand how to use the control flow, see the following high-level steps:

1. You must retrieve available check-in requests by querying /checkins or /properties/{property_id}/checkins with status CREATED.

   • Use /checkins to retrieve check-in requests for all your properties.
   • Use /properties/{property_id}/checkins to retrieve check-in requests for a specific property.

   If the property wants to continue the online check-in process, it requires more information from the guest.

2. To continue you must update the specific check-in request with status DATA_REQUIRED.

   The guest receives an email with prompts for information, such as address, passport info, and other personal information details. (What these legal details are can change depending on the property's country.)

3. You must retrieve the check-in requests again using status REQUESTED.

   The property can now choose to approve or deny the check-in.

4. You must update the check-in request with either status SUCCESS to approve the check-in or DENY to cancel.

5. In case of SUCCESS, you must provide instructions to access the accommodation (unit).

   The guest receives confirmation email with information on how to access accommodation (unit).

Automated flow¶

Guests can do an online check-in within 48 hours before the check-in date. To understand how to use the automated flow, see the following high-level steps:

1. You must retrieve the check-in requests again using status REQUESTED.

   The property can now choose to approve or deny the check-in.

2. You must update the check-in request with either status SUCCESS to approve the check-in or DENY to cancel.

3. In case of SUCCESS, you must provide instructions to access the accommodation (unit).

   The guest receives confirmation email with information on how to access accommodation (unit).

Retrieving check-in requests¶

You can retrieve check-in requests in two ways: For all your properties or per specific property. Both ways follow almost exactly the same format and functionalities. They only differ when it comes to the endpoint and path parameters:

• For all your properties
• Per specific property

Statuses¶

This API uses five statuses, which include both statuses you can retrieve and set. To understand what each status means, does, and what the response looks like, see:

• CREATED: A guest's reservation created a basic check-in request. You can only retrieve requests with this status.
• DATA_REQUIRED: The property wants to enable guest to do an online check-in, but required more information. You can set and retrieve requests with this status.
• REQUESTED: The guest checked in online (and therefore sent required information) via the tool sent to them by email. You can only retrieve requests with this status
• SUCCESS: The property approved the check-in and sent information on how to access the accommodation. You can set and retrieve requests with this status.
• DENIED: The property rejected the check-in for whatever reason. You can set and retrieve requests with this status.

The following diagrams show high-level overviews of the two possible status sequences. Blue refers to statuses that you can only retrieve, while green refers to statuses you can both set and retrieve:

Figure 1: Overview for the control flow
Figure 2: Overview for the automated flow

All properties¶

GET
https://supply-xml.booking.com/online-checkin-api/checkins

The GET /checkins request enables you to retrieve check-in requests for all your properties. You can filter the results by status. If you do not specify status, you retrieve all check-in requests.

Per property¶

GET
https://supply-xml.booking.com/online-checkin-api/properties/{property_id}/checkins

The GET /properties/{property_id}/checkins request enables you to retrieve check-in requests for per property. You can filter the results by status and reservation_id. If you do not specify status or reservation_id, you retrieve all check-in requests for the specified property.

Path parameters: Per property¶

You must only include this parameter if you want to retrieve check-in requests for a specific property.

Query parameters¶

The following table describes what elements you can add as query parameters:

Response body example: CREATED¶

The following is a successful response body example:

{
    "data": {
        "checkins": [
            {
                "checkout_date": "2021-03-03",
                "checkin_date": "2021-03-02",
                "updated_at": "2021-03-02T12:28:01Z",
                "main_guest": {
                    "last_name": "Doe",
                    "phone": "1234-5678",
                    "email": "johndoe@guest.booking.com",
                    "first_name": "John"
                },
                "expected_arrival_time": "2021-03-02T18:00:00Z",
                "created_at": "2021-03-02T12:28:01Z",
                "status": "CREATED",
                "reservation_id": "2114700015",
                "property_id": 6314570,
                "id": "f61a4afd43f81a50a3f2a008d203a2d7",
                "room_reservation_id": "3097793765"
            }
        ],
        "next_page": "https://supply-xml.booking.com/online-checkin-api/properties/6314570/checkins?page=2&page_size=1"
    },
    "meta": {
        "ruid": "UmFuZG9tSVYkc2RlIyh9YV/rUd3d3dDgYWUZJWVVAC7dFrVXAn+RVs+cXuij49FoehET/yv6Ft1MQtYqCJBlsM1TjRS1"
    },
    "warnings": [],
    "errors": []
}

Response body elements: CREATED¶

The following table describes the response elements:

Response body example: DATA_REQUIRED¶

The following is a successful response body example:

{
    "data": {
        "checkin_date": "2021-03-02",
        "property_id": 6314570,
        "updated_at": "2021-03-02T12:28:01Z",
        "main_guest": {
            "email": "johndoe@guest.booking.com",
            "first_name": "John",
            "phone": "1234-5678",
            "last_name": "Doe"
        },
        "id": "f61a4afd43f81a50a3f2a008d203a2d7",
        "expected_arrival_time": "2021-03-02T18:00:00Z",
        "status": "DATA_REQUIRED",
        "room_reservation_id": "3097793765",
        "reservation_id": "2114700015",
        "checkout_date": "2021-03-03",
        "created_at": "2021-03-02T12:28:01Z"
    },
    "warnings": [],
    "meta": {
        "ruid": "UmFuZG9tSVYkc2RlIyh9YY4dfhBVWE2AfpAWGztz+6JH6yh5oeLuuoFtZvd4QmUoserVrLGxZoCeHjz5LjD4Sy0dm7kGuYf9"
    },
    "errors": []
}

Response body elements: DATA_REQUIRED¶

The following table describes the response elements:

Response body example: REQUESTED¶

The following is a successful response body example:

{
    "meta": {
        "ruid": "UmFuZG9tSVYkc2RlIyh9YY4dfhBVWE2A/+m5d2Fqje1cfSuCcjhENO2t+jXA5kTsBIEU6cPjmRn+k6CA+c+1GI+GcIbOK8GT"
    },
    "warnings": [],
    "data": {
        "checkins": [
            {
                "created_at": "2021-03-02T12:28:01Z",
                "additional_guests": [],
                "expected_arrival_time": "2021-03-02T18:00:00Z",
                "checkin_date": "2021-03-02",
                "checkout_date": "2021-03-03",
                "updated_at": "2021-03-02T16:12:19Z",
                "reservation_id": "2114700015",
                "id": "f61a4afd43f81a50a3f2a008d203a2d7",
                "main_guest": {
                    "address": {
                        "country": "zz",
                        "city": "LONDON",
                        "zipcode": "1000AB",
                        "line2": "n.a.",
                        "line1": "Wegisweg, 42"
                    },
                    "signature": "data:image/png;base64,..",
                    "email": "johndoe@guest.booking.com",
                    "phone": "1234-5678",
                    "last_name": "Doe",
                    "documents": [
                        {
                            "expiration_date": "2022-01-01",
                            "identifier": "EN1111111",
                            "type": "passport"
                        }
                    ],
                    "gender": "unknown",
                    "first_name": "John"
                },
                "property_id": 6314570,
                "status": "REQUESTED",
                "room_reservation_id": "3097793765"
            }
        ],
        "next_page": null
    },
    "errors": []

Response body elements: REQUESTED¶

The following table describes the response elements. Keep in mind that not all elements show up for each request. This depends on the requirements per country.

Response body example: SUCCESS¶

The following is a successful response body example:

{
    "errors": [],
    "warnings": [],
    "data": {
        "main_guest": {
            "last_name": "Doe",
            "gender": "unknown",
            "email": "johndoe@guest.booking.com",
            "signature": "data:image/png;base64,..",
            "first_name": "John",
            "phone": "1234-5678",
            "address": {
                "country": "zz",
                "zipcode": "1000AB",
                "city": "LONDON",
                "line2": "n.a.",
                "line1": "Wegisweg, 42"
            }
        },
        "checkin_date": "2021-03-02",
        "room_access": {
            "additional_instructions": "2nd floor, go straight to the end, then turn left and find your room number.",
            "unit_label": "Room 550",
            "premises_access_pin": "1234567890",
            "unit_access_pin": "12345"
        },
        "status": "SUCCESS",
        "checkout_date": "2021-03-03",
        "updated_at": "2021-03-02T16:12:19Z",
        "reservation_id": "2114700015",
        "created_at": "2021-03-02T12:28:01Z",
        "property_id": 6314570,
        "expected_arrival_time": "2021-03-02T18:00:00Z",
        "room_reservation_id": "3097793765",
        "id": "f61a4afd43f81a50a3f2a008d203a2d7"
    },
    "meta": {
        "ruid": "UmFuZG9tSVYkc2RlIyh9YY4dfhBVWE2AnBP0+kFqiWEyTQrGRGmOP/iAqEchffPNp4sI8W+AWbJq4mu4mucXS/DewRPoSXNG"
    }

Response body elements: SUCCESS¶

The following table describes the response elements:

Response body example: DENIED¶

The following is a successful response body example:

{
    "warnings": [],
    "meta": {
        "ruid": "UmFuZG9tSVYkc2RlIyh9YY4dfhBVWE2ASSYaySTlbFSorPRB4qSJHQKB+UKCh1RenD3SMA2580L+rsurcMi0dLs7u6xBZXYr"
    },
    "errors": [],
    "data": {
        "reservation_id": "3338885609",
        "room_access": {},
        "status": "DENIED",
        "checkin_date": "2021-03-02",
        "checkout_date": "2021-03-03",
        "id": "c5135a8be42d276f459993a60a917b8b",
        "created_at": "2021-03-02T12:33:58Z",
        "property_id": 6314570,
        "expected_arrival_time": "2021-03-02T22:00:00Z",
        "main_guest": {
            "first_name": "John",
            "last_name": "Doe",
            "phone": "1234-5678",
            "email": "johndoe@guest.booking.com",
            "signature": "data:image/png;base64,..",
            "gender": "unknown",
            "address": {
                "line2": "n.a.",
                "zipcode": "1000AA",
                "country": "zz",
                "line1": "Awesomestreet",
                "city": "Amsterdam"
            }
        },
        "updated_at": "2021-03-02T16:33:17Z",
        "room_reservation_id": "3097798232"
    }

Response body elements: DENIED¶

The following table describes the response elements:

Updating a check-in request¶

PUT
https://supply-xml.booking.com/online-checkin-api/properties/{property_id}/checkins/{check-in_id}

The PUT /properties/{property_id}/checkins/{check-in_id} request enables you to update check-in requests. You can update a check-in request in the following ways:

• DATA_REQUIRED: Request currently has status CREATED, which means the property has a reservation for which online check-ins are possible. Setting this status triggers an email to be sent to the guest to retrieve the required information (dependent on country) by enabling the guest to check in online.

• SUCCESS: Request currently has status REQUESTED, which mean the property approves the online check-in and optionally sends information on how to access the accommodation (unit).

• DENIED: Request currently has status REQUESTED, which means the property denies the online check-in.

Path parameters¶

The following table describes what elements you must add in the request path:

Body parameters¶

The following table describes what elements you can add as query parameters:

Request body example: DATA_REQUIRED¶

The following is a successful request body example:

{
    "status": "DATA_REQUIRED"
}

Request body example: SUCCESS¶

The following is a successful request body example:

{
    "status": "SUCCESS",
    "room_access": {
        "premises_access_pin": "1234567890",
        "unit_access_pin": "12345",
        "unit_label": "Room 550",
        "additional_instructions": "2nd floor, go straight to the end, then turn left and find your room number."
    }
}

Request body example: DENIED¶

The following are successful request body examples:

{
    "status": "DENIED",
    "denial_reason": "OTHER",
    "denial_description": "Our systems doesnot work today, in-person check-in is therefore required."
}

{
    "status": "DENIED",
    "denial_reason": "INVALID_ID_DOCUMENT",
    "denial_description": "Passport is expired"
}

Response body example: DATA_REQUIRED¶

The following is a successful response body example:

{
    "warnings": [],
    "data": {
        "expected_arrival_time": null,
        "additional_guests": null,
        "property_id": 6314570,
        "room_reservation_id": "3060335376",
        "room_access": null,
        "id": "5ca8d53a69267a6d383687df840439ab",
        "checkin_date": "2021-01-05",
        "status": "DATA_REQUIRED",
        "checkout_date": "2021-01-06",
        "created_at": "2021-01-05T12:49:00Z",
        "main_guest": null,
        "updated_at": "2021-01-05T12:49:00Z",
        "reservation_id": "2865149165"
    },
    "meta": {
        "ruid": "UmFuZG9tSVYkc2RlIyh9YYrCGLva4KjLpuUdyffqcDcRfAxi9pKPLbrRp5+FvYqtFU4X9l6hYqyL6aaxBT26pXRV5Iemv7+3"
    },
    "errors": []
}

Response body elements: DATA_REQUIRED¶

The following table describes the response elements:

Response body example: SUCCESS¶

The following is a successful response body example:

{
    "meta": {
        "ruid": "UmFuZG9tSVYkc2RlIyh9YYrCGLva4KjLy4IJ0KBuafppRHkaFfW9UoTODRK75igo9NzEXVY6QUg3jTI2HVKP7whIbTJbx1Dk"
    },
    "data": {
        "checkin_date": "2021-01-05",
        "reservation_id": "2865149165",
        "room_reservation_id": "3060335376",
        "property_id": 6314570,
        "status": "SUCCESS",
        "updated_at": "2021-01-05T16:40:42Z",
        "created_at": "2021-01-05T12:49:00Z",
        "id": "5ca8d53a69267a6d383687df840439ab",
        "expected_arrival_time": null,
        "room_access": {
            "premises_access_pin": "1234567890",
            "unit_access_pin": "12345",
            "unit_label": "Room 550",
            "unit_lockbox_code": "1234",
            "additional_instructions": "2nd floor, go straight to the end, then turn left and find your room number.",
            "qrcode_content": null,
            "front_desk_key_pickup": null
        },
        "main_guest": {
            "signature": null,
            "last_name": "Janssens",
            "birth_city": null,
            "birthdate": "1946-07-11",
            "first_name": "Luca",
            "birth_country": null,
            "nationality": "ai",
            "gender": "unknown",
            "middle_name": null,
            "documents": [],
            "address": {
                "line1": "H.J.E. Wenckebachweg, 6 V15",
                "country": "be",
                "city": "Amsterdam",
                "zipcode": "1096AN",
                "line2": "n.a."
            },
            "email": "ljanss.991164@guest.booking.com"
        },
        "checkout_date": "2021-01-06",
        "additional_guests": []
    },
    "warnings": [],
    "errors": []
}

Response body elements: SUCCESS¶

The following table describes the response elements:

Response body example: DENIED¶

The following is a successful response body example:

{
    "data": {
      "id": "5c87144ab85859f449dcffa730c535e6",
      "property_id": 7344457,
      "checkin_date": "2023-03-01",
      "checkout_date": "2023-03-02",
      "room_reservation_id": "2370121818",
      "room_access": {},
      "reservation_id": "2370121818",
      "status": "DENIED",
      "denial_reason": "OTHER",
      "denial_description": "Our systems doesnot work today, in-person check-in is therefore required.",
      "main_guest": {
        "last_name": "Ballen",
        "gender": "unknown",
        "first_name": "Peter",
        "birth_country": "nl",
        "email": "noreply@booking.com"
      },
      "created_at": "2023-02-28T15:22:38Z",
      "updated_at": "2023-02-28T15:24:19Z"
    },
    "warnings": [],
    "errors": [],
    "meta": {
      "ruid": "UmFuZG9tSVYkc2RlIyh9Yd3xljKm++FDDtH9jZ1q9JX2ssWL8dOqzF7mwuaziu3b0Ix9fBXDdelJAbooncF/oJNqfG3ll6O+OJXYb0ZyIj8="
    }

Response body elements: DENIED¶

The following table describes the response elements: