Help

This guide covers the agency cabinet — everything you see after signing in as an agency. The chapters follow the menu of the cabinet, so you can read it top to bottom or jump straight to the section you need from the list on the left.

Registration and approval

Agencies sign up on the Join page. The form asks for the company details (legal name, registration and VAT numbers, company type, year of foundation), the office address, contacts, the logo and the documents we need for the check. Two fields deserve attention:

  • Office country is the country of your office. It is chosen at registration and can be changed later in the profile. It does not limit where you work: listings can be added in any country, and your subscriptions decide where they are shown. The regions you work in are set later on the Work Regions page.
  • Documents are stored encrypted and are visible only to the administrator.

The account is created immediately, but until an administrator approves it only the Profile page is open — the rest of the menu redirects back to it. When the agency is approved you get an email; if it is rejected, the reason is shown in the cabinet and sent by email, and the application can be corrected and sent again.

Confirm your email address by the link from the letter we send after registration. While it is not confirmed, a reminder with a Resend button hangs at the top of every page of the cabinet. The button sends a new letter no more than once a minute; the link in the letter lives 24 hours.

Signing in

The cabinet uses the same sign-in form as the rest of the site: the account type is recognised by the email address. Before the form is accepted the slider has to be moved — it is a check against automatic sign-in attempts, and it also guards the “Continue with Google” button.

Five failed attempts from one IP address close the form for fifteen minutes. If you forgot the password, use Forgot password: the link from the letter is valid for one hour.

Subscription and credit

Everything paid on the site is paid from one place — the credit balance of the agency. The balance and the Top up button are at the top of the Packages page; payment goes through the card form of our payment provider, and the money appears on the balance as soon as the provider confirms it.

The packages themselves:

  • Subscription: 1 country and Subscription: All countries — the main packages. With any active subscription the Properties, New Buildings, Agents and XML Import pages are open, and you can add listings in any country. Visitors see a listing only if a subscription covers its country: 1 country covers the country you choose when buying it (buy it again for every further country), All countries covers every country. Without a subscription those pages are closed and the listings of the agency are hidden from the public catalogue. The Profile, Packages and Payments pages stay open.
  • Agency VIP — the agency is marked as VIP in the catalogue and its listings can show labels.
  • Logo on image — your logo is drawn on the photos of your listings in the search results.
  • Home Week and Country Week — advertising weeks, see the chapter below.

Every package has its own duration and can be bought for one to twelve months at once; the price and the period are written on the package card. The period is counted from the day of the purchase, not from the day the previous one ends, so a package is best renewed on its last days rather than in advance.

Profile

The public face of the agency: name, logo, description, contacts and social links. The description is multilingual — switch the language above the editor and fill in the versions you need; visitors see the text in their own language and English where the translation is missing.

The Location block holds the office address and the point on the map; the office can be in any country. Under it you see the countries of your subscription.

Changing the email address starts the confirmation again: the new address has to be confirmed by the link from the letter.

Properties

The list of your listings with a filter (status, type, deal, location, price, marks) and bulk actions for the selected rows. A new listing is created by the + button, an existing one opens in the editor by a click on the row.

The editor is split into tabs:

  • Common — status, code, type of the property, deal, price, condition, area, rooms, description, labels.
  • Location — address and the point on the map; the location is chosen from the reference book, not typed by hand, so the listing lands in the right filters.
  • Features and Energy — amenities and the energy certificate.
  • Images, Floor plans, Videos — the gallery, the plans and the links to video; the first image is the cover.
  • Agents — who of your agents is responsible for the listing. The assigned agent is shown as the contact on the property page and receives the messages from the form.
  • Co-ownership — for listings sold in shares (only for sale, see the separate chapter).
  • Promotions — the paid extras of this listing.

Two fields on the Common tab are worth explaining. Access code makes the listing private: it opens only by a direct link with the code, and it is not shown in the catalogue. 3D tour URL takes a Matterport or Kuula link and shows the tour on the property page.

A listing is visible on the site when its status is enabled, the agency is approved and a subscription of the agency covers the country of the listing. Listings in other countries stay in the cabinet with the Not on the site mark: visitors cannot find them or open them by a link. As soon as you buy a subscription for that country, they are shown again.

Labels and Open house

A listing can carry up to two labels — “Sold”, “Reserved”, “Price reduced”, “Exclusive”, “Open house” and so on. They are chosen on the Common tab and shown as a badge on the photo in the search results. Labels are a paid extra: each of the two slots is bought on the Promotions tab, and they are shown only for VIP agencies.

The Open house label additionally asks for the dates of the viewing. The badge then shows the date — or the range, if the viewing takes more than one day.

New buildings

A new building is a project with its own name, address, number of floors, gallery and description. It is created on the New Buildings page and is shown on the site as a separate card with the list of the apartments inside it.

The apartments are ordinary listings tied to the building: they share its address and location, so the address does not have to be typed for every one of them. They are edited in the same editor as any other listing.

XML import

If your listings already live in another system, they can be imported instead of being typed by hand. The page keeps two separate feeds, on two tabs: Objects and New buildings. Each has its own source and its own field mapping. The third tab, Help, is the full list of fields we accept — tag by tag, with an explanation of what goes into each one and a downloadable example.

Loading a feed

In the top row you choose the Source — a URL we will fetch, or a file you upload — and the Feed format. Leave the format on Auto and we will recognise it ourselves; if the feed is one of the standard exports (OpenImmo, Kyero, Immobiliare/Indomio, OLX) the fields are laid out without any work from you. Anything else is read as a universal feed, where you point the fields at your own tags yourself.

Load XML reads the feed and checks it. Nothing is imported at this point. If the file does not parse, you get the parser errors with line numbers, and the previously loaded feed stays untouched — a broken export cannot destroy a working import. The feed is never re-read on its own: to pick up changes from your system, press Load XML again.

Mapping

The left column is our fields, the right one is your tags. What was recognised automatically is already selected; the rest you set by hand. Next to the table is Record XML — one record of your feed as it really is, with arrows to leaf through the records. Drag a tag from there onto a field (or click the tag and then the field) and it is bound; the value from the current record appears immediately next to the field, so the mapping is checked with your eyes rather than guessed.

Tags that sit inside containers are shown as a path — images/image, descriptions/en — because the same name can appear in several places of one record. The Validate button re-checks the whole feed against the mapping as it is on screen, without saving it: you see at once how many records will pass and how many will be rejected.

Two fields work differently from the rest. Currency can be taken from a tag or fixed for the whole feed — useful when the export has no currency at all; the price is converted to euro anyway, and the original amount with its currency is kept next to it. Location: the country can be taken from a tag (an ISO code such as DE, or the name of the country); without it the country is found from the coordinates, and without coordinates it is the country of your office. The region, city and districts are calculated from the coordinates. Map Lat and Lng, and the resulting path is shown right under the address. Listings are imported into any country; the import log names the countries where they are not shown because your subscription does not cover them.

Objects

The tab shows everything the feed contains — before the import runs, not after. Green panels are the listings that will be created, pink ones are those that will not. Click a pink one and it says exactly what is missing: missing required fields: price, photos. The counters on the tab caption keep the score, green and red.

On the right are the fields of the selected record with their values, the location path calculated from the coordinates, the photos and the floor plans. Pictures are shown straight from your links, so you can see whether they open at all, and each one carries its state — not loaded yet, stored, or failed. The list has a text search by code and address and a filter for normal or faulty records.

Import process

Start begins the import and turns into Pause; the work goes on in the background, in portions, and when it is done the stream becomes Done. Process now does one round immediately instead of waiting. Rescan re-reads the records from the feed already loaded — that is what you press after changing the mapping. Restart wipes everything imported and starts from scratch. Delete All removes the feed together with everything it created; listings added by hand are not touched.

Below is the log of the run: the last hundred lines on screen, the full one by a link. It starts from scratch with every new feed, so it always describes the current import: how many records were read, created, updated and removed, and what went wrong with the particular ones.

What the feed must contain

Every record needs a code — your own identifier of the listing. It is the only thing that lets us tell your listings apart between exports, so records without a code are skipped, and a code that repeats twice in one file is an error: only the first record is imported. Keep the codes stable; a changed code means a new listing, not an updated one.

A listing is published when it has an address, a type, a deal, a price and at least one photo that we managed to download. Anything missing and the record is marked as faulty and does not reach the site; if it was published before, it is switched off. Up to 30 photos per listing are taken. Photos are downloaded to our side and keep working even if the links in your system die; a link that fails to download makes the record faulty rather than publishing it with a broken gallery.

Between runs we compare the records: what is unchanged is not touched, and its photos are not fetched again. What disappeared from the feed is removed from the site along with its images — a listing deleted in your system disappears here too.

Listings are marked XML or Manual so you always know where a listing came from. If you typed a listing by hand and the feed later brings the same code, the existing listing is taken over rather than duplicated, and from then on it is managed by the feed.

Agents

Agents are the employees who work with your listings. An agent is added on the Agents page and gets their own login into the same cabinet, but with a shorter menu: profile, listings and new buildings.

By default an agent sees only the listings assigned to them. The single permission in the agent card — access to all objects of the agency — opens the whole catalogue of the agency to them.

The agent assigned to a listing is shown on its page as the contact person: name, photo, phone and languages. Messages sent from the form on the property page come to them by email.

Work regions

The regions where the agency actually works — in any country. The list has a practical meaning: requests that visitors send from the Sell form go to the agencies whose regions cover the location of the request and whose subscription covers its country. An empty or outdated list means fewer requests, not more.

Regions are chosen from the same reference book as the location of a listing, at any depth — a whole region, a district or a single city.

Home Week

An advertising week is the showcase on the main page: for one week the block belongs to a single agency. There are two kinds — the week of the home page of a country (Home Week) and the week of the country page (Country Week). A week is bought for one of the countries of your subscription, and every country has its own calendar.

How it works:

  • Open the calendar on the Home Week page, choose the country if your subscription covers several, and take any free week. Weeks that are already taken are marked, and a week next to your own in the same country cannot be taken — any number of weeks is allowed, but not two in a row.
  • The week is paid from the credit balance at the moment of booking.
  • Fill the showcase: the text at the top and the listings that go into the Rent, Sale and Video sections. The listings are marked in the editor of the listing itself (the Home Week checkboxes on the Promotions tab).

Mark the listings before the week starts: the grids show only the marked listings in the country of the week, and an unmarked week is displayed empty. The text of the showcase is edited on the Home Week page and is multilingual, like the description in the profile.

Promotions

Promotions are paid extras of one particular listing. They are bought on the Promotions tab of the listing editor, are paid from the credit balance and are counted in days:

  • Highlight with frame — the card is framed in the search results.
  • Highlight with frame premium — a thicker frame and the “Premium listing” caption.
  • Label 1 and Label 2 — the two label slots described above.

The number of days is chosen when buying; the total is shown before the confirmation, and the day the service runs out is written on the tab. When it runs out the listing stays on the site, it simply loses the decoration.

Payments

The history of everything that was paid, newest first. Two kinds of records live in one list:

  • Packages — the subscription, VIP, logo, advertising weeks. They have a period they are valid for: “valid from” is the day of the purchase, “valid to” is the last day the service works.
  • Credit movements — top-ups and the payments for promotions. They have no period, only the date and the amount; a minus means the money was taken from the balance.

The filter above the list narrows it down to one package, and the Total in the header is counted over packages only — mixing the payments for packages with the movement of the credit would give a number that means nothing.

API for listings

If your listings live in your own CRM, you do not have to retype them here. The API lets your software create, update and delete your listings and new buildings on BSRealty directly. It covers exactly two things — Properties and New buildings. Everything else (packages, promotions, payments, agents, leads) is available in the cabinet only.

Turning it on

The API is opened by the API package: buy it in your cabinet under Packages and access starts working at once — nobody has to approve anything. When the package runs out the API stops answering until you renew it; your listings stay where they are.

Two more things are set on the XML page of your cabinet, and without them the API refuses to work:

  • The key. Press Create new key and copy what appears — the key is shown once and never again. Pressing the button again issues a new key and kills the old one, which is also how you revoke a key that leaked. You cannot supply a key of your own: the server generates it.
  • The IP address. Exactly one address — the one your software calls from. Requests from anywhere else are refused even with the correct key, so if your server moves, change the address here first.

Base address and format

All calls go to https://bsrealty.eu/api/v1/…. Requests and responses are JSON in UTF-8; send Content-Type: application/json with every request that has a body. A successful answer always contains "ok": true, a failed one "ok": false and an error object. The HTTP status matches the error, so you can branch on either.

Authentication

There is no login and no password: the key is the whole authentication, so there is nothing for a bot to guess. Send it with every request in the Authorization header — X-Api-Key: bsr_… works too if that suits your HTTP client better.

Authorization: Bearer bsr_2f9c…

Check that everything is in place with a harmless call:

GET https://bsrealty.eu/api/v1/meta
Authorization: Bearer bsr_2f9c…

→ {"ok": true,
   "meta": {…, "agency": {"id": 42, "name": "Your Agency", "country": "EE", "subscription_countries": ["EE", "LV"]}}}

A wrong or replaced key answers 401 bad_key, a call from another address 403 ip_not_allowed, and an expired package 403 api_disabled. Keys belong to agency accounts only — agents work in the cabinet.

Rate limits

What Limit
Reading (GET, search) 120 requests per minute
Writing (POST, PUT, DELETE) 30 requests per minute, 2000 per day
New photo links queued 500 per day
Requests with an unknown key 20 per hour from one address

Every answer carries X-RateLimit-Remaining. If you go over, you get 429 rate_limited and a Retry-After header telling you how many seconds to wait. One request may carry up to 1000 listings, so a nightly sync of a large portfolio fits into a handful of calls.

Endpoints

Method and path What it does
GET /api/v1/meta Reference lists: property types, deals, conditions, features, currencies, limits
GET /api/v1/properties Your listings, with filters in the query string
POST /api/v1/properties/search The same list, with the filters sent as JSON
GET /api/v1/properties/Code One listing
POST /api/v1/properties Create — one listing, or {"items": [ … ]} for many
PUT /api/v1/properties/Code Update one listing
PUT /api/v1/properties Update many: {"items": [ … ]}, each with its code
DELETE /api/v1/properties/Code Delete one listing
DELETE /api/v1/properties Delete many: {"codes": ["A-1", "A-2"]}

New buildings work exactly the same way under /api/v1/nb — the same five verbs, the same batching, their own set of fields (see below).

In a batch, one bad record does not spoil the rest: each item gets its own result.

{"ok": true,
 "results": [
   {"code": "A-1", "ok": true,  "id": 5120},
   {"code": "A-2", "ok": false, "error": {"code": "code_exists", "message": "…"}}
 ],
 "summary": {"total": 2, "ok": 1, "failed": 1}}

The code is the key

Every listing is addressed by its code — the same short reference you see in the cabinet. Put it in the URL for a single record, or in the body of each item in a batch. Two rules follow from that:

  • The code is required in every create, update, read and delete.
  • The code cannot be changed afterwards. If you really need a different one, delete the listing and create it again.

Codes are yours alone: another agency may use the same code, and it will never collide with yours. If two of your own listings happen to share one code (it can happen with older records), the API refuses to guess and answers 409 code_ambiguous — fix the duplicate in the cabinet and try again.

Updates change only what you send

A PUT touches only the fields present in the JSON. Send {"code": "A-1", "price": 195000} and only the price changes — the description, photos and everything else stay as they were.

  • Field absent from the JSON — it is not touched.
  • Field present but empty ("" or null) — it is cleared.
  • code, address and price can be changed but never cleared: a listing without them makes no sense.

Validation is all-or-nothing: if any field is wrong, nothing is saved and the answer lists what to fix.

Listing fields

The names are the same as the tags of our XML feed import, so one dictionary serves both. To create a listing you need at least code, address, type, deal and price; everything else is optional.

Field Value
code Your reference, up to 40 characters. Required, never changes.
deal sale or rent
type Slug or id from /meta: apartment, house, villa, land, office…
price Number in the currency below. Stored in euro as well, converted at the daily rate.
currency ISO code (EUR, USD…). Empty — the currency of the country.
price_prefix Short note next to the price: from, per week
description Plain text, or an object per language: {"en": "…", "de": "…"}
country ISO code of the country (DE, ES…). Optional: without it the country is found from the coordinates or the address.
address Street address. Required; the location is derived from it (see below).
zip Postal code
lat, lng Coordinates, if you have them
area_m2, land_m2 Living area and plot, in square metres
rooms, bedrooms, bathrooms Counts
floor, floors Which floor, and how many the building has
year_built Year of construction
garage, garage_m2 Parking places and their area
condition Slug from /meta: new, not_new, under_construction, needs_renovation, dilapidated
features Array or comma-separated list of codes from /meta: ["balcony", "elevator"]
energy_class A+ … G
energy_global_index, energy_renewable_index, energy_building_perf, energy_epc_current, energy_epc_potential Energy certificate numbers
complete_month, complete_year Completion date for property under construction
available_from Date a rental becomes available, YYYY-MM-DD
nb_code Code of the new building this unit belongs to
access_code Private access code: with it set, the listing opens only by direct link
video_url, tour_url Video and 3D tour links
crypto_pay true if you accept crypto for this one
images, fp Photos and floor plans — see below
enabled true to publish, false to hide

Reading a listing gives you the same fields back plus a few you cannot set: id, moderation, price_eur, country, state, loc1…loc5, created, updated, url and geo_pending. Promotions are not exposed through the API at all — buy and manage them in the cabinet.

Location is worked out for you

You never fill in the region or city by hand — send the address (and the country, if you know it) and we do the rest.

  • If you send lat and lng, we use them straight away and the location appears immediately.
  • If you send only the address, it goes into a queue and is looked up within a few minutes. Until then the answer shows "geo_pending": true.
  • The country comes from the country field (an ISO code such as EE). Without it the country is taken from the coordinates or found by the address, and as a last resort it is the country of your office. Listings can be placed in any country, but visitors see them only in the countries of your subscription.

If an address cannot be found after three attempts, the listing simply stays without coordinates — it still works, it just will not appear on the map. Sending exact coordinates is always the more reliable option.

Photos and floor plans

You do not upload files. You send links, and we download the pictures ourselves, convert them and store them. Photos go into images, floor plans into fp.

PUT https://bsrealty.eu/api/v1/properties/A-1

{"images": ["https://your-crm.example/1.jpg",
            "https://your-crm.example/2.jpg"],
 "fp":     [{"url": "https://your-crm.example/plan-2.jpg", "floor": 2}]}

Each of the two lists is the complete list for that listing. Links you keep sending stay as they are and are not downloaded again; links you drop disappear together with their files. If you leave the key out of the JSON entirely, the pictures are not touched at all — so an update of the price does not disturb the gallery.

A picture can also be an object with a category: {"url": "…", "category": "Kitchen"}. Floor plans take floor instead. The first photo becomes the main one.

Downloading happens in the background, so reading a listing shows the state of every picture:

"images": [
  {"url": "https://…/1.jpg", "status": "ready",
   "site_url": "https://bsrealty.eu/img/a/b/c/d/…webp"},
  {"url": "https://…/2.jpg", "status": "pending"},
  {"url": "https://…/3.jpg", "status": "failed", "error": "HTTP 404"}
]

A failed link is retried three times before it is given up on; fix the address and send the list again. Links must be publicly reachable over http or https — addresses inside private networks are refused.

Publishing

A listing created through the API is switched off: it is saved, you can check it in the cabinet, and nobody sees it on the site yet. Publish it when it is ready:

PUT https://bsrealty.eu/api/v1/properties/A-1
{"enabled": true}

Publishing requires at least one photo that has actually been downloaded. If the pictures are still in the queue you get 409 images_pending — wait a few minutes and repeat. With no photos at all it is 409 no_images. Sending {"enabled": false} hides the listing again at any time.

New buildings

Under /api/v1/nb, with the same rules: addressed by code, updates change only what you send, pictures work identically. Only name is required to create one. The fields are code, name, description, country, address, zip, lat, lng, floors, video_url, tour_url, images, fp and enabled. Neither name nor address can be cleared.

To attach a unit to a new building, put the building's code into the listing's nb_code.

Reading and filtering

The list understands the same filters as the cabinet. Pass them in the query string, or as JSON to /properties/search if you prefer.

GET https://bsrealty.eu/api/v1/properties?deal=sale&type=apartment&price_min=100000&per_page=200

POST https://bsrealty.eu/api/v1/properties/search
{"deal": "sale", "price_min": 100000, "rooms_min": 2, "per_page": 200}
Filter Meaning
search Text search over the code, address, location
code Exact code
enabled 1 — published only, 0 — hidden only
deal, type, condition, features As in the fields above
price_min, price_max, area_min, area_max, land_min, land_max Ranges
rooms, rooms_min, bedrooms, bedrooms_min, bathrooms, bathrooms_min Counts, exact or minimum
year_min, year_max, floor_min, floor_max Ranges
country, state, loc1…loc5, geo_id Location
nb_code Units of one new building
since Only records changed after this date/time — for incremental sync
page, per_page Paging. per_page=0 returns everything found.

Instead of downloading the whole catalogue every hour, remember the time of your last successful sync and ask for since — you will get only what actually changed.

Errors

Every failure looks the same, and the machine-readable code is what you should branch on:

{"ok": false,
 "error": {"code": "validation",
           "message": "Missing required fields: address, price",
           "fields": {"address": "required", "price": "required"}}}
Code HTTP What happened
no_key 401 No Authorization header in the request
bad_key 401 The key is unknown — it was replaced or mistyped
api_disabled 403 The API package is not active — renew it in the cabinet
subscription_required 403 No active subscription (1 country or All countries): listings cannot be created or changed
ip_required 403 No allowed IP is set on the XML page of your cabinet
ip_not_allowed 403 The request came from a different address
agency_not_approved 403 The agency account is not approved yet
not_found 404 No record of yours with that code
code_exists 409 You already have a record with that code
code_ambiguous 409 Several of your records share this code — fix it in the cabinet
images_pending, no_images 409 Cannot publish yet: no downloaded photo
batch_too_large 413 More than 1000 records in one request
validation, code_immutable 422 The data is wrong; fields says where
rate_limited 429 Too many requests — wait Retry-After seconds
maintenance 503 The site is closed for maintenance, try later
server_error 500 Our fault. If it repeats, write to us.

A complete example

# 1. create a listing (it is created switched off)
curl -s -X POST https://bsrealty.eu/api/v1/properties \
     -H "Authorization: Bearer bsr_2f9c…" \
     -H "Content-Type: application/json" \
     -d '{"code":"A-1024",
          "address":"Narva mnt 5, Tallinn",
          "type":"apartment", "deal":"sale",
          "price":180000, "currency":"EUR",
          "rooms":3, "area_m2":72.5,
          "description":{"en":"Bright flat near the park"},
          "features":["balcony","elevator"],
          "images":["https://your-crm.example/1.jpg",
                    "https://your-crm.example/2.jpg"]}'

# 2. a few minutes later, when the photos are downloaded — publish it
curl -s -X PUT https://bsrealty.eu/api/v1/properties/A-1024 \
     -H "Authorization: Bearer bsr_2f9c…" \
     -H "Content-Type: application/json" \
     -d '{"enabled": true}'

# 3. later: change just the price, nothing else is touched
curl -s -X PUT https://bsrealty.eu/api/v1/properties/A-1024 \
     -H "Authorization: Bearer bsr_2f9c…" \
     -H "Content-Type: application/json" \
     -d '{"price": 175000}'

Keep the key out of anything a browser can reach — a web page, a mobile app, a public repository: what reaches a browser reaches your visitors too. The API is meant for server-to-server use. If you suspect the key has leaked, press Create new key: the old one dies the same second.

Sell

This chapter is for property owners rather than for agencies. Sell in the top menu is where an owner hands a property over to the agencies working in their region: they describe it once, and the agencies come back to them with an offer. The service is free for the owner.

A visitor who is not signed in sees a page explaining how it works, with buttons to sign in or to create an account; the form itself opens for a signed-in user with a confirmed email address. The text of that page is edited in Templates → Sell.

What the owner fills in: the deal (sale or rent), the property type, the price, the size, the rooms, the year of construction, the amenities, the address on the map and up to ten photos. As soon as the region is chosen, the agencies working there are listed in the form — the owner ticks the ones the request should go to, or sends it to every VIP agency in the region with one button.

The request is emailed to the chosen agencies together with the owner's name, email and phone. From the agency side it arrives like any other enquiry, and the answer goes straight back to the owner. Owners do not publish anything on the site themselves — the request only goes to the agencies, and nothing from it appears in the catalogue.

One account holds one such property: sending the form again updates the same request instead of creating a second one.

Support

Something is unclear, does not work or looks wrong? Write to us through the Contact page — describe what you did and what you expected, and attach the code of the listing if the question is about a particular one.