Feed API - Technical Documentation

Real estate portal integration with Lukian CRM

v2.0

1. Introduction

Lukian CRM offers two integration methods for real estate portals:

Push (standard)

Lukian automatically publishes listings to the portal API (Storia, Imobiliare.ro, Publi24). We do all the work.

Pull (feed)

The portal reads listings from our API feed. This document covers the Pull method.

For most partner portals, the Lukian team performs the complete integration based on the portal's API documentation. If you prefer this approach, contact us.

2. Authentication

Each portal receives a unique API key from Lukian. The key is passed as a query parameter:

GET
https://api.lukian.ai/api/v2/portals/homezz/feed.json?api_key=YOUR_KEY
  • Keys are per-portal, not per-agency
  • Limit: 120 requests/hour per API key
  • Server-side cache: 5 minutes

3. Endpoints

MethodEndpointDescription
GET/api/v2/portals/{portal}/feed.jsonComplete JSON feed
GET/api/v2/portals/{portal}/feed.xmlComplete XML feed
GET/api/v2/portals/{portal}/feed.json?agency={slug}Feed filtered by agency
GET/api/v2/portals/{portal}/statusFeed status (count, last update)

All endpoints require the ?api_key=YOUR_KEY parameter

4. JSON Response Format

application/json
feed.json
{
  "portal": "homezz",
  "generated_at": "2026-04-06T14:00:00Z",
  "total_agencies": 2,
  "total_properties": 500,
  "agencies": [
    {
      "id": "deximoweb",
      "name": "Deximo Imobiliare",
      "domain": "deximo.ro",
      "logo": "https://api.lukian.ai/cdn/storage/...",
      "phone": "+40724310800",
      "email": "[email protected]",
      "city": "Constanta"
    }
  ],
  "properties": [
    {
      "id": 123,
      "agency_id": "deximoweb",
      "external_id": "REF-123",
      "title": "Apartament 2 camere Tomis Nord",
      "property_type": "apartment",
      "transaction_type": "sale",
      "price": 85000,
      "currency": "EUR",
      "surface": {
        "usable": 52,
        "built": 58,
        "land": null
      },
      "rooms": 2,
      "bedrooms": 1,
      "bathrooms": 1,
      "floor": 3,
      "total_floors": 8,
      "year_built": 2020,
      "location": {
        "city": "Constanta",
        "neighborhood": "Tomis Nord",
        "street": "Str. Exemplu 12",
        "latitude": 44.186,
        "longitude": 28.634
      },
      "description": "Apartament modern, complet mobilat...",
      "features": ["centrala proprie", "balcon", "parcare"],
      "energy_class": "B",
      "heating": "centrala proprie",
      "photos": [
        "https://api.lukian.ai/cdn/storage/photo1.jpg",
        "https://api.lukian.ai/cdn/storage/photo2.jpg"
      ],
      "url": "https://deximo.ro/123-apartament-2-camere-tomis-nord",
      "agent": {
        "name": "Ionel Groze",
        "phone": "+40724000000"
      },
      "created_at": "2026-04-01T10:00:00Z",
      "updated_at": "2026-04-05T14:30:00Z"
    }
  ]
}

5. XML Response Format

application/xml
feed.xml
<?xml version="1.0" encoding="UTF-8"?>
<feed xmlns="https://api.lukian.ai/feed/v2"
      portal="homezz"
      generated="2026-04-06T14:00:00Z">
  <agencies total="2">
    <agency id="deximoweb">
      <name>Deximo Imobiliare</name>
      <domain>deximo.ro</domain>
      <phone>+40724310800</phone>
      <email>[email protected]</email>
      <city>Constanta</city>
    </agency>
  </agencies>
  <properties total="500">
    <property id="123" agency_id="deximoweb">
      <title>Apartament 2 camere Tomis Nord</title>
      <url>https://deximo.ro/123-apartament-2-camere-tomis-nord</url>
      <property_type>Apartament</property_type>
      <transaction_type>Vanzare</transaction_type>
      <price currency="EUR">85000</price>
      <surface>
        <usable>52</usable>
        <built>58</built>
      </surface>
      <rooms>2</rooms>
      <bedrooms>1</bedrooms>
      <bathrooms>1</bathrooms>
      <floor>3</floor>
      <total_floors>8</total_floors>
      <year_built>2020</year_built>
      <location>
        <city>Constanta</city>
        <neighborhood>Tomis Nord</neighborhood>
        <street>Str. Exemplu 12</street>
        <latitude>44.186</latitude>
        <longitude>28.634</longitude>
      </location>
      <description>Apartament modern...</description>
      <features>
        <feature>centrala proprie</feature>
        <feature>balcon</feature>
        <feature>parcare</feature>
      </features>
      <energy_class>B</energy_class>
      <heating>centrala proprie</heating>
      <photos>
        <photo>https://api.lukian.ai/cdn/storage/photo1.jpg</photo>
        <photo>https://api.lukian.ai/cdn/storage/photo2.jpg</photo>
      </photos>
      <agent>
        <name>Ionel Groze</name>
        <phone>+40724000000</phone>
      </agent>
      <created_at>2026-04-01T10:00:00Z</created_at>
      <updated_at>2026-04-05T14:30:00Z</updated_at>
    </property>
  </properties>
</feed>

6. Property Fields Reference

FieldTypeDescriptionExample
idintegerID unic proprietate in Lukian1234
agency_idstringSlug-ul agentiei"deximoweb"
external_idstring | nullReferinta externa (optional)"REF-456"
titlestringTitlu complet"Apartament 2 camere Tomis Nord"
property_typestringTip proprietate (vezi tabel mai jos)"apartment"
transaction_typestringTip tranzactie"sale"
pricenumberPretul proprietatii85000
currencystringMoneda (EUR/RON)"EUR"
surface.usablenumber | nullSuprafata utila (mp)52.5
surface.builtnumber | nullSuprafata construita (mp)58
surface.landnumber | nullSuprafata teren (mp, pt case/terenuri)250
roomsinteger | nullNumar camere2
bedroomsinteger | nullNumar dormitoare1
bathroomsinteger | nullNumar bai1
floorinteger | nullEtaj (0 = parter)3
total_floorsinteger | nullEtaje totale cladire8
year_builtinteger | nullAnul constructiei2020
location.citystring | nullOras"Constanta"
location.neighborhoodstring | nullCartier / Zona"Tomis Nord"
location.streetstring | nullStrada (daca e publica)"Str. Exemplu 12"
location.latitudenumber | nullLatitudine GPS44.186
location.longitudenumber | nullLongitudine GPS28.634
descriptionstringDescriere completa HTML"..."
featuresstring[]Lista facilitati["centrala proprie", "balcon"]
energy_classstring | nullClasa energetica (A, B, C...)"B"
heatingstring | nullTip incalzire"centrala proprie"
photosstring[]URL-uri fotografii (ordonate)["https://..."]
urlstringLink proprietate pe site agentie"https://deximo.ro/..."
agent.namestring | nullNumele agentului"Ionel Groze"
agent.phonestring | nullTelefon agent"+40..."
agent.emailstring | nullEmail agent"ionel@..."
created_atstringData adaugarii (ISO 8601)"2026-04-01T10:00:00Z"
updated_atstringUltima actualizare (ISO 8601)"2026-04-05T14:30:00Z"

7. Property Type Mapping

ValueDescription RODescription EN
apartmentApartamentApartment
houseCasa / VilaHouse / Villa
landTerenLand
commercialSpatiu comercialCommercial space
officeBirouOffice
garageGaraj / ParcareGarage / Parking
studioGarsonieraStudio

8. Transaction Type Mapping

ValueDescription
saleSale
rentRent

9. HTTP Status Codes

CodeDescription
200Success
401Missing or invalid API key
404Portal not found
429Rate limit exceeded (Header: Retry-After)
500Server error

10. Rate Limiting

Every response includes the following headers:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 1712412000
  • X-RateLimit-Limit: Maximum limit per hour (120)
  • X-RateLimit-Remaining: Requests remaining in current window
  • X-RateLimit-Reset: Unix timestamp when window resets

If you exceed the limit, you'll receive a 429 response with a Retry-After header.

11. Webhook Notifications (optional, future)

Coming soon

In the future, Lukian will be able to send webhook notifications when:

  • A new property is added
  • A property is updated (price, description, photos)
  • A property is removed / sold

Contact us if you'd like to be notified when this feature becomes available.

12. curl Examples

# Complete JSON feed
curl "https://api.lukian.ai/api/v2/portals/homezz/feed.json?api_key=YOUR_KEY"
# Complete XML feed
curl "https://api.lukian.ai/api/v2/portals/homezz/feed.xml?api_key=YOUR_KEY"
# Filtered by agency
curl "https://api.lukian.ai/api/v2/portals/homezz/feed.json?api_key=YOUR_KEY&agency=deximoweb"
# Feed status
curl "https://api.lukian.ai/api/v2/portals/homezz/status?api_key=YOUR_KEY"

13. Contact & Support

Portal integration email:

[email protected]

For push integration (Lukian automatically publishes to your portal), you can send us your portal's API documentation and we'll implement the integration end-to-end.

Currently integrated portals via push: Storia + OLX, Imobiliare.ro, Publi24