Create Exchange

🚧

Exchange API Deprecation Notice

The Exchange API is a realtime authentication method that requires the cloud and connectivity to be fully intact during the key exchange. This module predates and by its nature cannot support our offline key exchange capability. With Offline Mode, the MS5 and MS4 SmartBoxes can continue operating even when connectivity is lost or the cloud is disrupted by reverting to their last synced state, enhancing reliability and ensuring a seamless key exchange experience. Thus, we strongly encourage using Accesses and Permissions for development which sync with the SmartBox in advance of the key exchange. A seamless user experience can be implemented by presenting a QR code for the user to present at the SmartBox.

For more details on Offline Mode, visit our help center.

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

// Create by ID
{
    "type": "DROPOFF",
    "user": { "id": 123456 },
    "key": { "id": 123456 },
    "location" : { "id": 123456 }
}
// Create by email
{
    "type": "DROPOFF",
    "user": { "email": "[email protected]" },
    "key": { "id": 123456 },
    "location" : { "id": 123456 }
}
// Create by mobile
{
    "type": "DROPOFF",
    "user": { "mobile": "16042656073" },
    "key": { "id": 123456 },
    "location" : { "id": 123456 }
}

Example Workflows

A typical pickup workflow follows these steps:

1. Prompt the user to select a key.
2. Create an exchange (POST), specifying the type (PICKUP), key and user. Note the exchange ID from the response.
3. Prompt the user to press the flashing button on the SmartBox to open their key bin.
4. Periodically retrieve (GET) the exchange using the ID. Note the state of the exchange from the "completed" and "cancelled" properties.
   • If "completed" becomes true, stop retrieving the exchange data and prompt the user to retrieve their key from the bin and close the door.
   • If "cancelled" becomes true, stop retrieving the exchange data, display an error and prompt the user to try again.

A typical drop off workflow follows these steps:

1. Prompt the user to select a key and location.
2. Create an exchange (POST), specifying the type (DROPOFF), key, location and user. Note the exchange ID from the response.
3. Prompt the user to scan their key fob at the SmartBox.
4. Periodically retrieve (GET) the exchange using the ID. Note the state of the exchange from the "completed" and "cancelled" properties.
   • If "completed" becomes true, stop retrieving the exchange data and prompt the user to place their key in the bin and close the door.
   • If "cancelled" becomes true, stop retrieving the exchange data, display an error and prompt the user to try again.

A typical activation workflow follows these steps:

1. Prompt the user to select a key and location.
2. Create an exchange (POST), specifying the type (ACTIVATION), key, location and user. Note the exchange ID from the response.
3. Prompt the user to press the flashing button on the SmartBox to open the fob bin.
4. Periodically retrieve (GET) the exchange using the ID. Note the state of the exchange from the "released" and "cancelled" properties.
   • If "released" becomes true, prompt the user to retrieve a fob from the fob bin, close the door and scan their new fob.
   • If "cancelled" becomes true, stop retrieving the exchange data, display an error and prompt the user to try again.
5. Continue retrieving (GET) the exchange using the ID. Note the state of the exchange from the "completed" and "cancelled" properties.
   • If "completed" becomes true, stop retrieving the exchange data and prompt the user to attach the fob to their keys.
   • If "cancelled" becomes true, stop retrieving the exchange data, display an error and prompt the user to try again.