Documentation
Everything you need to publish your agencies' sale and rental listings on Novi Kvadrat: sign-up, signing, connections, the listing payload, webhooks and the certification checklist.
Getting started
- OverviewWhat the Novi Kvadrat partner API does, where it lives, how one request travels, and what it deliberately leaves out.
- The Partner Portal: sign-up and approvalCreate your company's account in the Novi Kvadrat Partner Portal, set up two-step sign-in, and wait for approval.
- Sandbox and the test agencyYour sandbox app runs every check and publishes nothing. Get a test agency's connect code and push your first listings.
- CertificationTwo checks with one name — staff certify every new connection's first listings, and your company passes the sandbox checklist before a live app.
- Requesting live accessAfter the sandbox connection is certified and the checklist passes, ask for a live app, register a live key and connect real agencies.
Authentication
- KeysGenerate an Ed25519 key pair, register the public key in the Partner Portal, and send the key id with every request.
- NK-SIG-1 signingThe five headers, the seven-line signature base, the canonical query, and the order in which we verify a request.
- Worked example and test vectorA published test key, one signed PUT, and every intermediate value, so you can check your NK-SIG-1 implementation byte for byte.
- Rotation with two keysReplace a key without downtime — register a second key, switch your software, then revoke the first.
- IP allowlistLive apps accept requests only from the addresses you list; sandbox apps only when you add some.
- ErrorsThe error envelope, every error code with its HTTP status and fix, the details shapes, Retry-After, and the order of the checks.
Connections
- Consent flowAn agency connects your software with a one-time code from its own Novi Kvadrat portal; you redeem it. Nothing in a payload names an agency.
- StatesThe five connection states, what each one means for your writes and reads, the Connection object, and the status webhook.
- Redeeming a codeTurn an agency's connect code into a connection, list your connections, and read one.
- Pause by the agencyAn agency or Novi Kvadrat staff can pause a connection. Your writes are refused, waiting items wait, and published listings stay as they are.
- Revoke and what it means for listingsEnding a connection releases its listings to the agency — they stay online. A later connection picks them up again by external id.
Listings
- Payload v1The listing object field by field — every object, type, bound and rule the API checks before anything is stored.
- Sale versus rent shapestransaction picks the schema. Rentals carry rent and house_rules and must not carry price or the thirteen sale-only fields.
- Mapping notesWhat we do with your fields — titles and translations, prices in RSD, commission, the agent, virtual tours, places and coordinates, the mandate and the broker licence.
- Photos and the fetcherSend HTTPS photo URLs; our fetcher downloads, checks and re-encodes them. The rules, the caps, reuse by digest, and what happens when a fetch fails.
- StatesHow state active and inactive become listing statuses, moderation, quotas, the item results of a push, what unchanged means, and the 60-day renewal.
- RemovalRemove one listing with a reason — sold, rented, withdrawn, expired or error — and what each reason does.
- ReconcileSee what we hold for a connection, then archive everything live that your export no longer lists — with a guard against mass removal.
- IdempotencyRetry batches and reconciles safely with Idempotency-Key; PUT is safe to repeat on its own; redeem has no key.
- LimitsEvery limit a partner meets — signing, keys, codes, rates, batch sizes, photos, the listing TTL and the idempotency window — and how to spread pushes.
Vocabularies
- Using /vocabularies and /placesRead every enumeration once and cache it with ETag; look up cities and municipalities by Latin, Cyrillic or English name or official code.
- Serbian specificsOwnership and legalization, heating, building group, condition, rental types, categories, Latin and Cyrillic names, the register number, the mandate, EUR and RSD.
Webhooks
- Events and deliveriesRegister an HTTPS endpoint in the Partner Portal and receive the twelve partner events, with their fields, Send test, deliveries and retries.
- Verifying signaturesEvery webhook is signed with HMAC-SHA256 over the timestamp and the raw body. Check it, reject old ones, dedupe by data.id, and answer fast.
Reference client
Certification checklist
Legal
Changelog
What changed in the API, newest first: read the changelog.