DomuHQ Partner Listing Sync API Documentation

DomuHQ Partner Listing Sync API

This is the technical documentation for CRM vendors integrating listing synchronization with DomuHQ. Our API is built on the Sreality.cz addAdvert v4.0.0 specification. Every field name and codebook value matches the official Sreality import spec.

If you already implement Sreality XML-RPC, this is your same payload in JSON.

For the complete documentation with code examples, curl commands, and JSON request/response samples, download the full PDF version. For questions, contact us at integrations@domuhq.cz.

Endpoint and Environments

Push a listing: POST /v1/domu-hq/listing/external/sync/listing

Each call creates or updates exactly one listing. To sync many, loop on the CRM side.

• Sandbox / Dev: https://api.dev.domuhq.cz
• Production: https://api.domuhq.cz

Authentication

Every request requires these headers:

• X-API-Key (required): Static key issued to you. One per partner.
• X-Source (required): Your partner slug, e.g. llr, softreal, realitni-spravce.
• Idempotency-Key (required): UUID v4 per logical operation. Reuse on retry.
• Content-Type: application/json (UTF-8).

Source IPs are allowlisted at the gateway. Provide us the CIDR of the host you will push from.

Top-Level Fields

• advert_rkid (string, required): Your listing ID. Upsert key, must be unique within your CRM.
• client_login (email, required): Agent email. Must exist in DomuHQ.
• seller_rkid (string, optional): Your agent ID for cross-system correlation.
• agency_rkid (string, optional): Your agency ID for cross-system correlation.
• client_name (string, optional): Agent display name.
• contact_gsm (string, optional): Agent phone number.
• advert_data (object, required): The listing payload with all property fields.
• photos (array of 1-10, required): Photo objects with URL, ordering, and room categorization.

Listing Payload (advert_data)

Field names match the Sreality addAdvert.advert_data struct verbatim. All codebook fields use integer codes per Sreality spec. The API accepts the following field groups:

• Category (required): advert_function (2=rent), advert_type (1=apartment, 2=house), advert_subtype (room layout codebook)
• Pricing (required): advert_price, advert_price_currency (1=CZK, 2=USD, 3=EUR), advert_price_unit (2=monthly), commission, refundable_deposit
• Description (required): description (max 10,000 chars)
• Location: locality_city (required), locality_inaccuracy_level (required), GPS coordinates, RUIAN registry code, street, city part, postal code
• Building attributes: building_type (1-8), building_condition (1-10), usable_area, floor_number, floors, ceiling_height, year built, reconstruction year, ownership type
• Amenities: balcony, loggia, cellar, terrace, garage, elevator, wheelchair access, solar panels
• Features: furnished (1=yes, 2=no, 3=partly), heating, electricity, gas, water, sewage, internet, parking
• Energy: energy_efficiency_rating (1=A through 7=G), energy performance certificate, kWh/m2/year summary
• Availability: lease_type (lease/sublease), ready_date (ISO date), status flags

Any Sreality field not listed above is preserved in raw_partner_payload and returned as an informational warning.

Key Codebook Values

• Room layout (advert_subtype): 2=1+kk, 3=1+1, 4=2+kk, 5=2+1, 6=3+kk, 7=3+1, 8=4+kk, 9=4+1, 10=5+kk, 11=5+1, 12=6+, 16=atypical, 47=room
• Building type: 1=wood, 2=brick, 3=stone, 4=prefab, 5=panel, 6=skeleton, 7=mixed, 8=modular
• Condition: 1=very-good, 2=good, 3=bad, 4=under-construction, 5=project, 6=new, 7=for-demolition, 8=before-reconstruction, 9=after-reconstruction, 10=under-reconstruction

Photos

1-10 photos per listing. Each photo is an object with: data (URL, required), main (1=hero), order, alt (caption), photo_kind (photo/photo_360/floor_plan), and room_type (32-category codebook from living room to mountain view). We fetch and upload to our CDN. JPG, PNG, WebP, GIF accepted, max 10 MB each.

Responses

• 200 Success: Returns advert_rkid (echo), advert_id (DomuHQ UUID), status (active), action (created/updated), warnings array.
• 422: Validation failure. Listing not saved. Fix fields, retry with new Idempotency-Key.
• 409: Conflict. Listing was soft-deleted, cannot be resurrected via partner push.
• 401/403/400/429/500: Auth errors, IP not allowlisted, malformed JSON, rate limit, server error. Safe to retry 5xx with same Idempotency-Key.

Contact

For integration questions, test credentials, and partnership inquiries: integrations@domuhq.cz

Authoritative codebook reference: Sreality import spec v4.0.0 (admin.sreality.cz/doc/import.pdf)