Introduction

Welcome to the Havr API documentation!

This example API documentation page was created with Slate. Feel free to edit it and use it as a base for your own API's documentation.

Authentication

Introduction

It's possible to authenticate using one of the methods below.

When authenticating, an access_token and a refresh_token are retrieved.

After the authentication, each request should use the following header:

["Authorization": "Bearer ACCESS_TOKEN"]

The access_token can be used multiple times. When the validity ends, the server will send back 401 Unauthorized for authenticated requests. At that time, the refresh_token (valid only once), can be used to get a new access_token and refresh_token (alike after a typical authentication).

Get access token with password

{
  "client_id": "mobile_client_id",
  "grant_type": "password",
  "email_or_username": "email",
  "password": "password",
  "user_agent": "android/5.1",
  "uuid": "uuid"
}

{
  "access_token": "access_token",
  "refresh_token": "refresh_token",
  "user_id": "user_id",
  "fresh_user": true
}

Parameter	Type	Required	Description
client_id	string, `ios_client_id`, `android_client_id`, `mobile_client_id`, `web_platform_client_id`, `customer_space_client_id`	yes	Client identifier
grant_type	`password`	yes	Password type
email_or_username	string	yes	Email or username of the user
password	string	yes	Password of the user
user_agent	string	yes	Identifies the requester
uuid	string	yes (for mobile clients only)	Identifies the mobile phone

HTTP request

POST /oauth/v1/token

Errors

`user_agent` is missing:

{
    "error": "Missing parameter (user_agent)."
}

status 400 bad_request

Check user password

Checks if the sent user password is correct. Returns true if it's correct and false if it's not.

{
  "client_id": "mobile_client_id",
  "grant_type": "password",
  "email_or_username": "email",
  "password": "password",
  "user_agent": "android/5.1",
  "uuid": "uuid"
}

HTTP response code

200 ok

{
  "correct_password": true
}

HTTP request

POST /oauth/v1/check_passowrd

Errors

`User` is inactive:

{
    "error": "Account is inactive",
    "error_code": "account_inactive"
}

status 403 forbidden

`uuid` is missing:

{
    "error": "Missing parameter (uuid)."
}

status 400 bad_request

Get access token with refresh_token

{
  "client_id": "mobile_client_id",
  "grant_type": "refresh_token",
  "refresh_token": "refresh_token",
  "user_agent": "android/5.1",
  "uuid": "uuid"
}

{
  "access_token": "access_token",
  "refresh_token": "refresh_token",
  "fresh_user": true
}

Parameter	Type	Required	Description
client_id	string, `ios_client_id`, `android_client_id`, `mobile_client_id` , `web_platform_client_id`, `customer_space_client_id`	yes	Client identifier
grant_type	`refresh_token`	yes	Refresh token type
refresh_token	string	yes	Refresh token of the user
user_agent	string	yes	Identifies the requester
uuid	string	yes (for mobile clients only)	Identifies the mobile phone

HTTP request

POST /oauth/v1/token

Errors

`uuid` is missing:

{
    "error": "Missing parameter (uuid)."
}

status 400 bad_request

Get access token with client_secret

{
  "client_id": "client_id",
  "grant_type": "client_credentials",
  "client_secret": "client_secret",
  "user_agent": "android/5.1"
}

{
  "access_token": "access_token",
  "refresh_token": "refresh_token",
  "user_id": "user_id",
  "fresh_user": true
}

Parameter	Type	Required	Description
client_id	string, `ios_client_id`, `mobile_client_id`, `android_client_id` or `web_platform_client_id`, `customer_space_client_id`	yes	Client identifier
grant_type	`client_credentials`	yes	Client credentials type
client_secret	string	yes	Client secret of the user
user_agent	string	yes	Identifies the requester

HTTP request

POST /oauth/v1/token

Ping

Check token validity.

HTTP request

GET /oauth/v1/ping

Logout

Unvalidates the access token.

HTTP request

GET /oauth/v1/logout

Contacts

Contact object

{
    "id": 5,
    "user_id": 6,
    "user_contact_id": 4,
    "request_status": "accepted"
}

Attribute	Type	Required	Description
id	integer	yes	Identifier of the `contact`
user_id	integer	yes	Identifier of the `contact` owner
user_contact_id	integer	yes	Identifier of the `contact` user
request_status	`accepted`, `pending`, `blocked` or `declined`	yes	Status of the `contact` request

Get own contacts

Returns all the contact relations of the current authenticated user. You are the user of the relation if you sent the contact request. Otherwise, you are user_contact.

The attribute request_status can have different values depending on the status of the contact request : pending if the user_contact still did not answer the request, accepted if he answered positively, declined if he answered negatively and blocked if he marked you as a spam user.

HTTP request

GET /v1/contacts

HTTP response code

200 ok

Response

[Contact]

Get own contacts with last activity

Same as index, but with last lock_log of user

HTTP request

GET /v1/contacts/index_with_activity

HTTP response code

200 ok

Response

[{Contact, "last_activity": LockLog}]

Show specific contact from contact id

HTTP request

GET /v1/contacts/:contact_id

HTTP response code

200 ok

Response

Contact

Errors

`user_contact` does not exist :

{
  "error": "Contact does not exist ",
  "error_code": "contact_does_not_exist"
}

status 404 not_found

`contact` does not belong to current user:

{
  "error": "Can't access anyone else's contact",
  "error_code":"cant_access_another_ones_contact"
}

status 403 forbidden

Show specific contact from user email or username

{
"contact": {
     "email_or_username": "email_or_username"
  }
}

Parameter	Type	Required	Description
email_or_username	string	yes	Username or email of the user we want to get

HTTP request

POST /v1/contacts/contact_from_user

HTTP response code

200 ok

Response

Contact

Errors

Current user is not a contact of the `user_contact`:

{
  "error": "No contacts found",
  "error_code": "no_contacts_found"
}

status 404 not_found

`user_contact` does not exist :

{
  "error": "User does not exist"
}

status 404 not_found

Send a contact request

{
    "contact": {
                "email_or_username": "email_or_username"
            }
}

Parameter	Type	Required	Description
email_or_username	string	yes	Username or email of the user we want to add

Will create a contact item with a request_status attribute set to pending.

If the item already exists and the request_status is set to declined, it will set it to pending and send a new contact request to the user_contact.

HTTP request

POST /v1/contacts

HTTP response code

201 created

Response

Contact

Errors

`user_contact` does not exist :

{
  "error": "User %user_contact_email_or_username% does not exist"
}

status 400 bad_request

Specified `user_contact` is the current user:

{
  "error": "Can't add yourself as contact",
  "error_code": "add_self_as_contact"
}

status 400 bad_request

Current user and specified `user_contact` are already contacts :

{
  "error": "These users are already contacts",
  "error_code": "users_already_contacts"
}

status 403 forbidden

Current user already sent the contact request to the specified `user_contact` :

{
  "error": "The contact request is already pending",
  "error_code": "contact_request_already_pending"
}

status 403 forbidden

`user_contact` blocked the current user :

{
  "error": "User %current_user.username% was blocked by %user_contact.username%"
}

status 403 forbiden

Delete a contact

HTTP request

DELETE /v1/contacts/:contact_id

HTTP response code

204 no_content

Errors

`contact` does not exist:

{
  "error": "Contact does not exist",
  "error_code": "contact_does_not_exist"
}

status 404 not_found

`contact` does not belong to current user:

{
  "error": "Can't access anyone else's contact",
  "error_code": "cant_access_another_ones_contact"
}

status 403 forbidden

Delete a contact from user

{
    "contact": {
                "email_or_username": "email_or_username"
            }
}

Parameter	Type	Required	Description
email_or_username	string	yes	Username or email of the user we want to remove

HTTP request

POST /v1/contacts/delete_from_user

HTTP response code

204 no_content

Errors

Current user is not a contact of the `user_contact`:

{
  "error": "No contacts found",
  "error_code": "no_contacts_found"
}

status 404 not_found

`user_contact` does not exist :

{
  "error": "User does not exist",
  "error_code": "contact_does_not_exist"
}

status 404 not_found

Delete multiple contacts

{
    "contacts": {
      "ids": ["contact_id", "contact_id"]
    }
}

Parameter	Type	Required	Description
ids	integer[]	yes	Identifier of the contacts we want to remove

HTTP request

POST v1/contacts/delete_multiple_contacts

HTTP response code

200 ok

Errors

`contact` does not exist:

{
  "error": "Contact does not exist",
  "error_code": "contact_does_not_exist"
}

status 404 not_found

`contact` does not belong to current user:

{
  "error": "Can't access anyone else's contact",
  "error_code": "cant_access_another_ones_contact"
}

status 403 forbidden

Devices

Device object

{
    "id": 2,
    "name": "device name",
    "device_type": "ios",
    "user_id": 6,
    "uuid": "uuid",
    "device_user_id": 4,
    "fcm_token": "fcm_token",
    "existing_status": "active",
    "created_at": "2018-10-30T08:15:54.122Z",
    "last_connected_at": "2018-10-30T08:15:54.122Z"
}

Attribute	Type	Required	Description
id	integer	yes	Identifier of the `device`
name	string	yes	Name of the `device`
user_id	integer	yes	Identifier of the `device` owner
device_type	`ios` or `android`	yes	Type of the `device`
uuid	string	yes	UUID of the `device`
device_user_id	integer	yes	Identifier of the `device` among the user's devices
fcm_token	string	no	Token of the `device` for Firebase Cloud Messaging
existing_status	`active`, `deleted`	yes	Existing status of the `device`
created_at	string	yes	Creation date of the `device`
last_connected_at	string	yes	Date of the last connection procedure of the `device`

Get own devices

Returns all the devices of the current authenticated user. The attribute device_type should take the ios or android values.

existing_status can be active or deleted.

HTTP request

GET /v1/devices

HTTP response code

200 ok

Response

[Device]

Show specific device

HTTP request

GET /v1/devices/:device_id

existing_status can be active or deleted.

HTTP response code

200 ok

Response

Device

Errors

`device` does not exist :

{
  "error": "Device does not exist",
  "error_code": "device_does_not_exist"
}

status 404 not_found

`device` does not belong to current user :

{
  "error": "Can't access another one's device",
  "error_code": "cant_access_another_ones_device"
}

status 403 forbidden

Check if uuid is already associated to user

{
  "device": {
    "uuid": "uuid"
   }
}

Parameter	Type	Required	Description
uuid	string	yes	UUID of the device

HTTP request

POST /v1/devices/uuid_associated_to_user

HTTP response code

200 ok OR 204 no_content

Response

Device OR "null"

Add a new device

{
  "device": {
    "name": "desired_device_name",
    "uuid": "uuid",
    "device_type": "ios_or_android",
    "fcm_token": "fcm_token"
   }
}

Parameter	Type	Required	Description
name	string	yes	Name of the device
uuid	string	yes	UUID of the device
device_type	`"ios"` or `"android"`	yes	Type of the `device`
fcm_token	string	no	FCM token of the device for Firebase messaging

Will create a device item that belongs to the current user.

HTTP request

POST /v1/devices

HTTP response code

201 created

Response

Device

Errors

`uuid` already associated to User :

{
  "error": "Device already associated to User",
  "error_code": "device_already_associated_to_user"
}

status 400 bad_request

Maximum number of devices is reached for User :

{
  "error": "You have reached the maximum number of devices", 
  "error_code": "maximum_devices_reached"
}

status 403 forbidden

Update a device

{
  "device": {
    "name": "desired_device_name",
    "device_type": "ios_or_android",
    "fcm_token": "fcm_token"
  }
}

Parameter	Type	Required	Description
name	string	no	Name of the device
device_type	`"ios"` or `"android"`	no	Type of the `device`
fcm_token	string	no	FCM token of the device for Firebase messaging

HTTP request

PATCH /v1/devices/:device_id

HTTP response code

200 ok

Response

Device

Errors

`device` does not exist :

{
  "error": "Device does not exist",
  "error_code": "device_does_not_exist"
}

status 404 not_found

`device` does not belong to current user :

{
  "error": "Can't access another one's device",
  "error_code": "cant_access_another_ones_device"
}

status 403 forbidden

Delete a device

HTTP request

DELETE /v1/devices/:device_id

HTTP response code

200 ok

Response

Device

Errors

`device` does not exist :

{
  "error": "Device does not exist",
  "error_code": "device_does_not_exist"
}

status 404 not_found

`device` does not belong to current user :

{
  "error": "Can't access another one's device",
  "error_code": "cant_access_another_ones_device"
}

status 403 forbidden

Check app version

Checks whether an app_version for ios or android is obsolete, latest, if an update is recommended/required for that version and what is the latest version.

 {
   "platform": "android",
   "app_version": "2.5.0"
 }

Parameter	Type	Required	Description
platform	string	yes	Can be `ios` or `android`
app_version	string	yes	Should have A.B.C format where A , B and C are integers

HTTP request

POST /v1/devices/check_app_version

HTTP response code

200 ok

Response

{
  "update_available": true,
  "update_mandatory": false,
  "latest_app_version": "2.5.0"
}

Errors

Invalid sent app version:

{
  "error": "Mobile version is invalid",
  "error_code": "invalid_mobile_version"
}

status 400 bad_request

Door Locks

Door Lock object

{
    "id": 4,
    "lock_serial_number": "lock_serial_number",
    "description": "description of lock",
    "user_id": 6,
    "lisa_token": "AbZ123",
    "existing_status": "active",
    "secondary_type": "main",
    "nb_users": "nb_users",
    "lock_group_id": 34,
    "battery_level": "battery_level",
    "last_k_token_id": "last_k_token_id",
    "mode": "normal"
}

Attribute	Type	Required	Description
id	integer	yes	Identifier of the `door_lock`
lock_serial_number	string	yes	Serial number of the `door_lock`
description	string (less than 40 characters)	yes	Name of the `door_lock`
secondary_type	`main`, `front`, `back`, `garage` or `room`	no	Secondary type of the `door_lock`
user_id	integer	yes	Identifier of the `door_lock` owner
lisa_token	string	yes	Token to identify the lock using lisa
lock_group_id	integer	no	Identifier of the `lock_group`
battery_level	integer	no	Battery level of the `door_lock`
nb_users	integer	no	Number of users that have access to the `door_lock`
existing_status	`active`, `deleted`, `inactive` or `waiting_for_activation`	yes	Existing status of the `door_lock`
last_k_token_id	string	yes	Identifier of the last sync of ktoken for the owner
mode	`normal` or `offline`	no	Indicates whether the lock is offline or not

Firmware Versions	Flash Modes
1 - 7	60 bits prefix + 73 bits data
8 - +	10 bits prefix + 73 bits data

Get own door locks

Returns all the door locks of the current user.

Confirmation level	Description
0	All accesses can be given without confirmation of the owner
1	Only admin accesses have to be confirmed by the owner
2	Only admin and unlimited accesses have to be confirmed by the owner
3	All accesses have to be confirmed by the owner

HTTP request

GET /v1/door_locks

HTTP response code

200 ok

Response

[DoorLock]

Get own door locks with lock groups

Same as index, but with all the lock groups of the user.

HTTP request

GET /v1/door_locks/index_with_lock_groups

HTTP response code

200 ok

Response

"lock_groups" : [LockGroup], "door_locks": [DoorLock]

Show specific door lock

HTTP request

GET /v1/door_locks/:door_lock_id

HTTP response code

200 ok

Response

DoorLock

Errors

`door_lock` does not belong to current user :

{
  "error": "Can't access another one's lock",
  "error_code": "cant_access_another_ones_door_lock"
}

status 403 forbidden

`door_lock` does not exist :

{
  "error": "Door lock does not exist",
  "error_code": "door_lock_does_not_exist"
}

status 404 not_found

`door_lock` access is invalid :

{
  "error": "Lock access is invalid",
  "error_code": "invalid_access"
}

status 403 forbidden

Show specific door lock with lock group

Same as show, but with the lock group of the door_lock.

HTTP request

GET /v1/door_locks/show_with_lock_group/:door_lock_id

HTTP response code

200 ok

Response

"door_lock": DoorLock, "lock_group: LockGroup

Errors

Same as show

Check if serial number is valid

{
  "door_lock": {
    "lock_serial_number": "lock_serial_number"
  }
}

{
  "serial_number_is_valid": true
}

Parameter	Type	Required	Description
lock_serial_number	string	yes	Serial number of the `door_lock`

Checks if the given serial number is connected to an existing door lock, and if this door lock is waiting for activation.

HTTP request

POST /v1/door_locks/serial_number_valid

HTTP response code

200 ok

Get firmware available update for own door locks

Checks if there's a firmware update available for owned door locks.

A specific doorlock id can be passed as an optional parameter to get a specific doorlock update status

HTTP request

GET /v1/door_locks/check_available_update_owned_door_locks or GET /v1/door_locks/check_available_update_owned_door_locks/:door_lock_id

HTTP response code

200 ok

[ 
   {
     "door_lock_id": 5,
     "firmware_available_update": true
   },
   {
     "door_lock_id": 6,
     "firmware_available_update": true
   },
   {
     "door_lock_id": 9,
     "firmware_available_update": false
   } 
]

Errors

`door_lock` does not belong to current user :

{
  "error": "Can't access another one's lock",
  "error_code": "cant_access_another_ones_door_lock"
}

status 403 forbidden

`door_lock` does not exist :

{
  "error": "Door lock does not exist",
  "error_code": "door_lock_does_not_exist"
}

status 404 not_found

Get door lock settings

Get base64 image for qrcode with embedded settings

HTTP request

POST /v1/door_locks/retrieve_settings

HTTP response code

200 ok

Errors

`door_lock` does not belong to current user :

{
  "error": "Can't access another one's lock",
  "error_code": "cant_access_another_ones_door_lock"
}

status 403 forbidden

`door_lock` does not exist :

{
  "error": "Door lock does not exist",
  "error_code": "door_lock_does_not_exist"
}

status 404 not_found

Get door lock configurations

Get lock WiFi credentials (ssid and password)

HTTP request

GET /v1/door_locks/retrieve_lock_configurations

HTTP response code

200 ok

Errors

`door_lock` does not belong to current user :

{
  "error": "Can't access another one's lock",
  "error_code": "cant_access_another_ones_door_lock"
}

status 403 forbidden

`door_lock` does not exist :

{
  "error": "Door lock does not exist",
  "error_code": "door_lock_does_not_exist"
}

status 404 not_found

Check if activation_token is valid

{
  "door_lock": {
    "lock_serial_number": "lock_serial_number",
    "activation_token": "activation_token"
  }
}

{
  "activation_token_is_valid": true
}

Parameter	Type	Required	Description
lock_serial_number	string	yes	Serial number of the `door_lock`
activation_token	string	yes	Activation token of the `door_lock`

Checks if the given activation token is connected to an existing door lock, and if this door lock is waiting for activation.

HTTP request

POST /v1/door_locks/activation_token_valid

HTTP response code

200 ok

Set Installation Start Date

When this service is called , installation_start_date of the door_lock is set to current timestamp.

HTTP request

POST /v1/door_locks/start_installation

HTTP response code

201 no_content

Errors

`door_lock` does not exist :

{
  "error": "Door lock does not exist",
  "error_code": "door_lock_does_not_exist"
}

status 404 not_found

`door_lock` is already installed:

{
  "error": "Door lock is already active",
  "error_code": "door_lock_already_active"
}

status 403 forbidden

Update a door lock

{
"door_lock": {
            "description": "new_description"
        }
}

Parameter	Type	Required	Description
description	string (should not exceed 40 characters)	no	Name of the `door_lock`
secondary_type	`main`, `front`, `back`, `garage` or `room`	no	Secondary type of the `door_lock`

HTTP request

PATCH /v1/door_locks/:door_lock_id

HTTP response code

200 ok

Response

DoorLock

Errors

`door_lock` does not belong to current user :

{
  "error": "Can't access another one's lock",
  "error_code": "cant_access_another_ones_door_lock"
}

status 403 forbidden

`door_lock` does not exist :

{
  "error": "Door lock does not exist",
  "error_code": "door_lock_does_not_exist"
}

status 404 not_found

`description` exceeds 40 characters limit :

{
  "error": "Door lock description length should not exceed 40 characters",
  "error_code": "invalid_lock_description"
}

status 400 bad_request

Transfer ownership of a door lock

{
"door_lock": {
            "door_lock_id": "door_lock_id",
            "user_id": "user_id"
        }
}

Parameter	Type	Required	Description
door_lock_id	integer	yes	Identifer of the `door_lock`
user_id	integer	yes	Identifer of the new `user`

HTTP request

POST /v1/door_locks/owner_transfer

HTTP response code

200 ok

Response

DoorLock

Errors

`door_lock` does not belong to current user :

{
  "error": "Can't access another one's lock",
  "error_code": "cant_access_another_ones_door_lock"
}

status 403 forbidden

`door_lock` does not exist :

{
  "error": "Door lock does not exist",
  "error_code": "door_lock_does_not_exist"
}

status 404 not_found

`user` does not exist :

{
  "error": "User does not exist",
  "error_code": "user_does_not_exist"
}

status 404 not_found

Activate door lock

{
        "door_lock": {
            "lock_serial_number": "qwerty",
            "description": "Fabian Home New",
            "activation_token": "activation_token",
            "lock_group_id": 6
        }
    }

Parameter	Type	Required	Description
lock_serial_number	string	yes	Serial number of the `door_lock`
description	string	yes	Name of the `door_lock`
activation_token	string	yes	Activation token found on documentation of the `door_lock`
secondary_type	`main`, `front`, `back`, `garage` or `room`	no	Secondary type of the `door_lock`
lock_group_id	integer	yes	Identifier of the lock group

Will activate a door lock item.

Default max_users value is 10.

HTTP request

POST /v1/door_locks/activate

HTTP response code

201 created

Response

DoorLock

Errors

`door_lock` does not exist :

{
  "error": "Door lock does not exist",
  "error_code": "door_lock_does_not_exist"
}

status 404 not_found

`door_lock` does not belong to current user :

{
  "error": "Can't access another one's lock",
  "error_code": "cant_access_another_ones_door_lock"
}

status 403 forbidden

`door_lock` does not waiting for activation :

{
  "error": "Door lock is not waiting for activation",
  "error_code": "door_lock_not_waiting_for_activation"
}

status 403 forbidden

`lock_group` is not valid :

{
  "error": "Lock group not found or must be the owner",
  "error_code": "lock_group_not_found_or_must_be_the_owner"
}

status 403 forbidden

Delete a door lock

{
    "user": {
        "password": "user_password"
    }
}

Parameter	Type	Required	Description
password	string	yes	The password of the user account

HTTP request

DELETE /v1/door_locks/:door_lock_id

HTTP response code

204 no_content

Errors

`door_lock` does not exist :

{
  "error": "Door lock does not exist",
  "error_code": "door_lock_does_not_exist"
}

status 404 not_found

`door_lock` does not belong to current user :

{
  "error": "Can't access another one's lock",
  "error_code": "cant_access_another_ones_door_lock"
}

status 403 forbidden

Get K token

{
  "k_token": {
    "door_lock_id": "door_lock_id",
    "p_key": "p_key"
  }
}

{
  "k_token": "encrypted_k_token",
  "last_k_token_id": "last_k_token_id"
}

Parameter	Type	Required	Description
door_lock_id	integer	yes	Identifier of the door lock
p_key	string	yes	RSA public key - 2048

Resets your k token sent to unlock the door.

HTTP request

POST /v1/door_locks/get_k_token

HTTP response code

200 ok

Errors

`door_lock` does not exist :

{
  "error": "Door lock does not exist",
  "error_code": "door_lock_does_not_exist"
}

status 404 not_found

`door_lock` does not belong to current user :

{
  "error": "Can't access another one's lock",
  "error_code": "cant_access_another_ones_door_lock"
}

status 403 forbidden

`p_key` is missing :

{
  "error": "Error generating k token",
  "error_code": "generating_k_token"
}

status 400 bad_request

Get K tokens

{
  "door_lock_ids": ["door_lock_id_1", "door_lock_id_2"]
}

{
  "door_locks": {
    "door_lock_id_1": {
      "k_token": "k_token",
      "last_k_token_id": "last_k_token_id"
    },
    "door_lock_id_2": {
      "k_token": "k_token",
      "last_k_token_id": "last_k_token_id"
    }
  }
}

Parameter	Type	Required	Description
door_lock_ids	integer[]	yes	Identifier of the door locks

Resets your k token sent to unlock the door.

HTTP request

POST /v1/door_locks/get_k_tokens

HTTP response code

200 ok

Errors

`door_lock` does not exist :

{
  "error": "Door lock does not exist",
  "error_code": "door_lock_does_not_exist"
}

status 404 not_found

`door_lock` does not belong to current user :

{
  "error": "Can't access another one's lock",
  "error_code": "cant_access_another_ones_door_lock"
}

status 403 forbidden

Add locks to group

{
    "group_id": "lock_group_id",
    "locks": [1, 3]
}

Parameter	Type	Required	Description
group_id	integer	yes	Identifier of the lock group
locks	[integer]	yes	Identifiers of the locks contained in the lock group

HTTP request

POST /v1/door_locks/add_locks_to_group

HTTP response code

200 ok

Response

LockGroup

Errors

`lock_group_id` does not exist or the user is not the owner:

{
  "error": "Lock group not found or you must be the owner",
  "error_code": "lock_group_not_found_or_must_be_the_owner"
}

status 404 not_found

`door_lock` is already member of the group:

{
  "error": "Door lock is already member of the group",
  "error_code": "door_lock_already_in_group"
}

status 400 bad_request

`door_lock` does not exist:

{
  "error": "Door lock does not exist",
  "error_code": "door_lock_does_not_exist"
}

status 400 bad_request

Get door lock status from lock serial number

{
    "door_lock": {
      "lock_serial_number": "lock_serial_number"
    }
}

{
  "door_lock": {
    "existing_status": "inactive",
    "id": 2,
    "mode": "offline"
  }

}

Parameter	Type	Required	Description
lock_serial_number	string	yes	Lock serial number of door lock

HTTP request

POST /v1/door_locks/retrieve_status_from_serial_number

HTTP response code

200 ok

Errors

`lock_serial_number` does not exist:

{
  "error": "Door lock does not exist",
  "error_code": "door_lock_does_not_exist"
}

status 404 not_found

Get door lock statuses

{
  "door_lock_id_1": {
    "description": "my lock",
    "status": "no_info"
  },
  "door_lock_id_2":  {
    "description": "best lock",
    "status": "alert",
    "lock_log": {
      LockLog,
      "user_id": null  
    },
  },
  "door_lock_id_3":  {
    "description": "here & there",
    "status": "locked",
    "lock_log": {
      LockLog,
      "user_id": null
    }
  },
  "door_lock_id_4":  {
    "description": "I am number 4",
    "status": "locked",
    "lock_log": {
      LockLog,
      "user": User
    }
  }
}

For all the user locks (owned, active shared key), the status is returned. Multiple situations are possible:

door_lock_id_1 : no info (not any log from the lock)
door_lock_id_2 : alert, the lock log does not have any user
door_lock_id_3 : autolock (locked, unlocked), the user is null
door_lock_id_4 : user action (locked, unlocked), the user is not null

Attribute	Type	Description
description	String	`description` attribute of DoorLock model
status	String	Identifies the current status of the door lock. Possible value are the one of `LockLog.door_lock_status` plus `no_info` when no log has been registered yet
lock_log	LockLog	Last log received for the door lock. Can contain a user object according to specified cases above

HTTP request

GET /v1/door_locks/door_lock_status

HTTP response code

200 ok

Get offline mode flashing payload

{
  "payload": "010101010101010101010101010101010101010101010101010101010101010101010101010101010101010101"
}

For an offline lock, that route send the payload needed to flash the lock. Must be the owner of the lock or have an active access when doing the request.

HTTP request

GET /v1/door_locks/retrieve_offline_flash_payload/:door_lock_id

HTTP response code

200 ok

Errors

`door_lock_id` does not exist:

{
  "error": "Door lock does not exist",
  "error_code": "door_lock_does_not_exist"
}

status 404 not_found

have no access to the lock:

{
  "error": "Can't access another one's lock",
  "error_code": "cant_access_another_ones_door_lock"
}

the access is not valid at the time of the request:

{
  "error": "CLock access is invalid",
  "error_code": "invalid_access"
}

status 403 forbidden

the door lock is not configure as offline:

{
  "error": "Door lock is not in offline mode",
  "error_code": "door_lock_is_not_offline"
}

status 40 bad_request

EniqLockSharedKeyData

EniqLockSharedKeyData object

{
    "id": 2,
    "wallet_id": "000000000000000000001A2B3C4D5E60",
    "wallet_key": "000000000000000000001A2B3C4D5E60",
    "badge_id": "000000001A2B3C4D5E60",
    "existing_status": "active",
    "created_at": "2018-10-30T08:15:54.122Z",
    "updated_at": "2018-10-30T08:15:54.122Z"
}

Attribute	Type	Required	Description
id	integer	yes	Identifier of the `EniqLockSharedKeyData`
wallet_id	hex_string[32]	yes	Waller identifier of the `EniqLockSharedKeyData`
wallet_key	hex_string[32]	yes	Wallet key of the `EniqLockSharedKeyData`
badge_id	hex_string[20]	yes	Badge identifier of the `EniqLockSharedKeyData`
existing_status	`active`, `deleted`	yes	Existing status of the `EniqLockSharedKeyData`
created_at	string	yes	Creation date of the `EniqLockSharedKeyData`
updated_at	string	yes	Last update date of the `EniqLockSharedKeyData`

Get own EniqLockSharedKeyData

Returns all the EniqLockSharedKeyData of the current authenticated user. They are deduced from the SharedKey the user has on EniqLocks. When the use is the owner and has no SharedKey, record are created dynamically.

existing_status can be active or deleted.

HTTP request

GET /v1/eniq_lock_shared_key_data

HTTP response code

200 ok

Response

[EniqLockSharedKeyData]

Show specific EniqLockSharedKeyData

HTTP request

GET /v1/eniq_lock_shared_key_data/:eniq_lock_shared_key_data_id

existing_status can be active or deleted.

HTTP response code

200 ok

Response

EniqLockSharedKeyData

Errors

`eniq_lock_shared_key_data` does not exist or the user is not the owner of the associated SharedKey :

{
  "error_code": "eniq_lock_shared_key_data_does_not_exist"
}

status 403 forbidden

Floor map groups

FloorMapGroup object

{
    "id": 1,
    "user_id": 6,
    "name": "my building"
}

Attribute	Type	Required	Description
id	integer	yes	Identifier of the `FloorMapGroup`
name	string	yes	Description of the group
user_id	integer	yes	Identifier of the `FloorMapGroup` owner

A floor map group has associated floor maps.

Get all floor map groups

Returns all the floor map groups of the current user.

HTTP request

GET /v1/floor_map_groups

HTTP response code

200 ok

Response

[FloorMapGroup]

Show specific floor map group

HTTP request

GET /v1/floor_map_groups/:floor_map_group_id

HTTP response code

200 ok

Response

FloorMapGroup

Errors

`floor_map_group_id` does not exist :

{
  "error": "Floor map group does not exist",
  "error_code": "floor_map_group_does_not_exist"
}

status 404 not_found

Show floor map group with floor maps

Shows floor maps of the group with the picture file.

HTTP request

GET /v1/floor_map_groups/show_with_floor_maps

HTTP response code

200 ok

Response

{FloorMapGroup, floor_maps: [FloorMap]}

Errors

`floor_map_group_id` does not exist :

{
  "error": "Floor map group does not exist",
  "error_code": "floor_map_group_does_not_exist"
}

status 404 not_found

Show floor map group with floor maps with picture files

Shows floor maps of the group with the picture file.

HTTP request

GET /v1/floor_map_groups/show_with_floor_maps_with_file

HTTP response code

200 ok

Response

{FloorMapGroup, floor_maps: [FloorMap]}

with floor_map: FloorMapModel and its base64_picture, file_extension, picture_url attributes

Errors

`floor_map_group_id` does not exist :

{
  "error": "Floor map group does not exist",
  "error_code": "floor_map_group_does_not_exist"
}

status 404 not_found

Create a new floor map group

{
    "floor_map_group": {
        "name": "my building"
    }
}

Parameter	Type	Required	Description
name	string	yes	Description of the group

Will create a floor map group item.

HTTP request

POST /v1/floor_map_groups

HTTP response code

201 created

Response

FloorMapGroup

Update a floor map group

{
    "floor_map_group": {
        "name": "my building"
    }
}

Parameter	Type	Required	Description
name	string	yes	Description of the group

Will update a floor map group item.

HTTP request

PATCH /v1/floor_map_groups/floor_map_group_id

HTTP response code

200 ok

Response

FloorMapGroup

Errors

`floor_map_group_id` does not exist :

{
  "error": "Floor map group does not exist",
  "error_code": "floor_map_group_does_not_exist"
}

status 404 not_found

Delete a floor map group

HTTP request

DELETE /v1/floor_map_groups/:floor_map_group_id

HTTP response code

204 no_content

Errors

`floor_map_group_id` does not exist :

{
  "error": "Floor map group does not exist",
  "error_code": "floor_map_group_does_not_exist"
}

status 404 not_found

Floor map positions

Floor Map Position object

{
    "id": 1,
    "floor_map_id": 1,
    "door_lock_id": 2,
    "x": 0.0,
    "y": 100
}

Attribute	Type	Required	Description
id	integer	yes	Identifier of the `FloorMapPosition`
floor_map_id	bigint	yes	Identifier of the `FloorMap` the `FloorMapPosition` is part of
door_lock_id	bigint	yes	Identifier of the `DoorLock` position on the `FloorMap`
x	float	yes	Position in percent of the pin's map on the x axis
y	float	yes	Position in percent of the pin's map on the y axis

Get all floor map positions

Returns all the floor map positions of the current user (for all his active FloorMap).

HTTP request

GET /v1/floor_map_positions

HTTP response code

200 ok

Response

[FloorMapPosition]

Show a specific floor map position

HTTP request

GET /v1/floor_map_positions/:floor_map_position_id

HTTP response code

200 ok

Response

FloorMapPosition

Errors

`floor_map_position_id` does not exist or must be the owner :

{
  "error": "FloorMapPosition does not exist or must be the owner",
  "error_code": "floor_map_position_does_not_exist_or_must_be_the_owner"
}

status 404 not_found

Create a new floor map position

{
    "floor_map_position": {
        "floor_map_id": 1,
        "door_lock_id": 2,
        "x": 0.0,
        "y": 100
    }
}

Parameter	Type	Required	Description
floor_map_id	bigint	yes	Identifier of the `FloorMap` the `FloorMapPosition` is part of. Must be the owner of the `FloorMap`
door_lock_id	bigint	yes	Identifier of the `DoorLock` position on the `FloorMap`. Must be the owner of the `DoorLock`
x	float	yes	Position in percent of the pin's map on the x axis
y	float	yes	Position in percent of the pin's map on the y axis

Will create a floor map position record.

HTTP request

POST /v1/floor_map_positions

HTTP response code

201 created

Response

FloorMapPosition

Bulk create floor map positions

{
    "floor_map_positions": [{
        "floor_map_id": 1,
        "door_lock_id": 2,
        "x": 0.0,
        "y": 100
    },{
      "floor_map_id": 1,
      "door_lock_id": 3,
      "x": 50,
      "y": 50
    }]
}

Parameter	Type	Required	Description
floor_map_id	bigint	yes	Identifier of the `FloorMap` the `FloorMapPosition` is part of. Must be the owner of the `FloorMap`
door_lock_id	bigint	yes	Identifier of the `DoorLock` position on the `FloorMap`. Must be the owner of the `DoorLock`
x	float	yes	Position in percent of the pin's map on the x axis
y	float	yes	Position in percent of the pin's map on the y axis

Will create multiple floor map position records.

HTTP request

POST /v1/floor_map_positions/bulk_create

HTTP response code

201 created

Response

[FloorMapPosition]

Update a floor map position

{
    "floor_map_position": {
        "floor_map_id": 1,
        "door_lock_id": 2,
        "x": 0.0,
        "y": 100
    }
}

Parameter	Type	Required	Description
floor_map_id	bigint	no	Identifier of the `FloorMap` the `FloorMapPosition` is part of. Must be the owner of the `FloorMap`
door_lock_id	bigint	no	Identifier of the `DoorLock` position on the `FloorMap`. Must be the owner of the `DoorLock`
x	float	no	Position in percent of the pin's map on the x axis
y	float	no	Position in percent of the pin's map on the y axis

Will update a floor map position record.

HTTP request

PATCH /v1/floor_map_positions/floor_map_position_id

HTTP response code

200 ok

Response

FloorMapPosition

Errors

`floor_map_position_id` does not exist or must be the owner :

{
  "error": "FloorMapPosition does not exist or must be the owner",
  "error_code": "floor_map_position_does_not_exist_or_must_be_the_owner"
}

Delete a floor map position

HTTP request

DELETE /v1/floor_map_positions/:floor_map_position_id

HTTP response code

204 no_content

Errors

`floor_map_position_id` does not exist or must be the owner :

{
  "error": "FloorMapPosition does not exist or must be the owner",
  "error_code": "floor_map_position_does_not_exist_or_must_be_the_owner"
}

Floor maps

FloorMap object

{
    "id": 1,
    "floor_map_group_id": 6,
    "name": "my building",
    "file_extension": "png",
    "picture_url": "pictures/floor_map/eef477e129cbe2509d90c3aba4b5e808eef477e129cbe2509d90c3aba4b5e808.png"
}

Attribute	Type	Required	Description
id	integer	yes	Identifier of the `FloorMap`
name	string	yes	Description of the group
floor_map_group_id	integer	yes	Identifier of the `FloorMapGroup`
file_extension	string	maybe	extension of the base64 file
picture_url	string	maybe	Url to download the profile picture of the user, check with the admin for the endpoint

A floor map is associated to a floor map group.

Get all floor map

Returns all the floor maps of the current user.

HTTP request

GET /v1/floor_maps

HTTP response code

200 ok

Response

[FloorMap]

Show specific floor map

HTTP request

GET /v1/floor_maps/:floor_map_id

HTTP response code

200 ok

Response

FloorMap

Errors

`floor_map_id` does not exist :

{
  "error": "Floor map does not exist",
  "error_code": "floor_map_does_not_exist"
}

status 404 not_found

Show floor map with picture files

Shows floor map with the picture file.

HTTP request

GET /v1/floor_maps/show_with_file/:floor_map_id

HTTP response code

200 ok

Response

FloorMap

with base64_picture attribute

Errors

`floor_map_id` does not exist :

{
  "error": "Floor map does not exist",
  "error_code": "floor_map_does_not_exist"
}

status 404 not_found

Create a new floor map

{
    "floor_map_group": {
        "name": "my building",
        "floor_map_group_id": 5,
        "file_extension": "png",
        "base64_picture": "4RiDRXhpZgAATU0AKgA..."
    }
}

Parameter	Type	Required	Description
name	string	yes	Description of the group
floor_map_group_id	integer	yes	Identifier of the `FloorMapGroup`
file_extension	string	yes	extension of the base54 file, should be `png`, `jpg` or `jpeg`
base64_picture	string	yes	map file base64 encoded

Will create a floor map item.

HTTP request

POST /v1/floor_maps

HTTP response code

201 created

Response

FloorMap

Errors

`file_extension` is not valid :

{
  "error": "The extension of the picture is invalid",
  "error_code": "invalid_picture_extension"
}

status 400 bad_request

Update a floor map

{
    "floor_map_group": {
        "name": "my building",
        "floor_map_group_id": 5,
        "file_extension": "png",
        "base64_picture": "4RiDRXhpZgAATU0AKgA..."
    }
}

Parameter	Type	Required	Description
name	string	yes	Description of the group
floor_map_group_id	integer	yes	Identifier of the `FloorMapGroup`
file_extension	string	yes	extension of the base54 file, should be `png`, `jpg` or `jpeg`
base64_picture	string	yes	map file base64 encoded

Will update a floor map item.

HTTP request

PATCH /v1/floor_maps/:floor_map_id

HTTP response code

200 ok

Response

FloorMap

Errors

`floor_map_id` does not exist :

{
  "error": "Floor map does not exist",
  "error_code": "floor_map_does_not_exist"
}

status 404 not_found

`file_extension` is not valid :

{
  "error": "The extension of the picture is invalid",
  "error_code": "invalid_picture_extension"
}

status 400 bad_request

Delete a floor map

HTTP request

DELETE /v1/floor_maps/:floor_map_id

HTTP response code

204 no_content

Errors

`floor_map_id` does not exist :

{
  "error": "Floor map does not exist",
  "error_code": "floor_map_does_not_exist"
}

status 404 not_found

Lock groups

Lock Group object

{
    "id": "lock_group_id",
    "user_id": "owner_id",
    "description": "a group",
    "sub_groups": [],
    "lock_group_id": "parent_lock_group_id",
    "lock_group_type": "personal",
    "icon": "icon_code",
    "address_street":  "99, rue de Rivoli",
    "address_city": "Paris",
    "address_country": "France",
    "zip_code": "75000"
}

Attribute	Type	Required	Description
id	integer	yes	Identifier of the `lock_group`
user_id	integer	yes	Identifier of the `lock_group` owner
lock_group_type	`personal` or `business`	yes, default is `personal`	Type of the `lock_group`
description	string	yes	Name description of the `lock_group`
sub_groups	[integer]	no	Identifiers of the lock groups contained in the `lock_group`
lock_group_id	integer	no	Identifier of the optional parent group
icon	string	no, default is `default`	Icon code for the lock group
address_street	string	no, default is ``	Building & street description of the lock group address
address_city	string	no, default is ``	City of the lock group address
address_country	string	no, default is ``	Country of the lock group address
zip_code	string	no, default is ``	Zip code of the lock group address

Get all lock groups owned by the user

HTTP request

GET /v1/lock_groups

HTTP response code

200 ok

Response

[LockGroup]

Get lock group details

HTTP request

GET /v1/lock_groups/lock_group_id

HTTP response code

200 ok

Response

LockGroup

Errors

`lock_group_id` does not exist :

{
  "error": "Lock group not found or you must be the owner",
  "error_code": "lock_group_not_found_or_must_be_the_owner"
}

status 404 not_found

Get lock group info (if not owner, but has access)

{
  "id": "lock_group_id",
  "description": "lock_group_description",
  "user_id":  6,
  "lock_group_id": "parent_group_id",
  "icon": "default",
  "address_street":  "99, rue de Rivoli",
  "address_city": "Paris",
  "address_country": "France",
  "zip_code": "75000",
  "parent_lock_group": {
     "id": "lock_group_id",
     "description": "parent_group_description",
     "user_id": 6,
     "lock_group_id": null
  }
}

HTTP request

GET /v1/lock_groups/lock_group_info/lock_group_id

HTTP response code

200 ok

Errors

`lock_group_id` does not exist :

{
  "error": "Lock group not found or you must have access",
  "error_code": "lock_group_not_found_or_must_have_access"
}

status 404 not_found

Get lock groups info (if not owner but has access)

{
  "lock_group": {
      "ids": [1, 2, 3]
    }
}

Parameter	Type	Required	Description
ids	int[]	yes	List of lock group ids to be retrieved

[{
  "id": "lock_group_id",
  "description": "lock_group_description",
  "user_id":  6,
  "lock_group_id": "parent_group_id",
  "icon": "default",
  "address_street":  "99, rue de Rivoli",
  "address_city": "Paris",
  "address_country": "France",
  "zip_code": "75000",
  "parent_lock_group": {
     "id": "lock_group_id",
     "description": "parent_group_description",
     "user_id": 6,
     "lock_group_id": null,
     "icon": "default"
  }
}]

HTTP request

POST /v1/lock_groups/lock_groups_info

HTTP response code

200 ok

{
  "lock_group": {
      "token": "token",
      "lock_group_id": "lock_group_id"
    }
}

Parameter	Type	Required	Description
token	string	yes	Token string received from link
lock_group_id	integer	yes	Identifier of the `lock_group`

{
  "id": "lock_group_id",
  "description": "lock_group_description",
  "user_id":  6,
  "lock_group_id": "parent_group_id",
  "locks": [23, 46],
  "lock_group_type": "personal",
  "icon": "default",
  "address_street":  "99, rue de Rivoli",
  "address_city": "Paris",
  "address_country": "France",
  "zip_code": "75000",
  "parent_lock_group": {
     "id": "lock_group_id",
     "description": "parent_group_description",
     "user_id": 6,
     "lock_group_type": "personal",
     "lock_group_id": null,
     "icon": "default"
  }
}

HTTP request

POST /v1/lock_groups/lock_group_info_from_token/

HTTP response code

200 ok

Errors

`lock_group_id` does not exist or token is invalid:

{
  "error": "Lock group not found or you must have access",
  "error_code": "lock_group_not_found_or_must_have_access"
}

status 404 not_found

Create a lock group

{
  "lock_group": {
      "description": "new group",
      "icon": "default",
      "sub_groups": [],
      "lock_group_id": "parent_lock_group_id",
      "address_street":  "99, rue de Rivoli",
      "address_city": "Paris",
      "address_country": "France",
      "zip_code": "75000"
    }
}

Parameter	Type	Required	Description
description	string	yes	Name of the lock group
icon	string	no	Icon of the lock group
sub_groups	[integer]	no	Identifiers of the lock groups contained in the lock group
lock_group_id	integer	no	Identifier of the optional parent group
address_street	string	no	Street for the address
address_city	string	no	City for the address
address_country	string	no	Country for the address
zip_code	string	no	Zip code for the address

HTTP request

POST /v1/lock_groups

HTTP response code

201 created

Response

LockGroup

Errors

`lock_group_id` does not exist or is not owned by the current user:

{
  "error": "Lock group not found or must be the owner",
  "error_code": "lock_group_not_found_or_must_be_the_owner"
}

status 400 bad_request

Patch a lock group

{
  "lock_group": {
      "description": "update group",
      "icon": "default",
      "sub_groups": [],
      "lock_group_id": "parent_lock_group_id",
      "address_street":  "99, rue de Rivoli",
      "address_city": "Paris",
      "address_country": "France",
      "zip_code": "75000"
    }
}

Parameter	Type	Required	Description
description	string	no	Name of the lock group
icon	string	no	Icon of the lock group
sub_groups	[integer]	no	Identifiers of the lock groups contained in the lock group
lock_group_id	integer	no	Identifier of the optional parent group
address_street	string	no	Street for the address
address_city	string	no	City for the address
address_country	string	no	Country for the address
zip_code	string	no	Zip code for the address

HTTP request

PATCH /v1/lock_groups/lock_group_id

HTTP response code

200 ok

Response

LockGroup

Errors

`lock_group_id` does not exist or is not owner by the current user:

{
  "error": "Lock group not found or must be the owner",
  "error_code": "lock_group_not_found_or_must_be_the_owner"
}

status 400 bad_request

Delete a lock group

HTTP request

DELETE /v1/lock_groups/lock_group_id

HTTP response code

204 no_content

Errors

`lock_group_id` does not exist or the user is not the owner:

{
  "error": "Lock group not found or must be the owner",
  "error_code": "lock_group_not_found_or_must_be_the_owner"
}

status 404 not_found

`lock_group` is not empty:

{
  "error": "Lock group is not empty",
  "error_code": "lock_group_is_not_empty"
}

status 403 forbidden

Lock logs

Lock Log object

{
    "id": 1,
    "user_id": 6,
    "door_lock_id": 1,
    "device_id": 2,
    "door_lock_status": "locked",
    "alert": "security_alert",
    "event_timestamp": "2018-10-30T08:15:54.122Z",
    "log_type": "flash"
}

Attribute	Type	Required	Description
id	integer	yes	Identifier of the `lock_log`
user_id	integer	no	Identifier of the `lock_log` owner
door_lock_id	integer	yes	Identifier of the `door_lock`
device_id	integer	yes	Identifier of the `device`
door_lock_status	`locked`, `unlocked` or `alert`	yes	Status of the `door_lock`
alert_code	string	no	Detail string of the alert
event_timestamp	string	yes	Datetime of the event
log_type	string	yes	Means used to do the lock action

Get own lock logs

Returns all the lock logs of the current user.

HTTP request

GET /v1/lock_logs

HTTP response code

200 ok

Show specific door lock logs

{ 
  "door_lock": {
    "door_lock_id": "door_lock_id"
   }
}

Parameter	Type	Required	Description
door_lock_id	integer	yes	Identifier of the door lock

Shows all the logs of a specific door lock.

HTTP request

POST /v1/lock_logs/door_lock_detail

HTTP response code

200 ok

Response

[LockLog]

Errors :

`door_lock` does not belong to current user

{
  "error": "Can't access another one's lock",
  "error_code": "cant_access_another_ones_door_lock"
}

status 403 forbidden

`door_lock` does not exist :

{
  "error": "Door lock does not exist",
  "error_code": "door_lock_does_not_exist"
}

status 404 not_found

Show specific user logs

{ 
  "user": {
    "user_id": "user_id"
   }
}

Parameter	Type	Required	Description
user_id	integer	yes	Identifier of the user

Shows all the logs of a specific user with administrated door locks.

HTTP request

POST /v1/lock_logs/user_detail

HTTP response code

200 ok

Response

[LockLog]

Errors :

`user` does not exist :

{
  "error": "User does not exist",
  "error_code": "user_does_not_exist"
}

status 404 not_found

Get lock activity by date

{ 
    "start_date": "2017-03-14T17:00:00Z",
    "end_date": "2018-03-14T17:00:00Z"
}

Parameter	Type	Required	Description
start_date	date iso8601	no	lock logs since start_date
end_date	date iso8601	no	lock logs until end_date

Shows all the logs of user of owned and administrated door locks.

HTTP request

POST /v1/lock_logs/door_lock_activity

HTTP response code

200 ok

Response

[LockLog]

[
    {
        "id": 5,
        "door_lock_id": 1,
        "door_lock_status": "locked",
        "log_type": "flash",
        "event_timestamp": "2007-01-01T00:00:00.000Z"
    },
    {
        "id": 4,
        "door_lock_id": 2,
        "door_lock_status": "unlocked",
        "log_type": "flash",
        "event_timestamp": "2008-01-01T00:00:00.000Z"
    },
    {
        "id": 2,
        "door_lock_id": 5,
        "door_lock_status": "locked",
        "log_type": "auto",
        "event_timestamp": "2018-01-01T00:00:00.000Z"
    }
]

Errors :

`date` does not have a valid format :

{
  "error": "Invalid date format: should be UTC: ISO8601",
  "error_code": "invalid_date_format"
}

status 404 not_found

Get building last activity

{ 
  "lock_group": {
    "lock_group_id": "lock_group_id"
   }
}

Parameter	Type	Required	Description
lock_group_id	integer	yes	Identifier of the building

Shows the last activity of all locks within the specified lock group.

HTTP request

POST /v1/lock_logs/lock_group_last_activity

HTTP response code

200 ok

Response

[
    {
        "door_lock_id": 1,
        "last_activity": "[LockLog]"
    },
    {
        "door_lock_id": 2,
        "last_activity": "[LockLog]"
    },
    {
        "door_lock_id": 5,
        "last_activity": "[LockLog]"
    }
]

Errors :

`lock_group` does not exist :

{
  "error": "Lock group not found or must have access",
  "error_code": "lock_group_not_found_or_must_have_access"
}

status 404 not_found

Locks

Lock object

{
    "id": 2,
    "description": "My house",
    "user_id": 10,
    "lock_group_id": 11,
    "existing_status": "active",
    "created_at": "2018-10-30T08:15:54.122Z",
    "updated_at": "2018-10-30T08:15:54.122Z"
}

Attribute	Type	Required	Description
id	integer	yes	Identifier of the `Lock`
description	string	yes	Description of the `Lock`
user_id	integer	yes	User identifier of the owner of the `Lock`
lock_group_id	integer	yes	Lock group identifier of the `Lock`
existing_status	`active`, `deleted`	yes	Existing status of the `Lock`
created_at	string	yes	Creation date of the `Lock`
updated_at	string	yes	Last update date of the `Lock`

Get own Lock

Returns all the Lock of the current authenticated user. They are deduced from the SharedKey the user has on those Locks.

existing_status can be active or deleted.

HTTP request

GET /v1/locks

HTTP response code

200 ok

Response

[Lock]

Show specific Lock

HTTP request

GET /v1/locks/:lock_id

existing_status can be active or deleted.

HTTP response code

200 ok

Response

Lock

Errors

`lock` does not exist or the user is not not related with a SharedKey :

{
  "error_code": "lock_does_not_exist"
}

status 403 forbidden

Lock Configurations

Lock Configuration object

{
    "id": 1,
    "door_lock_id": 1,
    "wifi_ssid": "A wifi name",
    "wifi_password": "toto-Tata",
    "bold_time": "5",
    "ssid_last_updated_at": "2018-10-30T08:15:54.122Z",
    "bolt_last_updated_at": "2018-10-30T08:15:54.122Z",
    "auto_locking_timer": 5,
    "auto_locking_last_updated_at": "2018-10-30T08:15:54.122Z",
    "scheduled_locking_enabled": true,
    "scheduled_locking_start": 3600,
    "scheduled_locking_duration": 7200,
    "scheduled_locking_delay": 10
}

Attribute	Type	Required	Description
id	integer	no	Identifier of the `lock_config`
door_lock_id	integer	yes (if it's a user's log)	Identifier of the `door_lock` to which belongs the lock configuration
wifi_ssid	string	The lock's wifi ssid
wifi_password	string	yes	The lock's wifi password of flash
bold_time	integer (between 1 and 10 )	yes	the bolt golding time of the lock
auto_locking_timer	integer (between 2 and 30 and default is 5s )	no	auto locking timer of the lock
ssid_last_updated_at	string	no	Datetime of the last time the `wifi_ssid` update event occured
bolt_last_updated_at	string	no	Datetime of the last time the `bolt_Time` update event occured
auto_locking_last_updated_at	string	no	Datetime of the last time the `auto_locking_timer` update event occured
scheduled_locking_enabled	boolean	no	Flag to activate the scheduled locking feature on the brightlock
scheduled_locking_start	int	no	Number of seconds since midnight that represent the beginning of the time period the scheduled locking feature is active, can't be more than 606024
scheduled_locking_duration	int	no	Number of seconds the scheduled locking feature will be active, can't be less than 6060 & more than 6060*24 - 1
scheduled_locking_delay	int	no	Number of seconds the lock will wait after an opening before triggering the closing action. Must be between 5 and 300

Get own lock configurations

Returns all the lock configurations of locks owned/administred by the current user.

HTTP request

GET /v1/lock_configurations

HTTP response code

200 ok

Show specific lock configuration

HTTP request

GET /v1/lock_configurations/:id

HTTP response code

200 ok

Response

[LockConfiguration]

Errors

`LockConfiguration` does not exist :

{
  "error": "lock configuration does not exist",
  "error_code": "lock_config_does_not_exist"
}

status 404 not_found

Update a lock configuration

{
  "lock_configuration": {
    "wifi_ssid": "new name"
  }
}

HTTP request

PATCH /v1/lock_configurations/:id

HTTP response code

200 ok

Response

[LockConfiguration]

Errors

`door_lock` does not exist :

{
  "error": "Door lock does not exist",
  "error_code": "door_lock_does_not_exist"
}

status 404 not_found

`lock_configuration` does not exist :

{
  "error": "Lock configuration does not exist",
  "error_code": "lock_config_does_not_exist"
}

status 404 not_found

`door_lock` does not belong to current user :

{
  "error": "Can't access another one's door lock",
  "error_code": "cant_access_another_ones_door_lock"
}

status 403 forbidden

Update multiple lock Configurations

If you want to send multiple lock configurations logs , you should send :

{
   "lock_configurations": [
                  {
                      "door_lock_id": 2,
                      "bolt_time": 5
                  },
                  {
                      "door_lock_id": 4,
                      "wifi_password": "titi-Toto",
                      "wifi_ssid": "An amazing Wifi network"
                  }
      ]
}

HTTP request

POST /v1/lock_configurations/update_multiple_lock_configs

HTTP response code

200 ok

Response

[LockConfigurations]

Errors

`door_lock` does not exist :

{
  "error": "Door lock does not exist",
  "error_code": "door_lock_does_not_exist"
}

status 404 not_found

`lock_configuration` does not exist :

{
  "error": "Lock configuration does not exist",
  "error_code": "lock_config_does_not_exist"
}

status 404 not_found

`door_lock` does not belong to current user :

{
  "error": "Can't access another one's door lock",
  "error_code": "cant_access_another_ones_door_lock"
}

status 403 forbidden

Lock Preferences

Lock Preference object

{
  "id": 1,
  "user_id": 32,
  "door_lock_id": 13,
  "existing_status": "active",
  "flash_lock_temp": ["none"], 
  "flash_unlock_temp": ["none"],
  "flash_lock_user": ["none"],
  "flash_unlock_user": ["none"], 
  "flash_lock_admin": ["none"],
  "flash_unlock_admin": ["none"],
  "auto_lock": ["none"], 
  "auto_unlock": ["none"],
  "manual_lock": ["none"], 
  "manual_unlock": ["none"],
  "new_user_access": ["none"],
  "new_admin_access": ["none"], 
  "access_update": ["none"], 
  "access_delete": ["push", "email"],
  "battery_critical": ["push"],
  "battery_warning": ["email"]
}

Attribute	Type	Required	Description
id	integer	no	Identifier of the `lock_preference`
door_lock_id	integer	no	Identifier of the `door_lock` to which belongs the lock preference
flash_lock_temp	string[]	no	Notification preferences for temp users flash locking
flash_unlock_temp	string[]	no	Notification preferences for temp users flash unlocking
flash_lock_user	string[]	no	Notification preferences for users flash locking
flash_unlock_user	string[]	no	Notification preferences for users flash unlocking
flash_lock_admin	string[]	no	Notification preferences for admins flash locking
flash_unlock_admin	string[]	no	Notification preferences for admins flash unlocking
auto_lock	string[]	no	Notification preferences for auto locking
auto_unlock	string[]	no	Notification preferences for auto unlocking
new_user_access	string[]	no	Notification preferences for a new user access creation of an owned/administered lock
new_admin_access	string[]	no	Notification preferences for a new admin access creation of an owned/administered lock
access_update	string[]	no	Notification preferences for a modification of an access
access_delete	string[]	no	Notification preferences for a removal of an access
battery_warning	string[]	no	Notification preferences when a lock battery level is under 20%
battery_critical	string[]	no	Notification preferences when a lock battery level is under 10%

Get own lock preferences

Returns all the lock preferences of locks owned/administered by the current user.

HTTP request

GET /v1/lock_preferences

HTTP response code

200 ok

Show specific lock preference

HTTP request

GET /v1/lock_preferences/:id

HTTP response code

200 ok

Response

LockPreference

Errors

`LockPreference` does not exist :

{
  "error": "lock preference does not exist",
  "error_code": "lock_preference_does_not_exist"
}

status 404 not_found

Show specific lock preference from lock id

HTTP request

POST /v1/lock_preferences/show_from_door_lock

{
  "lock_preference": {
      "door_lock_id": 112
    }
}

HTTP response code

200 ok

Response

LockPreference

Errors

`Door_lock` does not exist :

{
  "error": "door lock does not exist",
  "error_code": "door_lock_does_not_exist"
}

`LockPreference` does not exist :

{
  "error": "lock preference does not exist",
  "error_code": "lock_preference_does_not_exist"
}

status 404 not_found

`door_lock` does not belong to current user :

{
  "error": "Can't access another one's lock",
  "error_code": "cant_access_another_ones_door_lock"
}

status 403 forbidden

Create a lock preference

{
  "lock_preference": {
      "battery_critical": ["push"],
      "flash_lock_admin": ["none"],
      "door_lock_id": 112
    }
}

HTTP request

POST /v1/lock_preferences

HTTP response code

201 created

Response

LockPreference

Errors

`door_lock` does not exist :

{
  "error": "Door lock does not exist",
  "error_code": "door_lock_does_not_exist"
}

status 404 not_found

`door_lock` does not belong to current user :

{
  "error": "Can't access another one's lock",
  "error_code": "cant_access_another_ones_door_lock"
}

status 403 forbidden

Update a lock preference

{
  "lock_preference": {
    "battery_critical": ["push","email"]
  }
}

HTTP request

PATCH /v1/lock_preferences/:id

HTTP response code

200 ok

Response

LockPreference

Errors

`lock_preference` does not exist :

{
  "error": "Lock preference does not exist",
  "error_code": "lock_preference_does_not_exist"
}

status 404 not_found

Update lock preference from lock id

HTTP request

POST /v1/lock_preferences/update_from_door_lock

{
  "lock_preference": {
    "battery_critical": ["push","email"],
    "door_lock_id": 112
    }
}

HTTP response code

200 ok

Response

LockPreference

Errors

`Door_lock` does not exist :

{
  "error": "door lock does not exist",
  "error_code": "door_lock_does_not_exist"
}

`LockPreference` does not exist :

{
  "error": "lock preference does not exist",
  "error_code": "lock_preference_does_not_exist"
}

status 404 not_found

Delete a lock preference

HTTP request

DELETE /v1/lock_preference/:lock_preference_id

HTTP response code

204 no_content

Errors

`lock_preference` does not exist :

{
  "error": "Lock preference does not exist",
  "error_code": "lock_preference_does_not_exist"
}

status 404 not_found

Notifications

Notification object

{
    "id": 1,
    "user_id": 6,
    "existing_status": "active",
    "is_read": false,
    "secondary_user_id": 2,
    "notif_type": "contact_request",
    "description": "description",
    "object_id": 1,
    "secondary_type": 1,
    "object_info": "{\"user_username\":\"Simsfx\",\"door_lock_description\":\"Porte demo\"}"
}

Attribute	Type	Required	Description
id	integer	yes	Identifier of the `notification`
user_id	integer	yes	Identifier of the `notification` owner
description	string	yes	Description of the `notification`
existing_status	`active` or `deleted`	yes	Existing status of the `notification`
is_read	boolean	yes	Whether the `notification` is read
secondary_user_id	integer	no	Identifier of the secondary user of the `notification`
notif_type	`log`, `lock_alert`, `contact_request`, `contact_answer`, `shared_key`,	yes	Type of the `notification`
object_id	integer	yes	Identifier of the object of the `notification`
secondary_type	integer	yes	Secondary type of the `notification`
created_at	date	yes	Timestamp of creation of the object
object_info	serialized json	no	Additional information about the notification objects

Object Info attributes

Notification type	Attributes
`log`	`user_initials`, `user_name`, `user_username`, `door_lock_description`, `door_lock_id`, `event_timestamp`, `log_type`
`lock_alert`	`user_initials`, `user_name`, `user_username`, `door_lock_description`, `door_lock_id`
`contact_request`	`user_initials`, `user_name`, `user_username`
`contact_answer`	`user_initials`, `user_name`, `user_username`
`shared_key`	`user_initials`, `user_name`, `user_username`, `door_lock_description`, `door_lock_id`

Get all notifications

Returns all the notifications of the current user.

HTTP request

GET /v1/notifications(?page_size=1) or GET /v1/notifications(?page=2&page_size=1)

You can send these optional parameters:

Parameter	Type	Required	Description
page	integer	no	The page number (page 3 of `notifications` for example
page_size	integer	no	How many elemenets should one page of `notifications`

or send limit (integer) which is the maximum number of notifications to receive

HTTP response code

200 ok

Response

[Notification]

Get all notifications from specific door lock

Returns all the notifications of the current user for a specific door lock.

HTTP request

POST /v1/notifications/index_for_door_lock

{
"notification": {
            "door_lock_id": "door_lock_id"
        }
}

Parameter	Type	Required	Description
door_lock_id	string	yes	Identifier of the `door_lock`

HTTP response code

200 ok

Response

[Notification]

Errors :

`door_lock_id` does not exist :

{
  "error": "Door lock does not exist",
  "error_code": "door_lock_does_not_exist"
}

status 404 not_found

`door_lock` does not belong to current user :

{
  "error": "Can't access another one's door lock",
  "error_code": "cant_access_another_ones_door_lock"
}

status 403 forbidden

Show specific notification

HTTP request

GET /v1/notifications/:notification_id

HTTP response code

200 ok

Response

Notification

Errors :

`notification_id` does not exist :

{
  "error": "Notification does not exist",
  "error_code": "notification_does_not_exist"
}

status 404 not_found

`notification` does not belong to current user :

{
  "error": "Can't access another one's notification",
  "error_code": "cant_access_another_ones_notification"
}

status 403 forbidden

Update a notification

{
"notification": {
            "is_read": true
        }
}

Parameter	Type	Required	Description
is_read	boolean	no	Whether the notification has been read.

HTTP request

PATCH /v1/notifications/:notification_id

HTTP response code

200 ok

Response

Notification

Errors :

`notification_id` does not exist :

{
  "error": "Notification does not exist",
  "error_code": "notification_does_not_exist"
}

status 404 not_found

`notification` does not belong to current user :

{
  "error": "Can't access another one's notification",
  "error_code": "cant_access_another_ones_notification"
}

status 403 forbidden

Read all notifications

HTTP request

GET /v1/notifications/read_all

HTTP response code

200 ok

Delete a notification

HTTP request

DELETE /v1/notifications/:notification_id

HTTP response code

200 ok

Errors :

`notification_id` does not exist :

{
  "error": "Notification does not exist",
  "error_code": "notification_does_not_exist"
}

status 404 not_found

`notification` does not belong to current user :

{
  "error": "Can't access another one's notification",
  "error_code": "cant_access_another_ones_notification"
}

status 403 forbidden

Offline Mode Configurations

Offline Mode Configuration object

{
    "id": 1,
    "door_lock_id": 1,
    "existing_status": "active",
}

Attribute	Type	Required	Description
id	integer	yes	Identifier of the `offline_mode_configuration`
door_lock_id	integer	yes	Identifier of the `door_lock`
existing_status	string	yes	Status of the configuration

Access all Offline Mode Configurations

Returns all the offline mode configurations for the locks the user is the owner or an admin.

HTTP request

GET /v1/offline_mode_configurations

HTTP response code

200 ok

Response

[OfflineModeConfiguration]

Create an offline mode configuration

{ 
  "offline_mode_configuration": {
    "door_lock_id": "door_lock_id"
   }
}

Parameter	Type	Required	Description
door_lock_id	integer	yes	Identifier of the door lock

Create an offline mode configuration for a door lock.

HTTP request

POST /v1/offline_mode_configurations

HTTP response code

200 ok

Response

OfflineModeConfiguration

Errors :

user is not owner/admin of the `door_lock` :

{
  "error": "Can't access another one's lock",
  "error_code": "cant_access_another_ones_door_lock"
}

status 403 forbidden

A configuration already exists for this `door_lock` :

{
  "error": "Offline mode configuration already exists for lock",
  "error_code": "offline_mode_configuration_exists"
}

status 400 bad_request

Delete an offline mode configuration

Parameter	Type	Required	Description
id	integer	yes	Identifier of the offline mode configuration

Remove an offline mode configuration for the door lock.

HTTP request

POST /v1/offline_mode_configurations/:id

HTTP response code

204 no_content

Errors :

user is not owner/admin of the `door_lock` :

{
  "error": "Can't access another one's lock",
  "error_code": "cant_access_another_ones_door_lock"
}

status 403 forbidden

Session Log

Session Log object

{
    "id": 3,
    "user_id": 6,
    "device_id": null,
    "oauth_client_id": 12,
    "user_agent": "ios/10.2",
    "active": true
}

Attribute	Type	Required	Description
id	integer	yes	Identifier of the `session_log`
user_id	integer	yes	Identifier of the `session_log` owner
device_id	integer	yes	Identifier of the `device`
oauth_client_id	integer	yes	Identifies the support used for the connection
user_agent	string	no	Description of the connecting device
active	boolean	yes	Identifies it the log has been save while authenticating or login out

Get own session logs

Returns all the session logs from the current user.

HTTP request

GET /v1/session_logs

HTTP response code

200 ok

Response

[SessionLog]

Shared keys

A shared key gives to the user an access to a door lock. The access is characterized by its start_date. If an end_date is set, the access can be recurrent for each day, week month or year.

Shared Key object

{
    "id": 20,
    "user_id": 6,
    "door_lock_id": 9,
    "lock_id": 10,
    "eniq_lock_shared_key_data_id": 5,
    "start_date": "2017-04-01T12:30:00.000Z",
    "end_date": "2017-04-01T13:00:00.000Z",
    "admin": false,
    "existing_status": "active",
    "lock_user_number": "lock_user_number",
    "origin_user_id": 8,
    "temp_user_id": null,
    "last_k_token_id": "last_k_token_id" ,
    "note": null
}

Attribute	Type	Required	Description
id	integer	yes	Identifier of the `shared_key`
user_id	integer	no	Identifier of the `user` (when not sharing with link)
door_lock_id	integer	no	Identifier of the `door_lock`
lock_id	integer	no	Identifier of the `lock`. Is exclusive with `door_lock_id`
eniq_lock_shared_key_data_id	integer	no	Identifier of the `eniq_lock_shared_key_data`. Is set when `lock_id` is an EniqLock
start_date	date	no	Start of the access
end_date	date	no	End of the access
admin	boolean	yes	Whether the user will be able to administrate the lock
recurrency	`day`, `week`, `month`, `year` or `none`	yes	Recurrency of the access
origin_user_id	integer	yes	Identifier of the origin `user` (the user that created the access)
temp_user_id	integer	no	Identifier of the `temp_user` (when sharing with link)
exising_status	`active` or `waiting_for_user`	yes	Status of the object. Is `waiting_for_user` if was shared with link.
last_k_token_id	string	yes	Identifier of the last sync of ktoken
note	string	no	Note about the shared access

Shared key types

Type	`start_date`	`end_date`	`admin`	Description
normal	yes	yes	no	User can lock/unlock within given period
unlimited	yes	no	no	User can lock/unlock until the access is removed or changed
admin	yes	-	yes	User can lock/unlock and administrate the lock until the access is expired, removed or changed

Shared key statuses

Get own shared keys

Returns all the door locks that have been shared with the current user.

HTTP request

GET /v1/shared_keys

HTTP response code

200 ok

Response

[SharedKey]

Show specific shared key

HTTP request

GET /v1/shared_keys/:shared_key_id

HTTP response code

200 ok

Response

SharedKey

Errors

`shared_key` does not belong to current user :

{
  "error": "Can't access another one's shared key",
  "error_code": "cant_access_another_ones_shared_key"
}

status 403 forbidden

`shared_key` does not exist :

{
  "error": "Shared key does not exist",
  "error_code": "shared_key_does_not_exist"
}

status 404 not_found

{
"shared_key": {
  "token": "token"
  }
}

Parameter	Type	Required	Description
token	string	yes	Token string received from link

HTTP request

POST /v1/shared_keys/show_from_token

HTTP response code

200 ok

Response

SharedKey, "user": User, "temp_user": TempUser, "door_lock": { DoorLock, "user": User }, "device": 12

Where device is the device id to send when generating the flash sequence

Errors

`shared_key` does not belong to current user :

{
  "error": "Can't access another one's shared key",
  "error_code": "cant_access_another_ones_shared_key"
}

status 403 forbidden

`shared_key` does not exist or token is invalid:

{
  "error": "Shared key does not exist",
  "error_code": "shared_key_does_not_exist"
}

status 404 not_found

`shared_key` or token has expired:

{
  "error": "Shared key has expired",
  "details": "temp_access_expired",
  "error_code": "shared_key_has_expired"
}

status 403 forbidden

`shared_key` cannot be retrieved since the temp user has already retrieved a different access. A temp user can only retrieve one access before being forced to create an account

{
  "error": "Shared key has expired",
  "details": "limited_to_one_access",
  "error_code": "shared_key_has_expired"
}

status 403 forbidden

Can't get show_from_token if a different access already has been retrieved :

{
"error": "You can only retrieve one access without having an account",
"error_code": "can_only_retrieve_one_access_without_account", 
"details": "limited_to_one_access"
}

status 403 forbidden

Show specific shared key with details

HTTP request

GET /v1/shared_keys/show_with_details/:shared_key_id

HTTP response code

200 ok

Response

SharedKey, "user": User, "temp_user": TempUser, "door_lock": { DoorLock, "user": User }, "lock": Lock

Errors

`door_lock` does not belong to current user :

{
  "error": "Can't access another one's shared key",
  "error_code": "cant_access_another_ones_shared_key"
}

status 403 forbidden

`shared_key` does not exist :

{
  "error": "Shared key does not exist",
  "error_code": "shared_key_does_not_exist"
}

status 404 not_found

Get door lock and users details

HTTP request

GET v1/shared_keys/index_with_details

HTTP response code

200 ok

Response

[SharedKey, "door_lock": { DoorLock, "user": User, "lock_group": { LockGroup, "parent_lock_group": LockGroup }, "user": User, "origin_user": User, "temp_user": TempUser, "lock": { Lock, "user": User, "lock_group": { LockGroup, "parent_lock_group": LockGroup }]

Errors

`door_lock` does not belong to current user :

{
  "error": "Can't access another one's lock",
  "error_code": "cant_access_another_ones_door_lock"
}

status 403 forbidden

Get door lock and user details for specific door lock

{
"shared_key": {
  "door_lock_id": "door_lock_id"
  }
}

Parameter	Type	Required	Description
door_lock_id	integer	yes	Identifier of the door lock

HTTP request

POST v1/shared_keys/index_with_details

HTTP response code

200 ok

Response

[SharedKey, "door_lock": { DoorLock, "user": User, "lock_group": { LockGroup, "parent_lock_group": LockGroup } }, "user": User, "origin_user": User, "temp_user": TempUser]

Errors

`door_lock` does not belong to current user :

{
  "error": "Can't access another one's lock",
  "error_code": "cant_access_another_ones_door_lock"
}

status 403 forbidden

`door_lock` does not exist :

{
  "error": "Door lock does not exist",
  "error_code": "door_lock_does_not_exist"
}

status 404 not_found

Get shared keys for a specific user

{
  "shared_key": {
    "user_id": 9
  }
}

Parameter	Type	Required	Description
user_id	integer	yes	Identifier of the user

HTTP request

POST /v1/shared_keys/shared_keys_for_user

HTTP response code

200 ok

Response

[SharedKey]

Errors

`user_id` does not exit:

{
  "error": "User does not exist",
  "error_code": "user_does_not_exist"
}

status 404 not_found

Get shared keys lock details for a specific user

{
  "shared_key": {
    "user_id": 9
  }
}

Parameter	Type	Required	Description
user_id	integer	yes	Identifier of the user

HTTP request

POST /v1/shared_keys/detail_shared_keys_for_user

HTTP response code

200 ok

Response

[SharedKey, "door_lock": DoorLock, "lock": Lock]

Errors

`user_id` does not exit:

{
  "error": "User does not exist",
  "error_code": "user_does_not_exist"
}

status 404 not_found

Get shared keys for a specific door lock

{
  "shared_key": {
    "door_lock_id": 9
  }
}

Parameter	Type	Required	Description
door_lock_id	integer	yes	Identifier of the door lock

HTTP request

POST /v1/shared_keys/shared_keys_for_door_lock

HTTP response code

200 ok

Response

[SharedKey]

Errors

`door_lock` does not belong to current user :

{
  "error": "Can't access another one's lock",
  "error_code": "cant_access_another_ones_door_lock"
}

status 403 forbidden

`door_lock` does not exist :

{
  "error": "Door lock does not exist",
  "error_code": "door_lock_does_not_exist"
}

status 404 not_found

Get shared keys lock details for a specific door lock

{
  "shared_key": {
    "door_lock_id": 9
  }
}

Parameter	Type	Required	Description
door_lock_id	integer	yes	Identifier of the door lock

HTTP request

POST /v1/shared_keys/detail_shared_keys_for_door_lock

HTTP response code

200 ok

Response

[SharedKey, "user": User, "temp_user": TempUser]

Errors

`door_lock` does not belong to current user :

{
  "error": "Can't access another one's lock",
  "error_code": "cant_access_another_ones_door_lock"
}

status 403 forbidden

`door_lock` does not exist :

{
  "error": "Door lock does not exist",
  "error_code": "door_lock_does_not_exist"
}

status 404 not_found

{
  "shared_key": {
    "start_date": "2017-04-01T12:30:00Z",
    "end_date": "2017-05-01T12:30:00Z",
    "admin": false,
    "recurrency": "day",
    "lock_group_ids": ["lock_group_1", "lock_group_2"],
    "user_list_ids": ["user_id1", "user_id2"],
    "lock_list_ids": ["door_lock_id1", "door_lock_id2"],
    "lock_ids": ["lock_id1", "lock_id2"],
    "user_group_ids": ["door_lock_id1", "door_lock_id2"]
  }
}

Parameter	Type	Required	Description
start_date	date	no	Start of the access, zulu time without millisecond
end_date	date	no	End of the access, zulu time without millisecond
admin	boolean	yes	Whether the user will be able to administrate the lock
recurrency	`day`, `week`, `month`, `year` or `none`	no	Recurrency of the access
lock_group_ids	integer[]	no	Identifiers of the `lock_groups` to share
user_group_ids	integer[]	no	To share the key with user group members
user_list_ids	integer[]	no	To share the key with a list of users
lock_list_ids	integer[]	no	Share key to a list of door locks
lock_ids	integer[]	no	Share key to a list of locks

Will create a shared key item associated to all specified users (from user_list_ids and user_group_ids) for all specified door locks (from lock_list_ids and lock_group_ids).

HTTP request

POST /v1/shared_keys

HTTP response code

201 created

Response

[SharedKey, "door_lock": { DoorLock, "user": User }, "lock": { Lock, "user": User }, "user": User, "temp_user": TempUser]

Errors

No user is targeted with `user_group_ids` or `user_list_ids` :

{
  "error": "Must be shared with a user group or a user list",
  "error_code": "must_be_shared_with_user_group_or_user_list"
}

status 400 bad_request

No door lock is targeted with `lock_group_ids` or `lock_list_ids` or `lock_ids` :

{
  "error": "Must be shared with a lock group or a lock list",
  "error_code": "must_be_shared_with_lock_group_or_door_lock_list"
}

status 400 bad_request

The user_group does not exist or the user is not the owner:

{
  "error": "User group not found or you must be the owner",
  "error_code": "user_group_not_found_or_must_be_the_owner"
}

status 404 not_found

The lock_group does not exist or the user is not the owner:

{
  "error": "Lock group not found or must be the owner",
  "error_code": "lock_group_not_found_or_must_be_the_owner"
}

status 404 not_found

`door_lock` does not belong to current user :

{
  "error": "Can't access another one's lock",
  "error_code": "cant_access_another_ones_door_lock"
}

status 403 forbidden

A user sent to be recipient does not exist :

{
  "error": "User does not exist",
  "error_code": "user_does_not_exist"
}

status 404 not_found

`door_lock` does not exist :

{
  "error": "Door lock does not exist",
  "error_code": "door_lock_does_not_exist"
}

status 404 not_found

User is admin of door lock :

{
  "error": "User is admin of door lock",
  "error_code": "user_admin_of_lock"
}

status 400 bad_request

`recurrency` is invalid :

{
  "error": "Week recurrency cannot be applied to a multiple week period",
  "error_code": "week_recurrency_cannot_be_applied_to_multiple_week_period"
}

status 403 forbiden

{
  "shared_key": {
    "start_date": "2017-04-01T12:30:00Z",
      "end_date": "2017-04-01T16:30:00Z",
      "admin": false,
      "email": "user_email",
      "emails": ["foo_mail", "bar_mail"],
      "lock_list_ids": ["door_lock_id"],
      "lock_ids": ["lock_id"],
      "recurrency": "day"
  }
}

Parameter	Type	Required	Description
email	string	yes if `emails` is empty	Email of the user
emails	string[]	yes if `email` is empty	Email of the users to share the access with
start_date	date	no	Start of the access
end_date	date	no	End of the access, zulu time without millisecond
admin	boolean	yes	Whether the user will be able to administrate the lock
recurrency	`day`, `week`, `month` or `year`	no	Recurrency of the access
lock_list_ids	integer[]	no	Share key to a list of door locks
lock_ids	integer[]	no	Share key to a list of locks
lock_group_ids	integer[]	no	Identifiers of the `lock_groups` to share
note	string	no	A note about the shared access

Will create a temp user item associated to the shared_key and the specified email.

A token will be sent to the users email address. This token can be used to retrieve the access to the door_lock. This token has an expiration date set to 8 hours after the start_date of the shared_key.

HTTP request

POST /v1/shared_keys/create_with_link

HTTP response code

201 created

Response

SharedKey

Errors

`door_lock` does not belong to current user :

{
  "error": "Can't access another one's lock",
  "error_code": "cant_access_another_ones_door_lock"
}

status 403 forbidden

`door_lock` does not exist :

{
  "error": "Door lock does not exist",
  "error_code": "door_lock_does_not_exist"
}

status 404 not_found

`recurrency` is invalid :

{
  "error": "Week recurrency cannot be applied to a multiple week period",
  "error_code": "week_recurrency_cannot_be_applied_to_multiple_week_period"
}

status 403 forbiden

`door_lock` does not belong to `lock_group` :

{
  "error": "Door lock does not belong to the lock group",
  "error_code": "door_lock_does_not_belong_to_lock_group"
}

status 400 bad_request

`door_lock` needs to be shared with `lock_group` or door lock list:

{
  "error": "Must be shared with a lock group or a door lock list",
  "error_code": "must_be_shared_with_lock_group_or_door_lock_list"
}

status 400 bad_request

Date format is invalid:

{
  "error": "Invalid date format: should be UTC: ISO8601",
  "error_code": "invalid_date_format"
}

status 400 bad_request

Update a shared key

{
  "shared_key": {
    "admin": true
  }
}

Parameter	Type	Required	Description
start_date	date	no	Start of the access, zulu time without millisecond
end_date	date	no	End of the access, zulu time without millisecond
admin	boolean	no	Whether the user will be able to administrate the lock
recurrency	`day`, `week`, `month` or `year`	no	Recurrency of the access

HTTP request

PATCH /v1/shared_keys/:shared_key_id

HTTP response code

200 ok

Response

SharedKey

Errors

`door_lock` does not belong to current user :

{
  "error": "Can't access another one's lock",
  "error_code": "cant_access_another_ones_door_lock"
}

status 403 forbiden

`shared_key` does not exist :

{
  "error": "Shared key does not exist",
  "error_code": "shared_key_does_not_exist"
}

status 404 not_found

`recurrency` is invalid :

{
  "error": "Year recurrency cannot be applied to a multiple years period",
  "error_code": "year_recurrency_cannot_be_applied_to_multiple_years_period"
}

status 403 forbiden

Create or update a shared key

{
  "user_id": 2,
  "door_lock_id": 1,
  "lock_id": 1,
  "start_date": "2017-04-01T12:00:00Z",
  "end_date": "2017-05-01T14:00:00Z",
  "admin": true
}

Parameter	Type	Required	Description
user_id	integer	depends (if user_group_id is present)	Identifier of the user
door_lock_id	integer	yes	Identifier of the door lock
lock_id	integer	yes	Identifier of the lock (exclusive with `door_lock_id`)
start_date	date	no	Start of the access, zulu time without millisecond
end_date	date	no	End of the access, zulu time without millisecond
admin	boolean	yes	Whether the user will be able to administrate the lock
recurrency	`day`, `week`, `month` or `year`	no	Recurrency of the access
note	string	no	A note about the shared access

Redirect the request to create or update a sharedKey without knowing the entry id

HTTP request

POST /v1/shared_keys/create_or_update

HTTP response code

200 ok

201 created

Response

SharedKey

Errors

See errors of a creation or update

Delete a shared key

HTTP request

DELETE /v1/shared_keys/:shared_key_id

HTTP response code

204 no_content

Errors

`door_lock` does not belong to current user :

{
  "error": "Can't access another one's lock",
  "error_code": "cant_access_another_ones_door_lock"
}

status 403 forbiden

`shared_key` does not exist :

{
  "error": "Shared key does not exist",
  "error_code": "shared_key_does_not_exist"
}

status 404 not_found

Delete multiple shared keys

{
  "shared_keys": [
    {
      "shared_key_id": "shared_key_id"
    },
    {
      "shared_key_id": "shared_key_id"
    },
    {
      "shared_key_id": "shared_key_id"
    }
  ]
}

Parameter	Type	Required	Description
shared_key_id	integer	yes	Identifier of the shared key

HTTP request

POST v1/shared_keys/delete_multiple_shared_keys

HTTP response code

204 no_content

Errors

`door_lock` does not belong to current user :

{
  "error": "Can't access another one's lock",
  "error_code": "cant_access_another_ones_door_lock"
}

status 403 forbiden

`shared_key` does not exist :

{
  "error": "Shared key does not exist",
  "error_code": "shared_key_does_not_exist"
}

status 404 not_found

Dismiss a shared key

{
  "shared_key": {
    "id": "shared_key_id"
  }
}

Parameter	Type	Required	Description
id	integer	yes	Identifier of the shared key

Lets the user dismiss a shared key from his shared keys.

HTTP request

POST /v1/shared_keys/dismiss

HTTP response code

200 ok

Errors

`shared_key` does not belong to current user :

{
  "error": "Can't access another one's shared key",
  "error_code": "cant_access_another_ones_shared_key"
}

status 403 forbiden

`shared_key` does not exist :

{
  "error": "Shared key does not exist",
  "error_code": "shared_key_does_not_exist"
}

status 404 not_found

Get K token for shared_key on door lock

{
    "k_token": {
        "shared_key_id": "shared_key_id",
        "p_key": "p_key"
    }
}

{
  "k_token": "encrypted_k_token",
  "last_k_token_id": "last_k_token_id"
}

Parameter	Type	Required	Description
shared_key_id	integer	yes	Identifier of the shared key
p_key	string	yes	RSA public key - 2048

Resets your k token sent to unlock the door.

HTTP request

POST /v1/shared_keys/get_k_token

HTTP response code

200 ok

Errors

`shared_key` does not belong to current user :

{
  "error": "Can't access another one's shared key",
  "error_code": "cant_access_another_ones_shared_key"
}

status 403 forbiden

`shared_key` does not exist :

{
  "error": "Shared key does not exist",
  "error_code": "shared_key_does_not_exist"
}

status 404 not_found

`k_token` could not be generated :

{
  "error": "Error generating k token",
  "error_code": "generating_k_token"
}

status 400 bad_request

Get K tokens for shared_keys on door lock

{
  "shared_key_ids": ["shared_key_id_1", "shared_key_id_2"]
}

{
  "shared_keys": {
    "shared_key_id_1": {
      "k_token": "k_token",
      "last_k_token_id": "last_k_token_id"
    },
    "shared_key_id_2": {
      "k_token": "k_token",
      "last_k_token_id": "last_k_token_id"
    }
  }
}

Parameter	Type	Required	Description
shared_key_ids	integer[]	yes	Identifier of the shared keys

Resets your k token sent to unlock the door.

HTTP request

POST /v1/shared_keys/get_k_tokens

HTTP response code

200 ok

Errors

`shared_key` does not belong to current user :

{
  "error": "Can't access another one's shared key",
  "error_code": "cant_access_another_ones_shared_key"
}

status 403 forbiden

`shared_key` does not exist :

{
  "error": "Shared key does not exist",
  "error_code": "shared_key_does_not_exist"
}

status 404 not_found

{
    "k_token": {
        "token": "token",
        "p_key": "p_key"
    }
}

{
  "k_token": "k_token",
  "last_k_token_id": "last_k_token_id"
}

Parameter	Type	Required	Description
token	string	yes	Token string received from link
p_key	string	yes	RSA public key - 2048

Resets your k token sent to unlock the door.

HTTP request

POST /v1/shared_keys/get_k_token_from_token

HTTP response code

200 ok

Errors

`shared_key` does not belong to current user :

{
  "error": "Can't access another one's shared key",
  "error_code": "cant_access_another_ones_shared_key"
}

status 403 forbiden

`shared_key` does not exist :

{
  "error": "Shared key does not exist",
  "error_code": "shared_key_does_not_exist"
}

status 404 not_found

`shared_key` or token has expired:

{
  "error": "Shared key has expired",
  "details": "temp_access_expired",
  "error_code": "shared_key_has_expired"
}

status 403 forbidden

`shared_key` cannot be retrieved since the temp user has already retrieved a different access. A temp user can only retrieve one access before being forced to create an account

{
  "error": "Shared key has expired",
  "details": "limited_to_one_access",
  "error_code": "shared_key_has_expired"
}

status 403 forbidden

Support emails

Bug Report

{
  "bug_report": {
    "message": "message"
  }
}

Parameter	Type	Required	Description
message	string	yes	Bug message

HTTP request

POST support/v1/report_bug

Feedback

{
  "feedback": {
    "message": "message"
  }
}

Parameter	Type	Required	Description
message	string	yes	Feedback message

HTTP request

post support/v1/feedback

Custom Service

{
  "custom_service": {
    "message": "message"
  }
}

Parameter	Type	Required	Description
message	string	yes	Custom service message

HTTP request

POST support/v1/custom_service

Send Eula Email

Sends End user License Agreement email to the sent email

{
  "eula": {
    "email": "email@email.com",
    "language": "en"
  }
}

Parameter	Type	Required	Description
email	string	yes	Recipient of the email
language	string	yes	Language of the email : Supported languages are FR and EN

HTTP request

POST support/v1/send_eula

Website privacy url

HTTP request

GET support/v1/website_privacy_url

HTTP response code

200 ok

Response

{ "privacy_route": "https://url.havr.io"}

Synchronization

Returns detailed data about active and not active entries for models selected by the user since the last sync date. The current supported models are : lock_groups, door_locks, shared_keys , user, notifications, lock_logs and contacts

{
    "shared_keys": [SharedKey],
    "door_locks": [DoorLock],
    "contacts": [Contact],
    "lock_groups": [LockGroup], 
    "users": [User],
    "notifications": [Notification],
    "lock_logs": [LockLog]
}

Parameter	Type	Required	Description
sync_date	int	no	Locks since sync_date
models	integer[]	yes	Models to renders

Example

{
    "models": ["shared_keys","contacts","lock_groups","door_locks", "users"],
    "sync_date": "1555231440"
}

HTTP request

POST /v1/synchronization

HTTP response code

200 ok

Errors

Null Models parameter:

{
    "error": "Models parameter can't be nil",
    "error_code": "invalid_models"
}

Invalid epoch format:

{
    "error": "Invalid epoch format: should have integer value",
    "error_code": "invalid_epoch_format"
}

User groups

User Group object

{
    "id": "user_group_id",
    "user_id": 4,
    "description": "a group",
    "members": []
}

Attribute	Type	Required	Description
id	integer	yes	Identifier of the `user_group`
user_id	integer	yes	Identifier of the `user`
description	string	yes	Name of the user group
members	[integer]	no	Identifiers of the users

Get all user groups owned by the user

HTTP request

GET /v1/user_groups

HTTP response code

200 ok

Response

[UserGroup]

Get user group details

HTTP request

GET /v1/user_groups/user_group_id

HTTP response code

200 ok

Response

UserGroup

Errors

`user_group_id` does not exist :

{
  "error": "User group not found or you must be the owner",
  "error_code": "user_group_not_found_or_must_be_the_owner"
}

status 404 not_found

Create a user group

{
    "description": "a group",
    "members": [1, 3]
}

Parameter	Type	Required	Description
description	string	yes	Name of the user group
members	[integer]	no	Identifiers of the users

HTTP request

POST /v1/user_groups

HTTP response code

201 created

Response

UserGroup

Errors

`members_id` does not exist :

{
  "error": "User does not exist",
  "error_code": "user_does_not_exist"
}

status 400 bad_request

Patch a user group

{
    "description": "a group updated",
    "members": [1, 3, 7]
}

Parameter	Type	Required	Description
description	string	no	Name of the user group
members	[integer]	no	Identifiers of the users

HTTP request

PATCH /v1/user_groups/user_group_id

HTTP response code

200 ok

Response

UserGroup

Errors

`members_id` does not exist :

{
  "error": "User does not exist",
  "error_code": "user_does_not_exist"
}

status 400 bad_request

`user_group_id` does not exist or the user is not the owner:

{
  "error": "User group not found or you must be the owner",
  "error_code": "user_group_not_found_or_must_be_the_owner"
}

status 404 not_found

Add users to group

{
    "group_id": "user_group_id",
    "users": [1, 3]
}

Parameter	Type	Required	Description
group_id	integer	no	Identifier of the user group
users	[integer]	no	Identifiers of the users to add

HTTP request

POST /v1/user_groups/add_users_to_group

HTTP response code

200 ok

Response

UserGroup

Errors

`user_group_id` does not exist or the user is not the owner:

{
  "error": "User group not found or you must be the owner",
  "error_code": "user_group_not_found_or_must_be_the_owner"
}

status 404 not_found

`user` is already member of the group:

{
  "error": "User is already member of the group",
  "error_code": "user_already_in_group"
}

status 400 bad_request

`user` does not exist:

{
  "error": "User does not exist",
  "error_code": "user_does_not_exist"
}

status 400 bad_request

User preferences

User Preference object

{
    "id": 20,
    "newsletter": true,
    "updates": true,
    "eula": true,
    "notification101": true,
    "notification102": true,
    "notification200": true,
    "notification202": true,
    "notification300": true,
    "notification401": true
}

Attribute	Type	Required	Description
id	integer	yes	Identifier of the `user_preference`
newsletter	boolean	no	Preferences to receive newsletter
updates	boolean	no	Preferences to receive updates
eula	boolean	no	Specifies whether user agreed to "End User License Agreement" or not
notification101	boolean	no	To be notify about updates for shared key
notification102	boolean	no	To be notify about deletion of shared key
notification200	boolean	no	To be notify about new contacts
notification202	boolean	no	To be notify about contact deletion
notification300	boolean	no	To be notify about new lock log
notification401	boolean	no	To be notify about booking owner answer (no dot disturb)

Get own preferences

Returns all the user preferences.

HTTP request

GET /v1/user_preferences

HTTP response code

200 ok

Response

SharedKey

Update preferences

{
  "user_preferences": {
    "newsletter": true,
    "updates": true,
    "eula": true,
    "notification101": true,
    "notification102": true,
    "notification200": true,
    "notification202": true,
    "notification300": true,
    "notification401": true
  }
}

Parameter	Type	Required	Description
newsletter	boolean	no	Preferences to receive newsletter
updates	boolean	no	Preferences to receive updates
eula	boolean	no	Specifies whether user agreed to "End User License Agreement" or not
notification101	boolean	no	To be notify about updates for shared key
notification102	boolean	no	To be notify about deletion of shared key
notification200	boolean	no	To be notify about new contacts
notification202	boolean	no	To be notify about contact deletion
notification300	boolean	no	To be notify about new lock log
notification401	boolean	no	To be notify about booking owner answer (no dot disturb)

HTTP request

PATCH /v1/user_preferences

HTTP response code

200 ok

Response

SharedKey

Users

User object

{
    "id": 6,
    "email": "email",
    "first_name": "first_name",
    "last_name": "last_name",
    "phone_number": "phone_number",
    "account_status": "active",
    "preferred_language": "en",
    "favorites": [1, 5],
    "picture_url": "pictures/profile/eef477e129cbe2509d90c3aba4b5e808eef477e129cbe2509d90c3aba4b5e808.png"
}

Attribute	Type	Required	Description
id	integer	yes	Identifier of the `user`
email	string	yes	Email
first_name	string	yes	First name
last_name	string	yes	Last name
phone_number	string	no	Phone number
password	string	yes	Password
preferred_language	`en` or `fr`	no	Preferred language
favorites	integer[]	yes	Identifiers of the favorite `door_locks` of the user
picture_url	string	no	Url to download the profile picture of the user, check with the admin for the endpoint

Get own info

Returns all the info related to the authenticated user.

HTTP request

GET /v1/users

HTTP response code

200 ok

Response

User

Errors

`email` is not verified for user :

{
  "error": "Email is not verified",
  "error_code": "email_not_verified"
}

status 403 forbidden

`user` account is not active :

{
  "error": "Account is inactive",
  "error_code": "account_inactive"
}

status 403 forbidden

Show specific user

Shows information of specific user. If user is not in contacts of the current user, the info of the user will be minimal.

HTTP request

GET /v1/users/:user_id

HTTP response code

200 ok

Response

User

Errors

`user` does not exist :

{
  "error": "User does not exist",
  "error_code": "user_does_not_exist"
}

status 404 not_found

Get user contacts

Returns all current user's contacts. Returns a contact only if the request_status is accepted.

HTTP request

GET /v1/users/contacts

HTTP response code

200 ok

Response

[User]

Get user contacts with last activity

Same as Get current user contacts, but with last activity.

HTTP request

GET /v1/users/contacts_with_activity

HTTP response code

200 ok

Response

[{User, "last_activity": LockLog}]

Get own pending contacts

Returns all contacts from the current user that are pending. Returns a contact only if the request_status is pending.

HTTP request

GET /v1/users/pending_contacts

HTTP response code

200 ok

Response

[User]

Get own pending requests

Returns all contacts requests from the current user that are pending.

HTTP request

GET /v1/users/pending_requests

HTTP response code

200 ok

Response

[Contact, "user": User]

Errors

`email` is not verified for user :

{
  "error": "Email is not verified",
  "error_code": "email_not_verified"
}

status 403 forbidden

`user` account is not active :

{
  "error": "Account is inactive",
  "error_code": "account_inactive"
}

status 403 forbidden

Answer a pending request

{
  "contact": {
    "contact_id": "contact_id",
    "request_accepted": "true"
  }
}

Parameter	Type	Required	Description
contact_id	integer	yes	Identifier of the contact request
request_accepted	boolean	yes	Whether the request is accepted

Answer a pending contact request.

HTTP request

POST /v1/users/answer_contact_request

HTTP response code

200 ok

Response

Contact

Errors

`user` can't access anyone's else's contact :

{
  "error": "Can't access anyone else's contact",
  "error_code":"cant_access_another_ones_contact"
}

status 403 forbidden

`contact` does not exist :

{
  "error": "Contact does not exist ",
  "error_code": "contact_does_not_exist"
}

status 404 not_found

Request is not pending:

{
  "error": "Contact request is not pending",
  "error_code": "contact_request_not_pending"
}

status 400 bad_request

Check if username or email already exists

{
  "username_or_email": "username_or_email"
}

{
  "already_exists": true
}

Parameter	Type	Required	Description
username_or_email	string	yes	Username or email to query

HTTP request

POST /v1/users/username_or_email_used

HTTP response code

200 ok

Create user

{
  "user": {
    "email": "email",
    "first_name": "first_name",
    "last_name": "last_name",
    "phone_number": "phone_number",
    "password": "password",
    "extension": "png",
    "base64_picture": "iVBORw0KGgoAAAANSUhEUgAAAZAAAKQgPD..."
   },
  "user_preferences": {
    "newsletter": true,
    "updates": true,
    "eula": true
  }
}

Parameter	Type	Required	Description
email	string	yes	Email
first_name	string	yes	First name
last_name	string	yes	Last name
phone_number	string	no	Phone number
password	string	yes	Password
extension	`png`, `jpeg` or `jpg`	yes if `base64_picture` is set	Image extension
base64_picture	string	no	Image - base64
preferred_language	`en` or `fr`	no	Preferred language

Parameter	Type	Required	Description
newsletter	boolean	no	Preferences to receive newsletter
updates	boolean	no	Preferences to receive updates
eula	boolean	no	Specifies whether user agreed to "End User License Agreement" or not
notification101	boolean	no	To be notify about updates for shared key
notification102	boolean	no	To be notify about deletion of shared key
notification200	boolean	no	To be notify about new contacts
notification202	boolean	no	To be notify about contact deletion
notification300	boolean	no	To be notify about new lock log
notification401	boolean	no	To be notify about booking owner answer (no dot disturb)

Will create a new user.

Accepted phone number formats are FR and UK phone numbers

Country	Example of Accepted Formats
FR	'0648243834', '+33648243834'
UK	'07222555555', '+447222555555'

password should match one of those cases :
* length >= 16 & < 50 among lower case chars, upper case chars, numbers, special chars
* length >= 8 & < 50 with at least 1 upper case, 1 lower case, 1 number, 1 special char
To be noticed that supported special characters are : !"#$%&'()*+,-./:;<=>?@[]^_`{|}~¡¢£¤¥¦§¨©ª«¬®¯°±²³´µ¶·¸¹º»¼½¾¿ÀÁÂÃÄÅÆÇÈÉÊËÌÍÎÏÐÑÒÓÔÕÖ×ØÙÚÛÜÝÞßàáâãäåæçèéêëìíîïðñòóôõö÷øùúûüýþÿ€

HTTP request

POST /v1/users

HTTP response code

201 created

Response

User

Errors

`phone_number` has a bad format:

{
  "error": "Invalid phone number format",
  "error_code": "invalid_phone_number_format"
}

status 400 bad_request

`user` with that email already exists:

{
  "error": "User already exists",
  "error_code": "user_exists"
}

status 400 bad_request

Update a user

{
  "user": {
    "first_name": "new_first_name"
  }
}

Parameter	Type	Required	Description
first_name	string	yes	First name
last_name	string	yes	Last name
phone_number	string	no	Phone number
preferred_language	`en` or `fr`	no	Preferred language

HTTP request

PATCH /v1/users/:user_id

HTTP response code

200 ok

Response

User

Errors

`user` does not exist :

{
  "error": "User does not exist",
  "error_code": "user_does_not_exist"
}

status 404 not_found

`user` is not current user :

{
  "error": "Can't access user",
  "error_code": "cant_access_other_user"
}

status 400 bad_request

`phone_number` has a bad format:

{
  "error": "Invalid phone number format",
  "error_code": "invalid_phone_number_format"
}

status 400 bad_request

Delete a user

HTTP request

DELETE /v1/users/:user_id

HTTP response code

200 ok

Errors

`user` does not exist :

{
  "error": "User does not exist",
  "error_code": "user_does_not_exist"
}

status 404 not_found

`user` is not current user :

{
  "error": "Can't access user",
  "error_code": "cant_access_other_user"
}

status 400 bad_request

Reset password

{
  "forgot_password": {
    "email": "email",
    "platform": "customer_space"
  }
}

Parameter	Type	Required	Description
email	string	yes	Email
platform	string	yes	Client platform to use : `dashboard` or `customer_space`

Sends a email to reset the password to specified email.

HTTP request

POST /support/v1/forgot_password

HTTP response code

204 no content

Errors

`email` does not exist :

{
  "error": "Unknown email address"
}

status 404 not_found

Password token is null :

{
  "error": "Password reset token is null"
  "error_code": "password_reset_token_is_null"
}

status 400 bad_request

Invalid password reset token :

{
  "error": "Invalid password reset token"
  "error_code": "invalid_password_reset_token"
}

status 400 bad_request

Invalid new password :

{
  "error": "Invalid new password"
  "error_code": "invalid_new_password"
}

status 400 bad_request

Verify email

token=abc

Parameter	Type	Required	Description
token	string	yes	Token received to confirm the ownership of the mail address

Finalize the email verification

You should receive a confirmation screen saying Account is activated if the user's account is already active or if the account is inactive but the token is valid and not expired. Otherwise, you will be directed to an error screen.

HTTP request

GET /v1/users/verify_email

HTTP response code

200 ok

Errors

`token` is null :

{
  "error": "Email verification token is null",
  "error_code": "email_verification_token_is_null"
}

status 400 bad_request

`token` is invalid :

{
  "error": "Invalid email verification token",
  "error_code": "invalid_email_verification_token"
}

status 400 bad_request

`token` is expired :

{
  "error": "Email verification token expired",
  "error_code": "email_verification_token_expired"
}

status 400 bad_request

Change email

{
  "user": {
    "email": "new_email",
    "password": "password"
  },
  "platform": "customer_space"
}

Parameter	Type	Required	Description
email	string	yes	New email
password	string	yes	Current password
platform	string	yes	Client platform to use : `dashboard` or `customer_space`

Sends a email to confirm the new email address.

HTTP request

POST /v1/users/change_email

HTTP response code

200 ok

Response

User

Errors

`password` is invalid :

{
  "error": "Invalid password",
  "error_code": "invalid_password"
}

status 403 forbidden

`email` already in use :

{
  "error": "Email already in use",
  "error_code": "email_already_in_use"
}

status 400 bad_request

Resend Change email

Enable users that do already have an email change in progress to get the email change mail without the API re-doing the email change procedure.

{
  "platform": "customer_space"
}

Parameter	Type	Required	Description
platform	string	no	Client platform to use : `dashboard` or `customer_space`

HTTP request

GET /v1/users/resend_email_change

HTTP response code

200 ok

Response

User

Errors

No `email` pending :

{
  "error":  "There's no email change procedure already pending",
  "error_code": "no_email_pending"
}

status 400 bad_request

Know about email change status

{
    "user": {
        "email_modification_in_progress" : true
    }
}

Get the status about an email update in progress

HTTP request

GET /v1/users/email_modification_in_progress

HTTP response code

200 ok

Confirm email change

email_verification_token=abc

{
    "user": {
        "email" : "new.mail@domain.com"
    }
}

Parameter	Type	Required	Description
email_verification_token	string	yes	Token received to confirm the ownership of the mail address

Finalize the switch to the new email.

HTTP request

GET /v1/users/change_email_confirmed

HTTP response code

200 ok

Errors

`email_verification_token` is null :

{
  "error": "Email verification token is null",
  "error_code": "email_verification_token_is_null"
}

status 400 bad_request

`email_verification_token` is invalid :

{
  "error": "Invalid email verification token",
  "error_code": "invalid_email_verification_token"
}

status 400 bad_request

`email_verification_token` is expired :

{
  "error": "Email verification token expired",
  "error_code": "email_verification_token_expired"
}

status 400 bad_request

Cancel email change

email_verification_token=abc

Parameter	Type	Required	Description
email_verification_token	string	yes	Token received to confirm the ownership of the mail address

Cancel the switch to the new email.

HTTP request

GET /v1/users/cancel_email_modification

HTTP response code

200 ok

Errors

`email_verification_token` is null :

{
  "error": "Email verification token is null",
  "error_code": "email_verification_token_is_null"
}

status 400 bad_request

`email_verification_token` is invalid :

{
  "error": "Invalid email verification token",
  "error_code": "invalid_email_verification_token"
}

status 400 bad_request

`email_verification_token` is expired :

{
  "error": "Email verification token expired",
  "error_code": "email_verification_token_expired"
}

status 400 bad_request

Cancel email change (authenticated user)

Cancel the switch to the new email but use authentication instead of sending email_verification_token as a parameter

HTTP request

GET /v1/users/cancel_email_modification_authenticated

HTTP response code

200 ok

Errors

`pending_mail_token` is null (no email update in progress) :

{
  "error": "There's no mail change procedure in progress",
  "error_code": "null_pending_mail"
}

status 400 bad_request

Change password (authenticated user)

{
  "change_password": {
    "new_password": "new_password",
    "current_password": "current_password"
  }
}

Parameter	Type	Required	Description
new_password	string	yes	New password
current_password	string	yes	Current password

HTTP request

POST /v1/users/change_password

HTTP response code

200 ok

Reset password (unauthenticated user)

{
    "user": {
        "password_reset_token": "password_reset_token",
        "new_password": "new_password"
    }
}

Parameter	Type	Required	Description
password_reset_token	string	yes	Temporary token received from password reset email
new_password	string	yes	New password

HTTP request

POST /v1/users/reset_password

HTTP response code

204 no content

Errors

reset token is invalid :

{
  "error": "Invalid password reset token",
  "error_code": "invalid_password_reset_token"
}

status 400 bad_request

new password is invalid :

{
  "error": "Invalid new password",
  "error_code": "invalid_password"
}

status 400 bad_request

Cancel reset password procedure

password_reset_token=abc

Parameter	Type	Required	Description
password_reset_token	string	yes	Token received to cancel the password reset procedure

HTTP request

GET /v1/users/cancel_password_reset

HTTP response code

204 no content

Errors

reset token is invalid :

{
  "error": "Invalid password reset token",
  "error_code": "invalid_password_reset_token"
}

status 400 bad_request

`reset_token` is null :

{
  "error": "Password reset token is null",
  "error_code": "password_reset_token_is_null"
}

status 400 bad_request

Set profile picture

{
    "user": {
        "extension": "png",
        "base64_picture": "iVBORw0KGgoAAAANSUhEUgAAAZAAAKQgPD...",
        "picture_url": "pictures/profile/eef477e129cbe2509d90c3aba4b5e808eef477e129cbe2509d90c3aba4b5e808.png"
    }
}

Parameter	Type	Required	Description
extension	`png`, `jpeg` or `jpg`	yes	Image extension
base64_picture	string	yes	Image - base64

Save a profile picture for the user

HTTP request

POST /v1/users/profile_picture

HTTP response code

200 ok

Errors

profile picture has an invalid extension :

{
  "error": "The extension of the picture is invalid",
  "error_code": "invalid_picture_extension"
}

status 400 bad_request

profile picture image is too large :

{
  "error": "File too large",
  "error_code": "file_too_large"
}

status 400 bad_request

Get profile picture

{
    "mime": "image/png",
    "base64": "iVBORw0KGgoAAAANSUhEUgAAAZAAAKQgPD...",
    "picture_url": "pictures/profile/eef477e129cbe2509d90c3aba4b5e808eef477e129cbe2509d90c3aba4b5e808.png"
}

Get the user profile picture

HTTP request

GET /v1/users/profile_picture

HTTP response code

200 ok

The content-type contains the mime type of the picture sent.

Delete profile picture

Remove the profile picture of the user set previously

HTTP request

DELETE /v1/users/profile_picture

HTTP response code

204 no_content

Errors

profile picture has not been set before :

{
  "error": "The profile picture does not exist",
  "error_code": "profile_picture_does_not_exist"
}

status 400 bad_request

Get profile picture of user

{
    "user": {
        "id": 12
    }
}

{
    "mime": "image/png",
    "base64": "iVBORw0KGgoAAAANSUhEUgAAAZAAAKQgPD...",
    "picture_url": "pictures/profile/eef477e129cbe2509d90c3aba4b5e808eef477e129cbe2509d90c3aba4b5e808.png"
}

Get the user profile picture of a user

HTTP request

POST /v1/users/profile_picture_for_user

Parameter	Type	Required	Description
id	integer	yes	Identifies of the user contact

HTTP response code

200 ok

The content-type contains the mime type of the picture sent.

Errors

the specified user does not exist :

{
  "error": "User does not exist",
  "error_code": "user_does_not_exist"
}

status 404 not_found

Get profile picture of users

{
    "user": {
        "ids": [12, 64]
    }
}

[{
    "user_id": "user_id",
    "mime": "image/png",
    "base64": "iVBORw0KGgoAAAANSUhEUgAAAZAAAKQgPD...",
    "picture_url": "pictures/profile/eef477e129cbe2509d90c3aba4b5e808eef477e129cbe2509d90c3aba4b5e808.png"
},
{
    "user_id": "user_id",
    "mime": "image/png",
    "base64": "iVBORw0KGgoAAAANSUhEUgAAAZAAAKQgPD...",
    "picture_url": "pictures/profile/eef477e129cbe2509d90c3aba4b5e808eef477e129cbe2509d90c3aba4b5e808.png"
  }]

Get the user profile pictures of users

HTTP request

POST /v1/users/profile_picture_for_users

Parameter	Type	Required	Description
ids	array of integers	yes	Identifies of the users

HTTP response code

200 ok

The content-type contains the mime type of the picture sent.

Errors

the specified user does not exist :

{
  "error": "User does not exist",
  "error_code": "user_does_not_exist"
}

status 404 not_found

Update favorites of user

{
    "user": {
        "favorites": [1, 6]
    }
}

Updates the favorite door_locks of the current user.

HTTP request

PATCH /v1/users/favorites

Parameter	Type	Required	Description
favorites	[integer]	yes	Identifiers of the `door_locks`

Response

User

HTTP response code

200 ok

Resend account confirmation email (unauthenticated user)

{
  "email": "mail@domain.com"
}

Parameter	Type	Required	Description
email	string	yes	User's current email

HTTP request

POST /v1/users/resend_confirmation_email

HTTP response code

204 no content

Errors

Bad parameters:

{
  "error": "Request badly formatted",
  "error_code": "request_badly_formatted"
}

status 400 bad_request

Welcome

Ping

HTTP request

GET /v1/ping

HTTP response code

200 ok

Response

{}

Updates

april 2021

deletion of /v1/shared_keys/ask_on_demand_access/:shared_key_id
deletion of /v1/shared_keys/answer_on_demand_access/:shared_key_id

august 2019

deprecation of endpoint_arn for device model
addition of post /v1/door_locks/get_k_tokens
addition of post /v1/shared_keys/get_k_tokens
deletion of post /v1/shared_keys/show_with_details, use get /v1/shared_keys/show_with_details/:id' instead

october 2018

modification of get /door_locks/show_with_lock_groups/:id to get /door_locks/show_with_lock_group/:id

august 2018

addition of post /lock_logs/user_detail with user_id parameter
addition of get /contacts/index_with_activity
addition of get /users/contacts_with_activity

april 2018

deletion of get /shared_keys/ with door_lock_id parameter, use post /shared_keys/shared_keys_for_door_lock instead
deletion of get /shared_keys/index_with_details with door_lock_id parameter, use post /shared_keys/detail_shared_keys_for_door_lock instead

february 2018

deletion of post /shared_keys/detail_users, use post /shared_keys/index_with_details instead
deletion of get /shared_keys/detail_users, use get /shared_keys/index_with_details instead
deletion of post /shared_keys/detail_door_locks, use post /shared_keys/index_with_details instead
deletion of get /shared_keys/detail_door_locks, use get /shared_keys/index_with_details instead
deletion of post /shared_keys/share_multiple_keys, user post /shared_keys instead
deletion of all on_demand_access routes. Use shared key with on_demand attribute instead

Introduction

Authentication

Introduction

Get access token with password

Errors

user_agent is missing:

Check user password

Errors

User is inactive:

uuid is missing:

Get access token with refresh_token

Errors

uuid is missing:

Get access token with client_secret

Ping

Logout

Contacts

Contact object

Get own contacts

Get own contacts with last activity

Show specific contact from contact id

Errors

user_contact does not exist :

contact does not belong to current user:

Show specific contact from user email or username

Errors

Current user is not a contact of the user_contact:

user_contact does not exist :

Send a contact request

Errors

user_contact does not exist :

Specified user_contact is the current user:

Current user and specified user_contact are already contacts :

Current user already sent the contact request to the specified user_contact :

user_contact blocked the current user :

Delete a contact

Errors

contact does not exist:

contact does not belong to current user:

Delete a contact from user

Errors

Current user is not a contact of the user_contact:

user_contact does not exist :

Delete multiple contacts

Errors

contact does not exist:

contact does not belong to current user:

Devices

Device object

Get own devices

Show specific device

Errors

device does not exist :

device does not belong to current user :

Check if uuid is already associated to user

Add a new device

Errors

uuid already associated to User :

Maximum number of devices is reached for User :

Update a device

Errors

device does not exist :

device does not belong to current user :

Delete a device

Errors

device does not exist :

device does not belong to current user :

Check app version

Errors

Invalid sent app version:

Door Locks

Door Lock object

Get own door locks

Get own door locks with lock groups

Show specific door lock

Errors

door_lock does not belong to current user :

door_lock does not exist :

door_lock access is invalid :

Show specific door lock with lock group

`user_agent` is missing:

`User` is inactive:

`uuid` is missing:

`uuid` is missing:

`user_contact` does not exist :

`contact` does not belong to current user:

Current user is not a contact of the `user_contact`:

`user_contact` does not exist :

`user_contact` does not exist :

Specified `user_contact` is the current user:

Current user and specified `user_contact` are already contacts :

Current user already sent the contact request to the specified `user_contact` :

`user_contact` blocked the current user :

`contact` does not exist:

`contact` does not belong to current user:

Current user is not a contact of the `user_contact`:

`user_contact` does not exist :

`contact` does not exist:

`contact` does not belong to current user:

`device` does not exist :

`device` does not belong to current user :

`uuid` already associated to User :

`device` does not exist :

`device` does not belong to current user :

`device` does not exist :

`device` does not belong to current user :

`door_lock` does not belong to current user :

`door_lock` does not exist :

`door_lock` access is invalid :

`door_lock` does not belong to current user :

`door_lock` does not exist :

`door_lock` does not belong to current user :

`door_lock` does not exist :

`door_lock` does not belong to current user :

`door_lock` does not exist :

`door_lock` does not exist :

`door_lock` is already installed:

`door_lock` does not belong to current user :

`door_lock` does not exist :

`description` exceeds 40 characters limit :

`door_lock` does not belong to current user :

`door_lock` does not exist :

`user` does not exist :

`door_lock` does not exist :

`door_lock` does not belong to current user :

`door_lock` does not waiting for activation :

`lock_group` is not valid :

`door_lock` does not exist :

`door_lock` does not belong to current user :

`door_lock` does not exist :

`door_lock` does not belong to current user :

`p_key` is missing :

`door_lock` does not exist :

`door_lock` does not belong to current user :

`lock_group_id` does not exist or the user is not the owner:

`door_lock` is already member of the group:

`door_lock` does not exist:

`lock_serial_number` does not exist:

`door_lock_id` does not exist:

`eniq_lock_shared_key_data` does not exist or the user is not the owner of the associated SharedKey :