Skip to main content

Implement in-app unlocks

Follow this step-by-step guide on how to implement Kisi in-app unlocks in your own application.

  1. Obtain the user login
  2. Fetch a list of locks
  3. Handle lock statuses
  4. Implement proximity checks
  5. Unlock locks via the API

Obtain the user login​

Obtaining the user's API key is necessary to ensure that only the doors that the user has access to are displayed. You can obtain this by creating a login on the user's behalf.

Once you've acquired the API key, you can go ahead and fetch the list of locks this partricular user can access.

Fetch a list of locks​

It is important to ensure that your app displays all the locks that the user has access to within your premises. Depending on the your use case, you may need to retrieve either all the locks at your organization or just the locks at a particular place.

Send a GET request to the Fetch locks endpoint, while making sure you use the respective user's API key, as shown below:

Example

curl --request GET \
  --url https://api.kisi.io/locks \
  --header 'Authorization: KISI-LOGIN <API_KEY>' \
  --header 'Content-Type: application/json'

Response

If your request was successful, you'll receive a 200 OK response, with the list of all the locks that the respective user can access, and their attributes.

{
  "id": 0,
  "name": "string",
  "description": null,
  "latitude": null,
  "longitude": null,
  "configured": false,
  "online": false,
  "unlocked": false,
  "unlocked_until": null,
  "locked_down": false,
  "locked_down_since": null,
  "open": false,
  "geofence_restriction_enabled": null,
  "geofence_restriction_radius": 300,
  "reader_restriction_enabled": null,
  "time_restriction_enabled": null,
  "time_restriction_time_zone": "Europe/Budapest",
  "groups_count": 0,
  "order_id": null,
  "floor_id": 0,
  "integration_id": null,
  "place_id": 0,
    "place": {
      "id": 0,
      "name": "string",
      "latitude": 0,
      "longitude": 0
    }
}

Handle lock statuses​

To properly handle lock statuses in the user interface, please consider the following statuses:

  • Locked
  • Unlocked
  • Locked Down
  • Offline

You can find all lock statuses in the API documentation.

info

After a successful unlock, it's recommended that you assume the door is unlocked for a few seconds in terms of the UI state, as waiting for real-time data on the door's actual state might be too slow.

Implement proximity checks​

For doors with Kisi Reader restriction, make sure to implement proximity checks as described in our SDK documentation.

Unlock locks via the API​

In the example below we demonstrate the Unlock lock endpoint, without using any physical Kisi hardware. Still, you'll be able to see the door's response to the API call.

Send a POST request to the Unlock lock endpoint, while replacing {id} with the id of the lock you want to unlock

Example

curl --request POST \
  --url 'https://api.kisi.io/locks/{id}/unlock' \
  --header 'Authorization: KISI-LOGIN <API_KEY>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json'

Response

Since in this example we didn't use any Kisi hardware, you should receive a 409 Conflict response, containing a JSON body as follows:

{
  "error": "The door has no assigned Kisi controller."
}

The 409 Conflict message shows two things:

  1. there isn't any controller assigned to the respective door
  2. the door is reacting to the API calls
info

If your door is connected to the Kisi hardware and the connected relay is triggered, you should receive a 200 OK response.