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 this endpoint 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.

Example:

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

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.

Example:

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

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.

Example:

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

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"]
    ]
}