Skip to content

Lock Holders API

The Lock Holders API is a part of the Integrators API, and is used for creating and managing Lock Holders. A Lock Holder is an entity used for holding locks, and must be managed by an Integrator.
All locks must belong to a Lock Holder.

Endpoints

Get manageable lock holders

GET integrators/v1//lock-holders/

This endpoint returns an array named "lock-holders" containing all Lock Holders that can be managed by the authenticated Integrator.

Info

If the authenticated Integrator has authenticated with a given scope then at most one Lock Holder will be returned. This is because the very purpose of the scope is to limit the Integrator's permissions to exactly one Lock Holder.

Request

Example:
GET https://api.unloc.app/integrators/v1/lock-holders/

Response

200

Example:

{
    "lock-holders": [
        {
            "id": "1d7c7d59-dd94-4b0e-8df4-501c028e37ea",
            "name": "Snook Ave Apts",
            "countryIso": "NO",
            "organizationId": "123",
            "organizationIdSuffix": ""
        },
        {
            "id": "2d7c7d59-dd94-4b0e-8df4-501c028e37eb",
            "name": "Carlyle Condos",
            "countryIso": "NO",
            "organizationId": "456",
            "organizationIdSuffix": ""
        }
    ]
}

Create a lock holder

POST integrators/v1/lock-holders/

This endpoint creates a new Lock Holder to be managed by the authenticated Integrator

Request

Field Optional Type Location Description
name no string body Displayname for the lock holder. 4 to 1024 characters.
countryIso no string body ISO 3166-1 alpha-2 country code.
organizationId no string body Nationally unique id for the lock holder. In Norway this is the Organization Id. 4 to 1024 characters. Only alphanumerics, underscore, or dashes.
organizationIdSuffix yes string body Optional suffix for the org id. Use this if you need several lock holders with the same org id. Max 1024 characters. Only alphanumerics, underscore, or dashes.
createVendorAccount yes boolean body If true we will try to create an account with the given vendor and a vendor connection, in addition to the lockHolder
vendor yes string body What vendor to create the account with. Only needed if createVendorAccount is true. Only danalock is supported so far.
email yes string body Username when creating a vendor account. Only needed if createVendorAccount is true and vendor is danalock
password yes string body Password when creating a vendor account. Only needed if createVendorAccount is true and vendor is danalock

Note

When createVendorAccount is true we will do a number of calls to external APIs. If any of these calls fail we will do our best to revert the changes to a state before you did the call, but certain edge cases may leave you in a state we are not able to automatically fix. We always return error messages on the same format so make sure you log anything unexpected.

Example:
POST https://api.unloc.app/integrators/v1/lock-holders/

{
    "name": "unloc-locks",
    "countryIso": "NO",
    "organizationId": "919424508",
    "organizationIdSuffix": "",
    "createVendorAccount": true,
    "vendor": "danalock",
    "email": "testuser@unloc.app",
    "password": "longsecurepassword"
}

Response

200
Field Optional Type Location Description
id no string body UUID v4. Used as url param in other calls.
name no string body Display name for the lock holder
countryIso no string body ISO 3166-1 alpha-2 country code.
organizationId no string body Nationally unique id for the lock holder. In Norway this is the Organization Id.
organizationIdSuffix no string body Blank if no organizationIdSuffix was supplied.

Example:

{
    "lock-Holder": {
        "id": "5d7c7d59-dd94-4b0e-8df4-501c028e37ea",
        "name": "unloc-locks",
        "countryIso": "NO",
        "organizationId": "919424508",
        "organizationIdSuffix": ""
    }
}

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": "invalidRequest",
    "error_description": "A Lock Holder with this org id and org id suffix already exist"
}