Version 2 of the Unloc API was released September 2023, and makes it easier to manage Keys on the Unloc Platform. Use this guide to learn about the improvements in the API, and how to migrate from Version 1.

The first things to notice is that entire API has been renamed from Integrator API to Unloc API. All other changes are described in detail below.

If you are migrating your integration from Version 1 to Version 2 without implementing any new features, then changing the relevant paths and updating some request and response bodies should be enough to switch to the new version.

Table of contents

What has changed?

Renaming of core concepts
From Roles to Sharing Rights
Separate endpoints for adding Lock Connections
Creating Keys
Recurrence

What is new?

Access Groups
Managed Users
Doorbell
Subproject
Jobs

What has changed?

A lot of changes has been done from V1 to V2. Here you can read about the changes.

Renaming of core concepts

In order to make it easier to get started with the Unloc platform, we have done an extensive renaming job of some of our core concepts. This is also reflected in the API paths. We believe the result makes it easier to talk about the integrations, and easier to use the API.

The new terms will be used in all communication about Unloc going forwards, and the old terms will be deprecated. For instance we will no longer use the word Lock Holder, but instead talk about Projects.

See table below:

In addition we have changed how some fields in request/response bodies are named:

From Roles to Sharing Rights

Allowing users to share Keys with the Unloc App is one of the biggest value propositions of Unloc. In Version 1 of the Unloc API you could assign a Role to a User, and the User would able be create Keys in the Unloc App. We found that talking about Roles were confusing, as a Role can mean so many things. It wasn't understood from the term what giving a User a Role would mean. That's why we decided to change it.

In Version 2 we want to make it more explicit what a User can do. So we got rid of the Role term, and are now calling it Sharing Rights. As a bonus, we now support multiple Sharing Rights per User+Lock-combo, enabling us to add Subprojects.

Sharing Rights is backwards compatible with Roles. Roles you created in V1 will appear as Sharing Rights in V2, and vice versa.

Separate endpoints for adding Lock Connections

In Version 1 of the API we had a single endpoint to onboard a VendorLock Connection. When the number of different Vendors we support in the platform increased, the complexity of the endpoint got more and more insufferable. So in Version 2 we have decided to split it into one endpoint per Lock Vendor.

See the API reference for each vendor to get the details.

Creating Keys

In Version 1 of the API you would create Keys one by one, with an API call for each key – that is a thing of the past! In Version 2 there is only one API endpoint for Creating Keys, and it accepts input for multiple Keys in one go.

The new API endpoints accepts an array of Key inputs. The request body below show how you can create two keys to the same user with one request:

{
  "keys": [
    {
      "lockId": "30826020-d32b-4178-a510-ab3c67b8dd46",
      "appUserId": "+4790010100"
    },
    {
      "lockId": "c70e900d-b905-4902-b64c-1ce429bac9f6",
      "appUserId": "+4790010100"
    }    
  ]
}

If any of the Key inputs fail validation, the call will fail. If everything looks good, the API call returns a reference to a Job that you can use to monitor how the Key creation job is proceeding with the new Jobs feature.

Recurrence

In Version 1 of the API we only supported a single recurrence period per day, but in Version 2 we are planning to make it possible to add multiple periods per day. Because of this we needed to change the data structure in which we represent Recurrence.

This is how recurrence was defined in V1:

`
export type RecurrenceDTOV1 = {
    // days with timespans
    [day in Weekday]?: TimeSpanDTOV1
}

export interface TimeSpanDTOV1 {
    startHour: number
    startMinute: number
    endHour: number
    endMinute: number
}

This is the new definition for V2:

export type RecurrenceDTOV2 = {
    timeSpans: TimeSpanV2[]
}

export interface TimeSpanV2 {
    weekday: Weekday
    startHour: number
    startMinute: number
    endHour: number
    endMinute: number
}

Note: Multiple recurrence periods is not yet available.

Read more about Recurrence

What is new?

Organization and Project Modules

In Version 2 we introduce a new concept: Modules. A Module is a piece of functionality that can be activated in your Organizations and Projects. Activating a Module will enable the relevant endpoints in the API, and enable new sections in the Unloc Control Center.

Project modules:

Organization modules:

Seeing what Modules is activated for a given Organization or Project is available through the API, and will be displayed in the Unloc Control Center.

📘

At launch Modules need to be activated for a specific Organization/Project through Unloc support.

Access Groups

Access groups allow you to create groups of doors and people, where every user in a group get a key to every door in the group. This make it more efficient to create and revoke keys when several people need access to the same doors.

An example of this could be different entrances in a residential building, or a specific company within a commercial building.

Access Group Keys is not revokable through the Revoke Keys endpoint. To remove a Key you need to either remove the user or the Lock from the Access Group.

Read more about Access Groups

Managed Users

Managed Users is a new way to add users to your Project without giving them a Key. The model lets you add metadata about a user that is only visible in the context your Project. You can use this to add users before giving them Keys.

Managed Users will be automatically created when you create Keys or Sharing Rights to a new user that does not exist.

In the data model we distinguish between App Users and Managed Users. Despite representing the same individual, these terms signify two different user representations.

An App User refers to a user logged into the app, displaying the name and image that the user has set.
On the other hand, a Managed User represents a user as defined by you. This allows you to assign a name and add metadata relevant to your Project.

When deleting a Managed Users, the user will be removed from all Doorbells and Access Groups, and all keys and sharing rights will be revoked.

Doorbell

With Version 2 of the Unloc API you can finally manage Unloc Doorbell through the API.

With Unloc Doorbell, visitors simply scan a QR code next to the door to call who they want to visit, and with a single click of a button, the resident can open the door.

The Doorbell API lets you create Doorbells and keep the lists up to date.

Read more about Doorbell

Subproject

Subprojects allow you to delegate access management of your doors to other administrators in the Unloc Control Center. Create a Subproject, add doors, add an administrator, and let them add users and create keys. All the while keeping full control of who has access to what.

You can at any time remove a door from the Subproject, and all keys for that door within the Subproject will be automagically removed.

The feature is great if you want to delegate access to some one else in the Unloc Control Center, but can also been used through the API to logically split up your Project.

All Managed Users, Keys, and Sharing Rights created in the context of a Subproject will be tagged with a SubprojectId.

Read more about Subprojects

Jobs

Version 1 of the API left a lot to be desired when it comes to feedback when creating Keys and refreshing Lock Connections. So in Version 2 we introduce the concept of Jobs which give you the option to monitor ongoing Jobs on the server side.

Through the Jobs Status endpoint you can get information about a running Job. With the launch of V2 we have four types of Jobs:

Read more about Jobs