🚧
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.

Creating an Exchange

To create an Exchange, submit a POST request containing the necessary data formatted as a JSON object. You can specify the user by ID, email address, or mobile number.

Example JSON Payloads

Create Exchange by User ID

{
  "type": "DROPOFF",
  "user": { "id": 123456 },
  "key": { "id": 123456 },
  "location": { "id": 123456 }
}

Create Exchange by User Email

{
  "type": "DROPOFF",
  "user": { "email": "test@yourdomain.com" },
  "key": { "id": 123456 },
  "location": { "id": 123456 }
}

Create Exchange by User Mobile Number

{
  "type": "DROPOFF",
  "user": { "mobile": "16042656073" },
  "key": { "id": 123456 },
  "location": { "id": 123456 }
}

Example Workflows

Pickup Workflow

Prompt the user to select a key.
Create an Exchange by sending a POST request, specifying:
- type: PICKUP
- key
- user
Save the Exchange ID returned in the response.
Instruct the user to press the flashing button on the SmartBox to open their key bin.
Poll the Exchange (GET request) using the Exchange ID to monitor its status:
- If completed becomes true, prompt the user to retrieve their key and close the door.
- Ifcancelled becomes true, display an error message and prompt the user to try again.

Drop-Off Workflow

Prompt the user to select a key and location.
Create an Exchange by sending a POST request, specifying:
- type: DROPOFF
- key
- location
- user
Save the Exchange ID returned in the response.
Instruct the user to scan their key fob at the SmartBox.
Poll the Exchange (GET request) using the Exchange ID to monitor its status:
- If completed becomes true, prompt the user to place the key in the bin and close the door.
- If cancelled becomes true, display an error message and prompt the user to try again.

Activation Workflow

Prompt the user to select a key and location.
Create an Exchange by sending a POST request, specifying:
- type: ACTIVATION
- key
- location
- user
Save the Exchange ID returned in the response.
Instruct the user to press the flashing button on the SmartBox to open the fob bin.
Poll the Exchange (GET request) using the Exchange ID to monitor the released and cancelled properties:
- If released becomes true, instruct the user to retrieve a fob from the bin, close the door, and scan their new fob.
- If cancelled becomes true, display an error message and prompt the user to try again.
Continue polling the Exchange to monitor the completed and cancelled properties:
- If completed becomes true, instruct the user to attach the fob to their keys.
- If cancelled becomes true, display an error message and prompt the user to retry the process.