homeit
API docs by Redocly

homeit Core API (2.7)

Download OpenAPI specification:

homeit Backend: backend@homeit.io Terms of Service

Introduction

homeit is a property management system, designed for short-term rentals. The homeit platform allows you to manage all your properties from a single place.

The homeit Core API allows you to view your properties, create keys and check entry logs.

If you have any suggestions or questions regarding this API, please send us an email.

These documentation pages were automatically generated from an OpenAPI file, and are intended to be used by developers as detailed descriptions of our API.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC 2119] [RFC 8174] when, and only when, they appear in all capitals, as shown here.

What this API does for partners

The homeit Core API allows partners to integrate with the homeit network.

  • Channel Managers can issue keys automatically for each reservation, check if guests have checked in, or even open a door on request.
  • Integration Platforms can provide all the functionality of the homeit system to their clients and let them automate processes seamlessly.

Our API is REST-compliant and uses resource-oriented URLs and common HTTP response codes to indicate API errors.

This document is entirely written in English. Similarly, all enumerated values used in this API are also written in English.

Overview

The API is available at https://api.homeit.io/v2.

This API consists of several resource routes. Each resource route allows a user to find, create, update or remove a specific resource type.

All resource routes follow the same structure and offer similar high-level functionality. When applicable, resource routes include the following endpoints:

  • GET /{{resource}}: Find all available resources the authenticated user is allowed to access. Search query parameters may be used to filter results.
  • POST /{{resource}}: Create a new resource.
  • GET /{{resource}}/{{id}}: Create a specific resource by its ID.
  • PUT /{{resource}}/{{id}}: Update a specific resource.
  • DELETE /{{resource}}/{{id}}: Remove a specific resource.

For example, to update the name of a Key resource with ID 123456 to "HOMEIT", an HTTP PUT request should be sent to https://api.homeit.io/v2/keys/123456 with the body {"name":"HOMEIT"}.

Document Structure

This document's first sections provide details on how to use the API, including security considerations, data formats, and testing instructions.

Then, all resource routes are listed. In this section, you will find request and response formats for each resource type, as well as example responses and code snippets.

Finally, we include the data model for each resource type, along with data type requirements and example values. Fields present in a resource document but not included in the resource's data model should not be used, as they are subject to change at any moment without prior notice. Deprecated fields will be marked as such and should also not be used.

Security

HTTPS

All API requests must be made over HTTPS. Requests made over HTTP will be redirected to HTTPS.

Authentication

Most API routes require authentication using an API Key or a Bearer token. Requests made without authentication will fail with a 401 Unauthorized error.

When applicable, requests may be authenticated using one of the following methods:

  • API Key: Used as a query parameter. Example: https://api.homeit.io/v2/resource?apikey={{apikey}}
  • OAuth2: The OAuth2 flows produce tokens in the JSON Web Token format. This authentication method is fully compliant with the OAuth2 standard. These tokens can be used as a bearer token in the Authorization HTTP header. Example: Authorization: Bearer {{token}}

You can find additional information in the Authentication section.

Rate Limits

If too many requests are sent in a short amount of time, a 429 Too Many Requests error is returned until request rates return to normal. Client applications should honour the following request rate limits:

  • 100 requests per second
  • 1000 requests per minute

Pagination

All operations are automatically paginated in the following way:

{ docs: [], total: 120, limit: 10, skip: 0 }

Operations which return a single resource are still paginated, but will show total and limit values of 1.

You can define a limit on the number of documents to be returned which can range between 1 and 100 items. The default is 10 items.

Similarly, you can skip any number of documents, effectively setting the starting position by providing an index. This index should not exceed the total amount of available documents.

For example, https://api.homeit.io/v2/keys?limit=100&skip=10 returns at most 100 items, skipping the first 10 documents.

Sorting

All list operations can be sorted by any of the document's fields, as long as its assigned value is a number, a string or a date.

The sortBy parameter provides the key you want to sort by, while the order parameter tells the API in which order you want your results: asc for ascending and desc for descending.

For example, https://api.homeit.io/v2/keys?sortBy=id&order=desc returns items sorted by ID, in descending order.

Hypermedia

All operations return a collection of hypermedia links to other pages of the same request or other related requests. This collection follows the HAL format.

This behavior can be disabled by setting the hypermedia query parameter to false.

For example, https://api.homeit.io/v2/keys?hypermedia=false returns a response without hypermedia information.

Formatting

JSON

All API responses are given in JSON format. All requests bodies should also be provided as JSON.

Request body content type should be application/json. Response body content type will always be application/json+hal.

Dates

All dates follow the ISO 8601 format standard.

Errors

In case of internal or external error, the following HTTP error codes will be returned:

  • 401 Unauthorized: Request lacks valid authentication credentials.
  • 403 Forbidden: Access to requested resource is not allowed.
  • 404 Not Found: Requested resource could not be found. Also returned if the requested route could not be found.
  • 405 Method Not Allowed: Request HTTP method is not allowed on the requested route or resource.
  • 409 Conflict: Requested data changes create conflicts with current state of resource.
  • 422 Unprocessable Entity: Payload validation failed. Usually accompanied by a detailed explanation message.
  • 429 Too Many Requests: Request rate exceeded rate limits.

Other 4XX and 5XX error codes may be returned upon malformed request payload or gateway errors.

During normal operation, the following HTTP codes will be returned:

  • 201 Created: Successful resource creation operations.
  • 200 OK: All other successful operations.

Testing

All operations accept a dry boolean query parameter. When testing, you can enable dry-run mode by setting this parameter to true.

In this mode, all side-effects (such as database writes) are disabled, but responses are still returned as normal.

For example, an update request to https://api.homeit.io/v2/keys/123?dry=true would return the updated document, but no changes would be persisted.

Feedback

If you would like to report an error or have any suggestions or questions regarding this API, please send us an email to backend@homeit.io. Any feedback is greatly appreciated. Please, use English for all communications.

Changelog

2020-11-26

  • Add Overview, Structure and Errors sections.

2020-02-13

  • First release of this documentation page.

Boxes

Get all Boxes.

Get all Boxes you have access to. You may use filters to narrow your search.

Authorizations:
(oauthapikey)
query Parameters
id
Array of integers <int64> [ items <int64 > ]
Example: id=123

A list of resource IDs.

name
string
Example: name=Example

The resource's name, or part of it. Case-insensitive.

description
string
Example: description=Example

The resource's description, or part of it. Case-insensitive.

mac
Array of strings
Example: mac=8426ab951c73

A list of resource MAC addresses.

isActive
boolean
Example: isActive=true

Filter by active status.

createdBefore
string
Example: createdBefore=2020-01-01T00:00:00.000Z

Filter by creation date. Format MUST comply with ISO 8601.

createdAfter
string
Example: createdAfter=2020-01-01T00:00:00.000Z

Filter by creation date. Format MUST comply with ISO 8601.

dry
boolean
Default: false
Example: dry=true

Enable dry-run mode, for testing.

hypermedia
boolean
Default: true
Example: hypermedia=false

Disable hypermedia links in response.

Responses

Request samples 

curl -XGET "https://api.homeit.io/v2/boxes?id=1&id=2&name=Example" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer {{token}}"

Response samples

Content type
application/json+hal
{
  • "docs": [
    ],
  • "total": 2,
  • "limit": 10,
  • "skip": 0
}

Get a Box.

Get a single Box by ID or MAC address.

Authorizations:
(oauthapikey)
path Parameters
id
string
Example: 123

A resource's ID or MAC address.

Responses

Request samples 

curl -XGET "https://api.homeit.io/v2/boxes/1" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer {{token}}"

Response samples

Content type
application/json+hal
{
  • "docs": [
    ],
  • "total": 1,
  • "limit": 1,
  • "skip": 0
}

Update a Box.

Update a Box you own.

Authorizations:
(oauthapikey)
path Parameters
id
string
Example: 123

A resource's ID or MAC address.

Request Body schema: application/json
required

Box object.

name
string

The Box's name.

description
string

The Box's description.

Responses

Request samples

Content type
application/json
{
  • "name": "Box 1",
  • "description": "This is a Box."
}

Response samples

Content type
application/json+hal
{
  • "docs": [
    ],
  • "total": 1,
  • "limit": 1,
  • "skip": 0
}

Delete a Box.

Delete a Box you own.

Authorizations:
(oauthapikey)
path Parameters
id
string
Example: 123

A resource's ID or MAC address.

Responses

Request samples 

curl -XDELETE "https://api.homeit.io/v2/boxes/1" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer {{token}}"

Response samples

Content type
application/json+hal
{
  • "docs": [
    ],
  • "total": 1,
  • "limit": 1,
  • "skip": 0
}

Doors

Get all Doors.

Get all Doors you have access to. You may use filters to narrow your search.

Authorizations:
(oauthapikey)
query Parameters
id
Array of integers <int64> [ items <int64 > ]
Example: id=123

A list of resource IDs.

name
string
Example: name=Example

The resource's name, or part of it. Case-insensitive.

description
string
Example: description=Example

The resource's description, or part of it. Case-insensitive.

box
Array of integers <int64> [ items <int64 > ]
Example: box=123

A list of Box IDs.

property
Array of integers <int64> [ items <int64 > ]
Example: property=123

A list of Property IDs.

keypad
Array of integers <int64> [ items <int64 > ]
Example: keypad=123

A list of Keypad IDs.

lock
Array of integers <int64> [ items <int64 > ]
Example: lock=123

A list of Lock IDs.

isActive
boolean
Example: isActive=true

Filter by active status.

createdBefore
string
Example: createdBefore=2020-01-01T00:00:00.000Z

Filter by creation date. Format MUST comply with ISO 8601.

createdAfter
string
Example: createdAfter=2020-01-01T00:00:00.000Z

Filter by creation date. Format MUST comply with ISO 8601.

dry
boolean
Default: false
Example: dry=true

Enable dry-run mode, for testing.

hypermedia
boolean
Default: true
Example: hypermedia=false

Disable hypermedia links in response.

Responses

Request samples 

curl -XGET "https://api.homeit.io/v2/doors?id=1&id=2&name=Example" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer {{token}}"

Response samples

Content type
application/json+hal
{
  • "docs": [
    ],
  • "total": 2,
  • "limit": 10,
  • "skip": 0
}

Get a Door.

Get a single Door by ID or MAC address.

Authorizations:
(oauthapikey)
path Parameters
id
integer <int64>
Example: 123

A resource's ID.

Responses

Request samples 

curl -XGET "https://api.homeit.io/v2/doors/1" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer {{token}}"

Response samples

Content type
application/json+hal
{
  • "docs": [
    ],
  • "total": 1,
  • "limit": 1,
  • "skip": 0
}

Update a Door.

Update a Door you own.

Authorizations:
(oauthapikey)
path Parameters
id
integer <int64>
Example: 123

A resource's ID.

Request Body schema: application/json
required

Door object.

name
string

The Door's name.

description
string

The Door's description.

Responses

Request samples

Content type
application/json
{
  • "name": "Door 1",
  • "description": "This is a Door."
}

Response samples

Content type
application/json+hal
{
  • "docs": [
    ],
  • "total": 1,
  • "limit": 1,
  • "skip": 0
}

Delete a Door.

Delete a Door you own.

Authorizations:
(oauthapikey)
path Parameters
id
integer <int64>
Example: 123

A resource's ID.

Responses

Request samples 

curl -XDELETE "https://api.homeit.io/v2/doors/1" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer {{token}}"

Response samples

Content type
application/json+hal
{
  • "docs": [
    ],
  • "total": 1,
  • "limit": 1,
  • "skip": 0
}

Keys

Get all Keys.

Get all Keys you have access to. You may use filters to narrow your search.

Authorizations:
(oauthapikey)
query Parameters
id
Array of integers <int64> [ items <int64 > ]
Example: id=123

A list of resource IDs.

name
string
Example: name=Example

The resource's name, or part of it. Case-insensitive.

description
string
Example: description=Example

The resource's description, or part of it. Case-insensitive.

door
Array of integers <int64> [ items <int64 > ]
Example: door=123

A list of Door IDs.

isActive
boolean
Example: isActive=true

Filter by active status.

createdBefore
string
Example: createdBefore=2020-01-01T00:00:00.000Z

Filter by creation date. Format MUST comply with ISO 8601.

createdAfter
string
Example: createdAfter=2020-01-01T00:00:00.000Z

Filter by creation date. Format MUST comply with ISO 8601.

dry
boolean
Default: false
Example: dry=true

Enable dry-run mode, for testing.

hypermedia
boolean
Default: true
Example: hypermedia=false

Disable hypermedia links in response.

Responses

Request samples 

curl -XGET "https://api.homeit.io/v2/keys?id=1&id=2&name=Example" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer {{token}}"

Response samples

Content type
application/json+hal
{
  • "docs": [
    ],
  • "total": 2,
  • "limit": 10,
  • "skip": 0
}

Create a Key.

Create a new Key.

Authorizations:
(oauthapikey)
Request Body schema: application/json
required

Key object.

name
string

The Key's name.

description
string

The Key's description.

doors
Array of integers <int64> <= 10 items unique [ items <int64 > ]

The numeric IDs of the Doors this Key can open.

numericCode
string

The code to be entered in the Keypads. Always 5 digits.

checkIn
string

Check in date and time, after which the key becomes valid. Format MUST comply with ISO 8601.

checkOut
string

Check out date and time, after which the key becomes invalid. Format MUST comply with ISO 8601.

isExpiring
boolean

Does the Key expire. If false, the Key is permanent and check out value can be ignored.

canUse
Array of strings unique
Items Enum: "app" "sms" "keypad"

A list of methods in which the Key can be used.

tags
Array of strings unique

List of tags.

Responses

Request samples

Content type
application/json
{
  • "id": 123
}

Response samples

Content type
application/json+hal
{
  • "docs": [
    ],
  • "total": 1,
  • "limit": 1,
  • "skip": 0
}

Get a Key.

Get a single Key by ID or MAC address.

Authorizations:
(oauthapikey)
path Parameters
id
integer <int64>
Example: 123

A resource's ID.

Responses

Request samples 

curl -XGET "https://api.homeit.io/v2/keys/1" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer {{token}}"

Response samples

Content type
application/json+hal
{
  • "docs": [
    ],
  • "total": 1,
  • "limit": 1,
  • "skip": 0
}

Update a Key.

Update a Key you own.

Authorizations:
(oauthapikey)
path Parameters
id
integer <int64>
Example: 123

A resource's ID.

Request Body schema: application/json
required

Key object.

name
string

The Key's name.

description
string

The Key's description.

doors
Array of integers <int64> <= 10 items unique [ items <int64 > ]

The numeric IDs of the Doors this Key can open.

checkIn
string

Check in date and time, after which the key becomes valid. Format MUST comply with ISO 8601.

checkOut
string

Check out date and time, after which the key becomes invalid. Format MUST comply with ISO 8601.

isExpiring
boolean

Does the Key expire. If false, the Key is permanent and check out value can be ignored.

canUse
Array of strings unique
Items Enum: "app" "sms" "keypad"

A list of methods in which the Key can be used.

tags
Array of strings unique

List of tags.

Responses

Request samples

Content type
application/json
{
  • "name": "Key 1",
  • "description": "This is a Key.",
  • "doors": [
    ],
  • "checkIn": "2020-01-01T00:00:00.000Z",
  • "checkOut": "2021-01-01T00:00:00.000Z",
  • "isExpiring": true,
  • "canUse": [
    ]
}

Response samples

Content type
application/json+hal
{
  • "docs": [
    ],
  • "total": 1,
  • "limit": 1,
  • "skip": 0
}

Delete a Key.

Delete a Key you own.

Authorizations:
(oauthapikey)
path Parameters
id
integer <int64>
Example: 123

A resource's ID.

Responses

Request samples 

curl -XDELETE "https://api.homeit.io/v2/keys/1" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer {{token}}"

Response samples

Content type
application/json+hal
{
  • "docs": [
    ],
  • "total": 1,
  • "limit": 1,
  • "skip": 0
}

Key Events

Get all Key Events.

Get all Key Events you have access to. You may use filters to narrow your search.

Authorizations:
(oauthapikey)
query Parameters
id
Array of integers <int64> [ items <int64 > ]
Example: id=123

A list of resource IDs.

door
Array of integers <int64> [ items <int64 > ]
Example: door=123

A list of Door IDs.

source
Array of strings
Items Enum: "keypad" "app" "sms" "owner"
Example: source=keypad

A list of Key Event sources.

createdBefore
string
Example: createdBefore=2020-01-01T00:00:00.000Z

Filter by creation date. Format MUST comply with ISO 8601.

createdAfter
string
Example: createdAfter=2020-01-01T00:00:00.000Z

Filter by creation date. Format MUST comply with ISO 8601.

dry
boolean
Default: false
Example: dry=true

Enable dry-run mode, for testing.

hypermedia
boolean
Default: true
Example: hypermedia=false

Disable hypermedia links in response.

Responses

Request samples 

curl -XGET "https://api.homeit.io/v2/keyevents?id=1&id=2&name=Example" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer {{token}}"

Response samples

Content type
application/json+hal
{
  • "docs": [
    ],
  • "total": 2,
  • "limit": 10,
  • "skip": 0
}

Get a Key Event.

Get a single Key Event by ID or MAC address.

Authorizations:
(oauthapikey)
path Parameters
id
integer <int64>
Example: 123

A resource's ID.

Responses

Request samples 

curl -XGET "https://api.homeit.io/v2/keyevents/1" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer {{token}}"

Response samples

Content type
application/json+hal
{
  • "docs": [
    ],
  • "total": 1,
  • "limit": 1,
  • "skip": 0
}

Keypads

Get all Keypads.

Get all Keypads you have access to. You may use filters to narrow your search.

Authorizations:
(oauthapikey)
query Parameters
id
Array of integers <int64> [ items <int64 > ]
Example: id=123

A list of resource IDs.

name
string
Example: name=Example

The resource's name, or part of it. Case-insensitive.

description
string
Example: description=Example

The resource's description, or part of it. Case-insensitive.

type
Array of strings
Items Enum: "wired" "ble"
Example: type=ble

A list of Keypad types.

mac
Array of strings
Example: mac=8426ab951c73

A list of resource MAC addresses.

isActive
boolean
Example: isActive=true

Filter by active status.

createdBefore
string
Example: createdBefore=2020-01-01T00:00:00.000Z

Filter by creation date. Format MUST comply with ISO 8601.

createdAfter
string
Example: createdAfter=2020-01-01T00:00:00.000Z

Filter by creation date. Format MUST comply with ISO 8601.

dry
boolean
Default: false
Example: dry=true

Enable dry-run mode, for testing.

hypermedia
boolean
Default: true
Example: hypermedia=false

Disable hypermedia links in response.

Responses

Request samples 

curl -XGET "https://api.homeit.io/v2/keypads?id=1&id=2&name=Example" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer {{token}}"

Response samples

Content type
application/json+hal
{
  • "docs": [
    ],
  • "total": 2,
  • "limit": 10,
  • "skip": 0
}

Get a Keypad.

Get a single Keypad by ID or MAC address.

Authorizations:
(oauthapikey)
path Parameters
id
string
Example: 123

A resource's ID or MAC address.

Responses

Request samples 

curl -XGET "https://api.homeit.io/v2/keypads/1" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer {{token}}"

Response samples

Content type
application/json+hal
{
  • "docs": [
    ],
  • "total": 1,
  • "limit": 1,
  • "skip": 0
}

Update a Keypad.

Update a Keypad you own.

Authorizations:
(oauthapikey)
path Parameters
id
string
Example: 123

A resource's ID or MAC address.

Request Body schema: application/json
required

Keypad object.

name
string

The Keypad's name.

description
string

The Keypad's description.

Responses

Request samples

Content type
application/json
{
  • "name": "Keypad 1",
  • "description": "This is a Keypad."
}

Response samples

Content type
application/json+hal
{
  • "docs": [
    ],
  • "total": 1,
  • "limit": 1,
  • "skip": 0
}

Delete a Keypad.

Delete a Keypad you own.

Authorizations:
(oauthapikey)
path Parameters
id
string
Example: 123

A resource's ID or MAC address.

Responses

Request samples 

curl -XDELETE "https://api.homeit.io/v2/keypads/1" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer {{token}}"

Response samples

Content type
application/json+hal
{
  • "docs": [
    ],
  • "total": 1,
  • "limit": 1,
  • "skip": 0
}

Locks

Get all Locks.

Get all Locks you have access to. You may use filters to narrow your search.

Authorizations:
(oauthapikey)
query Parameters
id
Array of integers <int64> [ items <int64 > ]
Example: id=123

A list of resource IDs.

name
string
Example: name=Example

The resource's name, or part of it. Case-insensitive.

description
string
Example: description=Example

The resource's description, or part of it. Case-insensitive.

type
Array of strings
Items Enum: "passive" "active" "ble"
Example: type=ble

A list of Lock types.

mac
Array of strings
Example: mac=8426ab951c73

A list of resource MAC addresses.

isActive
boolean
Example: isActive=true

Filter by active status.

createdBefore
string
Example: createdBefore=2020-01-01T00:00:00.000Z

Filter by creation date. Format MUST comply with ISO 8601.

createdAfter
string
Example: createdAfter=2020-01-01T00:00:00.000Z

Filter by creation date. Format MUST comply with ISO 8601.

dry
boolean
Default: false
Example: dry=true

Enable dry-run mode, for testing.

hypermedia
boolean
Default: true
Example: hypermedia=false

Disable hypermedia links in response.

Responses

Request samples 

curl -XGET "https://api.homeit.io/v2/locks?id=1&id=2&name=Example" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer {{token}}"

Response samples

Content type
application/json+hal
{
  • "docs": [
    ],
  • "total": 2,
  • "limit": 10,
  • "skip": 0
}

Get a Lock.

Get a single Lock by ID or MAC address.

Authorizations:
(oauthapikey)
path Parameters
id
string
Example: 123

A resource's ID or MAC address.

Responses

Request samples 

curl -XGET "https://api.homeit.io/v2/locks/1" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer {{token}}"

Response samples

Content type
application/json+hal
{
  • "docs": [
    ],
  • "total": 1,
  • "limit": 1,
  • "skip": 0
}

Update a Lock.

Update a Lock you own.

Authorizations:
(oauthapikey)
path Parameters
id
string
Example: 123

A resource's ID or MAC address.

Request Body schema: application/json
required

Lock object.

object (lock_update)

[object Object]

Responses

Request samples

Content type
application/json
{
  • "name": "Lock 1",
  • "description": "This is a Lock."
}

Response samples

Content type
application/json+hal
{
  • "docs": [
    ],
  • "total": 1,
  • "limit": 1,
  • "skip": 0
}

Delete a Lock.

Delete a Lock you own.

Authorizations:
(oauthapikey)
path Parameters
id
string
Example: 123

A resource's ID or MAC address.

Responses

Request samples 

curl -XDELETE "https://api.homeit.io/v2/locks/1" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer {{token}}"

Response samples

Content type
application/json+hal
{
  • "docs": [
    ],
  • "total": 1,
  • "limit": 1,
  • "skip": 0
}

Properties

Get all Properties.

Get all Properties you have access to. You may use filters to narrow your search.

Authorizations:
(oauthapikey)
query Parameters
id
Array of integers <int64> [ items <int64 > ]
Example: id=123

A list of resource IDs.

name
string
Example: name=Example

The resource's name, or part of it. Case-insensitive.

description
string
Example: description=Example

The resource's description, or part of it. Case-insensitive.

address
string
Example: address=Portugal

An entire or part of an address. You can filter by country, city or any other address field. Case-insensitve.

isActive
boolean
Example: isActive=true

Filter by active status.

createdBefore
string
Example: createdBefore=2020-01-01T00:00:00.000Z

Filter by creation date. Format MUST comply with ISO 8601.

createdAfter
string
Example: createdAfter=2020-01-01T00:00:00.000Z

Filter by creation date. Format MUST comply with ISO 8601.

dry
boolean
Default: false
Example: dry=true

Enable dry-run mode, for testing.

hypermedia
boolean
Default: true
Example: hypermedia=false

Disable hypermedia links in response.

Responses

Request samples 

curl -XGET "https://api.homeit.io/v2/properties?id=1&id=2&name=Example" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer {{token}}"

Response samples

Content type
application/json+hal
{
  • "docs": [
    ],
  • "total": 2,
  • "limit": 10,
  • "skip": 0
}

Get a Property.

Get a single Property by ID or MAC address.

Authorizations:
(oauthapikey)
path Parameters
id
integer <int64>
Example: 123

A resource's ID.

Responses

Request samples 

curl -XGET "https://api.homeit.io/v2/properties/1" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer {{token}}"

Response samples

Content type
application/json+hal
{
  • "docs": [
    ],
  • "total": 1,
  • "limit": 1,
  • "skip": 0
}

Update a Property.

Update a Property you own.

Authorizations:
(oauthapikey)
path Parameters
id
integer <int64>
Example: 123

A resource's ID.

Request Body schema: application/json
required

Property object.

name
string

The Property's name.

description
string

The Property's description.

object

The Property's address.

object

Location coordinates: longitude, latitude and optional altitude.

defaultCheckIn
integer <int32> [ 0 .. 1439 ]

This Property's default check in time. Used in user interfaces to provide a default value. Expressed in minutes after midnight (for example, a value of 120 would mean 2:00 AM).

defaultCheckOut
integer <int32> [ 0 .. 1439 ]

This Property's default check out time. Used in user interfaces to provide a default value. Expressed in minutes after midnight (for example, a value of 120 would mean 2:00 AM).

Responses

Request samples

Content type
application/json
{
  • "name": "Property 1",
  • "description": "This is a Property.",
  • "address": {
    },
  • "coordinates": {
    },
  • "defaultCheckIn": 600,
  • "defaultCheckOut": 1080
}

Response samples

Content type
application/json+hal
{
  • "docs": [
    ],
  • "total": 1,
  • "limit": 1,
  • "skip": 0
}

Delete a Property.

Delete a Property you own.

Authorizations:
(oauthapikey)
path Parameters
id
integer <int64>
Example: 123

A resource's ID.

Responses

Request samples 

curl -XDELETE "https://api.homeit.io/v2/properties/1" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer {{token}}"

Response samples

Content type
application/json+hal
{
  • "docs": [
    ],
  • "total": 1,
  • "limit": 1,
  • "skip": 0
}

Box

id
integer <int64>

The Box's numeric ID.

name
string

The Box's name.

description
string

The Box's description.

mac
string

The Box's MAC Address.

serialNumber
string

The Box's serial number.

isOnline
boolean

Is the Box online?

versionHw
string

The Box's hardware version. Follows SemVer.

versionFw
string

The Box's firmware Version. Follows SemVer.

versionFwFactory
string

The Box's factory firmware version. Follows SemVer.

isActive
boolean (isActive)

Is the resource active?

dateCreated
string (dateCreated)

Creation date and time. Format MUST comply with ISO 8601.

dateUpdated
string (dateUpdated)

Last update date and time. Format MUST comply with ISO 8601.

deleted
boolean (deleted)

Is the resource deleted?

deletedAt
string (deletedAt)

Deletion date and time. Format MUST comply with ISO 8601.

Box Example

{
  • "id": 123,
  • "name": "Box 1",
  • "description": "This is a Box.",
  • "mac": "8426ab951c73",
  • "serialNumber": "SERIAL123",
  • "isOnline": true,
  • "versionHw": "1.0.0",
  • "versionFw": "1.0.0",
  • "versionFwFactory": "1.0.0",
  • "isActive": true,
  • "dateCreated": "2021-01-01T00:00:00.000Z",
  • "dateUpdated": "2021-01-01T00:00:00.000Z",
  • "deleted": false
}

Door

id
integer <int64>

The Door's numeric ID.

name
string

The Door's name.

description
string

The Door's description.

property
integer <int64>

The Property to which this Door belongs.

box
integer <int64>

The Box currently installed on this Door.

locks
Array of integers <int64> unique [ items <int64 > ]

The Locks currently installed on this Door.

keypads
Array of integers <int64> unique [ items <int64 > ]

The Keypads currently installed on this Door.

isActive
boolean (isActive)

Is the resource active?

dateCreated
string (dateCreated)

Creation date and time. Format MUST comply with ISO 8601.

dateUpdated
string (dateUpdated)

Last update date and time. Format MUST comply with ISO 8601.

deleted
boolean (deleted)

Is the resource deleted?

deletedAt
string (deletedAt)

Deletion date and time. Format MUST comply with ISO 8601.

Door Example

{
  • "id": 123,
  • "name": "Door 1",
  • "description": "This is a Door.",
  • "property": 1,
  • "box": 2,
  • "locks": [
    ],
  • "keypads": [
    ],
  • "isActive": true,
  • "dateCreated": "2021-01-01T00:00:00.000Z",
  • "dateUpdated": "2021-01-01T00:00:00.000Z",
  • "deleted": false
}

Key

id
integer <int64>

The Key's numeric ID.

name
string

The Key's name.

description
string

The Key's description.

guests
Array of integers <int64> unique [ items <int64 > ]

The guests who can use this Key. Populated via integrations.

doors
Array of integers <int64> unique [ items <int64 > ]

The numeric IDs of the Doors this Key can open.

numericCode
string

The code to be entered in the Keypads. Always 5 digits.

smsToken
string

The token to be sent via SMS. Always 6 characters.

linkToken
string

The token to be used by the guest to access the Key's information.

checkIn
string

Check in date and time, after which the key becomes valid. Format MUST comply with ISO 8601.

checkOut
string

Check out date and time, after which the key becomes invalid. Format MUST comply with ISO 8601.

isExpiring
boolean

Does the Key expire. If false, the Key is permanent and check out value can be ignored.

isBooking
boolean

Was the Key created via an integration?

bookingSource
string

The name of the integration that generated the Key.

bookingId
string

The ID of the booking obtained via integration.

canUse
Array of strings unique

A list of methods in which the Key can be used.

tags
Array of strings unique

List of tags.

isActive
boolean (isActive)

Is the resource active?

dateCreated
string (dateCreated)

Creation date and time. Format MUST comply with ISO 8601.

dateUpdated
string (dateUpdated)

Last update date and time. Format MUST comply with ISO 8601.

deleted
boolean (deleted)

Is the resource deleted?

deletedAt
string (deletedAt)

Deletion date and time. Format MUST comply with ISO 8601.

Key Example

{
  • "id": 123,
  • "name": "Key 1",
  • "description": "This is a Key.",
  • "doors": [
    ],
  • "numericCode": "12345",
  • "smsToken": "ABC123",
  • "linkToken": "abcd1234efgh5678",
  • "checkIn": "2020-01-01T00:00:00.000Z",
  • "checkOut": "2021-01-01T00:00:00.000Z",
  • "isExpiring": true,
  • "isBooking": true,
  • "bookingSource": "ical",
  • "bookingId": "abc123",
  • "canUse": [
    ],
  • "tags": [
    ],
  • "isActive": true,
  • "dateCreated": "2021-01-01T00:00:00.000Z",
  • "dateUpdated": "2021-01-01T00:00:00.000Z",
  • "deleted": false
}

Key Event

id
integer <int64>

The Key Event's numeric ID.

timestamp
string

When the Key Event ocurred. Format MUST comply with ISO 8601.

key
integer <int64>

The Key that was used to open the door.

door
integer <int64>

The door that was opened to generate this Key Event.

guest
integer <int64>

The guest who generated this Key Event.

source
string
Enum: "keypad" "app" "sms" "owner"

The method used to open the door.

dateCreated
string (dateCreated)

Creation date and time. Format MUST comply with ISO 8601.

Key Event Example

{
  • "id": 123,
  • "key": 1,
  • "door": 2,
  • "guest": 3,
  • "source": "keypad",
  • "dateCreated": "2021-01-01T00:00:00.000Z"
}

Keypad

id
integer <int64>

The Keypad's numeric ID.

name
string

The Keypad's name.

description
string

The Keypad's description.

type
string
Enum: "wired" "ble"

The type of the Keypad.

mac
string

The Keypad's MAC Address.

model
string

The keypad's model name.

versionHw
string

The Keypad's hardware version. Follows SemVer.

versionFw
string

The Keypad's firmware Version. Follows SemVer.

batteryLevel
integer <int32> [ 0 .. 100 ]

The Keypad's remaining battery percentage.

isConnected
boolean

Is the device currently connected to the Box?

isActive
boolean (isActive)

Is the resource active?

dateCreated
string (dateCreated)

Creation date and time. Format MUST comply with ISO 8601.

dateUpdated
string (dateUpdated)

Last update date and time. Format MUST comply with ISO 8601.

deleted
boolean (deleted)

Is the resource deleted?

deletedAt
string (deletedAt)

Deletion date and time. Format MUST comply with ISO 8601.

Keypad Example

{
  • "id": 123,
  • "name": "Keypad 1",
  • "description": "This is a Keypad.",
  • "type": "ble",
  • "mac": "8426ab951c73",
  • "model": "pad",
  • "versionHw": "1.0.0",
  • "versionFw": "1.0.0",
  • "batteryLevel": 100,
  • "isConnected": true,
  • "isActive": true,
  • "dateCreated": "2021-01-01T00:00:00.000Z",
  • "dateUpdated": "2021-01-01T00:00:00.000Z",
  • "deleted": false
}

Lock

id
integer <int64>

The Lock's numeric ID.

name
string

The Lock's name.

description
string

The Lock's description.

type
string
Enum: "passive" "active" "ble"

The type of the Lock.

mac
string

The Lock's MAC Address.

model
string

The Lock's model name.

versionHw
string

The Lock's hardware version. Follows SemVer.

versionFw
string

The Lock's firmware Version. Follows SemVer.

batteryLevel
integer <int32> [ 0 .. 100 ]

The Lock's remaining battery percentage.

isConnected
boolean

Is the device currently connected to the Box?

timing
integer <int32>

Time (in seconds) before the auto-lock function is activated.

lockingType
string
Enum: "latch" "full" "1-turn" "2-turn"

How many turns it takes to lock the door.

isActive
boolean (isActive)

Is the resource active?

dateCreated
string (dateCreated)

Creation date and time. Format MUST comply with ISO 8601.

dateUpdated
string (dateUpdated)

Last update date and time. Format MUST comply with ISO 8601.

deleted
boolean (deleted)

Is the resource deleted?

deletedAt
string (deletedAt)

Deletion date and time. Format MUST comply with ISO 8601.

Lock Example

{
  • "id": 123,
  • "name": "Lock 1",
  • "description": "This is a Lock.",
  • "type": "ble",
  • "mac": "8426ab951c73",
  • "model": "nuki",
  • "versionHw": "1.0.0",
  • "versionFw": "1.0.0",
  • "batteryLevel": 100,
  • "isConnected": true,
  • "timing": 60,
  • "lockingType": "full",
  • "isActive": true,
  • "dateCreated": "2021-01-01T00:00:00.000Z",
  • "dateUpdated": "2021-01-01T00:00:00.000Z",
  • "deleted": false
}

Property

id
integer <int64>

The Property's numeric ID.

name
string

The Property's name.

description
string

The Property's description.

owners
Array of integers <int64> <= 100 items unique [ items <int64 > ]

A list of Property owners (Users and Organizations).

object

The Property's address.

object

The Property's coordinates. Expressed as a GeoJSON Point geometry.

timezone
string

The timezone of the Property. Expressed as a tz database time zone name.

defaultCheckIn
integer <int32> [ 0 .. 1439 ]

This Property's default check in time. Used in user interfaces to provide a default value. Expressed in minutes after midnight (for example, a value of 120 would mean 2:00 AM).

defaultCheckOut
integer <int32> [ 0 .. 1439 ]

This Property's default check out time. Used in user interfaces to provide a default value. Expressed in minutes after midnight (for example, a value of 120 would mean 2:00 AM).

isActive
boolean (isActive)

Is the resource active?

dateCreated
string (dateCreated)

Creation date and time. Format MUST comply with ISO 8601.

dateUpdated
string (dateUpdated)

Last update date and time. Format MUST comply with ISO 8601.

deleted
boolean (deleted)

Is the resource deleted?

deletedAt
string (deletedAt)

Deletion date and time. Format MUST comply with ISO 8601.

Property Example

{
  • "id": 123,
  • "name": "Property 1",
  • "description": "This is a Property.",
  • "owners": [
    ],
  • "address": {
    },
  • "location": {
    },
  • "timezone": "Europe/Lisbon",
  • "defaultCheckIn": 600,
  • "defaultCheckOut": 1080,
  • "isActive": true,
  • "dateCreated": "2021-01-01T00:00:00.000Z",
  • "dateUpdated": "2021-01-01T00:00:00.000Z",
  • "deleted": false
}