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
Parameters
{
"client_id": "mobile_client_id",
"grant_type": "password",
"email_or_username": "email",
"password": "password",
"user_agent": "android/5.1",
"uuid": "uuid"
}
Returned JSON
{
"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.
Parameters
{
"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
Returned JSON
{
"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
Parameters
{
"client_id": "mobile_client_id",
"grant_type": "refresh_token",
"refresh_token": "refresh_token",
"user_agent": "android/5.1",
"uuid": "uuid"
}
Returned JSON
{
"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
Parameters
{
"client_id": "client_id",
"grant_type": "client_credentials",
"client_secret": "client_secret",
"user_agent": "android/5.1"
}
Returned JSON
{
"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
Parameters
{
"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
Parameters
{
"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
Parameters
{
"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
Parameters
{
"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
Parameters
{
"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
Parameters
{
"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
Parameters
{
"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.
Parameters
{
"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
Returned JSON
{
"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
Parameters
{
"door_lock": {
"lock_serial_number": "lock_serial_number"
}
}
Returned JSON
{
"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
Returned JSON
json { "base64": "iv.....==" }
Decoded & de-serialized content
json { "ssid": "Havr-lock", "password": "password", "serial_number": "d13fa32510a1d73e48f0c78a41f6f018", "activation_token": "activation_token" }
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
Returned JSON
json { "ssid": "Havr-lock", "password": "password" }
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
Parameters
{
"door_lock": {
"lock_serial_number": "lock_serial_number",
"activation_token": "activation_token"
}
}
Returned JSON
{
"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
Parameters
json { "door_lock": { "lock_serial_number": "lock_serial_number" } }
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
Parameters
{
"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
Parameters
{
"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
Parameters
{
"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
Parameters
{
"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
Parameters
{
"k_token": {
"door_lock_id": "door_lock_id",
"p_key": "p_key"
}
}
Returned JSON
{
"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
Parameters
{
"door_lock_ids": ["door_lock_id_1", "door_lock_id_2"]
}
Returned JSON
{
"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
Parameters
{
"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
Parameters
{
"door_lock": {
"lock_serial_number": "lock_serial_number"
}
}
Returned JSON
{
"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
Returned JSON
{
"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 userdoor_lock_id_3
: autolock (locked
,unlocked
), the user is nulldoor_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
Returned JSON
{
"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
Parameters
{
"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
Parameters
{
"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
Parameters
{
"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
Parameters
{
"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
Parameters
{
"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
Parameters
{
"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)
Returned JSON
{
"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)
Parameters
{
"lock_group": {
"ids": [1, 2, 3]
}
}
Parameter | Type | Required | Description |
---|---|---|---|
ids | int[] | yes | List of lock group ids to be retrieved |
Returned JSON
[{
"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
Get lock group info from token (if not owner, but has access, when sharing with link)
Parameters
{
"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 |
Returned JSON
{
"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
Parameters
{
"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
Parameters
{
"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
Parameters
{
"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
Parameters
{
"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
Parameters
{
"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
Parameters
{
"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 60*60*24 |
scheduled_locking_duration | int | no | Number of seconds the scheduled locking feature will be active, can't be less than 60*60 & more than 60*60*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
Parameters
{
"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
Parameters
{
"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
Parameters
{
"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)
Parameters
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
Parameters
{
"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
Parameters
{
"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
Parameters
{
"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
Show specific shared key from token (when sharing with link)
Parameters
{
"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
Parameters
{
"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
Parameters
{
"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
Parameters
{
"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
Parameters
{
"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
Parameters
{
"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
Share a key
Parameters
{
"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
Share a key with link (email)
Parameters
{
"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 |
---|---|---|---|
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
Parameters
{
"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
Parameters
{
"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
or
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
Parameters
{
"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
Parameters
{
"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
Parameters
{
"k_token": {
"shared_key_id": "shared_key_id",
"p_key": "p_key"
}
}
Returned JSON
{
"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
Parameters
{
"shared_key_ids": ["shared_key_id_1", "shared_key_id_2"]
}
Returned JSON
{
"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
Get K token from token (when sharing with link)
Parameters
{
"k_token": {
"token": "token",
"p_key": "p_key"
}
}
Returned JSON
{
"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
Parameters
{
"bug_report": {
"message": "message"
}
}
Parameter | Type | Required | Description |
---|---|---|---|
message | string | yes | Bug message |
HTTP request
POST support/v1/report_bug
Feedback
Parameters
{
"feedback": {
"message": "message"
}
}
Parameter | Type | Required | Description |
---|---|---|---|
message | string | yes | Feedback message |
HTTP request
post support/v1/feedback
Custom Service
Parameters
{
"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
Parameters
{
"eula": {
"email": "email@email.com",
"language": "en"
}
}
Parameter | Type | Required | Description |
---|---|---|---|
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
Returned JSON
{
"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
Parameters
{
"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
Parameters
{
"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
Parameters
{
"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
Parameters
{
"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 |
string | yes | ||
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
Parameters
{
"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
Parameters
{
"username_or_email": "username_or_email"
}
Returned JSON
{
"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
Parameters
{
"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 |
---|---|---|---|
string | yes | ||
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
Parameters
{
"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
Parameters
{
"forgot_password": {
"email": "email",
"platform": "customer_space"
}
}
Parameter | Type | Required | Description |
---|---|---|---|
string | yes | ||
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
Parameters
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
Parameters
{
"user": {
"email": "new_email",
"password": "password"
},
"platform": "customer_space"
}
Parameter | Type | Required | Description |
---|---|---|---|
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.
Parameters
{
"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
Returned JSON
{
"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
Parameters
email_verification_token=abc
Returned JSON
{
"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
Parameters
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)
Parameters
{
"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)
Parameters
{
"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
Parameters
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
Parameters
{
"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
Returned JSON
{
"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
Parameters
{
"user": {
"id": 12
}
}
Returned JSON
{
"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
Parameters
{
"user": {
"ids": [12, 64]
}
}
Returned JSON
[{
"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
Parameters
{
"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)
Parameters
{
"email": "mail@domain.com"
}
Parameter | Type | Required | Description |
---|---|---|---|
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
, useget /v1/shared_keys/show_with_details/:id'
instead
october 2018
- modification of
get /door_locks/show_with_lock_groups/:id
toget /door_locks/show_with_lock_group/:id
august 2018
- addition of
post /lock_logs/user_detail
withuser_id
parameter - addition of
get /contacts/index_with_activity
- addition of
get /users/contacts_with_activity
april 2018
- deletion of
get /shared_keys/
withdoor_lock_id
parameter, usepost /shared_keys/shared_keys_for_door_lock
instead - deletion of
get /shared_keys/index_with_details
withdoor_lock_id
parameter, usepost /shared_keys/detail_shared_keys_for_door_lock
instead
february 2018
- deletion of
post /shared_keys/detail_users
, usepost /shared_keys/index_with_details
instead - deletion of
get /shared_keys/detail_users
, useget /shared_keys/index_with_details
instead - deletion of
post /shared_keys/detail_door_locks
, usepost /shared_keys/index_with_details
instead deletion of
get /shared_keys/detail_door_locks
, useget /shared_keys/index_with_details
insteaddeletion of
post /shared_keys/share_multiple_keys
, userpost /shared_keys
insteaddeletion of all
on_demand_access
routes. Use shared key withon_demand
attribute instead