Listing API

How to get access

1. 01

   Create an agency profile

   Sign in and create the profile of your agency. It is free and works at once.

2. 02

   Request access

   On the API tab of the agency page, tell us which system you keep your listings in and send the request.

3. 03

   We switch the API on

   We look at the request and answer by e-mail. Once the API is on, the API tab lets you create keys.

4. 04

   Create a key

   The owner creates a key and gives it to whoever connects your system. The key is shown once.

What the API does and does not do

• It works only with your agency's own listings: publish, update, take down and check them.
• It has no search and returns nothing about other agencies' or private sellers' listings. It is not a way to read the site.
• A key belongs to the agency, not to a person. Only the owner of the profile creates and revokes keys, at most 5 at a time.
• A key is shown once, Siia keeps only its fingerprint, and every key stops working after 365 days.
• Personal tokens from the "AI access" page do not work here.

Requests

All addresses start with https://siia.ee/api/agency/v1. Every request carries the header Authorization: Bearer <key>. Answers are JSON.

PUT/listings/{external_id}

Publish a new listing or replace an existing one. The body is one listing with the fields of the JSON feed; external_id is your own id for it and goes in the address. Checked at once; the address, photos and publishing follow within a minute.

DELETE/listings/{external_id}

Take the listing off the site. Send {"reason": "sold"} when it was sold. Sending it again with PUT brings it back.

GET/listings/{external_id}

The state of one listing and the result of the last change, with the reasons if it failed. Kept for 14 days.

GET/listings

Your agency's listings that have an external_id, newest change first, 100 per page. Pass next_cursor as ?cursor= for the next page.

Examples

Publish or update a listing. listing.json holds one listing:

curl -X PUT https://siia.ee/api/agency/v1/listings/KB-10231 \
  -H 'Authorization: Bearer YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d @listing.json

{
    "deal": "sale",
    "type": "apartment",
    "price": 189000,
    "address": {
        "county": "Harju maakond",
        "city": "Tallinn",
        "district": "Kalamaja",
        "street": "Vabriku",
        "house": "12",
        "unit": "5"
    },
    "coordinates": {
        "lat": 59.44731,
        "lng": 24.73142
    },
    "area": 54.3,
    "rooms": 2,
    "bedrooms": 1,
    "bathrooms": 1,
    "floor": 3,
    "floors_total": 5,
    "built_year": 1962,
    "renovated_year": 2021,
    "condition": "renovated",
    "energy_label": "C",
    "material": "stone",
    "balcony_area": 4.5,
    "features": [
        "balcony",
        "storage",
        "fibre"
    ],
    "headline": {
        "et": "Renoveeritud kahetoaline korter Kalamajas",
        "ru": "Двухкомнатная квартира после ремонта в Каламая",
        "en": "Renovated two-room apartment in Kalamaja"
    },
    "description": {
        "et": "Valgusküllane korter vaikse sisehoovi poole. Uus elektrisüsteem ja torustik, rõdu õhtupäikesega.\n\nTrammipeatus on kolme minuti kaugusel.",
        "ru": "Светлая квартира с окнами в тихий двор. Новая электрика и трубы, балкон на вечернее солнце.",
        "en": "A bright apartment facing a quiet courtyard. New wiring and plumbing, a balcony with evening sun."
    },
    "agent_email": "[email protected]",
    "photos": [
        "https://media.example.ee/listings/10231/01.jpg",
        "https://media.example.ee/listings/10231/02.jpg",
        "https://media.example.ee/listings/10231/03.jpg"
    ],
    "floor_plan": "https://media.example.ee/listings/10231/plan.png"
}

The listing passed the checks and is on its way:

{
    "external_id": "KB-10231",
    "state": "queued",
    "message": "Accepted. The listing is published or updated in a moment; read the result with GET on the same address.",
    "warnings": []
}

Something required is missing. Nothing was changed:

{
    "error": {
        "code": "invalid_listing",
        "message": "The listing was not accepted. Nothing was changed."
    },
    "problems": [
        {
            "level": "error",
            "code": "missing_price",
            "detail": null,
            "message": "The price is missing or not a number"
        }
    ]
}

Check the result:

curl https://siia.ee/api/agency/v1/listings/KB-10231 \
  -H 'Authorization: Bearer YOUR_KEY'

{
    "external_id": "KB-10231",
    "listing": {
        "external_id": "KB-10231",
        "status": "live",
        "is_public": true,
        "url": "https://siia.ee/homes/kalamaja-vabriku-12",
        "price": 189000,
        "updated_at": "2026-11-14T10:02:11+02:00"
    },
    "last_change": {
        "state": "done",
        "result": "created",
        "accepted_at": "2026-11-14T10:01:58+02:00",
        "finished_at": "2026-11-14T10:02:11+02:00"
    }
}

The home was sold:

curl -X DELETE https://siia.ee/api/agency/v1/listings/KB-10231 \
  -H 'Authorization: Bearer YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"reason": "sold"}'

Answer codes

200

Done, or here is what you asked for.

202

Accepted. Read the result with GET.

400

The body is not one listing as a JSON object.

401

No key, a wrong, revoked or expired key, or a personal token instead of an agency key.

403

The API is not switched on for this agency.

404

Your agency has no listing with this external_id.

409

Siia has taken this listing down. It cannot be published again.

413

The listing is too large. Send photos as links.

422

The listing was not accepted. The answer lists what to fix.

429

Too many requests. Wait for the number of seconds in Retry-After.

Rules and limits

• Fields, accepted values and checks are the same as in the feed. The feed page describes every field.
• Photos are links that Siia downloads (https only), in the order you send them.
• At most 120 requests per minute per key and 3000 changes per hour per agency; 120 requests per minute per address.
• A request body is at most 256 KB.
• Listings you typed by hand on Siia have no external_id, and the API never touches them.