The section explains the basic usage of the REST API.

API Key

To get an API key you can log into the landlord portal and find the integration settings page here. Be aware that the demo environment has separate API keys and you need to log into the demo environment to get the demo API keys.

Authentication

As stated above you can get the API credentials in the landlord portal. With the credentials you can then call the authentication endpoint to receive a JWT token that you can use in subsequent requests. Additionally to the jwt token you will also receive a user part which includes several things, like rights, current office, premium tier and more. Usually you do not need that additional information but it can be helpful in some situations.

Deprecation

One important aspect of every API is the method of how deprecation of older endpoints occurs. We have three mechanisms to announce our deprecations and our usual deprecation time is 3 months. The first is an announcement via E-Mail. Your company can configure a technical information email to get informed. Please visit https://www.homeq.se/documentation to set up the email.

The second mechanic is via this API Documentation where it will be marked documentation of the respective endpoint.

To test a deprecated endpoint please make a GET request to: https://api.homeq.se/api/v1/deprecation/ If you have questions, or need help with using the API, Deprecation or moving to a newer version of an endpoint please feel free to contact our customer support. Now that the formalities are out of the way let's get started:

Company - 🔗 Jump to API

The company is usually set up by our customer success team, that helps you with the onboarding. They will invite you to the landlord portal where you can configure your company.

Examples of what you can adjust are:

• integrations with Fastighetsägerna to use digital contracts
• your company bank information if it should be automatically filled into digital contracts
• your company logo
• minimum uptime for listings before offers can be made
• ...

Please contact your customer success manager if you need help with the configuration or reach out via email to support@homeq.se.

Offices - 🔗 Jump to API

Your company has a set of offices each with their own name organized in a tree like hierarchy. Mostly those offices are used to separate different regions or cities and hold some configuration that allows default values to be applied to listings that are created within that office. You can check the linked endpoint to see what configuration can be done on an office level.

Employees - 🔗 Jump to API

Employees are the users of the landlord portal which can be the day-to-day users of the system, managers who oversee performance and admins who can configure the system. Each employee is assigned to a root office and has access to all entities below their assigned office.

This may be estates, apartments and listings ads as well as applications handling.

Employees have a phone number, email address and a personal number which is used for signing contracts or for the prospective tenants to contact the landlord.

Access Control - 🔗 Jump to API

HomeQ provides four default access roles for users of the landlord portal: observer, employee, manager, and admin. As an admin you can also create custom right sets and assign them to employees within your company.

You can find the rights and what role has which permissions in the landlord portal.

After setting up your basic organization, you can start modeling your inventory. We are usually concerned with two entities: Estates and Apartments. Both cover entities that are physically present in the real world.

You create an estate representing a building, then you create apartments belonging to an estate - lastly you can create listings for apartments when filling a vacancy.

Estates - 🔗 Jump to API

Estates are the root entity in your inventory. They have a given name, assigned office and a city in which they are located. You can also specify more information about estates like an external_id (landlord_object_id) that makes it easier to find a given estate in our system with the identifier you usually use. For other fields check the documentation below.

Apartments area created belonging to an Estate and have an address defined by street, street number, zip code as well as rooms, floor, area, rental price, and other attributes. It should be updated as close as possible to represent the actual real world apartment.

Below you find a python code example that shows how you can create a simple estate within your company.

import requests
import json

token = "eyJ0eXAiOi...."

response = requests.post("https://api.homeq.se/api/v4/estate", json.dumps({
    "legal_name": "Solrosen I",
    "city": "Stockholm"
}), headers={
    "Content-Type": "application/json",
    "Authorization": f"JWT {token}"
})

assert response.status_code == 200, "could not create the estate"

# Extract the estate id to use when creating apartments within the estate
estate_id = response.json()["id"]

Apartments - 🔗 Jump to API

Once you have created an estate, you can fill it with apartments. Note that you do not need to provide an office when creating an apartment, as it will inherit the office from the estate. We consider an apartment to be a real world entity and is considered to be unique with a combination of [national_id, city, street, street_number]. This practice ensures that we do not have duplicates and that we can transfer apartments between landlords if they change ownership without needing to remove and recreate descriptions and media assets.

Below you can find a python code example that shows how you can create a simple apartment within your company. Media assets like images, videos, floor plans, and promotional material can be uploaded in a later step. You can refer to the media section for more information on how to upload media assets and assign them to your entities.

import requests
import json

token = "eyJ0eXAiOi...."
estate_id = 15

response = requests.post("https://api.homeq.se/api/v4/apartment", json.dumps({
    "estate": estate_id,
    "street_name": "Street name",
    "street_number": "4",
    "zip_code": "19448",
    "longitude": 17.9429115,
    "latitude": 59.3975395,
    "county": "Stockholm",
    "municipality": "Upplands Väsby",
    "rooms": 4,
    "floor": 3,
    "area": 81.40,
    "rent": 7400,
    "description": "Description of the apartment",
    "national_id": "1304",
    "landlord_object_id": "AF43CD7U",
    "renovation_date": "2017-01-14",
    "washing_machine": "PREPARED",
    "dishwasher": "PRESENT",
    "balcony": "NORTH",
    "dryer": "NONE",
    "bathtub": "PRESENT",
    "internet_included": True,
    "cable_package_included": False,
    "water": "COLD_INCLUDED",
    "garage": "INCLUDED",
    "parking": "INCLUDED",
    "electricity_included": True,
    "heating_included": True,
    "laundry_room": True,
    "security_door": True,
    "shower": True,
    "kitchen_fan": "PRESENT",
    "patio": True,
    "handicap_adapted": True,
    "accessibility_adapted": True,
    "elevator": True,
    "pantry": True
}), headers={
    "Content-Type": "application/json",
    "Authorization": f"JWT {token}"
})

assert response.status_code == 201, "could not create the apartment"

# Extract the apartment id to use when creating object ad or uploading images that belongs to the apartment
apartment_id = response.json()["id"]

Query Inventory - 🔗 Jump to API

After creating inventory you can find it by using the normal GET request for the given entity. However, when doing larger fetch operations it is recommended to use the inventory endpoint.

This endpoint allows you to fetch estates, apartments, and listings in one go. You can also filter the results by various parameters like status, project and your own landlord_object_id.

Be aware that the underlying data is fetched via elastic search and might be slightly delayed compared to the normal endpoints. We however recommend using this endpoint for larger fetch operations as it is more efficient than to iterate through your inventory with multiple requests.

Uploads - 🔗 Jump to API

To work with media files like pictures, videos and PDFs in our application you need to use our file reference endpoint. You will specify the content_type and a md5 hash of the file and will receive an upload url that you can use to upload the file directly to AWS.

You will also receive a file reference id that you can use to refer to the file when updating the floor plan of an apartment, adding pictures to an estate, etc.

You can find the documentation here:

Image Resizing

When you upload certain type sof pictures to our platform we automatically produce thumbnail images in different sizes.

The following categories will trigger the generation of smaller sizes: estate_images, estate_area_images, apartment_images, project_images and project_area_images.

The available sizes are 320, 460, 840, 1440, 1920 and 2880 pixels in width. The height is adjusted to keep the aspect ratio.

Video Compression

When uploading videos to apartments or projects we will also compress them and make the compressed version available for the end users. You can ensure that the compression kept the quality of the video by checking the listing or the project yourself. It might take a few minutes for the compressed video to be available.

Using Media Files outside HomeQ.se

When you are using media files outside HomeQ.se some rules apply to ensure image quality and performance. Usually this scenario applies when you want to make the active listings available on your own website with a custom implementation. Please ensure that you:

• Always use the smaller image sizes like 360 or 480 when displaying a card or gallery of active listings
• Always make sure to include the HTTP Referer Header when directly fetching the images rom our AWS S3 instance (mandatory from 1. May 2025)
• Always talk to us if your use case involves displaying videos on your page that are hosted on our AWS S3 instance

To access the smaller image sizes you have to adjust the URL of the image, as our API will usually only provide the original resource URI. You can do that by replacing the file ending with .jpeg as all resized images will be jpeg. Additionally, you have to insert the size you want to use before the type reference in the URL. As an example the url:

https://homeq-media-live.s3.amazonaws.com/apartment_images/c5c949b...7ea.png

would become

https://homeq-media-live.s3.amazonaws.com/320/apartment_images/c5c949b...7ea.jpeg

Requirements - 🔗 Jump to API

Before you start creating listings you should define a requirement profile. It describes the requirements that an applicant needs to meet in order to be considered approved. When an application is made, the applicant is matched against the requirement profile that you choose to use.

Requirement profiles contain checks for income, occupation type, credit information and more. Please refer to the specific API documentation for all the available fields.

Listings - 🔗 Jump to API

Once you are ready and want to fill a vacant apartment you can create a listing. With listings you have two options broadly speaking. You can rent out an apartment as a normal succession rental or as a project rental.

When renting out as a project rental you first need to create a project and then add an estate to that project. Then you can flag the call you make with is_project_rental=true to create the listing associated to the project. Normal rentals don't need this extra step and can be created directly.

When creating a listing there is a variety of information you can provide. How the candidates are sorted, when the apartment is accessible, whether it is a short lease or not, and more. Note that you can also create a draft listing that you can later publish when you are ready.

A widget is something you can easily embedd on your website to show all the published listings you currently have available for consumers to apply on.

If you want to show HomeQ Ads on your website you can simply use one of our widgets to easily embed ad cards. Currently there is only one type of widget that you can embed. How do do this is explained in the next section. Make sure to sign up on our technical email list so you get information regarding upgrades and changes in the widget.

1. Include the anchor

Introduce a div in your HTML where you want the widget to appear. You need to replace the company number with your company ID. If you don't know your company ID feel free to contact HomeQ support.

<div id="homeq-anchor" data-company="3"></div>

If you are using WordPress

If you are using the native editor for your page (Gutenberg or classic editor) you can follow the following link on how to add HTML to a WordPress page. Then copy and paste div where you want the widget to appear.

If you are not using the native editor for your WordPress page, look up how to add HTML to a section for the plugin you are using. Then copy and paste div where you want the widget to appear.

2. Add the js & css files

Copy and paste the following line at the end of the head of your HTML.

<link rel="stylesheet" type="text/css" href="https://widgets.homeq.se/widgets/overview.css"/>

Copy and paste the following line at the end of the body of your HTML.

<script type="application/javascript" src="https://widgets.homeq.se/widgets/overview.js"></script>

If you are using WordPress

If you have access to the code of your WordPress theme then you can follow the previous instructions and enqueue the files in yourfunctions.php file.

If you don't have access to the code of your WordPress site, you can use a plugin to load the JavaScript and CSS for the widget. First, you need to install and activate theInsert Headers and Footers plugin. If you don't know how to install the plugin, see a step by step guide on how to install a WordPress plugin. Upon activation, you need to visit theSettings » Insert Headers and Footers page. You will see two boxes, one for the header and the other for the footer section.

Insert Headers and Footers plugin

You can now copy the following line and then paste the line in to the header box. <link rel="stylesheet" type="text/css" href="https://widgets.homeq.se/widgets/overview.css"/>

Then copy and paste the following line in to the footer box.

<script type="application/javascript" src="https://widgets.homeq.se/widgets/overview.js"></script>

Finally click on the save button, and the CSS and JavaScript for the widget will be loaded on your WordPress site.

3. Enjoy

Custom Styling

We build in easy to change styling, in order to fit your brand colors and integrate it seamlessly. You can simply add a <style> element in your page and overwrite the various elements with custom colours. You can refer to this file.

Developing

In order to test the widget before you want to use it in production you can simply add a data parameter to the anchor.

<div id="homeq-anchor" data-company="3" data-environment="demo"></div>

When having a page about a project you are able to embed a widget to collect emails from interested people.

Copy the code below for the iframe and paste it where you want the widget to appear. You need to adjust the PROJECT_ID to match the project you want to collect emails for. If you don't know the id for your project, you can find it in the landlord portal or contact our support.

<iframe width="100%" height="400px" src="https://www.homeq.se/widgets/project?project=<PROJECT_ID>"/>

Webhooks are requests we make to your system to inform you of events that have occurred in our system.

As an admin user you can configure a webhook in the landlord portal. You can also specify which events you want to receive POST requests for. We will queue the events so they will be retried every 5 minutes if we do not receive a 200 status code on the POST request.

The maximum time we try this is 7 days. Each event will contain the id's referencing the objects involved during this specific event. Please check the reference below for the different events:

• Agreement Event
• Project Follower Event
• Reservation Event
• Signature Event
• Signing Completed Event