Skip to content

Locks API

The Locks API is a part of the Integrators API, and is used to fetch and update locks.
New locks are added by connecting to or refreshing the connection to a vendor.

Using these endpoints requires having a JWT scoped for the Lock Holder.
See Authentication for details.

If you don't have a Lock Holder yet you can create one using the Lock Holder API

Endpoints

Get all locks

GET integrators/v1/lock-holders/:lockHolderId/locks/

Return a list of all locks registered on this Lock Holder.

Request

Field Optional Type Location Description
lockHolderId no string url Id of the lock holder. Must match the one in the JWT scope.

Example: GET https://api.unloc.app/integrators/v1/lock-holders/5d7c7d59-dd94-4b0e-8df4-501c028e37ea/locks/

Response

200

The endpoint returns an array named "locks", with each lock having the following fields:

Field Optional Type Location Description
id no string body Unique identifier for this lock
name no string body Display name for the lock
vendor no string body What vendor the lock is from. E.g. Danalock
imageUrl no string body Url to get this locks image. May be empty.
canCreateKeysCount no number body The number of users who can create keys to this lock.
keysCreatedCount no number body The number of keys users have created to this lock

Example:

{
    "locks": [
        {
            "id": "73289bd1-6d3e-4dba-9e95-faf96899e480",
            "name": "Townroad 22A East",
            "vendor": "danalock",
            "imageUrl": "https://www.example.com/image1.jpg",
            "canCreateKeysCount": 3,
            "keysCreatedCount": 0
        },
        {
            "id": "461a3f22-8aee-41f4-80c0-ecfb739f7677",
            "name": "Townroad 22A West",
            "vendor": "danalock",
            "imageUrl": "https://www.example.com/image2.jpg",
            "canCreateKeysCount": 93,
            "keysCreatedCount": 1203
        }
    ]
}

4xx
Field Optional Type Location Description
error no string body The type of error that occurred
error_description no string body Verbose description of the error

Example:

{ 
    "error": "JsonWebTokenError",
    "error_description": "invalid signature"
}

Get a single lock

GET integrators/v1/lock-holders/:lockHolderId/locks/:lockId

Request

Field Optional Type Location Description
lockHolderId no string url Id of the lock holder. Must match the one in the JWT scope.
lockId no string url Id of the lock to get

Example:
GET https://api.unloc.app/lock-holders/5d7c7d59-dd94-4b0e-8df4-501c028e37ea/locks/19398e97-cef8-4e3e-90a2-43162f319356

Response

200

The endpoint returns a single lock with the following fields:

Field Optional Type Location Description
id no string body Unique identifier for this lock
name no string body Display name for the lock
vendor no string body What vendor the lock is from. E.g. Danalock
imageUrl no string body Url to get this locks image. May be empty.
canCreateKeysCount no number body The number of users who can create keys to this lock.
keysCreatedCount no number body The number of keys users have created to this lock

Example:

{
    "lock": {
        "id": "73289bd1-6d3e-4dba-9e95-faf96899e480",
        "name": "Townroad 22A East",
        "vendor": "danalock",
        "imageUrl": "https://www.example.com/image1.jpg",
        "canCreateKeysCount": 3,
        "keysCreatedCount": 0
    }
}

4xx
Field Optional Type Location Description
error no string body The type of error that occurred
error_description no string body Verbose description of the error

Example:

{ 
    "error": "notFound",
    "error_description": "Could not find lock with id \"909dd04b-8c7b-41e5-bbd1-fb5e88912a22\""
}

Update lock

PATCH integrators/v1/lock-holders/:lockHolderId/locks/:lockId

Update the name of a lock.
Additional updateable fields may be added later.

Request

Field Optional Type Location Description
lockHolderId no string url Id of the lock holder. Must match the one in the JWT scope.
lockId no string url Id of the lock to update
name no string body New name for the lock

Example:
PATCH https://api.unloc.app/lock-holders/5d7c7d59-dd94-4b0e-8df4-501c028e37ea/locks/19398e97-cef8-4e3e-90a2-43162f319356

{
    "name": "Townroad 22B East"
}

Response

200

The endpoint returns the updated lock, with the following fields:

Field Optional Type Location Description
id no string/uuid v4 body Unique identifier for this lock
name no string body Display name for the lock
vendor no string body What vendor the lock is from. E.g. Danalock
imageUrl no string body Url to get this lock's image. May be empty.
canCreateKeysCount no number body The number of users who can create keys to this lock.
keysCreatedCount no number body The number of keys users have created to this lock

Example:

{
    "lock": {
        "id": "73289bd1-6d3e-4dba-9e95-faf96899e480",
        "name": "Townroad 22B East",
        "vendor": "danalock",
        "imageUrl": "https://www.example.com/image1.jpg",
        "canCreateKeysCount": 3,
        "keysCreatedCount": 0
    }
}

4xx
Field Optional Type Location Description
error no string body The type of error that occurred
error_description no string or array body Verbose description of the error, possibly an array of validation errors.

Example:

{ 
    "error": "invalidRequest",
    "error_description": [
        ["name", "Must be 1024 characters or less"]
    ]
}

Delete Shared Keys

DELETE integrators/v1/lock-holders/:lockHolderId/locks/:lockId/:userId/shared-keys

Delete all keys to this lock the user has shared to others via the app.

Request

Field Optional Type Location Description
lockHolderId no string url Id of the lock holder. Must match the one in the JWT scope.
lockId no string url Id of the lock
userId no string url Url-encoded E.164-formatted phone number

Example:
DELETE https://api.unloc.app/lock-holders/5d7c7d59-dd94-4b0e-8df4-501c028e37ea/locks/19398e97-cef8-4e3e-90a2-43162f319356/%2B61452912447/shared-keys

Response

200

Returns the number of keys deleted

Field Optional Type Location Description
keysDeleted no number body The number of keys deleted

Example:

{
    "keysDeleted": 6
}

4xx
Field Optional Type Location Description
error no string body The type of error that occurred
error_description no string body Verbose description of the error

Example:

{ 
    "error": "notFound",
    "error_description": "Could not find lock holder"
}