NAV Navbar
json

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

Companies

Company object

{
    "id": 1,
    "user_id": 6,
    "existing_status": "active",
    "max_employees": 100,
    "name": "name",
    "activity": "delivery"
}
Attribute Type Required Description
id integer yes Identifier of the company
name string yes Name of the company
user_id integer yes Identifier of the company owner
max_employees integer yes Maximum number of employees for the company
existing_status active, pending or deleted yes Status of the company

Get all companies

Returns all the companies managed by the current user.

HTTP request

GET /v1/companies

HTTP response code

200 ok

Response

[Company]

Show specific company

HTTP request

GET /v1/companies/:company_id

HTTP response code

200 ok

Response

Company

 Errors

company_id does not exist :

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

status 404 not_found

company does not belong to current user :

{
  "error": "Can't access another one's company"
}

status 403 forbidden

Show employees of company

Returns employees of the current user's company

HTTP request

GET /v1/companies/company_with_employees

HTTP response code

200 ok

Returned JSON

{
  "company": "Company",
  "employees": ["User"]
} 

 Errors

status 404 not_found

{
  "error": "Company does not exist",
  "error_code": "company_does_not_exist"
}

Show specific company employees

Parameters

{ 
  "company": {
    "company_id": "company_id"
   }
}

Shows all employees of a specific company.

Parameter Type Required Description
company_id integer yes Identifier of the company object which we want the employees

HTTP request

POST /v1/companies/employees_of_company

HTTP response code

200 ok

Response

[User]

Errors

company does not exist :

{
  "error": "Company does not exist",
  "error_code": "company_does_not_exist"
}

status 404 not_found

company does not belong to current user :

{
  "error": "Can't access another one's company",
  "error_code": "cant_access_another_ones_company"
}

status 403 forbidden

Create a new company

Parameters

{
        "company": {
             "max_employees": 50,
             "name": "company_name",
             "activity": "other"
        }
    }

Will create a company item.

Parameter Type Required Description
max_employees integer yes Maximum number of employees this company will hold (can be modified later)
name string yes Name of the company
activity string yes General activity of the company

The activity must be one of the following: delivery, other

HTTP request

POST /v1/companies

HTTP response code

201 created

Response

Company

Update a company

Parameters

{
"company": {
            "max_employees": "new_max_employees"
        }
}
Parameter Type Required Description
max_employees integer no Maximum number of employees this company will hold (can be modified later)
name string no Name of the company
activity string no General activity of the company

HTTP request

PATCH /v1/companies/:company_id

HTTP response code

200 ok

Response

Company

 Errors

company_id does not exist :

{
  "error": "Company does not exist",
  "error_code": "company_does_not_exist"
}

status 404 not_found

company does not belong to current user :

{
  "error": "Can't access another one's company",
  "error_code" : "company_does_not_exist"
}

status 403 forbidden

Delete a company

HTTP request

DELETE /v1/companies/:company_id

HTTP response code

200 ok

 Errors

company_id does not exist :

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

status 404 not_found

company does not belong to current user :

{
  "error": "Can't access another one's company"
}

status 403 forbidden

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",
                "delete_accesses": true
            }
}
Parameter Type Required Description
email_or_username string yes Username or email of the user we want to remove
delete_accesses bool false Option to delete all keys shared with the contact, created by the requester

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"],
      "delete_accesses": true
    }
}
Parameter Type Required Description
ids integer[] yes Identifier of the contacts we want to remove
delete_accesses bool false Option to delete all keys shared with the contact, created by the requester

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

Do not disturb state

Do not disturb state object

{
    "id": 3,
    "user_id": 6,
    "door_lock_id": 1,
    "active": true,
    "manual": false,
    "start_date": "2017-03-14T17:00:00Z",
    "end_date": "2017-04-14T17:00:00Z",
    "recurrency": "week",
    "existing_status": "active"
}
Attribute Type Required Description
id integer yes Identifier of the do_not_disturb_state
user_id integer yes Identifier of the do_not_disturb_state owner
door_lock_id integer yes Identifier of the door_lock
active boolean yes Whether the do_not_disturb_state is active
start_date date yes Start of the do_not_disturb_state period
end_date date no End of the do_not_disturb_stateperiod
recurrency day, week, month, year or none yes Recurrency of the do_not_disturb_state
manual boolean no Whether the do_not_disturb_state was set by an user or not
existing_status active, pending or deleted yes Existing status of the do_not_disturb_state

Show specific do not disturb states

HTTP request

GET /v1/do_not_disturb_states/:do_not_disturb_state_id

HTTP response code

200 ok

Response

DoNotDisturbState

 Errors

do_not_disturb_state_id does not exist :

{
  "error": "Do not disturb state does not exist",
  "error_code": "do_not_disturb_state_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

Show specific door lock do not disturb states

Parameters

{ 
  "do_not_disturb_state": {
    "door_lock_id": "door_lock_id"
   }
}
Parameter Type Required Description
door_lock_id integer yes Identifier of the door lock which we want the do not disturb states

Shows all do not disturb states of a specific door lock.

HTTP request

POST /v1/do_not_disturb_states/do_not_disturb_states_of_lock

HTTP response code

200 ok

Response

[DoNotDisturbState]

 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

Create a new do not disturb state

Parameters

{
        "do_not_disturb_state": {
            "door_lock_id": "door_lock_id",
            "start_date": "2018-07-20T07:04:54Z",
             "end_date": "2018-08-20T07:04:54Z",
             "recurrency": "week"
        }
    }
Parameter Type Required Description
door_lock_id integer yes Identifier of the door lock
start_date date no Start of the do not disturb state, zulu format, not millisecond
end_date date no End of the do not disturb state, zulu format, no millisecond
recurrency "day", "week", "month", "year" or "none" no Reccurency of the do not disturb state
active boolean yes Boolean that indicates whether the do not disturb state is active

Will create a do not disturb state item. If you are not the owner or have an admin access to the specified door_lock, the request will be sent to all the admins of the door_lock.

HTTP request

POST /v1/do_not_disturb_states

HTTP response code

201 created

Response

DoNotDisturbState

 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 lock",
  "error_code": "cant_access_another_ones_door_lock"
}

status 403 forbidden

recurrency is invalid :

{
  "error": "Day recurrency cannot be applied to a multiple days period",
  "error_code": "day_recurrency_cannot_be_applied_to_multiple_day_period"
}

status 403 forbiden

date format is invalid :

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

status 400 bad_request

Update a do not disturb state

Parameters

{
"do_not_disturb_state": {
            "active": false
        }
}
Parameter Type Required Description
start_date date no Start of the do not disturb state, zulu format, not millisecond
end_date date no End of the do not disturb state, zulu format, no millisecond
recurrency "day", "week", "month" or "year" no Reccurendy of the do not disturb state
active boolean no Boolean that indicates whether the do not disturb state is active

HTTP request

PATCH /v1/do_not_disturb_states/:do_not_disturb_state_id

HTTP response code

200 ok

Response

DoNotDisturbState

Errors

do_not_disturb_state_id does not exist :

{
  "error": "Do not disturb state does not exist",
  "error_code": "do_not_disturb_state_does_not_exist"
}

status 404 not_found

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 lock",
  "error_code": "cant_access_another_ones_door_lock"
}

status 403 forbidden

recurrency is invalid :

{
  "error": "Day recurrency cannot be applied to a multiple days period",
  "error_code": "day_recurrency_cannot_be_applied_to_multiple_day_period"
}

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

Answer pending do not disturb state

Parameters

{
  "do_not_disturb_state": {
    "do_not_disturb_state_id": "do_not_disturb_state_id",
    "accepted": true
  }
}
Parameter Type Required Description
do_not_disturb_state_id integer yes Identifier of the do not disturb state
accepted boolean yes Answer to the request

Only the owner or admins of the door_lock can answer.

HTTP request

POST /v1/do_not_disturb_states/answer_pending_do_not_disturb_state

HTTP response code

200 ok

Response

DoNotDisturbState

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

shared_key does not exist :

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

status 404 not_found

shared_key is not pending :

{
  "error": "Shared key is not pending",
  "error_code": "shared_key_currently_not_pending"
}

status 404 not_found

Delete a do not disturb state

HTTP request

DELETE /v1/do_not_disturb_states/:do_not_disturb_state_id

HTTP response code

204 no_content

 Errors

do_not_disturb_state_id does not exist :

{
  "error": "Do not disturb state does not exist",
  "error_code": "do_not_disturb_state_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 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",
    "confirmation_level": "confirmation_level",
    "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
confirmation_level [0..3] no Confirmation level 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
confirmation_level [0..3] no Confirmation level 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
confirmation_level [0..3] no Confirmation level 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:

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

Employments

Employment object

{
    "id": 1,
    "user_id": 6,
    "existing_status": "active",
    "company_id": 1
}
Attribute Type Required Description
id integer yes Identifier of the employment
company_id integer yes Identifier of the company
user_id integer yes Identifier of the employment owner
existing_status active, pending, deleted, rejected yes Existing status of the employment

Get all employments

Returns all the employments of the current user.

HTTP request

GET /v1/employments

HTTP response code

200 ok

Response

[Employment]

Show specific employment

HTTP request

GET /v1/employments/:employment_id

HTTP response code

200 ok

Response

Employment

Errors

employment_id does not exist :

{
  "error": "Employment does not exist",
  "error_code": "employment_does_not_exist"
}

status 404 not_found

company does not belong to current user :

{
  "error": "Can't access another one's company",
  "error_code": "cant_access_another_ones_company"
}

status 403 forbidden

Show specific company employments

Parameters

{ 
  "employment": {
    "company_id": "company_id"
   }
}

Shows all employments of a specific company.

HTTP request

POST /v1/employments/employments_of_company

HTTP response code

200 ok

Response

[Employment]

 Errors

company does not exist :

{
  "error": "Company does not exist",
  "error_code": "company_does_not_exist"
}

status 404 not_found

company does not belong to current user :

{
  "error": "Can't access another one's company",
  "error_code": "cant_access_another_ones_company"
}

status 403 forbidden

Create a new employment

Parameters

{
        "employment": {
            "user_id": "user_id",
             "company_id": "company_id"
        }
    }
Parameter Type Required Description
user_id integer yes Identifier of the user
existing_status active, deleted or pending no Identifier of the company
company_id integer yes Identifier of the company

Will create an employment item.

HTTP request

POST /v1/employments

HTTP response code

201 created

Response

Employment

Errors

user_id does not exist :

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

status 404 not_found

company_id does not exist :

{
  "error": "Company does not exist",
  "error_code": "company_does_not_exist"
}

status 404 not_found

employment already exist :

{
  "error": "Employment already exist",
  "error_code": "employment_already_exists"
}

status 400 bad_request

user is owner of company :

{
  "error": "User is owner of company",
  "error_code": "user_is_owner_of_company"
}

status 400 bad_request

company does not belong to current user :

{
  "error": "Can't access another one's company",
  "error_code": "cant_access_another_ones_company"
}

status 403 forbidden

Delete an employment

HTTP request

DELETE /v1/employments/:employment_id

HTTP response code

200 ok

Errors

employment_id does not exist :

{
  "error": "Employment does not exist",
   "error_code": "employment_does_not_exist"
}

status 404 not_found

company does not belong to current user :

{
  "error": "Can't access another one's company",
  "error_code": "cant_access_another_ones_company"
}

status 403 forbidden

Answer pending request

Parameters

{
  "employment": {
    "accepted": true
  }
}
Parameter Type Required Description
accepted boolean yes The response of the user

HTTP request

POST /v1/employments/answer_employment_request/:employment_id

HTTP response code

200 ok

Errors

employment_id does not exist :

{
  "error": "Employment does not exist",
  "error_code": "employment_does_not_exist"
}

status 404 not_found

employment_id does not concern the current user :

{
  "error": "Can't access another one's employment",
  "error_code": "cant_access_another_ones_employment"
}

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 employment
name string yes Description of the group
user_id integer yes Identifier of the employment 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

Employment

with floor_map: FloorMapModel

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

Employment

with floor_map: FloorMapModel and its base64_picture attribute

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 employment
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

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

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

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

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, owner_access_confirmation, owner_booking_confirmation, owner_booking_answer 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
owner_access_confirmation user_initials, user_name, user_username, door_lock_description, door_lock_id
owner_booking_confirmation user_initials, user_name, user_username, door_lock_description, door_lock_id
owner_booking_answer user_initials, user_name, user_username, door_lock_description, door_lock_id
employment_request user_initials, user_name, user_username , company_description

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,
    "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 yes Identifier of the door_lock
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

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 }

 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]

 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]

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

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 }, "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 :

{
  "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

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"],
      "recurrency": "day"
  }
}
Parameter Type Required Description
email string yes if emails is empty Email of the user
emails string[] yes if email is empty Email of the users to share the access with
start_date date no Start of the access
end_date date no End of the access, zulu time without millisecond
admin boolean yes Whether the user will be able to administrate the lock
recurrency day, week, month or year no Recurrency of the access
lock_list_ids integer[] no Share key to a list of door locks
lock_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,
  "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
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

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

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

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

Answer pending shared key

Parameters

{
  "shared_key": {
    "shared_key_id": "shared_key_id",
    "accepted": true
  }
}
Parameter Type Required Description
shared_key_id integer yes Identifier of the shared key
accepted boolean yes Whether is request is accepted

Only the owner of the door_lock can answer.

HTTP request

POST /v1/shared_keys/answer_pending_shared_key

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

 shared_key is not pending :

{
  "error": "Shared key is not pending",
  "error_code": "cant_answer_not_pending_shared_key"
}

status 404 not_found

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
email string yes Recipient of the email
language string yes Language of the email : Supported languages are FR and EN

HTTP request

POST support/v1/send_eula

Website privacy url

HTTP request

GET support/v1/website_privacy_url

HTTP response code

200 ok

Response

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

Synchronization

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

Returned JSON

["shared_key": SharedKey, "door_lock": DoorLock, "contacts": Contact, "lock_groups": LockGroup, "users": User]

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
email string yes Email
first_name string yes First name
last_name string yes Last name
phone_number string no Phone number
password string yes Password
preferred_language en or fr no Preferred language
favorites integer[] yes Identifiers of the favorite door_locks of the user
picture_url string no Url to download the profile picture of the user, check with the admin for the endpoint

Get own info

Returns all the info related to the authenticated user.

HTTP request

GET /v1/users

HTTP response code

200 ok

Response

User

Errors

email is not verified for user :

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

status 403 forbidden

user account is not active :

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

status 403 forbidden

Show specific user

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

HTTP request

GET /v1/users/:user_id

HTTP response code

200 ok

Response

User

Errors

user does not exist :

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

status 404 not_found

Get user contacts

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

HTTP request

GET /v1/users/contacts

HTTP response code

200 ok

Response

[User]

Get user contacts with last activity

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

HTTP request

GET /v1/users/contacts_with_activity

HTTP response code

200 ok

Response

[{User, "last_activity": LockLog}]

Get own pending contacts

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

HTTP request

GET /v1/users/pending_contacts

HTTP response code

200 ok

Response

[User]

Get own pending requests

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

HTTP request

GET /v1/users/pending_requests

HTTP response code

200 ok

Response

[Contact, "user": User]

Errors

email is not verified for user :

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

status 403 forbidden

user account is not active :

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

status 403 forbidden

Answer a pending request

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..."
   },
   "employment": {
      "employment_id": "employment_id"
   },
  "user_preferences": {
    "newsletter": true,
    "updates": true,
    "eula": true
  }
}
Parameter Type Required Description
email string yes Email
first_name string yes First name
last_name string yes Last name
phone_number string no Phone number
password string yes Password
extension png, jpeg or jpg yes if base64_picture is set Image extension
base64_picture string no Image - base64
preferred_language en or fr no Preferred language
employment dictionary no Contains the employment_id
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
email string yes Email
platform string yes Client platform to use : dashboard or customer_space

Sends a email to reset the password to specified email.

HTTP request

POST /support/v1/forgot_password

HTTP response code

204 no content

Errors

email does not exist :

{
  "error": "Unknown email address"
}

status 404 not_found

Password token is null :

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

status 400 bad_request

Invalid password reset token :

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

status 400 bad_request

Invalid new password :

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

status 400 bad_request

Verify email

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
email string yes New email
password string yes Current password
platform string yes Client platform to use : dashboard or customer_space

Sends a email to confirm the new email address.

HTTP request

POST /v1/users/change_email

HTTP response code

200 ok

Response

User

Errors

password is invalid :

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

status 403 forbidden

email already in use :

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

status 400 bad_request

Resend Change email

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

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
email string yes User's current email

HTTP request

POST /v1/users/resend_confirmation_email

HTTP response code

204 no content

Errors

Bad parameters:

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

status 400 bad_request

Welcome

Ping

HTTP request

GET /v1/ping

HTTP response code

200 ok

Response

{}

Updates

april 2021

august 2019

october 2018

august 2018

april 2018

february 2018