Creating Intercom CRUD Endpoints

Overview

Intercom CRUD endpoints Seam to list intercoms owned by an Intercom Owner and trigger the intercom to open a door.

Listing Intercoms

After an Intercom Owner logs in, Seam lists all the intercoms they own and allows them to enable delivery on them. Your Intercom system should return a JSON list of intercoms.

List all intercoms owned by Intercom Owner

GET https://devicecloud.example.com/door_locks

Headers

Name	Type	Description
Authorization*	String	Bearer <access_token>

200: OK List of Intercoms in JSON

{
    "intercoms": [
        {
            "intercom_id": "3043fde0-3c6d-4913-981f-2607f05fe74e",
            // Optional, but recommended
            "name": "Office Front Door",
            "model": "example_model",
            "address": "123 Amy Lane, CA, 94110, United States"
        },
        {
            "intercom_id": "1c33d4cf-e178-4c06-8a9a-aadd6dc5a804",
            // Optional, but recommended
            "name": "Back Door",
            "model": "example_model",
            "address": "999 Louis Lane, CA, 94110, United States"
        }
    ]
}

Getting an Intercom

Seam may request intercom information to display information about the intercom to the connecting user.

Get information about a single intercom

GET https://devicecloud.example.com/intercoms/<INTERCOM_ID>

Query Parameters

Name	Type	Description
INTERCOM_ID*	String	Identifier for Intercom

Headers

Name	Type	Description
Authorization*	String	Bearer <access_token>

200: OK A single intercom JSON object

{
  "intercom_id": "3043fde0-3c6d-4913-981f-2607f05fe74e",
  // Optional, but recommended
  "name": "Office Front Door",
  "model": "example_model",
  "address": "123 Amy Lane, CA, 94110, United States"
}

Unlocking an Intercom Door

Seam unlocks doors to let in delivery people. If a door is disconnected or you're unable to unlock the door, return HTTP status code 500 with some details (see example below)

Temporary unlock the door for a delivery person

POST https://devicecloud.example.com/intercoms/<DOOR_LOCK_ID>/unlock

Headers

Name	Type	Description
Authorization*	String	Bearer <access_token>
Content-Type*	String	application/json

Request Body

Name	Type	Description
unlock_time*	String	Time in milliseconds the door should stay unlocked for

200: OK Door successfully unlocked

{
    "ok": true
}

500: Internal Server Error Something went wrong unlocking the door.

{
    "error_id": "INTERCOM_DISCONNECTED",
    "error_message": "Intercom is disconnected"
}

Other Intercom Features

You may want to include additional features for your intercom, such as configuring settings that are useful for delivery or apartment management. If you add additional endpoints, you should keep a similar URL format /intercoms/<INTERCOM_ID>/<SOME_PROPERTY_OR_FUNCTION>