homeit Core API (2.6.4)

Download OpenAPI specification:Download

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 start issuing 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.

Standards

REST

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

HTTPS

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

Security

API requests require authentication using an API Key or a Bearer token in the JSON Web Token format. Calls made without authentication will fail.

You can find additional information in the Authentication section.

JSON

All API responses are given in JSON format. All requests that require a body should also be provided as JSON.

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

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.

Sorting

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

The sort 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.

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.

Data formats

All dates follow the ISO 8601 format standard.

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.

Changelog

v2.6.3 2020-02-13

  • First release of this documentation page.

v2.6.4 2020-02-21

  • Added timestamp field to Key Events.

Authentication

bearer

Bearer token authentication. Used in the Authorization header. Example: Authorization: Bearer {{token}}

Security Scheme Type HTTP
HTTP Authorization Scheme bearer
Bearer format "JWT"

apikey

API Key authentication. Used as a query parameter. Example: https://api.homeit.io/v2/resource?apikey={{apikey}}

Security Scheme Type API Key
Query parameter name: apikey

oauth

OAuth2 authentication. The flow produces a JSON Web Token which can be used as a bearer token.

Security Scheme Type OAuth2
authorizationCode OAuth Flow
Authorization URL: https://auth.homeit.io/v2/oauth/authorization
Token URL: https://auth.homeit.io/v2/oauth/token
Refresh URL: https://auth.homeit.io/v2/oauth/token
Scopes:
  • external -

    REQUIRED Access and manage all your properties.

Boxes

Get all Boxes.

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

Authorizations:
bearerapikeyoauth (external)
query Parameters
id
Array of integers <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.

isDemo
boolean
Example: isDemo=false

Filter by demo 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

200

A collection of Boxes.

4XX

Error response

get /boxes

Main API server.

https://api.homeit.io/v2/boxes

Request samples

Copy
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
Copy
Expand all Collapse all
{
  • "docs":
    [
    ],
  • "total": 2,
  • "limit": 10,
  • "skip": 0
}

Get a Box.

Get a single Box by ID or MAC address.

Authorizations:
bearerapikeyoauth (external)
path Parameters
id
string
Example: 123

A resource's ID or MAC address.

Responses

200

The requested Box.

4XX

Error response

get /boxes/{id}

Main API server.

https://api.homeit.io/v2/boxes/{id}

Request samples

Copy
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
Copy
Expand all Collapse all
{
  • "docs":
    [
    ],
  • "total": 1,
  • "limit": 1,
  • "skip": 0
}

Update a Box.

Update a Box you own.

Authorizations:
bearerapikeyoauth (external)
path Parameters
id
string
Example: 123

A resource's ID or MAC address.

Request Body schema: application/json

Box object.

name
string

The Box's name.

description
string

The Box's description.

Responses

200

The updated Box.

4XX

Error response

put /boxes/{id}

Main API server.

https://api.homeit.io/v2/boxes/{id}

Request samples

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

Response samples

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

Delete a Box.

Delete a Box you own.

Authorizations:
bearerapikeyoauth (external)
path Parameters
id
string
Example: 123

A resource's ID or MAC address.

Responses

200

The deleted Box.

4XX

Error response

delete /boxes/{id}

Main API server.

https://api.homeit.io/v2/boxes/{id}

Request samples

Copy
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
Copy
Expand all Collapse all
{
  • "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:
bearerapikeyoauth (external)
query Parameters
id
Array of integers <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>
Example: box=123

A list of Box IDs.

property
Array of integers <int64>
Example: property=123

A list of Property IDs.

keypad
Array of integers <int64>
Example: keypad=123

A list of Keypad IDs.

lock
Array of integers <int64>
Example: lock=123

A list of Lock IDs.

isActive
boolean
Example: isActive=true

Filter by active status.

isDemo
boolean
Example: isDemo=false

Filter by demo 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

200

A collection of Doors.

4XX

Error response

get /doors

Main API server.

https://api.homeit.io/v2/doors

Request samples

Copy
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
Copy
Expand all Collapse all
{
  • "docs":
    [
    ],
  • "total": 2,
  • "limit": 10,
  • "skip": 0
}

Get a Door.

Get a single Door by ID or MAC address.

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

A resource's ID.

Responses

200

The requested Door.

4XX

Error response

get /doors/{id}

Main API server.

https://api.homeit.io/v2/doors/{id}

Request samples

Copy
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
Copy
Expand all Collapse all
{
  • "docs":
    [