Homeit API API Reference

Welcome to the Homeit API reference webpage.

What Homeit does

Homeit is a unique property management system, designed for the Sharing Economy. The Homeit platform allows you to manage all your properties from a single place.

What our API does for hosts

The Homeit API allows you to perform all the operations you would normally perform on the Homeit Host Dashboard, such as creating keys, checking entry logs or opening doors, using your own tools or through those of our partners.

We are currently developing several partnerships with channel managers and other online services. We will keep an updated list of partners on our website. In the meantime, if you have any suggestions, please send us an email.

What our API does for partners

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

Soon we will release libraries for Node.js and Python so you can start integrating straight away. Support for more languages will come in late 2018.

In the meantime, if you think your company can benefit from integrating with the Homeit network please send us an email and we'll will help you get started!

About these documents

These documentation pages were automatically generated from a Swagger file, and are intended primarily as detailed descriptions of our API for developers.

  • For first reads and general reference please go here.
  • If you want to start experimenting with our API calls right away, click here.

Standards

REST

Our API is REST-compliant and it 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 plain HTTP will fail.

JWT

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

You can read more about the authentication process in the Authentication and Tokens sections below.

JSON

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

Result Population

Results are not populated by default, but you can pass populate=true as a query parameter on any GET operation to get fully populated results.

Please use this feature only when needed, as population represents an additional burden for our servers.

List Pagination

All list operations are automatically paginated in the following way:

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

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

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

Sorting

All list operations can be sorted by any of the objects keys, as long as it's assigned value is an integer, 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.

API Endpoint
https://api.homeit.io/v1
Terms of Service: https://www.homeit.io/en/terms/
Contact: api@homeit.io
Request Content-Types: application/json
Response Content-Types: application/json
Schemes: https
Version: 1.0.0-beta

Authentication

JWT

description

All requests to the Homeit API must include a JWT access token in the header. You must first get a JWT access token through a simple request to our API. Please see more info in the dedicated Auth Tokens section.

You must use the following format: Bearer JWT_ACCESS_TOKEN

name
Authorization
in
header

Auth Tokens

Use these endpoint to obtain the JWT tokens you need to autheticate other requests.

Start by sending the e-mail address associated with your account, together with one of the API keys you created on the Homeit Host Dashboard, to the /auth/tokens endpoint. You will then receive a reply with two tokens: an access token and a refresh token.

NOTE: Since we are currently running a beta version of our API, we still don't offer the ability to generate API keys directly on the Homeit Host Dashboard. Please send us an e-mail to request an API Key for your account.

The access token is the one your are going to use in all your subsequent API requests, embedded in the Authorization header:

Authorization: Bearer JWT_ACCESS_TOKEN

Access tokens have a validity of 60 minutes, after which they expire. You must then use your refresh token to get a new pair of tokens via the /auth/tokens/refresh endpoint. The refresh token has a validity period of 1 month and it becomes void once used.

Please see more detailed request and response examples below.

Get JWT tokens

POST /auth/tokens

Get the initial JWT access and refresh tokens by authenticating with your email and one of your API keys.

Information needed to authenticate and retrieve JWT tokens

Request Content-Types: application/json
Request Example
{
  "grantType": "external",
  "email": "john@email.com",
  "apiKey": "API_KEY"
}
200 OK

Successful operation

Response Content-Types: application/json
Response Example (200 OK)
{
  "tokenType": "string",
  "expiresIn": 3600,
  "access": "JWT_ACCESS_TOKEN",
  "refresh": "JWT_REFRESH_TOKEN"
}

Refresh JWT tokens

POST /auth/tokens/refresh

Get new JWT access and refresh tokens once your access token has expired. You must send a a valid refresh token on the request.

Information needed to refresh JWT tokens

Request Content-Types: application/json
Request Example
{
  "grantType": "refreshToken",
  "refreshToken": "JWT_REFRESH_TOKEN"
}
200 OK

Successful operation

Response Content-Types: application/json
Response Example (200 OK)
{
  "tokenType": "string",
  "expiresIn": 3600,
  "access": "JWT_ACCESS_TOKEN",
  "refresh": "JWT_REFRESH_TOKEN"
}

Keys

key objects are the digital representation of a door key on the Homeit system. But they are also much more than that!

When you create a key you give a user access to one of the properties you own. Your guest will then be able to use the Homeit keypad, send a text message or use the Homeit app to open the doors.

Get a list of keys

GET /keys

Get a list of valid keys associated to all the properties you own. Valid keys include all keys which haven't expired yet and those which check-in date hasn't been reached yet.

You can optionally filter the results by providing a numeric ID for a guest, property or door or set a custom validity period using start and end date.

populate

Populate key objects with nested owner, guest and doors objects.

type
boolean false
in
query
guest

Filter keys by guest numeric ID.

type
integer
in
query
property

Filter keys by property numeric ID.

type
integer
in
query
door

Filter keys by door numeric ID.

type
integer
in
query
startDate

Set the start date and time for the validity period. The provided date should follow the ISO 8601 specification.

type
string
in
query
endDate

Set the end date and time for the validity period. The provided date should follow the ISO 8601 specification.

type
string
in
query
skip

Skip any number of objects, effectively setting the starting position by providing an index. This index should not exceed the total amount of available objects.

type
integer x ≥ 0 0
in
query
limit

A limit on the number of objects to be returned. Limit can range between 1 and 100 items, and the default is 10 items.

type
integer 1 ≤ x ≤ 100 10
in
query
sort

The key by which the returned objects should be sorted. Can be any key which is assigned a simple value, such as an integer, string or date.

type
string
in
query
order

The order in which the sorted objects will be returned. Use asc for ascending and desc for descending.

type
string asc, desc
in
query
200 OK

Successful operation

Response Content-Types: application/json
Response Example (200 OK)
{
  "docs": [
    {
      "_id": 6000000,
      "owner": 1000000,
      "guest": 1000001,
      "property": 3000000,
      "doors": [
        4000000,
        4000001
      ],
      "isActive": true,
      "numericCode": 39617,
      "token": "X5GW3",
      "checkIn": "2018-01-01T20:00:00Z",
      "checkOut": "2018-01-01T20:00:00Z",
      "canUse": [
        "sms",
        "keypad",
        "app"
      ],
      "dateCreated": "2018-01-01T20:00:00Z",
      "dateUpdated": "2018-01-01T20:00:00Z"
    }
  ],
  "total": 1,
  "skip": 0,
  "limit": 10
}

Create a new key

POST /keys

This is how you create a new key for one of the properties you own.

You must choose the numeric IDs for the property and doors that you want to give your guest access to, and provide check-in and check-out date and time according the ISO 8601 specification.

The amount of information you provide about your guest is optional. Please see the request example below.

Information needed to create a new key

Request Content-Types: application/json
Request Example
{
  "guest": {
    "name": {
      "first": "Susan",
      "last": "Holmes"
    },
    "phone": {
      "country": "US",
      "number": 1800800
    }
  },
  "property": 3000000,
  "doors": [
    4000000,
    4000001
  ],
  "checkIn": "2018-01-01T20:00:00Z",
  "checkOut": "2018-01-01T20:00:00Z",
  "canUse": [
    "sms",
    "keypad",
    "app"
  ]
}
200 OK
Key

Successful operation

Response Content-Types: application/json
Response Example (200 OK)
{
  "_id": 6000000,
  "owner": 1000000,
  "guest": 1000001,
  "property": 3000000,
  "doors": [
    4000000,
    4000001
  ],
  "isActive": true,
  "numericCode": 39617,
  "token": "X5GW3",
  "checkIn": "2018-01-01T20:00:00Z",
  "checkOut": "2018-01-01T20:00:00Z",
  "canUse": [
    "sms",
    "keypad",
    "app"
  ],
  "dateCreated": "2018-01-01T20:00:00Z",
  "dateUpdated": "2018-01-01T20:00:00Z"
}

Get a key

GET /keys/{id}

Get a specific key by numeric ID

populate

Populate key object with nested owner, guest and doors objects.

type
boolean false
in
query
id

key numeric ID

type
integer
in
path
200 OK
Key

Successful operation

Response Content-Types: application/json
Response Example (200 OK)
{
  "_id": 6000000,
  "owner": 1000000,
  "guest": 1000001,
  "property": 3000000,
  "doors": [
    4000000,
    4000001
  ],
  "isActive": true,
  "numericCode": 39617,
  "token": "X5GW3",
  "checkIn": "2018-01-01T20:00:00Z",
  "checkOut": "2018-01-01T20:00:00Z",
  "canUse": [
    "sms",
    "keypad",
    "app"
  ],
  "dateCreated": "2018-01-01T20:00:00Z",
  "dateUpdated": "2018-01-01T20:00:00Z"
}

Update a key

PUT /keys/{id}

Update an existing key by numeric ID

Information to update on key

id

key numeric ID

type
integer
in
path
Request Example
{
  "guest": 1000001,
  "property": 3000000,
  "doors": [
    4000000,
    4000001
  ],
  "checkIn": "2018-01-01T20:00:00Z",
  "checkOut": "2018-01-01T20:00:00Z",
  "canUse": [
    "sms",
    "keypad",
    "app"
  ]
}
200 OK
Key

Successful operation

Returns the updated key object

Response Example (200 OK)
{
  "_id": 6000000,
  "owner": 1000000,
  "guest": 1000001,
  "property": 3000000,
  "doors": [
    4000000,
    4000001
  ],
  "isActive": true,
  "numericCode": 39617,
  "token": "X5GW3",
  "checkIn": "2018-01-01T20:00:00Z",
  "checkOut": "2018-01-01T20:00:00Z",
  "canUse": [
    "sms",
    "keypad",
    "app"
  ],
  "dateCreated": "2018-01-01T20:00:00Z",
  "dateUpdated": "2018-01-01T20:00:00Z"
}

Delete a key

DELETE /keys/{id}

Delete an existing key by numeric ID

id

key numeric ID

type
integer
in
path
200 OK
Key

Successful operation

Returns the deleted key object

Response Example (200 OK)
{
  "_id": 6000000,
  "owner": 1000000,
  "guest": 1000001,
  "property": 3000000,
  "doors": [
    4000000,
    4000001
  ],
  "isActive": true,
  "numericCode": 39617,
  "token": "X5GW3",
  "checkIn": "2018-01-01T20:00:00Z",
  "checkOut": "2018-01-01T20:00:00Z",
  "canUse": [
    "sms",
    "keypad",
    "app"
  ],
  "dateCreated": "2018-01-01T20:00:00Z",
  "dateUpdated": "2018-01-01T20:00:00Z"
}

Key Events

keyevent objects represent a physical access into one of your properties.

They are essentially log instances and tell you which user accessed your property, when they did it and which door they used. They also provide information about the key and method (keypad, app or sms) this person used to open the door.

Get a list of key events

GET /keyevents/

Get a list of keyevent objects for all the properties you own.

You can optionally filter the results by providing a numeric ID for a guest, property, door, filter by source type, or set the start and end dates for the interval of time to be considered.

populate

Populate keyevent objects with nested guest, property and door objects.

type
boolean false
in
query
guest

Filter keys by guest numeric ID

type
integer
in
query
property

Filter keys by property numeric ID

type
integer
in
query
door

Filter keys by door numeric ID

type
integer
in
query
source

Filter keys by source type. Can be either keypad, app or sms.

type
string
in
query
startDate

Set the start date and time for the validity period. The provided date should follow the ISO 8601 specification.

type
string
in
query
endDate

Set the end date and time for the validity period. The provided date should follow the ISO 8601 specification.

type
string
in
query
skip

Skip any number of objects, effectively setting the starting position by providing an index. This index should not exceed the total amount of available objects.

type
integer x ≥ 0 0
in
query
limit

A limit on the number of objects to be returned. Limit can range between 1 and 100 items, and the default is 10 items.

type
integer 1 ≤ x ≤ 100 10
in
query
sort

The key by which the returned objects should be sorted. Can be any key which is assigned a simple value, such as an integer, string or date.

type
string
in
query
order

The order in which the sorted objects will be returned. Use asc for ascending and desc for descending.

type
string asc, desc
in
query
200 OK

Successful operation

Response Content-Types: application/json
Response Example (200 OK)
{
  "docs": [
    {
      "_id": 9000000,
      "key": 6000000,
      "guest": 1000001,
      "property": 3000000,
      "door": 4000000,
      "source": "keypad",
      "isOwner": false,
      "dateCreated": "2018-01-01T20:00:00Z"
    }
  ],
  "total": 1,
  "skip": 0,
  "limit": 10
}

Calendars

calendar objects are used to synchronize one of your properties with a particular calendar file from platforms such as Airbnb.

After creating a calendar object, you can automatically create keys for all your future bookings with a simple click, using the Homeit Host Dashboard.

Get a list of calendars

GET /calendars

Get a list of all calendar objects which are associated with the properties you own.

You can optionally filter the results by providing a numeric ID for a property or door.

populate

Populate calendar objects with nested property and doors objects.

type
boolean false
in
query
property

Filter calendars by property numeric ID

type
integer
in
query
door

Filter calendars by door numeric ID

type
integer
in
query
skip

Skip any number of objects, effectively setting the starting position by providing an index. This index should not exceed the total amount of available objects.

type
integer x ≥ 0 0
in
query
limit

A limit on the number of objects to be returned. Limit can range between 1 and 100 items, and the default is 10 items.

type
integer 1 ≤ x ≤ 100 10
in
query
sort

The key by which the returned objects should be sorted. Can be any key which is assigned a simple value, such as an integer, string or date.

type
string
in
query
order

The order in which the sorted objects will be returned. Use asc for ascending and desc for descending.

type
string asc, desc
in
query
200 OK

Successful operation

Response Content-Types: application/json
Response Example (200 OK)
{
  "docs": [
    {
      "_id": 9000000,
      "property": 3000000,
      "doors": [
        4000000
      ],
      "service": "airbnb",
      "url": "https://airbnb.com/calendar/123",
      "dateCreated": "2018-01-01T20:00:00Z",
      "dateUpdated": "2018-01-01T20:00:00Z"
    }
  ],
  "total": 1,
  "skip": 0,
  "limit": 10
}

Create a new calendar

POST /calendars

This is how you create a new calendar synchronization for one of your properties.

You must choose the property and doors that relate to this calendar, as well as the service and url where the calendar can be found.

For the time being the only available service is airbnb, but we will soon incorporate more.

Information needed to create a new calendar object

Request Content-Types: application/json
Request Example
{
  "property": [
    3000000
  ],
  "doors": [
    4000000,
    4000001
  ],
  "service": "airbnb",
  "url": "https://airbnb.com/calendar/123"
}
200 OK

Successful operation

Response Content-Types: application/json
Response Example (200 OK)
{
  "_id": 9000000,
  "property": 3000000,
  "doors": [
    4000000
  ],
  "service": "airbnb",
  "url": "https://airbnb.com/calendar/123",
  "dateCreated": "2018-01-01T20:00:00Z",
  "dateUpdated": "2018-01-01T20:00:00Z"
}

Get a calendar

GET /calendars/{id}

Get a specfic calendar by numeric ID

populate

Populate calendar object with nested property and doors objects.

type
boolean false
in
query
id

calendar numeric ID

type
string
in
path
200 OK

Successful operation

Response Content-Types: application/json
Response Example (200 OK)
{
  "_id": 9000000,
  "property": 3000000,
  "doors": [
    4000000
  ],
  "service": "airbnb",
  "url": "https://airbnb.com/calendar/123",
  "dateCreated": "2018-01-01T20:00:00Z",
  "dateUpdated": "2018-01-01T20:00:00Z"
}

Update a calendar

PUT /calendars/{id}

Update a specfic calendar by numeric ID

Information to update on calendar

id

calendar numeric ID

type
string
in
path
Request Example
{
  "property": [
    3000000
  ],
  "doors": [
    4000000,
    4000001
  ],
  "service": "airbnb",
  "url": "https://airbnb.com/calendar/123"
}
200 OK

Successful operation

Returns the updated calendar object

Response Content-Types: application/json
Response Example (200 OK)
{
  "_id": 9000000,
  "property": 3000000,
  "doors": [
    4000000
  ],
  "service": "airbnb",
  "url": "https://airbnb.com/calendar/123",
  "dateCreated": "2018-01-01T20:00:00Z",
  "dateUpdated": "2018-01-01T20:00:00Z"
}

Delete a calendar

DELETE /calendars/{id}

Delete a specfic calendar by numeric ID

id

calendar numeric ID

type
string
in
path
200 OK

Successful operation

Returns the deleted calendar object

Response Content-Types: application/json
Response Example (200 OK)
{
  "_id": 9000000,
  "property": 3000000,
  "doors": [
    4000000
  ],
  "service": "airbnb",
  "url": "https://airbnb.com/calendar/123",
  "dateCreated": "2018-01-01T20:00:00Z",
  "dateUpdated": "2018-01-01T20:00:00Z"
}

Users

user objects represent both guests and hosts on the Homeit system. They provide contact infomation and other basic information about a person.

Get a user

GET /users/{id}

Get specific user by numeric ID

id

user numeric ID

type
integer
in
path
200 OK

Successful operation

Response Example (200 OK)
{
  "_id": 1000000,
  "name": {
    "first": "Susan",
    "last": "Holmes"
  },
  "about": "Hi I'm Susan!",
  "phone": {
    "country": "US",
    "number": 1800800
  },
  "email": {
    "address": "susan.holmes@gmail.com"
  },
  "isOnline": true,
  "languages": [
    "en",
    "pt"
  ]
}

Properties

property objects represent properties where you have installed the Homeit system.

They usually refer to whole buildings or houses and include relevant information such as address, geo-location data or a brief description of your property, which your guests will see on the Homeit app.

Get a list of properties

GET /properties/

Get a list of all properties you own.

populate

Populate property object with nested primaryOwner and owners objects.

type
boolean false
in
query
skip

Skip any number of objects, effectively setting the starting position by providing an index. This index should not exceed the total amount of available objects.

type
integer x ≥ 0 0
in
query
limit

A limit on the number of objects to be returned. Limit can range between 1 and 100 items, and the default is 10 items.

type
integer 1 ≤ x ≤ 100 10
in
query
sort

The key by which the returned objects should be sorted. Can be any key which is assigned a simple value, such as an integer, string or date.

type
string
in
query
order

The order in which the sorted objects will be returned. Use asc for ascending and desc for descending.

type
string asc, desc
in
query
200 OK

Successful operation

Response Content-Types: application/json
Response Example (200 OK)
{
  "docs": [
    {
      "_id": 3000000,
      "name": "Amazing Flat",
      "description": "Welcome to the nicest flat in town!",
      "primaryOwner": 1000000,
      "owners": [
        1000000
      ],
      "agentIds": [
        {
          "name": "airbnb",
          "url": "https://airbnb.com",
          "id": "abscddf8973984j"
        }
      ],
      "address": {
        "streetAddress": "Main Street, 12, 1A",
        "optionalAddress": "Door 5",
        "neighborhood": "Brooklin",
        "city": "New York",
        "state": "New York",
        "zipcode": 10069,
        "country": "USA"
      },
      "location": {
        "coordinates": [
          -74.856077,
          41.848447
        ],
        "type": "Point"
      },
      "dateCreated": "2018-01-01T20:00:00Z",
      "dateUpdated": "2018-01-01T20:00:00Z"
    }
  ],
  "total": 1,
  "skip": 0,
  "limit": 10
}

Get a property

GET /properties/{id}

Get a specific property by numeric ID

populate

Populate property object with nested primaryOwner and owners objects.

type
boolean false
in
query
id

property numeric ID

type
integer
in
path
200 OK

Successful operation

Response Content-Types: application/json
Response Example (200 OK)
{
  "_id": 3000000,
  "name": "Amazing Flat",
  "description": "Welcome to the nicest flat in town!",
  "primaryOwner": 1000000,
  "owners": [
    1000000
  ],
  "agentIds": [
    {
      "name": "airbnb",
      "url": "https://airbnb.com",
      "id": "abscddf8973984j"
    }
  ],
  "address": {
    "streetAddress": "Main Street, 12, 1A",
    "optionalAddress": "Door 5",
    "neighborhood": "Brooklin",
    "city": "New York",
    "state": "New York",
    "zipcode": 10069,
    "country": "USA"
  },
  "location": {
    "coordinates": [
      -74.856077,
      41.848447
    ],
    "type": "Point"
  },
  "dateCreated": "2018-01-01T20:00:00Z",
  "dateUpdated": "2018-01-01T20:00:00Z"
}

Update a property

PUT /properties/{id}

Update a specific property by numeric ID

Information to update on property

id

property numeric ID

type
integer
in
path
Request Example
{
  "name": "Amazing Flat",
  "description": "Welcome to the nicest flat in town!",
  "owners": [
    1000000
  ],
  "agentIds": [
    {
      "name": "airbnb",
      "url": "https://airbnb.com",
      "id": "abscddf8973984j"
    }
  ],
  "address": {
    "streetAddress": "Main Street, 12, 1A",
    "optionalAddress": "Door 5",
    "neighborhood": "Brooklin",
    "city": "New York",
    "state": "New York",
    "zipcode": 10069,
    "country": "USA"
  },
  "location": {
    "coordinates": [
      -74.856077,
      41.848447
    ],
    "type": "Point"
  }
}
200 OK

Successful operation

Response Content-Types: application/json
Response Example (200 OK)
{
  "_id": 3000000,
  "name": "Amazing Flat",
  "description": "Welcome to the nicest flat in town!",
  "primaryOwner": 1000000,
  "owners": [
    1000000
  ],
  "agentIds": [
    {
      "name": "airbnb",
      "url": "https://airbnb.com",
      "id": "abscddf8973984j"
    }
  ],
  "address": {
    "streetAddress": "Main Street, 12, 1A",
    "optionalAddress": "Door 5",
    "neighborhood": "Brooklin",
    "city": "New York",
    "state": "New York",
    "zipcode": 10069,
    "country": "USA"
  },
  "location": {
    "coordinates": [
      -74.856077,
      41.848447
    ],
    "type": "Point"
  },
  "dateCreated": "2018-01-01T20:00:00Z",
  "dateUpdated": "2018-01-01T20:00:00Z"
}

Doors

door objects represent actual doors on your property that you can open or give access to, using the Homeit system.

Besides name and description, door objects include specific information about the type of lock installed and system features that are available for that particular door, such as a keypad or sensors.

Get a list of doors

GET /doors/

Get a list of all doors which belong to properties you own.

You can optionally filter the results by providing a numeric ID for a property or box.

populate

Populate door objects with nested property and box objects.

type
boolean false
in
query
property

Filter returned door objects by property numeric ID.

type
integer
in
query
box

Filter returned door objects by box numeric ID.

type
integer
in
query
skip

Skip any number of objects, effectively setting the starting position by providing an index. This index should not exceed the total amount of available objects.

type
integer x ≥ 0 0
in
query
limit

A limit on the number of objects to be returned. Limit can range between 1 and 100 items, and the default is 10 items.

type
integer 1 ≤ x ≤ 100 10
in
query
sort

The key by which the returned objects should be sorted. Can be any key which is assigned a simple value, such as an integer, string or date.

type
string
in
query
order

The order in which the sorted objects will be returned. Use asc for ascending and desc for descending.

type
string asc, desc
in
query
200 OK

Successful operation

Response Content-Types: application/json
Response Example (200 OK)
{
  "docs": [
    {
      "_id": 4000000,
      "property": 3000000,
      "box": 2000000,
      "name": "Street Door",
      "description": "This is the blue door at number 12",
      "lockProperties": [
        "passive",
        "trigger"
      ],
      "features": [
        "keypad",
        "reed",
        "doorbell"
      ],
      "dateCreated": "2018-01-01T20:00:00Z",
      "dateUpdated": "2018-01-01T20:00:00Z"
    }
  ],
  "total": 1,
  "skip": 0,
  "limit": 10
}

Get a door

GET /doors/{id}

Get a specific door by numeric ID

populate

Populate door object with nested property and box objects.

type
boolean false
in
query
id

door numeric ID

type
integer
in
path
200 OK

Successful operation

Response Content-Types: application/json
Response Example (200 OK)
{
  "_id": 4000000,
  "property": 3000000,
  "box": 2000000,
  "name": "Street Door",
  "description": "This is the blue door at number 12",
  "lockProperties": [
    "passive",
    "trigger"
  ],
  "features": [
    "keypad",
    "reed",
    "doorbell"
  ],
  "dateCreated": "2018-01-01T20:00:00Z",
  "dateUpdated": "2018-01-01T20:00:00Z"
}

Update a door

PUT /doors/{id}

Update a specific door by numeric ID

Information to update on door

id

door numeric ID

type
integer
in
path
Request Example
{
  "name": "Street Door",
  "description": "This is the blue door at number 12"
}
200 OK

Successful operation

Response Content-Types: application/json
Response Example (200 OK)
{
  "_id": 4000000,
  "property": 3000000,
  "box": 2000000,
  "name": "Street Door",
  "description": "This is the blue door at number 12",
  "lockProperties": [
    "passive",
    "trigger"
  ],
  "features": [
    "keypad",
    "reed",
    "doorbell"
  ],
  "dateCreated": "2018-01-01T20:00:00Z",
  "dateUpdated": "2018-01-01T20:00:00Z"
}

Open a door

POST /doors/{id}/open

Open a specific door by numeric ID

id

door numeric ID

type
integer
in
path
200 OK

Door opened successfuly

503 Service Unavailable

Failed to open door

Response Content-Types: application/json
Response Example (200 OK)
{
  "type": "status",
  "message": "Door opened"
}
Response Example (503 Service Unavailable)
{
  "error": "doorOpen",
  "message": "Failed to open door"
}

Boxes

box objects represent actual Homeit boxes which have been installled on your properties.

They can show you the connection status of the box, as well as technical info, such as the serial number or software and hardware versions.

Get a list of boxes

GET /boxes

Get a list of all boxes which have been installed in properties you own.

isOnline

Is the box online?

type
boolean
in
query
skip

Skip any number of objects, effectively setting the starting position by providing an index. This index should not exceed the total amount of available objects.

type
integer x ≥ 0 0
in
query
limit

A limit on the number of objects to be returned. Limit can range between 1 and 100 items, and the default is 10 items.

type
integer 1 ≤ x ≤ 100 10
in
query
sort

The key by which the returned objects should be sorted. Can be any key which is assigned a simple value, such as an integer, string or date.

type
string
in
query
order

The order in which the sorted objects will be returned. Use asc for ascending and desc for descending.

type
string asc, desc
in
query
200 OK

Successful operation

Response Content-Types: application/json
Response Example (200 OK)
{
  "docs": [
    {
      "_id": 2000000,
      "mqttId": "d8803999e34c",
      "isOnline": true,
      "versionHw": "2.0",
      "versionFw": "2.2.0",
      "serialNumber": "HBXV20001",
      "dateCreated": "2018-01-01T20:00:00Z",
      "dateUpdated": "2018-01-01T20:00:00Z"
    }
  ],
  "total": 1,
  "skip": 0,
  "limit": 10
}

Get a box

GET /boxes/{id}

Get a specfic box by numeric ID

id

box numeric ID

type
number
in
path
200 OK
Box

Successful operation

Response Content-Types: application/json
Response Example (200 OK)
{
  "_id": 2000000,
  "mqttId": "d8803999e34c",
  "isOnline": true,
  "versionHw": "2.0",
  "versionFw": "2.2.0",
  "serialNumber": "HBXV20001",
  "dateCreated": "2018-01-01T20:00:00Z",
  "dateUpdated": "2018-01-01T20:00:00Z"
}

Status

Special endpoints that give you information about our API server

Check API server health

GET /health

Checks the current status of the API server

200 OK

Successful operation

Response Example (200 OK)
{
  "type": "status",
  "message": "API OK"
}

Schema Definitions

Key: object

_id: integer

Numeric ID

owner: integer

Owner user

guest: integer

Guest user

property: integer

Property to which this key gives access

doors: integer[]

List of doors to which this key gives access

isActive: boolean

Is the key active?

numericCode: integer 10000 ≤ x ≤ 99999

Numeric code to be used on all keypads belonging to above doors

token: string (6 chars)

Token user for SMS authentication

checkIn: string (date-time)

Check-in date and time

checkOut: string (date-time)

Check-out date and time

canUse: string[]

List of valid access options for this key

dateCreated: string (date-time)
dateUpdated: string (date-time)
Example
{
  "_id": 6000000,
  "owner": 1000000,
  "guest": 1000001,
  "property": 3000000,
  "doors": [
    4000000,
    4000001
  ],
  "isActive": true,
  "numericCode": 39617,
  "token": "X5GW3",
  "checkIn": "2018-01-01T20:00:00Z",
  "checkOut": "2018-01-01T20:00:00Z",
  "canUse": [
    "sms",
    "keypad",
    "app"
  ],
  "dateCreated": "2018-01-01T20:00:00Z",
  "dateUpdated": "2018-01-01T20:00:00Z"
}

KeyList: object

docs: Key
total: integer

Total number of keys available

skip: integer

Skipped docs

limit: integer

Limit

Example
{
  "docs": [
    {
      "_id": 6000000,
      "owner": 1000000,
      "guest": 1000001,
      "property": 3000000,
      "doors": [
        4000000,
        4000001
      ],
      "isActive": true,
      "numericCode": 39617,
      "token": "X5GW3",
      "checkIn": "2018-01-01T20:00:00Z",
      "checkOut": "2018-01-01T20:00:00Z",
      "canUse": [
        "sms",
        "keypad",
        "app"
      ],
      "dateCreated": "2018-01-01T20:00:00Z",
      "dateUpdated": "2018-01-01T20:00:00Z"
    }
  ],
  "total": 1,
  "skip": 0,
  "limit": 10
}

NewKey: object

guest: UserNewKey
property: integer

Property to which this key gives access

doors: integer[]

List of doors to which this key gives access

checkIn: string (date-time)

Check-in date and time

checkOut: string (date-time)

Check-out date and time

canUse: string[]

List of valid access options for this key

Example
{
  "guest": {
    "name": {
      "first": "Susan",
      "last": "Holmes"
    },
    "phone": {
      "country": "US",
      "number": 1800800
    }
  },
  "property": 3000000,
  "doors": [
    4000000,
    4000001
  ],
  "checkIn": "2018-01-01T20:00:00Z",
  "checkOut": "2018-01-01T20:00:00Z",
  "canUse": [
    "sms",
    "keypad",
    "app"
  ]
}

UpdateKey: object

guest: integer

Guest to which this key belongs

property: integer

Property to which this key gives access

doors: integer[]

List of doors to which this key gives access

checkIn: string (date-time)

Check-in date and time

checkOut: string (date-time)

Check-out date and time

canUse: string[]

List of valid access options for this key

Example
{
  "guest": 1000001,
  "property": 3000000,
  "doors": [
    4000000,
    4000001
  ],
  "checkIn": "2018-01-01T20:00:00Z",
  "checkOut": "2018-01-01T20:00:00Z",
  "canUse": [
    "sms",
    "keypad",
    "app"
  ]
}

User: object

_id: integer

Numeric ID

name: object

First and last name

about: string

A brief description of the user

phone: object

User phone number -- country + number

email: object

User e-mail

isOnline: boolean

Is the user online?

languages: string[]
Example
{
  "_id": 1000000,
  "name": {
    "first": "Susan",
    "last": "Holmes"
  },
  "about": "Hi I'm Susan!",
  "phone": {
    "country": "US",
    "number": 1800800
  },
  "email": {
    "address": "susan.holmes@gmail.com"
  },
  "isOnline": true,
  "languages": [
    "en",
    "pt"
  ]
}

UserNewKey: object

name: object

First and last name

phone: object

User phone number -- country + number

Example
{
  "name": {
    "first": "Susan",
    "last": "Holmes"
  },
  "phone": {
    "country": "US",
    "number": 1800800
  }
}

Box: object

_id: integer

Box numeric ID

mqttId: string

MQTT ID aka MAC Address

isOnline: boolean

Is this box online?

versionHw: string

Box hardware version

versionFw: string

Box firmware version

serialNumber: string

Box serial number

dateCreated: string (date-time)

Date and time when this box was created

dateUpdated: string (date-time)

Date and time when this box was last updated

Example
{
  "_id": 2000000,
  "mqttId": "d8803999e34c",
  "isOnline": true,
  "versionHw": "2.0",
  "versionFw": "2.2.0",
  "serialNumber": "HBXV20001",
  "dateCreated": "2018-01-01T20:00:00Z",
  "dateUpdated": "2018-01-01T20:00:00Z"
}

BoxList: object

docs: Box
total: integer

Total number of boxes available

skip: integer

Skipped docs

limit: integer

Limit

Example
{
  "docs": [
    {
      "_id": 2000000,
      "mqttId": "d8803999e34c",
      "isOnline": true,
      "versionHw": "2.0",
      "versionFw": "2.2.0",
      "serialNumber": "HBXV20001",
      "dateCreated": "2018-01-01T20:00:00Z",
      "dateUpdated": "2018-01-01T20:00:00Z"
    }
  ],
  "total": 1,
  "skip": 0,
  "limit": 10
}

Property: object

_id: integer

Property numeric ID

name: string

Simple name for property

description: string

Simple description of the property

primaryOwner: integer

User who is the primary owner of the property

owners: integer[]

List of users which own this property

agentIds: AgentId
address: Address
location: Location
dateCreated: string (date-time)

Date and time when this property was created

dateUpdated: string (date-time)

Date and time when this property was last updated

Example
{
  "_id": 3000000,
  "name": "Amazing Flat",
  "description": "Welcome to the nicest flat in town!",
  "primaryOwner": 1000000,
  "owners": [
    1000000
  ],
  "agentIds": [
    {
      "name": "airbnb",
      "url": "https://airbnb.com",
      "id": "abscddf8973984j"
    }
  ],
  "address": {
    "streetAddress": "Main Street, 12, 1A",
    "optionalAddress": "Door 5",
    "neighborhood": "Brooklin",
    "city": "New York",
    "state": "New York",
    "zipcode": 10069,
    "country": "USA"
  },
  "location": {
    "coordinates": [
      -74.856077,
      41.848447
    ],
    "type": "Point"
  },
  "dateCreated": "2018-01-01T20:00:00Z",
  "dateUpdated": "2018-01-01T20:00:00Z"
}

UpdateProperty: object

name: string

Simple name for property

description: string

Simple description of the property

owners: integer[]

List of users which own this property

agentIds: AgentId
address: Address
location: Location
Example
{
  "name": "Amazing Flat",
  "description": "Welcome to the nicest flat in town!",
  "owners": [
    1000000
  ],
  "agentIds": [
    {
      "name": "airbnb",
      "url": "https://airbnb.com",
      "id": "abscddf8973984j"
    }
  ],
  "address": {
    "streetAddress": "Main Street, 12, 1A",
    "optionalAddress": "Door 5",
    "neighborhood": "Brooklin",
    "city": "New York",
    "state": "New York",
    "zipcode": 10069,
    "country": "USA"
  },
  "location": {
    "coordinates": [
      -74.856077,
      41.848447
    ],
    "type": "Point"
  }
}

Address: object

streetAddress: string

Main address line. Street, house number and flat

optionalAddress: string

Optional address line for additional information

neighborhood: string

Neighboorhood where the property is located

city: string

City where the property is located

state: string

State where the property is located

zipcode: string

Property zip code

country: string

Country where the property is located

Example
{
  "streetAddress": "Main Street, 12, 1A",
  "optionalAddress": "Door 5",
  "neighborhood": "Brooklin",
  "city": "New York",
  "state": "New York",
  "zipcode": 10069,
  "country": "USA"
}

Location: object

coordinates: number[]

Latitude and longitude information

type: string

Type of information

Example
{
  "coordinates": [
    -74.856077,
    41.848447
  ],
  "type": "Point"
}

AgentId: object

name: string

Agent name

url: string

Agent URL

id: string

Listing Id

Example
{
  "name": "airbnb",
  "url": "https://airbnb.com",
  "id": "abscddf8973984j"
}

PropertyList: object

docs: Property
total: integer

Total number of objects available

skip: integer

Skipped objects

limit: integer

Number of objects which have been returned

Example
{
  "docs": [
    {
      "_id": 3000000,
      "name": "Amazing Flat",
      "description": "Welcome to the nicest flat in town!",
      "primaryOwner": 1000000,
      "owners": [
        1000000
      ],
      "agentIds": [
        {
          "name": "airbnb",
          "url": "https://airbnb.com",
          "id": "abscddf8973984j"
        }
      ],
      "address": {
        "streetAddress": "Main Street, 12, 1A",
        "optionalAddress": "Door 5",
        "neighborhood": "Brooklin",
        "city": "New York",
        "state": "New York",
        "zipcode": 10069,
        "country": "USA"
      },
      "location": {
        "coordinates": [
          -74.856077,
          41.848447
        ],
        "type": "Point"
      },
      "dateCreated": "2018-01-01T20:00:00Z",
      "dateUpdated": "2018-01-01T20:00:00Z"
    }
  ],
  "total": 1,
  "skip": 0,
  "limit": 10
}

UpdateDoor: object

name: string

Door name

description: string

Simple description

Example
{
  "name": "Street Door",
  "description": "This is the blue door at number 12"
}

Door: object

_id: integer

door numeric ID

property: integer

Property. Defaults to ID only, but can be populated

box: integer

Box. Defaults to ID only, but can be populated

name: string

Door name

description: string

Simple description

lockProperties: LockProperties
features: Features
dateCreated: string (date-time)

Date and time when this door was created

dateUpdated: string (date-time)

Date and time when this door was last updated

Example
{
  "_id": 4000000,
  "property": 3000000,
  "box": 2000000,
  "name": "Street Door",
  "description": "This is the blue door at number 12",
  "lockProperties": [
    "passive",
    "trigger"
  ],
  "features": [
    "keypad",
    "reed",
    "doorbell"
  ],
  "dateCreated": "2018-01-01T20:00:00Z",
  "dateUpdated": "2018-01-01T20:00:00Z"
}

LockProperties: array

string passive, active, trigger, toggle
Example
[
  "passive",
  "trigger"
]

Features: array

string keypad, reed, doorbell
Example
[
  "keypad",
  "reed",
  "doorbell"
]

DoorList: object

docs: Door
total: integer

Total number of objects available

skip: integer

Skipped objects

limit: integer

Number of objects which have been returned

Example
{
  "docs": [
    {
      "_id": 4000000,
      "property": 3000000,
      "box": 2000000,
      "name": "Street Door",
      "description": "This is the blue door at number 12",
      "lockProperties": [
        "passive",
        "trigger"
      ],
      "features": [
        "keypad",
        "reed",
        "doorbell"
      ],
      "dateCreated": "2018-01-01T20:00:00Z",
      "dateUpdated": "2018-01-01T20:00:00Z"
    }
  ],
  "total": 1,
  "skip": 0,
  "limit": 10
}

KeyEvent: object

_id: string

Key Event numberic ID

key: integer

Key which was used

guest: integer

User who just used the key

property: integer

Property which was accessed

door: integer

Door which was opened

source: string keypad, app, sms

Access method which was used to open the door

isOwner: boolean

Is this user a property owner?

dateCreated: string (date-time)

Date and time when this door was created

Example
{
  "_id": 9000000,
  "key": 6000000,
  "guest": 1000001,
  "property": 3000000,
  "door": 4000000,
  "source": "keypad",
  "isOwner": false,
  "dateCreated": "2018-01-01T20:00:00Z"
}

KeyEventList: object

docs: KeyEvent
total: integer

Total number of objects available

skip: integer

Skipped objects

limit: integer

Number of objects which have been returned

Example
{
  "docs": [
    {
      "_id": 9000000,
      "key": 6000000,
      "guest": 1000001,
      "property": 3000000,
      "door": 4000000,
      "source": "keypad",
      "isOwner": false,
      "dateCreated": "2018-01-01T20:00:00Z"
    }
  ],
  "total": 1,
  "skip": 0,
  "limit": 10
}

Calendar: object

_id: string

Calendar numberic ID

property: integer

Property to which this calendar relates

doors: integer[]

Doors to which this calendar relates

service: string airbnb

Name of the service that provides the calendar

url: string

URL to the calendar

dateCreated: string (date-time)

Date and time when this door was created

dateUpdated: string (date-time)

Date and time when this door was last updated

Example
{
  "_id": 9000000,
  "property": 3000000,
  "doors": [
    4000000
  ],
  "service": "airbnb",
  "url": "https://airbnb.com/calendar/123",
  "dateCreated": "2018-01-01T20:00:00Z",
  "dateUpdated": "2018-01-01T20:00:00Z"
}

NewCalendar: object

property: integer

Property to which this calendar relates

doors: integer[]

List of doors which relate to this calendar

service: string airbnb

Name of the service that provides the calendar

url: string

URL to the calendar

Example
{
  "property": [
    3000000
  ],
  "doors": [
    4000000,
    4000001
  ],
  "service": "airbnb",
  "url": "https://airbnb.com/calendar/123"
}

UpdateCalendar: object

property: integer

Property to which this calendar relates

doors: integer[]

List of doors which relate to this calendar

service: string airbnb

Name of the service that provides the calendar

url: string

URL to the calendar

Example
{
  "property": [
    3000000
  ],
  "doors": [
    4000000,
    4000001
  ],
  "service": "airbnb",
  "url": "https://airbnb.com/calendar/123"
}

CalendarList: object

docs: Calendar
total: integer

Total number of objects available

skip: integer

Skipped objects

limit: integer

Number of objects which have been returned

Example
{
  "docs": [
    {
      "_id": 9000000,
      "property": 3000000,
      "doors": [
        4000000
      ],
      "service": "airbnb",
      "url": "https://airbnb.com/calendar/123",
      "dateCreated": "2018-01-01T20:00:00Z",
      "dateUpdated": "2018-01-01T20:00:00Z"
    }
  ],
  "total": 1,
  "skip": 0,
  "limit": 10
}

Login: object

grantType: string external
email: string

Your e-mail address

apiKey: string

You API key

Example
{
  "grantType": "external",
  "email": "john@email.com",
  "apiKey": "API_KEY"
}

Refresh: object

grantType: string refreshToken
refreshToken: string

JWT refresh token

Example
{
  "grantType": "refreshToken",
  "refreshToken": "JWT_REFRESH_TOKEN"
}

JwtTokens: object

tokenType: string string
expiresIn: number
access: string

JWT access token

refresh: string

JWT refresh token

Example
{
  "tokenType": "string",
  "expiresIn": 3600,
  "access": "JWT_ACCESS_TOKEN",
  "refresh": "JWT_REFRESH_TOKEN"
}

Error: object

message: string
Example
{
  "message": "string"
}

NotFoundError: object

error: string
message: string
Example
{
  "error": "not found",
  "message": "Object not found"
}

Status: object

type: string
message: string
Example
{
  "type": "status",
  "message": "API OK"
}

DoorOpen: object

type: string
message: string
Example
{
  "type": "status",
  "message": "Door opened"
}

DoorOpenError: object

error: string
message: string
Example
{
  "error": "doorOpen",
  "message": "Failed to open door"
}