Sample Post Body Request

The post body should contain the necessary data to create the access as a JSON object:

{
    "user": {
        "id" : 123456,
        "email": "user@yourdomain.com",
        "mobile": "16042656073"
    },
    "key": { "id" : 123456, "serialNumber": "XXXXX" },
    "accessStartDate": "2025-04-21",
    "accessStartTime": "12:45",
    "accessEndDate": "2025-04-23",
    "accessEndTime": "12:45",
    "timeZone": "America/Vancouver",
    "name": "Bob S.",
    "returnReminder": false,
    "suppressGuestNotifications": false,
    "locale": "en",
    "allowSetup": false
}

Suppressing Guest Communications

If you prefer not to have Keycafe send any messages to your guests, set the suppressGuestNotifications property to true. In this case, you must provide the guest with the bookingCode and checkinLink yourself through your own communication channels.

The booking code can be entered directly into the SmartBox screen by the guest.
The check-in link offers a guided mobile experience for key pickup and drop-off.

These values allow your guest to complete their key exchange without any communication from Keycafe.

Offline Key Exchange Best Practice

To ensure a seamless key exchange experience with Offline Mode, it is recommended to communicate booking codes to users in advance or keep them available locally in your app. This approach avoids relying on API availability to retrieve and display booking codes during the key exchange, providing a reliable experience even in offline scenarios.

Date Formats

There are two methods for specifying access dates.

ISO 8601 Format (Deprecated)
Separated date, time and timezone components.

ISO 8601 Format (Deprecated)

A single timestamp (e.g., "2024-04-22T12:45:00Z"). This method is deprecated due inconsistent support for "local" times.

Separated Components (Recommended)

This approach breaks the access window into separate date and time fields:

Use individual fields:

accessStartDate, accessStartTime
accessEndDate, accessEndTime
timeZone (optional)

This offers more flexibility and predictable local time handling.

Time Zone Behavior

Omitting date/time data will result in an ongoing access.
If time zone is omitted, the provided times are interpreted as local to the key’s current location where the key is stored. For example: if the location is in New York, then an accessEndTime of 00:00 ends at midnight in New York time.
If time zone is specified, the times are first interpreted in the given time zone and then converted to the key’s local time. For example, an access window ending at 00:00 in America/Vancouver will end at 03:00 in America/New_York.