API reference

Every operation of the partner API v1, generated from the same registry the API validates with.

Base URL

https://novikvadrat.rs/api/partners/v1

Every request is signed (NK-SIG-1)

Five headers on every call: an Ed25519 signature over the method, host, path and query, a timestamp, a nonce and the body digest. How to sign a request

Download openapi.json

Operations

Ping
- GET/ping
Connections
Listings
Batches
- POST/connections/{id}/batches
- GET/batches/{id}
Validate
- POST/validate
Vocabularies
- GET/vocabularies
Places
- GET/places
- GET/places/{id}

Ping

GET`/ping`

Prove the signature works and read the app, key and limits.

Signed request; five headers

Responses

200 OK.

Unknown fields are rejected.

Response 200 of ping
Field	Type	Required	Constraints	Description
`app`	object	Yes	—	Unknown fields are rejected.
`app.id`	string (uuid)	Yes	—
`app.environment`	string (enum)`sandboxlive`	Yes	—
`app.name`	string	Yes	—
`key_id`	string	Yes	—
`partner`	object	Yes	—	Unknown fields are rejected.
`partner.id`	string (uuid)	Yes	—
`partner.name`	string	Yes	—
`server_time`	string (date-time)	Yes	—
`limits`	object	Yes	—	Unknown fields are rejected.
`limits.rate_limit_per_minute`	integer	Yes	≥ -9007199254740991 · ≤ 9007199254740991
`limits.connection_items_per_hour`	integer	Yes	≥ -9007199254740991 · ≤ 9007199254740991
`limits.max_batch_items`	integer	Yes	≥ -9007199254740991 · ≤ 9007199254740991

scrolls →

Examples

Request · ping

GET /api/partners/v1/ping
NK-Key-Id: nkp_sandbox_7f3k9q2m4x8c1v6b
NK-Timestamp: 1791792000
NK-Nonce: <16–64 random bytes, base64url>
Content-Digest: sha-256=:47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=:
NK-Signature: v1=<86 base64url characters, no padding>

Errors

No errors beyond the signed-request checks.

Errors on every endpoint (14)

Errors on every endpoint, ping
Code	HTTP	When it happens	What to do
`ingest_disabled`	503	Novi Kvadrat switched ingestion off.	Retry later with backoff.
`body_too_large`	413	The body is over 4 MiB (checked first).	Split the batch.
`signature_missing`	401	A signing header is absent or malformed.	Send all five headers.
`key_invalid`	401	Unknown or revoked key.	Register a new key.
`key_expired`	401	The key is past its 365 days.	Register a new key.
`app_suspended`	403	Staff suspended the app.	Write to partners@novikvadrat.rs.
`account_blocked`	403	Staff suspended or archived the organization.	Write to partners@novikvadrat.rs.
`ip_allowlist_empty`	403	A live app without addresses.	Edit the allowlist.
`ip_not_allowed`	403	The caller is not listed, or its address can't be determined.	Edit the allowlist.
`digest_mismatch`	400	The body changed after hashing.	Hash the exact bytes you send.
`timestamp_out_of_window`	401	The clock is off by more than 300 s.	Sync the clock (NTP).
`signature_invalid`	401	The base string or the key does not match.	Compare with the test vector.
`nonce_reused`	401	A nonce sent twice within 15 minutes.	A fresh random nonce per request.
`rate_limited`	429	Over the per-minute budget (replays count too).	Wait Retry-After.

scrolls →

Connections

POST`/connections`

Redeem a connect code an agency generated.

Signed request; five headers

Request body

Unknown fields are rejected.

Request body of connections.redeem
Field	Type	Required	Constraints	Description
`connect_code`	string	Yes	min length 12 · max length 32

scrolls →

Responses

201 Created.

Unknown fields are rejected.

Response 201 of connections.redeem
Field	Type	Required	Constraints	Description
`connection`	object	Yes	—	Unknown fields are rejected.
`connection.id`	string (uuid)	Yes	—
`connection.status`	string (enum)`certifyingactivepausedrevoked`	Yes	—
`connection.environment`	string (enum)`sandboxlive`	Yes	—
`connection.agency`	object	Yes	—	Unknown fields are rejected.
`connection.agency.name`	string	Yes	—
`connection.agency.register_number`	string \| null	Yes	—
`connection.agency.verification_status`	string (enum)`unverifiedpendingverifiedrejected`	Yes	—
`connection.agency.listing_quota`	object	Yes	—	Unknown fields are rejected.
`connection.agency.listing_quota.used`	integer	Yes	≥ 0 · ≤ 9007199254740991
`connection.agency.listing_quota.limit`	integer \| null	Yes	≥ -9007199254740991 · ≤ 9007199254740991
`connection.agency.photo_limit`	integer	Yes	≥ 0 · ≤ 9007199254740991
`connection.created_at`	string	Yes	—
`connection.redeemed_at`	string \| null	Yes	—
`connection.certified_at`	string \| null	Yes	—
`connection.paused`	object \| null	Yes	—	Unknown fields are rejected.
`connection.paused.at`	string	Yes	—
`connection.paused.by`	string (enum)`agencystaff`	Yes	—
`connection.paused.reason`	string \| null	Yes	—
`connection.counts`	object	Yes	—	Unknown fields are rejected.
`connection.counts.live`	integer	Yes	≥ 0 · ≤ 9007199254740991
`connection.counts.paused`	integer	Yes	≥ 0 · ≤ 9007199254740991
`connection.counts.review`	integer	Yes	≥ 0 · ≤ 9007199254740991
`connection.counts.failed`	integer	Yes	≥ 0 · ≤ 9007199254740991
`connection.last_push_at`	string \| null	Yes	—

scrolls →

400 body_invalid: The body is not a JSON object. The body is the error envelope.
404 connect_code_invalid: An unknown, expired, used or other app's code. The body is the error envelope.
422 agency_not_eligible: details.reason is register_number_missing or account_blocked. validation_failed: The payload is invalid (details array). The body is the error envelope.

Examples

Request · connections.redeem

POST /api/partners/v1/connections
NK-Key-Id: nkp_sandbox_7f3k9q2m4x8c1v6b
NK-Timestamp: 1791792000
NK-Nonce: <16–64 random bytes, base64url>
Content-Digest: sha-256=:<base64 SHA-256 of the exact body bytes>:
NK-Signature: v1=<86 base64url characters, no padding>
Content-Type: application/json

{
  "connect_code": "NK-7Q4M-X2PA-9KDF"
}

Errors

Errors of connections.redeem
Code	HTTP	When it happens	What to do
`body_invalid`	400	The body is not a JSON object.	Send valid JSON.
`connect_code_invalid`	404	An unknown, expired, used or other app's code.	Ask for a new code.
`agency_not_eligible`	422	details.reason is register_number_missing or account_blocked.	The agency fixes its profile.
`validation_failed`	422	The payload is invalid (details array).	Fix the fields at the pointers.

scrolls →

Errors on every endpoint (14)

Errors on every endpoint, connections.redeem
Code	HTTP	When it happens	What to do
`ingest_disabled`	503	Novi Kvadrat switched ingestion off.	Retry later with backoff.
`body_too_large`	413	The body is over 4 MiB (checked first).	Split the batch.
`signature_missing`	401	A signing header is absent or malformed.	Send all five headers.
`key_invalid`	401	Unknown or revoked key.	Register a new key.
`key_expired`	401	The key is past its 365 days.	Register a new key.
`app_suspended`	403	Staff suspended the app.	Write to partners@novikvadrat.rs.
`account_blocked`	403	Staff suspended or archived the organization.	Write to partners@novikvadrat.rs.
`ip_allowlist_empty`	403	A live app without addresses.	Edit the allowlist.
`ip_not_allowed`	403	The caller is not listed, or its address can't be determined.	Edit the allowlist.
`digest_mismatch`	400	The body changed after hashing.	Hash the exact bytes you send.
`timestamp_out_of_window`	401	The clock is off by more than 300 s.	Sync the clock (NTP).
`signature_invalid`	401	The base string or the key does not match.	Compare with the test vector.
`nonce_reused`	401	A nonce sent twice within 15 minutes.	A fresh random nonce per request.
`rate_limited`	429	Over the per-minute budget (replays count too).	Wait Retry-After.

scrolls →

Detail codes

Detail codes of connections.redeem
Detail code	Meaning	Example pointer
`unknown_field`	A key the schema doesn't know.	`/structure/balcon`
`required`	A required field is missing.	`/title/sr`
`invalid_type`	The wrong JSON type.	`/structure/rooms`
`too_small`	Below a minimum (length or value).	`/description/sr`
`too_big`	Above a maximum (length or value).	`/price/amount`
`invalid_enum`	A value outside the vocabulary.	`/structure/heating`
`invalid_format`	A malformed id, URL, date or pattern.	`/photos/0/url`

scrolls →

GET`/connections`

List this app's connections.

Signed request; five headers

Parameters

Parameters of connections.list
Name	In	Type	Required
`status`	query	enum: certifying, active, paused, revoked	No
`limit`	query	string, pattern ^\d{1,3}$	No
`cursor`	query	string	No

scrolls →

Responses

200 OK.

Unknown fields are rejected.

Response 200 of connections.list
Field	Type	Required	Constraints	Description
`connections`	array of object	Yes	—
`connections[].id`	string (uuid)	Yes	—
`connections[].status`	string (enum)`certifyingactivepausedrevoked`	Yes	—
`connections[].environment`	string (enum)`sandboxlive`	Yes	—
`connections[].agency`	object	Yes	—	Unknown fields are rejected.
`connections[].agency.name`	string	Yes	—
`connections[].agency.register_number`	string \| null	Yes	—
`connections[].agency.verification_status`	string (enum)`unverifiedpendingverifiedrejected`	Yes	—
`connections[].agency.listing_quota`	object	Yes	—	Unknown fields are rejected.
`connections[].agency.listing_quota.used`	integer	Yes	≥ 0 · ≤ 9007199254740991
`connections[].agency.listing_quota.limit`	integer \| null	Yes	≥ -9007199254740991 · ≤ 9007199254740991
`connections[].agency.photo_limit`	integer	Yes	≥ 0 · ≤ 9007199254740991
`connections[].created_at`	string	Yes	—
`connections[].redeemed_at`	string \| null	Yes	—
`connections[].certified_at`	string \| null	Yes	—
`connections[].paused`	object \| null	Yes	—	Unknown fields are rejected.
`connections[].paused.at`	string	Yes	—
`connections[].paused.by`	string (enum)`agencystaff`	Yes	—
`connections[].paused.reason`	string \| null	Yes	—
`connections[].counts`	object	Yes	—	Unknown fields are rejected.
`connections[].counts.live`	integer	Yes	≥ 0 · ≤ 9007199254740991
`connections[].counts.paused`	integer	Yes	≥ 0 · ≤ 9007199254740991
`connections[].counts.review`	integer	Yes	≥ 0 · ≤ 9007199254740991
`connections[].counts.failed`	integer	Yes	≥ 0 · ≤ 9007199254740991
`connections[].last_push_at`	string \| null	Yes	—
`next_cursor`	string \| null	Yes	—

scrolls →

422 validation_failed: The payload is invalid (details array). The body is the error envelope.

Examples

Request · connections.list

GET /api/partners/v1/connections
NK-Key-Id: nkp_sandbox_7f3k9q2m4x8c1v6b
NK-Timestamp: 1791792000
NK-Nonce: <16–64 random bytes, base64url>
Content-Digest: sha-256=:47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=:
NK-Signature: v1=<86 base64url characters, no padding>

Errors

Errors of connections.list
Code	HTTP	When it happens	What to do
`validation_failed`	422	The payload is invalid (details array).	Fix the fields at the pointers.

scrolls →

Errors on every endpoint (14)

Errors on every endpoint, connections.list
Code	HTTP	When it happens	What to do
`ingest_disabled`	503	Novi Kvadrat switched ingestion off.	Retry later with backoff.
`body_too_large`	413	The body is over 4 MiB (checked first).	Split the batch.
`signature_missing`	401	A signing header is absent or malformed.	Send all five headers.
`key_invalid`	401	Unknown or revoked key.	Register a new key.
`key_expired`	401	The key is past its 365 days.	Register a new key.
`app_suspended`	403	Staff suspended the app.	Write to partners@novikvadrat.rs.
`account_blocked`	403	Staff suspended or archived the organization.	Write to partners@novikvadrat.rs.
`ip_allowlist_empty`	403	A live app without addresses.	Edit the allowlist.
`ip_not_allowed`	403	The caller is not listed, or its address can't be determined.	Edit the allowlist.
`digest_mismatch`	400	The body changed after hashing.	Hash the exact bytes you send.
`timestamp_out_of_window`	401	The clock is off by more than 300 s.	Sync the clock (NTP).
`signature_invalid`	401	The base string or the key does not match.	Compare with the test vector.
`nonce_reused`	401	A nonce sent twice within 15 minutes.	A fresh random nonce per request.
`rate_limited`	429	Over the per-minute budget (replays count too).	Wait Retry-After.

scrolls →

Detail codes

Detail codes of connections.list
Detail code	Meaning	Example pointer
`unknown_field`	A key the schema doesn't know.	`/structure/balcon`
`required`	A required field is missing.	`/title/sr`
`invalid_type`	The wrong JSON type.	`/structure/rooms`
`too_small`	Below a minimum (length or value).	`/description/sr`
`too_big`	Above a maximum (length or value).	`/price/amount`
`invalid_enum`	A value outside the vocabulary.	`/structure/heating`
`invalid_format`	A malformed id, URL, date or pattern.	`/photos/0/url`

scrolls →

GET`/connections/{id}`

One connection with counts and the agency summary.

Signed request; five headers

Parameters

Parameters of connections.get
Name	In	Type	Required	Description
`id`	path	string (uuid)	Yes	The connection id.

scrolls →

Responses

200 OK.

Unknown fields are rejected.

Response 200 of connections.get
Field	Type	Required	Constraints	Description
`connection`	object	Yes	—	Unknown fields are rejected.
`connection.id`	string (uuid)	Yes	—
`connection.status`	string (enum)`certifyingactivepausedrevoked`	Yes	—
`connection.environment`	string (enum)`sandboxlive`	Yes	—
`connection.agency`	object	Yes	—	Unknown fields are rejected.
`connection.agency.name`	string	Yes	—
`connection.agency.register_number`	string \| null	Yes	—
`connection.agency.verification_status`	string (enum)`unverifiedpendingverifiedrejected`	Yes	—
`connection.agency.listing_quota`	object	Yes	—	Unknown fields are rejected.
`connection.agency.listing_quota.used`	integer	Yes	≥ 0 · ≤ 9007199254740991
`connection.agency.listing_quota.limit`	integer \| null	Yes	≥ -9007199254740991 · ≤ 9007199254740991
`connection.agency.photo_limit`	integer	Yes	≥ 0 · ≤ 9007199254740991
`connection.created_at`	string	Yes	—
`connection.redeemed_at`	string \| null	Yes	—
`connection.certified_at`	string \| null	Yes	—
`connection.paused`	object \| null	Yes	—	Unknown fields are rejected.
`connection.paused.at`	string	Yes	—
`connection.paused.by`	string (enum)`agencystaff`	Yes	—
`connection.paused.reason`	string \| null	Yes	—
`connection.counts`	object	Yes	—	Unknown fields are rejected.
`connection.counts.live`	integer	Yes	≥ 0 · ≤ 9007199254740991
`connection.counts.paused`	integer	Yes	≥ 0 · ≤ 9007199254740991
`connection.counts.review`	integer	Yes	≥ 0 · ≤ 9007199254740991
`connection.counts.failed`	integer	Yes	≥ 0 · ≤ 9007199254740991
`connection.last_push_at`	string \| null	Yes	—

scrolls →

404 connection_not_found: Unknown id, or another app's connection. The body is the error envelope.

Examples

Request · connections.get

GET /api/partners/v1/connections/{id}
NK-Key-Id: nkp_sandbox_7f3k9q2m4x8c1v6b
NK-Timestamp: 1791792000
NK-Nonce: <16–64 random bytes, base64url>
Content-Digest: sha-256=:47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=:
NK-Signature: v1=<86 base64url characters, no padding>

Errors

Errors of connections.get
Code	HTTP	When it happens	What to do
`connection_not_found`	404	Unknown id, or another app's connection.	Check the id and the key environment.

scrolls →

Errors on every endpoint (14)

Errors on every endpoint, connections.get
Code	HTTP	When it happens	What to do
`ingest_disabled`	503	Novi Kvadrat switched ingestion off.	Retry later with backoff.
`body_too_large`	413	The body is over 4 MiB (checked first).	Split the batch.
`signature_missing`	401	A signing header is absent or malformed.	Send all five headers.
`key_invalid`	401	Unknown or revoked key.	Register a new key.
`key_expired`	401	The key is past its 365 days.	Register a new key.
`app_suspended`	403	Staff suspended the app.	Write to partners@novikvadrat.rs.
`account_blocked`	403	Staff suspended or archived the organization.	Write to partners@novikvadrat.rs.
`ip_allowlist_empty`	403	A live app without addresses.	Edit the allowlist.
`ip_not_allowed`	403	The caller is not listed, or its address can't be determined.	Edit the allowlist.
`digest_mismatch`	400	The body changed after hashing.	Hash the exact bytes you send.
`timestamp_out_of_window`	401	The clock is off by more than 300 s.	Sync the clock (NTP).
`signature_invalid`	401	The base string or the key does not match.	Compare with the test vector.
`nonce_reused`	401	A nonce sent twice within 15 minutes.	A fresh random nonce per request.
`rate_limited`	429	Over the per-minute budget (replays count too).	Wait Retry-After.

scrolls →

DELETE`/connections/{id}`

Disconnect: the listings are released to the agency.

Signed request; five headers

Parameters

Parameters of connections.revoke
Name	In	Type	Required	Description
`id`	path	string (uuid)	Yes	The connection id.
`reason`	query	string	No

scrolls →

Responses

200 OK.

Unknown fields are rejected.

Response 200 of connections.revoke
Field	Type	Required	Constraints	Description
`connection`	object	Yes	—	Unknown fields are rejected.
`connection.id`	string (uuid)	Yes	—
`connection.status`	string (enum)`certifyingactivepausedrevoked`	Yes	—
`connection.environment`	string (enum)`sandboxlive`	Yes	—
`connection.agency`	object	Yes	—	Unknown fields are rejected.
`connection.agency.name`	string	Yes	—
`connection.agency.register_number`	string \| null	Yes	—
`connection.agency.verification_status`	string (enum)`unverifiedpendingverifiedrejected`	Yes	—
`connection.agency.listing_quota`	object	Yes	—	Unknown fields are rejected.
`connection.agency.listing_quota.used`	integer	Yes	≥ 0 · ≤ 9007199254740991
`connection.agency.listing_quota.limit`	integer \| null	Yes	≥ -9007199254740991 · ≤ 9007199254740991
`connection.agency.photo_limit`	integer	Yes	≥ 0 · ≤ 9007199254740991
`connection.created_at`	string	Yes	—
`connection.redeemed_at`	string \| null	Yes	—
`connection.certified_at`	string \| null	Yes	—
`connection.paused`	object \| null	Yes	—	Unknown fields are rejected.
`connection.paused.at`	string	Yes	—
`connection.paused.by`	string (enum)`agencystaff`	Yes	—
`connection.paused.reason`	string \| null	Yes	—
`connection.counts`	object	Yes	—	Unknown fields are rejected.
`connection.counts.live`	integer	Yes	≥ 0 · ≤ 9007199254740991
`connection.counts.paused`	integer	Yes	≥ 0 · ≤ 9007199254740991
`connection.counts.review`	integer	Yes	≥ 0 · ≤ 9007199254740991
`connection.counts.failed`	integer	Yes	≥ 0 · ≤ 9007199254740991
`connection.last_push_at`	string \| null	Yes	—

scrolls →

404 connection_not_found: Unknown id, or another app's connection. The body is the error envelope.
422 validation_failed: The payload is invalid (details array). The body is the error envelope.

Examples

Request · connections.revoke

DELETE /api/partners/v1/connections/{id}
NK-Key-Id: nkp_sandbox_7f3k9q2m4x8c1v6b
NK-Timestamp: 1791792000
NK-Nonce: <16–64 random bytes, base64url>
Content-Digest: sha-256=:47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=:
NK-Signature: v1=<86 base64url characters, no padding>

Errors

Errors of connections.revoke
Code	HTTP	When it happens	What to do
`connection_not_found`	404	Unknown id, or another app's connection.	Check the id and the key environment.
`validation_failed`	422	The payload is invalid (details array).	Fix the fields at the pointers.

scrolls →

Errors on every endpoint (14)

Errors on every endpoint, connections.revoke
Code	HTTP	When it happens	What to do
`ingest_disabled`	503	Novi Kvadrat switched ingestion off.	Retry later with backoff.
`body_too_large`	413	The body is over 4 MiB (checked first).	Split the batch.
`signature_missing`	401	A signing header is absent or malformed.	Send all five headers.
`key_invalid`	401	Unknown or revoked key.	Register a new key.
`key_expired`	401	The key is past its 365 days.	Register a new key.
`app_suspended`	403	Staff suspended the app.	Write to partners@novikvadrat.rs.
`account_blocked`	403	Staff suspended or archived the organization.	Write to partners@novikvadrat.rs.
`ip_allowlist_empty`	403	A live app without addresses.	Edit the allowlist.
`ip_not_allowed`	403	The caller is not listed, or its address can't be determined.	Edit the allowlist.
`digest_mismatch`	400	The body changed after hashing.	Hash the exact bytes you send.
`timestamp_out_of_window`	401	The clock is off by more than 300 s.	Sync the clock (NTP).
`signature_invalid`	401	The base string or the key does not match.	Compare with the test vector.
`nonce_reused`	401	A nonce sent twice within 15 minutes.	A fresh random nonce per request.
`rate_limited`	429	Over the per-minute budget (replays count too).	Wait Retry-After.

scrolls →

Detail codes

Detail codes of connections.revoke
Detail code	Meaning	Example pointer
`unknown_field`	A key the schema doesn't know.	`/structure/balcon`
`required`	A required field is missing.	`/title/sr`
`invalid_type`	The wrong JSON type.	`/structure/rooms`
`too_small`	Below a minimum (length or value).	`/description/sr`
`too_big`	Above a maximum (length or value).	`/price/amount`
`invalid_enum`	A value outside the vocabulary.	`/structure/heating`
`invalid_format`	A malformed id, URL, date or pattern.	`/photos/0/url`

scrolls →

Listings

PUT`/connections/{id}/listings/{external_id}`

Create or fully replace one listing.

Signed request; five headers

Parameters

Parameters of listings.put
Name	In	Type	Required	Description
`id`	path	string (uuid)	Yes	The connection id.
`external_id`	path	string, pattern ^[A-Za-z0-9._:-]{1,64}$	Yes	Your listing id (the payload’s external_id).

scrolls →

Request body

One listing; transaction picks the sale or the rent shape. Text lengths count Unicode code points, as maxLength does; titles are ALSO capped at 120 UTF-16 units (an emoji counts as two). A sale price is refused (too_big) when amount × 117 (rounded, for EUR) would exceed 2,147,483,647 RSD (about 18,354,561 EUR). state: active needs legal.mandate_attested: true. See https://developers.novikvadrat.rs/docs/listings/payload-v1.

Unknown fields are rejected.

Request body of listings.put
Field	Type	Required	Constraints	Description
`external_id`	string	Yes	min length 1 · max length 64 · pattern ^[A-Za-z0-9._:-]*$
`category`	string (enum)`apartmentstudiopenthouseduplexlofthousehouse_semi_detachedtownhouse`	Yes	—
`state`	string (enum)`activeinactive`	Yes	—
`title`	object	Yes	—	Unknown fields are rejected.
`title.sr`	string	Yes	min length 5 · max length 120
`title.en`	string \| null	No	max length 120
`title.tr`	string \| null	No	max length 120
`title.de`	string \| null	No	max length 120
`title.ru`	string \| null	No	max length 120
`description`	object	Yes	—	Unknown fields are rejected.
`description.sr`	string	Yes	min length 20 · max length 8000
`description.en`	string \| null	No	max length 8000
`description.tr`	string \| null	No	max length 8000
`description.de`	string \| null	No	max length 8000
`description.ru`	string \| null	No	max length 8000
`location`	object	Yes	—	Unknown fields are rejected.
`location.place_id`	string (uuid)	Yes	—
`location.address_line`	string	Yes	min length 3 · max length 200
`location.neighbourhood`	string \| null	No	max length 120
`location.lat`	number \| null	No	≥ -90 · ≤ 90
`location.lng`	number \| null	No	≥ -180 · ≤ 180
`amenities`	array of string (enum) \| null`loggiafrench_balconywalk_in_closetbuilt_in_wardrobesunderfloor_heatingfireplacelaundry_roomsoundproofing`	No	max items 40
`attributes`	map of any \| null	No	—
`photos`	array of object \| null	No	max items 64
`photos[].url`	string	Yes	max length 2048
`photos[].caption`	string \| null	No	max length 500
`photos[].room_type`	string (enum) \| null`exteriorliving_roomkitchenbedroombathroombalconyhallwayview`	No	—
`photos[].digest`	string \| null	No	pattern ^[0-9a-f]{64}$
`video_url`	string \| null	No	max length 2048
`virtual_tour_url`	string \| null	No	max length 2048
`agent`	object \| null	No	—	Unknown fields are rejected.
`agent.email`	string (email)	Yes	max length 254
`agent.name`	string \| null	No	max length 120
`agent.phone`	string \| null	No	max length 32
`source`	object	Yes	—	Unknown fields are rejected.
`source.updated_at`	string (date-time)	Yes	—
`source.url`	string \| null	No	max length 2048
`digest`	string \| null	No	max length 128
`transaction`	string (enum)`salerent`	Yes	—
`price`	object	sale only	—	Unknown fields are rejected.
`price.amount`	number	sale only	> 0 · ≤ 9999999999
`price.currency`	string (enum)`EURRSD`	sale only	—
`price.negotiable`	boolean \| null	sale only	—
`structure`	object	Yes	—	Unknown fields are rejected.
`structure.area_sqm`	number \| null	No	> 0 · ≤ 99999.99
`structure.bedrooms`	number \| null	No	≥ 0 · ≤ 99
`structure.bathrooms`	number \| null	No	≥ 0 · ≤ 99
`structure.floor`	integer \| null	No	≥ -5 · ≤ 60
`structure.levels`	integer \| null	No	≥ 1 · ≤ 6
`structure.furnished`	string (enum) \| null`furnishedsemi_furnishedunfurnished`	No	—
`structure.elevator`	boolean \| null	No	—
`structure.parking`	boolean \| null	No	—
`structure.balcony`	boolean \| null	No	—
`structure.terrace`	boolean \| null	No	—
`structure.air_conditioning`	boolean \| null	No	—
`structure.heating`	string (enum) \| null`districtgas_centralgas_localelectric_localstorage_heaterelectric_panelheat_pumpair_conditioning`	No	—
`structure.rooms`	number \| null	sale only	≥ 0 · ≤ 99
`structure.total_floors`	integer \| null	sale only	≥ 0 · ≤ 60
`structure.year_built`	integer \| null	sale only	≥ 1800 · ≤ 2035
`structure.building_group`	string (enum) \| null`newold`	sale only	—
`structure.condition`	string (enum) \| null`luxrenovatedoriginalrenovation_required`	sale only	—
`structure.garage`	boolean \| null	sale only	—
`structure.basement`	boolean \| null	sale only	—
`legal`	object	Yes	—	Unknown fields are rejected.
`legal.ownership_status`	string (enum) \| null`uknjizennije_uknjizenu_postupku`	sale only	—
`legal.legalization_status`	string (enum) \| null`legalizovanu_postupkunelegalizovan`	sale only	—
`legal.mortgage_eligible`	boolean \| null	sale only	—
`legal.mandate_attested`	boolean	Yes	—
`legal.exclusive`	boolean \| null	sale only	—
`legal.broker_license_no`	string \| null	sale only	max length 64
`legal.tapija_note`	string \| null	sale only	max length 500
`commission`	object \| null	No	—	Unknown fields are rejected.
`commission.buyer_pct`	number \| null	sale only	≥ 0 · ≤ 100
`commission.seller_pct`	number \| null	sale only	≥ 0 · ≤ 100
`commission.landlord_pct`	number \| null	rent only	≥ 0 · ≤ 100
`commission.agency_fee_pct`	number \| null	rent only	≥ 0 · ≤ 100
`rent`	object	rent only	—	Unknown fields are rejected.
`rent.amount`	number	rent only	≥ 1 · ≤ 10000000
`rent.currency`	string (enum)`EURRSD`	rent only	—
`rent.type`	string (enum)`long_termmid_termshort_termroom`	rent only	—
`rent.deposit_months`	number \| null	rent only	≥ 0 · ≤ 12
`rent.min_lease_months`	integer \| null	rent only	≥ 0 · ≤ 120
`rent.max_lease_months`	integer \| null	rent only	≥ 0 · ≤ 120
`rent.available_from`	string (date) \| null	rent only	—
`rent.utilities_included`	map of boolean \| null	rent only	—
`rent.utilities_estimate_rsd`	integer \| null	rent only	≥ 0 · ≤ 100000000
`rent.owner_lives_nearby`	boolean \| null	rent only	—
`rent.owner_proximity`	string (enum) \| null`same_apartmentsame_floorupstairsdownstairssame_buildingsame_streetwalking_distance`	rent only	—
`rent.max_occupants`	integer \| null	rent only	≥ 1 · ≤ 20
`house_rules`	object	rent only	—	Unknown fields are rejected.
`house_rules.pets`	object	rent only	—	Unknown fields are rejected.
`house_rules.pets.policy`	string (enum)`allowedon_requestnot_allowed`	rent only	—
`house_rules.pets.kinds`	array of string (enum)`dogscatssmall_cagedbirdsaquarium`	rent only	max items 5
`house_rules.pets.dog_size`	string (enum)`smallmediumany`	rent only	—
`house_rules.pets.max_count`	integer	rent only	≥ 1 · ≤ 5
`house_rules.pets.deposit_eur`	integer	rent only	≥ 0 · ≤ 100000
`house_rules.pets.note`	string	rent only	max length 200
`house_rules.smoking`	string (enum)`not_allowedbalcony_onlyallowed`	rent only	—
`house_rules.guests`	string (enum)`allowedask_firstnot_allowed`	rent only	—
`house_rules.parties`	string (enum)`not_allowedallowed`	rent only	—
`house_rules.quiet_hours`	string	rent only	max length 200
`house_rules.subletting`	string (enum)`not_allowedwith_consent`	rent only	—
`house_rules.students`	string (enum)`yesno`	rent only	—
`house_rules.families`	string (enum)`yesno`	rent only	—
`house_rules.foreign_tenants`	string (enum)`welcomeask_first`	rent only	—
`house_rules.registers_residence`	boolean	rent only	—
`house_rules.other`	string	rent only	max length 500

scrolls →

Responses

202 Accepted.

Unknown fields are rejected.

Response 202 of listings.put
Field	Type	Required	Constraints	Description
`item`	object	Yes	—	Unknown fields are rejected.
`item.position`	integer	Yes	≥ 0 · ≤ 9007199254740991
`item.external_id`	string	Yes	—
`item.result`	string (enum)`acceptedunchangedneeds_reviewrejectedremoved`	Yes	—
`item.candidate_id`	string (uuid) \| null	Yes	—
`item.listing_id`	string (uuid) \| null	Yes	—
`item.public_url`	string \| null	Yes	—
`item.failure_code`	string (enum) \| null`unmappable_categorymissing_requiredinvalid_payloadquota_exceededduplicategeo_unresolvedschema_invalidphoto_fetch_failed`	Yes	—
`item.details`	array of object \| map of any \| null	Yes	—
`item.warnings`	array of object	Yes	—
`item.warnings[].code`	string (enum)`agent_not_membervirtual_tour_droppedcommission_droppedfield_not_applicablecoordinates_outside_placephoto_cap_applied`	Yes	—
`item.warnings[].pointer`	string	No	—
`item.warnings[].message`	string	Yes	—

scrolls →

400 body_invalid: The body is not a JSON object. The body is the error envelope.
404 connection_not_found: Unknown id, or another app's connection. The body is the error envelope.
409 connection_not_active: details.status is pending, paused or revoked. The body is the error envelope.
422 validation_failed: The payload is invalid (details array). The body is the error envelope.
429 connection_item_limit: Over the hourly item budget. The body is the error envelope.

Examples

Request · listings.put

PUT /api/partners/v1/connections/{id}/listings/{external_id}
NK-Key-Id: nkp_sandbox_7f3k9q2m4x8c1v6b
NK-Timestamp: 1791792000
NK-Nonce: <16–64 random bytes, base64url>
Content-Digest: sha-256=:<base64 SHA-256 of the exact body bytes>:
NK-Signature: v1=<86 base64url characters, no padding>
Content-Type: application/json

{
  "external_id": "REAA-12345",
  "transaction": "sale",
  "category": "apartment",
  "state": "active",
  "title": {
    "sr": "Trosoban stan, Vračar",
    "en": "Three-room flat, Vračar"
  },
  "description": {
    "sr": "Svetao trosoban stan na Vračaru, renoviran 2024, na pet minuta od Hrama Svetog Save.",
    "en": "A bright three-room flat in Vračar, renovated in 2024, five minutes from the Temple of Saint Sava."
  },
  "price": {
    "amount": 245000,
    "currency": "EUR",
    "negotiable": false
  },
  "location": {
    "place_id": "b2c0d6a4-3f1e-4d2a-9c8b-7e6f5a4b3c2d",
    "address_line": "Njegoševa 10",
    "neighbourhood": "Crveni krst",
    "lat": 44.8012,
    "lng": 20.4722
  },
  "structure": {
    "area_sqm": 78.5,
    "rooms": 3,
    "bedrooms": 2,
    "bathrooms": 1,
    "floor": 3,
    "total_floors": 5,
    "levels": 1,
    "year_built": 1968,
    "building_group": "old",
    "condition": "renovated",
    "furnished": "semi_furnished",
    "heating": "district",
    "elevator": true,
    "parking": false,
    "garage": false,
    "balcony": true,
    "terrace": false,
    "air_conditioning": true,
    "basement": false
  },
  "legal": {
    "ownership_status": "uknjizen",
    "legalization_status": "legalizovan",
    "mortgage_eligible": true,
    "mandate_attested": true,
    "exclusive": false,
    "broker_license_no": null,
    "tapija_note": null
  },
  "commission": {
    "buyer_pct": 2,
    "seller_pct": 2
  },
  "amenities": [
    "built_in_wardrobes",
    "intercom"
  ],
  "attributes": {},
  "photos": [
    {
      "url": "https://cdn.reaa.rs/listings/12345/1.jpg",
      "caption": null,
      "room_type": "living_room",
      "digest": null
    },
    {
      "url": "https://cdn.reaa.rs/listings/12345/2.jpg",
      "caption": null,
      "room_type": "kitchen",
      "digest": null
    },
    {
      "url": "https://cdn.reaa.rs/listings/12345/3.jpg",
      "caption": null,
      "room_type": "bedroom",
      "digest": null
    }
  ],
  "video_url": null,
  "virtual_tour_url": null,
  "agent": {
    "email": "milan@agencija.rs",
    "name": "Milan Petrović",
    "phone": "+381601234567"
  },
  "source": {
    "updated_at": "2026-10-12T08:00:00Z",
    "url": "https://agencija.rs/nekretnine/12345"
  },
  "digest": null
}

Errors

Errors of listings.put
Code	HTTP	When it happens	What to do
`body_invalid`	400	The body is not a JSON object.	Send valid JSON.
`connection_not_found`	404	Unknown id, or another app's connection.	Check the id and the key environment.
`connection_not_active`	409	details.status is pending, paused or revoked.	Wait for the agency, or stop pushing.
`validation_failed`	422	The payload is invalid (details array).	Fix the fields at the pointers.
`connection_item_limit`	429	Over the hourly item budget.	Wait Retry-After, spread pushes.

scrolls →

Errors on every endpoint (14)

Errors on every endpoint, listings.put
Code	HTTP	When it happens	What to do
`ingest_disabled`	503	Novi Kvadrat switched ingestion off.	Retry later with backoff.
`body_too_large`	413	The body is over 4 MiB (checked first).	Split the batch.
`signature_missing`	401	A signing header is absent or malformed.	Send all five headers.
`key_invalid`	401	Unknown or revoked key.	Register a new key.
`key_expired`	401	The key is past its 365 days.	Register a new key.
`app_suspended`	403	Staff suspended the app.	Write to partners@novikvadrat.rs.
`account_blocked`	403	Staff suspended or archived the organization.	Write to partners@novikvadrat.rs.
`ip_allowlist_empty`	403	A live app without addresses.	Edit the allowlist.
`ip_not_allowed`	403	The caller is not listed, or its address can't be determined.	Edit the allowlist.
`digest_mismatch`	400	The body changed after hashing.	Hash the exact bytes you send.
`timestamp_out_of_window`	401	The clock is off by more than 300 s.	Sync the clock (NTP).
`signature_invalid`	401	The base string or the key does not match.	Compare with the test vector.
`nonce_reused`	401	A nonce sent twice within 15 minutes.	A fresh random nonce per request.
`rate_limited`	429	Over the per-minute budget (replays count too).	Wait Retry-After.

scrolls →

Detail codes

Detail codes of listings.put
Detail code	Meaning	Example pointer
`unknown_field`	A key the schema doesn't know.	`/structure/balcon`
`required`	A required field is missing.	`/title/sr`
`invalid_type`	The wrong JSON type.	`/structure/rooms`
`too_small`	Below a minimum (length or value).	`/description/sr`
`too_big`	Above a maximum (length or value).	`/price/amount`
`invalid_enum`	A value outside the vocabulary.	`/structure/heating`
`invalid_format`	A malformed id, URL, date or pattern.	`/photos/0/url`
`unknown_place`	place_id is not a city or municipality we know.	`/location/place_id`
`duplicate_external_id`	One external_id twice in one batch.	`/listings/3/external_id`
`duplicate_photo_url`	One photo URL listed twice.	`/photos/2/url`

scrolls →

Warnings of listings.put
Warning	Meaning	Example pointer
`agent_not_member`	agent.email is not an active member of the agency; the listing has no agent.	`/agent/email`
`virtual_tour_dropped`	The agency's plan has no virtual tours; the URL was not stored.	`/virtual_tour_url`
`commission_dropped`	The agency is a bank; commission was not stored.	`/commission`
`field_not_applicable`	A field that does not apply to the category was not stored.	`/structure/floor`
`coordinates_outside_place`	The coordinates fall outside the place's boundary (kept).	`/location`
`photo_cap_applied`	More photos than the agency's plan allows; the extra ones were dropped.	`/photos`

scrolls →

POST`/connections/{id}/listings/{external_id}/remove`

Remove a listing (sold, rented, withdrawn, expired, error).

Signed request; five headers

Parameters

Parameters of listings.remove
Name	In	Type	Required	Description
`id`	path	string (uuid)	Yes	The connection id.
`external_id`	path	string, pattern ^[A-Za-z0-9._:-]{1,64}$	Yes	Your listing id (the payload’s external_id).

scrolls →

Request body

Unknown fields are rejected.

Request body of listings.remove
Field	Type	Required	Constraints	Description
`reason`	string (enum)`soldrentedwithdrawnexpirederror`	Yes	—

scrolls →

Responses

200 OK.

Unknown fields are rejected.

Response 200 of listings.remove
Field	Type	Required	Constraints	Description
`item`	object	Yes	—	Unknown fields are rejected.
`item.position`	integer	Yes	≥ 0 · ≤ 9007199254740991
`item.external_id`	string	Yes	—
`item.result`	string (enum)`acceptedunchangedneeds_reviewrejectedremoved`	Yes	—
`item.candidate_id`	string (uuid) \| null	Yes	—
`item.listing_id`	string (uuid) \| null	Yes	—
`item.public_url`	string \| null	Yes	—
`item.failure_code`	string (enum) \| null`unmappable_categorymissing_requiredinvalid_payloadquota_exceededduplicategeo_unresolvedschema_invalidphoto_fetch_failed`	Yes	—
`item.details`	array of object \| map of any \| null	Yes	—
`item.warnings`	array of object	Yes	—
`item.warnings[].code`	string (enum)`agent_not_membervirtual_tour_droppedcommission_droppedfield_not_applicablecoordinates_outside_placephoto_cap_applied`	Yes	—
`item.warnings[].pointer`	string	No	—
`item.warnings[].message`	string	Yes	—

scrolls →

400 body_invalid: The body is not a JSON object. The body is the error envelope.
404 connection_not_found: Unknown id, or another app's connection. listing_not_found: No staged listing with that external_id on this connection. The body is the error envelope.
409 connection_not_active: details.status is pending, paused or revoked. The body is the error envelope.
422 validation_failed: The payload is invalid (details array). The body is the error envelope.

Examples

Request · listings.remove

POST /api/partners/v1/connections/{id}/listings/{external_id}/remove
NK-Key-Id: nkp_sandbox_7f3k9q2m4x8c1v6b
NK-Timestamp: 1791792000
NK-Nonce: <16–64 random bytes, base64url>
Content-Digest: sha-256=:<base64 SHA-256 of the exact body bytes>:
NK-Signature: v1=<86 base64url characters, no padding>
Content-Type: application/json

{
  "reason": "sold"
}

Errors

Errors of listings.remove
Code	HTTP	When it happens	What to do
`body_invalid`	400	The body is not a JSON object.	Send valid JSON.
`connection_not_found`	404	Unknown id, or another app's connection.	Check the id and the key environment.
`listing_not_found`	404	No staged listing with that external_id on this connection.	—
`connection_not_active`	409	details.status is pending, paused or revoked.	Wait for the agency, or stop pushing.
`validation_failed`	422	The payload is invalid (details array).	Fix the fields at the pointers.

scrolls →

Errors on every endpoint (14)

Errors on every endpoint, listings.remove
Code	HTTP	When it happens	What to do
`ingest_disabled`	503	Novi Kvadrat switched ingestion off.	Retry later with backoff.
`body_too_large`	413	The body is over 4 MiB (checked first).	Split the batch.
`signature_missing`	401	A signing header is absent or malformed.	Send all five headers.
`key_invalid`	401	Unknown or revoked key.	Register a new key.
`key_expired`	401	The key is past its 365 days.	Register a new key.
`app_suspended`	403	Staff suspended the app.	Write to partners@novikvadrat.rs.
`account_blocked`	403	Staff suspended or archived the organization.	Write to partners@novikvadrat.rs.
`ip_allowlist_empty`	403	A live app without addresses.	Edit the allowlist.
`ip_not_allowed`	403	The caller is not listed, or its address can't be determined.	Edit the allowlist.
`digest_mismatch`	400	The body changed after hashing.	Hash the exact bytes you send.
`timestamp_out_of_window`	401	The clock is off by more than 300 s.	Sync the clock (NTP).
`signature_invalid`	401	The base string or the key does not match.	Compare with the test vector.
`nonce_reused`	401	A nonce sent twice within 15 minutes.	A fresh random nonce per request.
`rate_limited`	429	Over the per-minute budget (replays count too).	Wait Retry-After.

scrolls →

Detail codes

Detail codes of listings.remove
Detail code	Meaning	Example pointer
`unknown_field`	A key the schema doesn't know.	`/structure/balcon`
`required`	A required field is missing.	`/title/sr`
`invalid_type`	The wrong JSON type.	`/structure/rooms`
`too_small`	Below a minimum (length or value).	`/description/sr`
`too_big`	Above a maximum (length or value).	`/price/amount`
`invalid_enum`	A value outside the vocabulary.	`/structure/heating`
`invalid_format`	A malformed id, URL, date or pattern.	`/photos/0/url`

scrolls →

GET`/connections/{id}/listings`

The reconcile view: what Novi Kvadrat holds for this connection.

Signed request; five headers

Parameters

Parameters of listings.list
Name	In	Type	Required	Description
`id`	path	string (uuid)	Yes	The connection id.
`cursor`	query	string	No
`limit`	query	string, pattern ^\d{1,3}$	No
`status`	query	string	No

scrolls →

Responses

200 OK.

Unknown fields are rejected.

Response 200 of listings.list
Field	Type	Required	Constraints
`items`	array of object	Yes	—
`items[].external_id`	string	Yes	—
`items[].transaction`	string (enum) \| null`salerent`	Yes	—
`items[].status`	string (enum)`pendingimportedfailedskippedneeds_reviewremovedvalidated`	Yes	—
`items[].listing_status`	string \| null	Yes	—
`items[].moderation_status`	string \| null	Yes	—
`items[].listing_id`	string (uuid) \| null	Yes	—
`items[].public_url`	string \| null	Yes	—
`items[].payload_digest`	string \| null	Yes	—
`items[].imported_digest`	string \| null	Yes	—
`items[].updated_at`	string \| null	Yes	—
`items[].failure_code`	string (enum) \| null`unmappable_categorymissing_requiredinvalid_payloadquota_exceededduplicategeo_unresolvedschema_invalidphoto_fetch_failed`	Yes	—
`next_cursor`	string \| null	Yes	—

scrolls →

404 connection_not_found: Unknown id, or another app's connection. The body is the error envelope.
409 connection_not_active: details.status is pending, paused or revoked. The body is the error envelope.
422 validation_failed: The payload is invalid (details array). The body is the error envelope.

Examples

Request · listings.list

GET /api/partners/v1/connections/{id}/listings
NK-Key-Id: nkp_sandbox_7f3k9q2m4x8c1v6b
NK-Timestamp: 1791792000
NK-Nonce: <16–64 random bytes, base64url>
Content-Digest: sha-256=:47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=:
NK-Signature: v1=<86 base64url characters, no padding>

Errors

Errors of listings.list
Code	HTTP	When it happens	What to do
`connection_not_found`	404	Unknown id, or another app's connection.	Check the id and the key environment.
`connection_not_active`	409	details.status is pending, paused or revoked.	Wait for the agency, or stop pushing.
`validation_failed`	422	The payload is invalid (details array).	Fix the fields at the pointers.

scrolls →

Errors on every endpoint (14)

Errors on every endpoint, listings.list
Code	HTTP	When it happens	What to do
`ingest_disabled`	503	Novi Kvadrat switched ingestion off.	Retry later with backoff.
`body_too_large`	413	The body is over 4 MiB (checked first).	Split the batch.
`signature_missing`	401	A signing header is absent or malformed.	Send all five headers.
`key_invalid`	401	Unknown or revoked key.	Register a new key.
`key_expired`	401	The key is past its 365 days.	Register a new key.
`app_suspended`	403	Staff suspended the app.	Write to partners@novikvadrat.rs.
`account_blocked`	403	Staff suspended or archived the organization.	Write to partners@novikvadrat.rs.
`ip_allowlist_empty`	403	A live app without addresses.	Edit the allowlist.
`ip_not_allowed`	403	The caller is not listed, or its address can't be determined.	Edit the allowlist.
`digest_mismatch`	400	The body changed after hashing.	Hash the exact bytes you send.
`timestamp_out_of_window`	401	The clock is off by more than 300 s.	Sync the clock (NTP).
`signature_invalid`	401	The base string or the key does not match.	Compare with the test vector.
`nonce_reused`	401	A nonce sent twice within 15 minutes.	A fresh random nonce per request.
`rate_limited`	429	Over the per-minute budget (replays count too).	Wait Retry-After.

scrolls →

Detail codes

Detail codes of listings.list
Detail code	Meaning	Example pointer
`unknown_field`	A key the schema doesn't know.	`/structure/balcon`
`required`	A required field is missing.	`/title/sr`
`invalid_type`	The wrong JSON type.	`/structure/rooms`
`too_small`	Below a minimum (length or value).	`/description/sr`
`too_big`	Above a maximum (length or value).	`/price/amount`
`invalid_enum`	A value outside the vocabulary.	`/structure/heating`
`invalid_format`	A malformed id, URL, date or pattern.	`/photos/0/url`

scrolls →

POST`/connections/{id}/reconcile`

Archive everything live that is not in the list.

Signed request; five headers

Parameters

Parameters of reconcile
Name	In	Type	Required	Description
`Idempotency-Key`	header	string, pattern ^[\x21-\x7e]{8,128}$	No	8–128 visible ASCII characters (no spaces); any other value → 422 `validation_failed`. Same key and same body → the stored outcome (`Idempotent-Replayed: true`); while the first runs → 409 `idempotency_in_progress`; another body → 422 `idempotency_key_reused`; forgotten after 7 days.
`id`	path	string (uuid)	Yes	The connection id.

scrolls →

Request body

Unknown fields are rejected.

Request body of reconcile
Field	Type	Required	Constraints	Description
`external_ids`	array of string	Yes	—
`confirm_mass_removal`	boolean	No	—

scrolls →

Responses

202 Accepted.

Unknown fields are rejected.

Response 202 of reconcile
Field	Type	Required	Constraints	Description
`batch`	object	Yes	—	Unknown fields are rejected.
`batch.id`	string (uuid)	Yes	—
`batch.kind`	string (enum)`reconcile`	Yes	—
`batch.to_remove`	integer	Yes	≥ 0 · ≤ 9007199254740991
`batch.removed_queued`	integer	Yes	≥ 0 · ≤ 9007199254740991

scrolls →

400 body_invalid: The body is not a JSON object. The body is the error envelope.
404 connection_not_found: Unknown id, or another app's connection. The body is the error envelope.
409 connection_not_active: details.status is pending, paused or revoked. mass_removal_requires_confirmation: A reconcile would remove too much. idempotency_in_progress: The same key while the first request runs (details.batch_id). The body is the error envelope.
422 batch_too_large: More than max_batch_items, more than 50 to validate, or more than 5,000 reconcile ids. idempotency_key_reused: The same key with a different body, within 7 days. validation_failed: The payload is invalid (details array). The body is the error envelope.

Examples

Request · reconcile

POST /api/partners/v1/connections/{id}/reconcile
NK-Key-Id: nkp_sandbox_7f3k9q2m4x8c1v6b
NK-Timestamp: 1791792000
NK-Nonce: <16–64 random bytes, base64url>
Content-Digest: sha-256=:<base64 SHA-256 of the exact body bytes>:
NK-Signature: v1=<86 base64url characters, no padding>
Content-Type: application/json

{
  "external_ids": [
    "REAA-12345",
    "REAA-12346"
  ]
}

Errors

Errors of reconcile
Code	HTTP	When it happens	What to do
`body_invalid`	400	The body is not a JSON object.	Send valid JSON.
`connection_not_found`	404	Unknown id, or another app's connection.	Check the id and the key environment.
`connection_not_active`	409	details.status is pending, paused or revoked.	Wait for the agency, or stop pushing.
`idempotency_in_progress`	409	The same key while the first request runs (details.batch_id).	Poll the batch.
`mass_removal_requires_confirmation`	409	A reconcile would remove too much.	Check, then confirm.
`validation_failed`	422	The payload is invalid (details array).	Fix the fields at the pointers.
`batch_too_large`	422	More than max_batch_items, more than 50 to validate, or more than 5,000 reconcile ids.	Split.
`idempotency_key_reused`	422	The same key with a different body, within 7 days.	A new key per distinct body.

scrolls →

Errors on every endpoint (14)

Errors on every endpoint, reconcile
Code	HTTP	When it happens	What to do
`ingest_disabled`	503	Novi Kvadrat switched ingestion off.	Retry later with backoff.
`body_too_large`	413	The body is over 4 MiB (checked first).	Split the batch.
`signature_missing`	401	A signing header is absent or malformed.	Send all five headers.
`key_invalid`	401	Unknown or revoked key.	Register a new key.
`key_expired`	401	The key is past its 365 days.	Register a new key.
`app_suspended`	403	Staff suspended the app.	Write to partners@novikvadrat.rs.
`account_blocked`	403	Staff suspended or archived the organization.	Write to partners@novikvadrat.rs.
`ip_allowlist_empty`	403	A live app without addresses.	Edit the allowlist.
`ip_not_allowed`	403	The caller is not listed, or its address can't be determined.	Edit the allowlist.
`digest_mismatch`	400	The body changed after hashing.	Hash the exact bytes you send.
`timestamp_out_of_window`	401	The clock is off by more than 300 s.	Sync the clock (NTP).
`signature_invalid`	401	The base string or the key does not match.	Compare with the test vector.
`nonce_reused`	401	A nonce sent twice within 15 minutes.	A fresh random nonce per request.
`rate_limited`	429	Over the per-minute budget (replays count too).	Wait Retry-After.

scrolls →

Detail codes

Detail codes of reconcile
Detail code	Meaning	Example pointer
`unknown_field`	A key the schema doesn't know.	`/structure/balcon`
`required`	A required field is missing.	`/title/sr`
`invalid_type`	The wrong JSON type.	`/structure/rooms`
`too_small`	Below a minimum (length or value).	`/description/sr`
`too_big`	Above a maximum (length or value).	`/price/amount`
`invalid_enum`	A value outside the vocabulary.	`/structure/heating`
`invalid_format`	A malformed id, URL, date or pattern.	`/photos/0/url`

scrolls →

Batches

POST`/connections/{id}/batches`

Up to max_batch_items upserts in one call.

Signed request; five headers

Parameters

Parameters of batches.create
Name	In	Type	Required	Description
`Idempotency-Key`	header	string, pattern ^[\x21-\x7e]{8,128}$	No	8–128 visible ASCII characters (no spaces); any other value → 422 `validation_failed`. Same key and same body → the stored outcome (`Idempotent-Replayed: true`); while the first runs → 409 `idempotency_in_progress`; another body → 422 `idempotency_key_reused`; forgotten after 7 days.
`id`	path	string (uuid)	Yes	The connection id.

scrolls →

Request body

Unknown fields are rejected.

Request body of batches.create
Field	Type	Required	Constraints	Description
`listings`	array of object	Yes	min items 1
`listings[].external_id`	string	Yes	min length 1 · max length 64 · pattern ^[A-Za-z0-9._:-]*$
`listings[].category`	string (enum)`apartmentstudiopenthouseduplexlofthousehouse_semi_detachedtownhouse`	Yes	—
`listings[].state`	string (enum)`activeinactive`	Yes	—
`listings[].title`	object	Yes	—	Unknown fields are rejected.
`listings[].title.sr`	string	Yes	min length 5 · max length 120
`listings[].title.en`	string \| null	No	max length 120
`listings[].title.tr`	string \| null	No	max length 120
`listings[].title.de`	string \| null	No	max length 120
`listings[].title.ru`	string \| null	No	max length 120
`listings[].description`	object	Yes	—	Unknown fields are rejected.
`listings[].description.sr`	string	Yes	min length 20 · max length 8000
`listings[].description.en`	string \| null	No	max length 8000
`listings[].description.tr`	string \| null	No	max length 8000
`listings[].description.de`	string \| null	No	max length 8000
`listings[].description.ru`	string \| null	No	max length 8000
`listings[].location`	object	Yes	—	Unknown fields are rejected.
`listings[].location.place_id`	string (uuid)	Yes	—
`listings[].location.address_line`	string	Yes	min length 3 · max length 200
`listings[].location.neighbourhood`	string \| null	No	max length 120
`listings[].location.lat`	number \| null	No	≥ -90 · ≤ 90
`listings[].location.lng`	number \| null	No	≥ -180 · ≤ 180
`listings[].amenities`	array of string (enum) \| null`loggiafrench_balconywalk_in_closetbuilt_in_wardrobesunderfloor_heatingfireplacelaundry_roomsoundproofing`	No	max items 40
`listings[].attributes`	map of any \| null	No	—
`listings[].photos`	array of object \| null	No	max items 64
`listings[].photos[].url`	string	Yes	max length 2048
`listings[].photos[].caption`	string \| null	No	max length 500
`listings[].photos[].room_type`	string (enum) \| null`exteriorliving_roomkitchenbedroombathroombalconyhallwayview`	No	—
`listings[].photos[].digest`	string \| null	No	pattern ^[0-9a-f]{64}$
`listings[].video_url`	string \| null	No	max length 2048
`listings[].virtual_tour_url`	string \| null	No	max length 2048
`listings[].agent`	object \| null	No	—	Unknown fields are rejected.
`listings[].agent.email`	string (email)	Yes	max length 254
`listings[].agent.name`	string \| null	No	max length 120
`listings[].agent.phone`	string \| null	No	max length 32
`listings[].source`	object	Yes	—	Unknown fields are rejected.
`listings[].source.updated_at`	string (date-time)	Yes	—
`listings[].source.url`	string \| null	No	max length 2048
`listings[].digest`	string \| null	No	max length 128
`listings[].transaction`	string (enum)`salerent`	Yes	—
`listings[].price`	object	sale only	—	Unknown fields are rejected.
`listings[].price.amount`	number	sale only	> 0 · ≤ 9999999999
`listings[].price.currency`	string (enum)`EURRSD`	sale only	—
`listings[].price.negotiable`	boolean \| null	sale only	—
`listings[].structure`	object	Yes	—	Unknown fields are rejected.
`listings[].structure.area_sqm`	number \| null	No	> 0 · ≤ 99999.99
`listings[].structure.bedrooms`	number \| null	No	≥ 0 · ≤ 99
`listings[].structure.bathrooms`	number \| null	No	≥ 0 · ≤ 99
`listings[].structure.floor`	integer \| null	No	≥ -5 · ≤ 60
`listings[].structure.levels`	integer \| null	No	≥ 1 · ≤ 6
`listings[].structure.furnished`	string (enum) \| null`furnishedsemi_furnishedunfurnished`	No	—
`listings[].structure.elevator`	boolean \| null	No	—
`listings[].structure.parking`	boolean \| null	No	—
`listings[].structure.balcony`	boolean \| null	No	—
`listings[].structure.terrace`	boolean \| null	No	—
`listings[].structure.air_conditioning`	boolean \| null	No	—
`listings[].structure.heating`	string (enum) \| null`districtgas_centralgas_localelectric_localstorage_heaterelectric_panelheat_pumpair_conditioning`	No	—
`listings[].structure.rooms`	number \| null	sale only	≥ 0 · ≤ 99
`listings[].structure.total_floors`	integer \| null	sale only	≥ 0 · ≤ 60
`listings[].structure.year_built`	integer \| null	sale only	≥ 1800 · ≤ 2035
`listings[].structure.building_group`	string (enum) \| null`newold`	sale only	—
`listings[].structure.condition`	string (enum) \| null`luxrenovatedoriginalrenovation_required`	sale only	—
`listings[].structure.garage`	boolean \| null	sale only	—
`listings[].structure.basement`	boolean \| null	sale only	—
`listings[].legal`	object	Yes	—	Unknown fields are rejected.
`listings[].legal.ownership_status`	string (enum) \| null`uknjizennije_uknjizenu_postupku`	sale only	—
`listings[].legal.legalization_status`	string (enum) \| null`legalizovanu_postupkunelegalizovan`	sale only	—
`listings[].legal.mortgage_eligible`	boolean \| null	sale only	—
`listings[].legal.mandate_attested`	boolean	Yes	—
`listings[].legal.exclusive`	boolean \| null	sale only	—
`listings[].legal.broker_license_no`	string \| null	sale only	max length 64
`listings[].legal.tapija_note`	string \| null	sale only	max length 500
`listings[].commission`	object \| null	No	—	Unknown fields are rejected.
`listings[].commission.buyer_pct`	number \| null	sale only	≥ 0 · ≤ 100
`listings[].commission.seller_pct`	number \| null	sale only	≥ 0 · ≤ 100
`listings[].commission.landlord_pct`	number \| null	rent only	≥ 0 · ≤ 100
`listings[].commission.agency_fee_pct`	number \| null	rent only	≥ 0 · ≤ 100
`listings[].rent`	object	rent only	—	Unknown fields are rejected.
`listings[].rent.amount`	number	rent only	≥ 1 · ≤ 10000000
`listings[].rent.currency`	string (enum)`EURRSD`	rent only	—
`listings[].rent.type`	string (enum)`long_termmid_termshort_termroom`	rent only	—
`listings[].rent.deposit_months`	number \| null	rent only	≥ 0 · ≤ 12
`listings[].rent.min_lease_months`	integer \| null	rent only	≥ 0 · ≤ 120
`listings[].rent.max_lease_months`	integer \| null	rent only	≥ 0 · ≤ 120
`listings[].rent.available_from`	string (date) \| null	rent only	—
`listings[].rent.utilities_included`	map of boolean \| null	rent only	—
`listings[].rent.utilities_estimate_rsd`	integer \| null	rent only	≥ 0 · ≤ 100000000
`listings[].rent.owner_lives_nearby`	boolean \| null	rent only	—
`listings[].rent.owner_proximity`	string (enum) \| null`same_apartmentsame_floorupstairsdownstairssame_buildingsame_streetwalking_distance`	rent only	—
`listings[].rent.max_occupants`	integer \| null	rent only	≥ 1 · ≤ 20
`listings[].house_rules`	object	rent only	—	Unknown fields are rejected.
`listings[].house_rules.pets`	object	rent only	—	Unknown fields are rejected.
`listings[].house_rules.pets.policy`	string (enum)`allowedon_requestnot_allowed`	rent only	—
`listings[].house_rules.pets.kinds`	array of string (enum)`dogscatssmall_cagedbirdsaquarium`	rent only	max items 5
`listings[].house_rules.pets.dog_size`	string (enum)`smallmediumany`	rent only	—
`listings[].house_rules.pets.max_count`	integer	rent only	≥ 1 · ≤ 5
`listings[].house_rules.pets.deposit_eur`	integer	rent only	≥ 0 · ≤ 100000
`listings[].house_rules.pets.note`	string	rent only	max length 200
`listings[].house_rules.smoking`	string (enum)`not_allowedbalcony_onlyallowed`	rent only	—
`listings[].house_rules.guests`	string (enum)`allowedask_firstnot_allowed`	rent only	—
`listings[].house_rules.parties`	string (enum)`not_allowedallowed`	rent only	—
`listings[].house_rules.quiet_hours`	string	rent only	max length 200
`listings[].house_rules.subletting`	string (enum)`not_allowedwith_consent`	rent only	—
`listings[].house_rules.students`	string (enum)`yesno`	rent only	—
`listings[].house_rules.families`	string (enum)`yesno`	rent only	—
`listings[].house_rules.foreign_tenants`	string (enum)`welcomeask_first`	rent only	—
`listings[].house_rules.registers_residence`	boolean	rent only	—
`listings[].house_rules.other`	string	rent only	max length 500

scrolls →

Responses

202 Accepted.

Unknown fields are rejected.

Response 202 of batches.create
Field	Type	Required	Constraints	Description
`batch`	object	Yes	—	Unknown fields are rejected.
`batch.id`	string (uuid)	Yes	—
`batch.status`	string (enum)`receivedprocessingcompletedfailed`	Yes	—
`batch.counts`	object	Yes	—	Unknown fields are rejected.
`batch.counts.accepted`	integer	Yes	≥ -9007199254740991 · ≤ 9007199254740991
`batch.counts.unchanged`	integer	Yes	≥ -9007199254740991 · ≤ 9007199254740991
`batch.counts.needs_review`	integer	Yes	≥ -9007199254740991 · ≤ 9007199254740991
`batch.counts.rejected`	integer	Yes	≥ -9007199254740991 · ≤ 9007199254740991
`batch.counts.removed`	integer	Yes	≥ -9007199254740991 · ≤ 9007199254740991
`batch.counts.total`	integer	Yes	≥ -9007199254740991 · ≤ 9007199254740991
`batch.items`	array of object	Yes	—
`batch.items[].position`	integer	Yes	≥ 0 · ≤ 9007199254740991
`batch.items[].external_id`	string	Yes	—
`batch.items[].result`	string (enum)`acceptedunchangedneeds_reviewrejectedremoved`	Yes	—
`batch.items[].candidate_id`	string (uuid) \| null	Yes	—
`batch.items[].listing_id`	string (uuid) \| null	Yes	—
`batch.items[].public_url`	string \| null	Yes	—
`batch.items[].failure_code`	string (enum) \| null`unmappable_categorymissing_requiredinvalid_payloadquota_exceededduplicategeo_unresolvedschema_invalidphoto_fetch_failed`	Yes	—
`batch.items[].details`	array of object \| map of any \| null	Yes	—
`batch.items[].warnings`	array of object	Yes	—
`batch.items[].warnings[].code`	string (enum)`agent_not_membervirtual_tour_droppedcommission_droppedfield_not_applicablecoordinates_outside_placephoto_cap_applied`	Yes	—
`batch.items[].warnings[].pointer`	string	No	—
`batch.items[].warnings[].message`	string	Yes	—

scrolls →

400 body_invalid: The body is not a JSON object. The body is the error envelope.
404 connection_not_found: Unknown id, or another app's connection. The body is the error envelope.
409 connection_not_active: details.status is pending, paused or revoked. idempotency_in_progress: The same key while the first request runs (details.batch_id). The body is the error envelope.
422 batch_too_large: More than max_batch_items, more than 50 to validate, or more than 5,000 reconcile ids. idempotency_key_reused: The same key with a different body, within 7 days. duplicate_external_id: One external_id twice in a batch. validation_failed: The payload is invalid (details array). The body is the error envelope.
429 connection_item_limit: Over the hourly item budget. The body is the error envelope.

Examples

Request · batches.create

POST /api/partners/v1/connections/{id}/batches
NK-Key-Id: nkp_sandbox_7f3k9q2m4x8c1v6b
NK-Timestamp: 1791792000
NK-Nonce: <16–64 random bytes, base64url>
Content-Digest: sha-256=:<base64 SHA-256 of the exact body bytes>:
NK-Signature: v1=<86 base64url characters, no padding>
Content-Type: application/json

{
  "listings": [
    {
      "external_id": "REAA-12345",
      "transaction": "sale",
      "category": "apartment",
      "state": "active",
      "title": {
        "sr": "Trosoban stan, Vračar",
        "en": "Three-room flat, Vračar"
      },
      "description": {
        "sr": "Svetao trosoban stan na Vračaru, renoviran 2024, na pet minuta od Hrama Svetog Save.",
        "en": "A bright three-room flat in Vračar, renovated in 2024, five minutes from the Temple of Saint Sava."
      },
      "price": {
        "amount": 245000,
        "currency": "EUR",
        "negotiable": false
      },
      "location": {
        "place_id": "b2c0d6a4-3f1e-4d2a-9c8b-7e6f5a4b3c2d",
        "address_line": "Njegoševa 10",
        "neighbourhood": "Crveni krst",
        "lat": 44.8012,
        "lng": 20.4722
      },
      "structure": {
        "area_sqm": 78.5,
        "rooms": 3,
        "bedrooms": 2,
        "bathrooms": 1,
        "floor": 3,
        "total_floors": 5,
        "levels": 1,
        "year_built": 1968,
        "building_group": "old",
        "condition": "renovated",
        "furnished": "semi_furnished",
        "heating": "district",
        "elevator": true,
        "parking": false,
        "garage": false,
        "balcony": true,
        "terrace": false,
        "air_conditioning": true,
        "basement": false
      },
      "legal": {
        "ownership_status": "uknjizen",
        "legalization_status": "legalizovan",
        "mortgage_eligible": true,
        "mandate_attested": true,
        "exclusive": false,
        "broker_license_no": null,
        "tapija_note": null
      },
      "commission": {
        "buyer_pct": 2,
        "seller_pct": 2
      },
      "amenities": [
        "built_in_wardrobes",
        "intercom"
      ],
      "attributes": {},
      "photos": [
        {
          "url": "https://cdn.reaa.rs/listings/12345/1.jpg",
          "caption": null,
          "room_type": "living_room",
          "digest": null
        },
        {
          "url": "https://cdn.reaa.rs/listings/12345/2.jpg",
          "caption": null,
          "room_type": "kitchen",
          "digest": null
        },
        {
          "url": "https://cdn.reaa.rs/listings/12345/3.jpg",
          "caption": null,
          "room_type": "bedroom",
          "digest": null
        }
      ],
      "video_url": null,
      "virtual_tour_url": null,
      "agent": {
        "email": "milan@agencija.rs",
        "name": "Milan Petrović",
        "phone": "+381601234567"
      },
      "source": {
        "updated_at": "2026-10-12T08:00:00Z",
        "url": "https://agencija.rs/nekretnine/12345"
      },
      "digest": null
    },
    {
      "external_id": "REAA-12346",
      "transaction": "sale",
      "category": "apartment",
      "state": "active",
      "title": {
        "sr": "Trosoban stan, Vračar",
        "en": "Three-room flat, Vračar"
      },
      "description": {
        "sr": "Svetao trosoban stan na Vračaru, renoviran 2024, na pet minuta od Hrama Svetog Save.",
        "en": "A bright three-room flat in Vračar, renovated in 2024, five minutes from the Temple of Saint Sava."
      },
      "price": {
        "amount": 245000,
        "currency": "EUR",
        "negotiable": false
      },
      "location": {
        "place_id": "b2c0d6a4-3f1e-4d2a-9c8b-7e6f5a4b3c2d",
        "address_line": "Njegoševa 10",
        "neighbourhood": "Crveni krst",
        "lat": 44.8012,
        "lng": 20.4722
      },
      "structure": {
        "area_sqm": 78.5,
        "rooms": 3,
        "bedrooms": 2,
        "bathrooms": 1,
        "floor": 3,
        "total_floors": 5,
        "levels": 1,
        "year_built": 1968,
        "building_group": "old",
        "condition": "renovated",
        "furnished": "semi_furnished",
        "heating": "district",
        "elevator": true,
        "parking": false,
        "garage": false,
        "balcony": true,
        "terrace": false,
        "air_conditioning": true,
        "basement": false
      },
      "legal": {
        "ownership_status": "uknjizen",
        "legalization_status": "legalizovan",
        "mortgage_eligible": true,
        "mandate_attested": true,
        "exclusive": false,
        "broker_license_no": null,
        "tapija_note": null
      },
      "commission": {
        "buyer_pct": 2,
        "seller_pct": 2
      },
      "amenities": [
        "built_in_wardrobes",
        "intercom"
      ],
      "attributes": {},
      "photos": [
        {
          "url": "https://cdn.reaa.rs/listings/12345/1.jpg",
          "caption": null,
          "room_type": "living_room",
          "digest": null
        },
        {
          "url": "https://cdn.reaa.rs/listings/12345/2.jpg",
          "caption": null,
          "room_type": "kitchen",
          "digest": null
        },
        {
          "url": "https://cdn.reaa.rs/listings/12345/3.jpg",
          "caption": null,
          "room_type": "bedroom",
          "digest": null
        }
      ],
      "video_url": null,
      "virtual_tour_url": null,
      "agent": {
        "email": "milan@agencija.rs",
        "name": "Milan Petrović",
        "phone": "+381601234567"
      },
      "source": {
        "updated_at": "2026-10-12T08:00:00Z",
        "url": "https://agencija.rs/nekretnine/12345"
      },
      "digest": null
    },
    {
      "external_id": "REAA-12347",
      "transaction": "sale",
      "category": "apartment",
      "state": "active",
      "title": {
        "sr": "Trosoban stan, Vračar",
        "en": "Three-room flat, Vračar"
      },
      "description": {
        "sr": "Svetao trosoban stan na Vračaru, renoviran 2024, na pet minuta od Hrama Svetog Save.",
        "en": "A bright three-room flat in Vračar, renovated in 2024, five minutes from the Temple of Saint Sava."
      },
      "price": {
        "amount": 245000,
        "currency": "EUR",
        "negotiable": false
      },
      "location": {
        "place_id": "b2c0d6a4-3f1e-4d2a-9c8b-7e6f5a4b3c2d",
        "address_line": "Njegoševa 10",
        "neighbourhood": "Crveni krst",
        "lat": 44.8012,
        "lng": 20.4722
      },
      "structure": {
        "area_sqm": 78.5,
        "rooms": 3,
        "bedrooms": 2,
        "bathrooms": 1,
        "floor": 3,
        "total_floors": 5,
        "levels": 1,
        "year_built": 1968,
        "building_group": "old",
        "condition": "renovated",
        "furnished": "semi_furnished",
        "heating": "district",
        "elevator": true,
        "parking": false,
        "garage": false,
        "balcony": true,
        "terrace": false,
        "air_conditioning": true,
        "basement": false
      },
      "legal": {
        "ownership_status": "uknjizen",
        "legalization_status": "legalizovan",
        "mortgage_eligible": true,
        "mandate_attested": true,
        "exclusive": false,
        "broker_license_no": null,
        "tapija_note": null
      },
      "commission": {
        "buyer_pct": 2,
        "seller_pct": 2
      },
      "amenities": [
        "built_in_wardrobes",
        "intercom"
      ],
      "attributes": {},
      "photos": [
        {
          "url": "https://cdn.reaa.rs/listings/12345/1.jpg",
          "caption": null,
          "room_type": "living_room",
          "digest": null
        },
        {
          "url": "https://cdn.reaa.rs/listings/12345/2.jpg",
          "caption": null,
          "room_type": "kitchen",
          "digest": null
        },
        {
          "url": "https://cdn.reaa.rs/listings/12345/3.jpg",
          "caption": null,
          "room_type": "bedroom",
          "digest": null
        }
      ],
      "video_url": null,
      "virtual_tour_url": null,
      "agent": {
        "email": "milan@agencija.rs",
        "name": "Milan Petrović",
        "phone": "+381601234567"
      },
      "source": {
        "updated_at": "2026-10-12T08:00:00Z",
        "url": "https://agencija.rs/nekretnine/12345"
      },
      "digest": null
    }
  ]
}

Errors

Errors of batches.create
Code	HTTP	When it happens	What to do
`body_invalid`	400	The body is not a JSON object.	Send valid JSON.
`connection_not_found`	404	Unknown id, or another app's connection.	Check the id and the key environment.
`connection_not_active`	409	details.status is pending, paused or revoked.	Wait for the agency, or stop pushing.
`idempotency_in_progress`	409	The same key while the first request runs (details.batch_id).	Poll the batch.
`validation_failed`	422	The payload is invalid (details array).	Fix the fields at the pointers.
`batch_too_large`	422	More than max_batch_items, more than 50 to validate, or more than 5,000 reconcile ids.	Split.
`duplicate_external_id`	422	One external_id twice in a batch.	Send each listing once.
`idempotency_key_reused`	422	The same key with a different body, within 7 days.	A new key per distinct body.
`connection_item_limit`	429	Over the hourly item budget.	Wait Retry-After, spread pushes.

scrolls →

Errors on every endpoint (14)

Errors on every endpoint, batches.create
Code	HTTP	When it happens	What to do
`ingest_disabled`	503	Novi Kvadrat switched ingestion off.	Retry later with backoff.
`body_too_large`	413	The body is over 4 MiB (checked first).	Split the batch.
`signature_missing`	401	A signing header is absent or malformed.	Send all five headers.
`key_invalid`	401	Unknown or revoked key.	Register a new key.
`key_expired`	401	The key is past its 365 days.	Register a new key.
`app_suspended`	403	Staff suspended the app.	Write to partners@novikvadrat.rs.
`account_blocked`	403	Staff suspended or archived the organization.	Write to partners@novikvadrat.rs.
`ip_allowlist_empty`	403	A live app without addresses.	Edit the allowlist.
`ip_not_allowed`	403	The caller is not listed, or its address can't be determined.	Edit the allowlist.
`digest_mismatch`	400	The body changed after hashing.	Hash the exact bytes you send.
`timestamp_out_of_window`	401	The clock is off by more than 300 s.	Sync the clock (NTP).
`signature_invalid`	401	The base string or the key does not match.	Compare with the test vector.
`nonce_reused`	401	A nonce sent twice within 15 minutes.	A fresh random nonce per request.
`rate_limited`	429	Over the per-minute budget (replays count too).	Wait Retry-After.

scrolls →

Detail codes

Detail codes of batches.create
Detail code	Meaning	Example pointer
`unknown_field`	A key the schema doesn't know.	`/structure/balcon`
`required`	A required field is missing.	`/title/sr`
`invalid_type`	The wrong JSON type.	`/structure/rooms`
`too_small`	Below a minimum (length or value).	`/description/sr`
`too_big`	Above a maximum (length or value).	`/price/amount`
`invalid_enum`	A value outside the vocabulary.	`/structure/heating`
`invalid_format`	A malformed id, URL, date or pattern.	`/photos/0/url`
`unknown_place`	place_id is not a city or municipality we know.	`/location/place_id`
`duplicate_external_id`	One external_id twice in one batch.	`/listings/3/external_id`
`duplicate_photo_url`	One photo URL listed twice.	`/photos/2/url`

scrolls →

Warnings of batches.create
Warning	Meaning	Example pointer
`agent_not_member`	agent.email is not an active member of the agency; the listing has no agent.	`/agent/email`
`virtual_tour_dropped`	The agency's plan has no virtual tours; the URL was not stored.	`/virtual_tour_url`
`commission_dropped`	The agency is a bank; commission was not stored.	`/commission`
`field_not_applicable`	A field that does not apply to the category was not stored.	`/structure/floor`
`coordinates_outside_place`	The coordinates fall outside the place's boundary (kept).	`/location`
`photo_cap_applied`	More photos than the agency's plan allows; the extra ones were dropped.	`/photos`

scrolls →

GET`/batches/{id}`

Status and per-item results of a push.

Signed request; five headers

Parameters

Parameters of batches.get
Name	In	Type	Required	Description
`id`	path	string (uuid)	Yes	The batch id.

scrolls →

Responses

200 OK.

Unknown fields are rejected.

Response 200 of batches.get
Field	Type	Required	Constraints	Description
`batch`	object	Yes	—
`batch.id`	string (uuid)	Yes	—
`batch.kind`	string (enum)`singlebatchremovereconcile`	Yes	—
`batch.status`	string (enum)`receivedprocessingcompletedfailed`	Yes	—
`batch.counts`	object	No	—	Unknown fields are rejected.
`batch.counts.accepted`	integer	Yes	≥ -9007199254740991 · ≤ 9007199254740991
`batch.counts.unchanged`	integer	Yes	≥ -9007199254740991 · ≤ 9007199254740991
`batch.counts.needs_review`	integer	Yes	≥ -9007199254740991 · ≤ 9007199254740991
`batch.counts.rejected`	integer	Yes	≥ -9007199254740991 · ≤ 9007199254740991
`batch.counts.removed`	integer	Yes	≥ -9007199254740991 · ≤ 9007199254740991
`batch.counts.total`	integer	Yes	≥ -9007199254740991 · ≤ 9007199254740991
`items`	array of object	Yes	—
`items[].position`	integer	Yes	≥ 0 · ≤ 9007199254740991
`items[].external_id`	string	Yes	—
`items[].result`	string (enum)`acceptedunchangedneeds_reviewrejectedremoved`	Yes	—
`items[].candidate_id`	string (uuid) \| null	Yes	—
`items[].listing_id`	string (uuid) \| null	Yes	—
`items[].public_url`	string \| null	Yes	—
`items[].failure_code`	string (enum) \| null`unmappable_categorymissing_requiredinvalid_payloadquota_exceededduplicategeo_unresolvedschema_invalidphoto_fetch_failed`	Yes	—
`items[].details`	array of object \| map of any \| null	Yes	—
`items[].warnings`	array of object	Yes	—
`items[].warnings[].code`	string (enum)`agent_not_membervirtual_tour_droppedcommission_droppedfield_not_applicablecoordinates_outside_placephoto_cap_applied`	Yes	—
`items[].warnings[].pointer`	string	No	—
`items[].warnings[].message`	string	Yes	—

scrolls →

404 batch_not_found: Unknown batch id, or another app's batch. The body is the error envelope.

Examples

Request · batches.get

GET /api/partners/v1/batches/{id}
NK-Key-Id: nkp_sandbox_7f3k9q2m4x8c1v6b
NK-Timestamp: 1791792000
NK-Nonce: <16–64 random bytes, base64url>
Content-Digest: sha-256=:47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=:
NK-Signature: v1=<86 base64url characters, no padding>

Errors

Errors of batches.get
Code	HTTP	When it happens	What to do
`batch_not_found`	404	Unknown batch id, or another app's batch.	—

scrolls →

Errors on every endpoint (14)

Errors on every endpoint, batches.get
Code	HTTP	When it happens	What to do
`ingest_disabled`	503	Novi Kvadrat switched ingestion off.	Retry later with backoff.
`body_too_large`	413	The body is over 4 MiB (checked first).	Split the batch.
`signature_missing`	401	A signing header is absent or malformed.	Send all five headers.
`key_invalid`	401	Unknown or revoked key.	Register a new key.
`key_expired`	401	The key is past its 365 days.	Register a new key.
`app_suspended`	403	Staff suspended the app.	Write to partners@novikvadrat.rs.
`account_blocked`	403	Staff suspended or archived the organization.	Write to partners@novikvadrat.rs.
`ip_allowlist_empty`	403	A live app without addresses.	Edit the allowlist.
`ip_not_allowed`	403	The caller is not listed, or its address can't be determined.	Edit the allowlist.
`digest_mismatch`	400	The body changed after hashing.	Hash the exact bytes you send.
`timestamp_out_of_window`	401	The clock is off by more than 300 s.	Sync the clock (NTP).
`signature_invalid`	401	The base string or the key does not match.	Compare with the test vector.
`nonce_reused`	401	A nonce sent twice within 15 minutes.	A fresh random nonce per request.
`rate_limited`	429	Over the per-minute budget (replays count too).	Wait Retry-After.

scrolls →

Validate

POST`/validate`

Dry run: validate without storing anything.

Signed request; five headers

Request body

Unknown fields are rejected.

Request body of validate
Field	Type	Required	Constraints	Description
`listing`	object	No	—	One listing; `transaction` picks the sale or the rent shape. Text lengths count Unicode code points, as `maxLength` does; titles are ALSO capped at 120 UTF-16 units (an emoji counts as two). A sale price is refused (`too_big`) when `amount × 117` (rounded, for EUR) would exceed 2,147,483,647 RSD (about 18,354,561 EUR). `state: active` needs `legal.mandate_attested: true`. See https://developers.novikvadrat.rs/docs/listings/payload-v1.
`listing.external_id`	string	Yes	min length 1 · max length 64 · pattern ^[A-Za-z0-9._:-]*$
`listing.category`	string (enum)`apartmentstudiopenthouseduplexlofthousehouse_semi_detachedtownhouse`	Yes	—
`listing.state`	string (enum)`activeinactive`	Yes	—
`listing.title`	object	Yes	—	Unknown fields are rejected.
`listing.title.sr`	string	Yes	min length 5 · max length 120
`listing.title.en`	string \| null	No	max length 120
`listing.title.tr`	string \| null	No	max length 120
`listing.title.de`	string \| null	No	max length 120
`listing.title.ru`	string \| null	No	max length 120
`listing.description`	object	Yes	—	Unknown fields are rejected.
`listing.description.sr`	string	Yes	min length 20 · max length 8000
`listing.description.en`	string \| null	No	max length 8000
`listing.description.tr`	string \| null	No	max length 8000
`listing.description.de`	string \| null	No	max length 8000
`listing.description.ru`	string \| null	No	max length 8000
`listing.location`	object	Yes	—	Unknown fields are rejected.
`listing.location.place_id`	string (uuid)	Yes	—
`listing.location.address_line`	string	Yes	min length 3 · max length 200
`listing.location.neighbourhood`	string \| null	No	max length 120
`listing.location.lat`	number \| null	No	≥ -90 · ≤ 90
`listing.location.lng`	number \| null	No	≥ -180 · ≤ 180
`listing.amenities`	array of string (enum) \| null`loggiafrench_balconywalk_in_closetbuilt_in_wardrobesunderfloor_heatingfireplacelaundry_roomsoundproofing`	No	max items 40
`listing.attributes`	map of any \| null	No	—
`listing.photos`	array of object \| null	No	max items 64
`listing.photos[].url`	string	Yes	max length 2048
`listing.photos[].caption`	string \| null	No	max length 500
`listing.photos[].room_type`	string (enum) \| null`exteriorliving_roomkitchenbedroombathroombalconyhallwayview`	No	—
`listing.photos[].digest`	string \| null	No	pattern ^[0-9a-f]{64}$
`listing.video_url`	string \| null	No	max length 2048
`listing.virtual_tour_url`	string \| null	No	max length 2048
`listing.agent`	object \| null	No	—	Unknown fields are rejected.
`listing.agent.email`	string (email)	Yes	max length 254
`listing.agent.name`	string \| null	No	max length 120
`listing.agent.phone`	string \| null	No	max length 32
`listing.source`	object	Yes	—	Unknown fields are rejected.
`listing.source.updated_at`	string (date-time)	Yes	—
`listing.source.url`	string \| null	No	max length 2048
`listing.digest`	string \| null	No	max length 128
`listing.transaction`	string (enum)`salerent`	Yes	—
`listing.price`	object	sale only	—	Unknown fields are rejected.
`listing.price.amount`	number	sale only	> 0 · ≤ 9999999999
`listing.price.currency`	string (enum)`EURRSD`	sale only	—
`listing.price.negotiable`	boolean \| null	sale only	—
`listing.structure`	object	Yes	—	Unknown fields are rejected.
`listing.structure.area_sqm`	number \| null	No	> 0 · ≤ 99999.99
`listing.structure.bedrooms`	number \| null	No	≥ 0 · ≤ 99
`listing.structure.bathrooms`	number \| null	No	≥ 0 · ≤ 99
`listing.structure.floor`	integer \| null	No	≥ -5 · ≤ 60
`listing.structure.levels`	integer \| null	No	≥ 1 · ≤ 6
`listing.structure.furnished`	string (enum) \| null`furnishedsemi_furnishedunfurnished`	No	—
`listing.structure.elevator`	boolean \| null	No	—
`listing.structure.parking`	boolean \| null	No	—
`listing.structure.balcony`	boolean \| null	No	—
`listing.structure.terrace`	boolean \| null	No	—
`listing.structure.air_conditioning`	boolean \| null	No	—
`listing.structure.heating`	string (enum) \| null`districtgas_centralgas_localelectric_localstorage_heaterelectric_panelheat_pumpair_conditioning`	No	—
`listing.structure.rooms`	number \| null	sale only	≥ 0 · ≤ 99
`listing.structure.total_floors`	integer \| null	sale only	≥ 0 · ≤ 60
`listing.structure.year_built`	integer \| null	sale only	≥ 1800 · ≤ 2035
`listing.structure.building_group`	string (enum) \| null`newold`	sale only	—
`listing.structure.condition`	string (enum) \| null`luxrenovatedoriginalrenovation_required`	sale only	—
`listing.structure.garage`	boolean \| null	sale only	—
`listing.structure.basement`	boolean \| null	sale only	—
`listing.legal`	object	Yes	—	Unknown fields are rejected.
`listing.legal.ownership_status`	string (enum) \| null`uknjizennije_uknjizenu_postupku`	sale only	—
`listing.legal.legalization_status`	string (enum) \| null`legalizovanu_postupkunelegalizovan`	sale only	—
`listing.legal.mortgage_eligible`	boolean \| null	sale only	—
`listing.legal.mandate_attested`	boolean	Yes	—
`listing.legal.exclusive`	boolean \| null	sale only	—
`listing.legal.broker_license_no`	string \| null	sale only	max length 64
`listing.legal.tapija_note`	string \| null	sale only	max length 500
`listing.commission`	object \| null	No	—	Unknown fields are rejected.
`listing.commission.buyer_pct`	number \| null	sale only	≥ 0 · ≤ 100
`listing.commission.seller_pct`	number \| null	sale only	≥ 0 · ≤ 100
`listing.commission.landlord_pct`	number \| null	rent only	≥ 0 · ≤ 100
`listing.commission.agency_fee_pct`	number \| null	rent only	≥ 0 · ≤ 100
`listing.rent`	object	rent only	—	Unknown fields are rejected.
`listing.rent.amount`	number	rent only	≥ 1 · ≤ 10000000
`listing.rent.currency`	string (enum)`EURRSD`	rent only	—
`listing.rent.type`	string (enum)`long_termmid_termshort_termroom`	rent only	—
`listing.rent.deposit_months`	number \| null	rent only	≥ 0 · ≤ 12
`listing.rent.min_lease_months`	integer \| null	rent only	≥ 0 · ≤ 120
`listing.rent.max_lease_months`	integer \| null	rent only	≥ 0 · ≤ 120
`listing.rent.available_from`	string (date) \| null	rent only	—
`listing.rent.utilities_included`	map of boolean \| null	rent only	—
`listing.rent.utilities_estimate_rsd`	integer \| null	rent only	≥ 0 · ≤ 100000000
`listing.rent.owner_lives_nearby`	boolean \| null	rent only	—
`listing.rent.owner_proximity`	string (enum) \| null`same_apartmentsame_floorupstairsdownstairssame_buildingsame_streetwalking_distance`	rent only	—
`listing.rent.max_occupants`	integer \| null	rent only	≥ 1 · ≤ 20
`listing.house_rules`	object	rent only	—	Unknown fields are rejected.
`listing.house_rules.pets`	object	rent only	—	Unknown fields are rejected.
`listing.house_rules.pets.policy`	string (enum)`allowedon_requestnot_allowed`	rent only	—
`listing.house_rules.pets.kinds`	array of string (enum)`dogscatssmall_cagedbirdsaquarium`	rent only	max items 5
`listing.house_rules.pets.dog_size`	string (enum)`smallmediumany`	rent only	—
`listing.house_rules.pets.max_count`	integer	rent only	≥ 1 · ≤ 5
`listing.house_rules.pets.deposit_eur`	integer	rent only	≥ 0 · ≤ 100000
`listing.house_rules.pets.note`	string	rent only	max length 200
`listing.house_rules.smoking`	string (enum)`not_allowedbalcony_onlyallowed`	rent only	—
`listing.house_rules.guests`	string (enum)`allowedask_firstnot_allowed`	rent only	—
`listing.house_rules.parties`	string (enum)`not_allowedallowed`	rent only	—
`listing.house_rules.quiet_hours`	string	rent only	max length 200
`listing.house_rules.subletting`	string (enum)`not_allowedwith_consent`	rent only	—
`listing.house_rules.students`	string (enum)`yesno`	rent only	—
`listing.house_rules.families`	string (enum)`yesno`	rent only	—
`listing.house_rules.foreign_tenants`	string (enum)`welcomeask_first`	rent only	—
`listing.house_rules.registers_residence`	boolean	rent only	—
`listing.house_rules.other`	string	rent only	max length 500
`listings`	array of object	No	min items 1
`listings[].external_id`	string	Yes	min length 1 · max length 64 · pattern ^[A-Za-z0-9._:-]*$
`listings[].category`	string (enum)`apartmentstudiopenthouseduplexlofthousehouse_semi_detachedtownhouse`	Yes	—
`listings[].state`	string (enum)`activeinactive`	Yes	—
`listings[].title`	object	Yes	—	Unknown fields are rejected.
`listings[].title.sr`	string	Yes	min length 5 · max length 120
`listings[].title.en`	string \| null	No	max length 120
`listings[].title.tr`	string \| null	No	max length 120
`listings[].title.de`	string \| null	No	max length 120
`listings[].title.ru`	string \| null	No	max length 120
`listings[].description`	object	Yes	—	Unknown fields are rejected.
`listings[].description.sr`	string	Yes	min length 20 · max length 8000
`listings[].description.en`	string \| null	No	max length 8000
`listings[].description.tr`	string \| null	No	max length 8000
`listings[].description.de`	string \| null	No	max length 8000
`listings[].description.ru`	string \| null	No	max length 8000
`listings[].location`	object	Yes	—	Unknown fields are rejected.
`listings[].location.place_id`	string (uuid)	Yes	—
`listings[].location.address_line`	string	Yes	min length 3 · max length 200
`listings[].location.neighbourhood`	string \| null	No	max length 120
`listings[].location.lat`	number \| null	No	≥ -90 · ≤ 90
`listings[].location.lng`	number \| null	No	≥ -180 · ≤ 180
`listings[].amenities`	array of string (enum) \| null`loggiafrench_balconywalk_in_closetbuilt_in_wardrobesunderfloor_heatingfireplacelaundry_roomsoundproofing`	No	max items 40
`listings[].attributes`	map of any \| null	No	—
`listings[].photos`	array of object \| null	No	max items 64
`listings[].photos[].url`	string	Yes	max length 2048
`listings[].photos[].caption`	string \| null	No	max length 500
`listings[].photos[].room_type`	string (enum) \| null`exteriorliving_roomkitchenbedroombathroombalconyhallwayview`	No	—
`listings[].photos[].digest`	string \| null	No	pattern ^[0-9a-f]{64}$
`listings[].video_url`	string \| null	No	max length 2048
`listings[].virtual_tour_url`	string \| null	No	max length 2048
`listings[].agent`	object \| null	No	—	Unknown fields are rejected.
`listings[].agent.email`	string (email)	Yes	max length 254
`listings[].agent.name`	string \| null	No	max length 120
`listings[].agent.phone`	string \| null	No	max length 32
`listings[].source`	object	Yes	—	Unknown fields are rejected.
`listings[].source.updated_at`	string (date-time)	Yes	—
`listings[].source.url`	string \| null	No	max length 2048
`listings[].digest`	string \| null	No	max length 128
`listings[].transaction`	string (enum)`salerent`	Yes	—
`listings[].price`	object	sale only	—	Unknown fields are rejected.
`listings[].price.amount`	number	sale only	> 0 · ≤ 9999999999
`listings[].price.currency`	string (enum)`EURRSD`	sale only	—
`listings[].price.negotiable`	boolean \| null	sale only	—
`listings[].structure`	object	Yes	—	Unknown fields are rejected.
`listings[].structure.area_sqm`	number \| null	No	> 0 · ≤ 99999.99
`listings[].structure.bedrooms`	number \| null	No	≥ 0 · ≤ 99
`listings[].structure.bathrooms`	number \| null	No	≥ 0 · ≤ 99
`listings[].structure.floor`	integer \| null	No	≥ -5 · ≤ 60
`listings[].structure.levels`	integer \| null	No	≥ 1 · ≤ 6
`listings[].structure.furnished`	string (enum) \| null`furnishedsemi_furnishedunfurnished`	No	—
`listings[].structure.elevator`	boolean \| null	No	—
`listings[].structure.parking`	boolean \| null	No	—
`listings[].structure.balcony`	boolean \| null	No	—
`listings[].structure.terrace`	boolean \| null	No	—
`listings[].structure.air_conditioning`	boolean \| null	No	—
`listings[].structure.heating`	string (enum) \| null`districtgas_centralgas_localelectric_localstorage_heaterelectric_panelheat_pumpair_conditioning`	No	—
`listings[].structure.rooms`	number \| null	sale only	≥ 0 · ≤ 99
`listings[].structure.total_floors`	integer \| null	sale only	≥ 0 · ≤ 60
`listings[].structure.year_built`	integer \| null	sale only	≥ 1800 · ≤ 2035
`listings[].structure.building_group`	string (enum) \| null`newold`	sale only	—
`listings[].structure.condition`	string (enum) \| null`luxrenovatedoriginalrenovation_required`	sale only	—
`listings[].structure.garage`	boolean \| null	sale only	—
`listings[].structure.basement`	boolean \| null	sale only	—
`listings[].legal`	object	Yes	—	Unknown fields are rejected.
`listings[].legal.ownership_status`	string (enum) \| null`uknjizennije_uknjizenu_postupku`	sale only	—
`listings[].legal.legalization_status`	string (enum) \| null`legalizovanu_postupkunelegalizovan`	sale only	—
`listings[].legal.mortgage_eligible`	boolean \| null	sale only	—
`listings[].legal.mandate_attested`	boolean	Yes	—
`listings[].legal.exclusive`	boolean \| null	sale only	—
`listings[].legal.broker_license_no`	string \| null	sale only	max length 64
`listings[].legal.tapija_note`	string \| null	sale only	max length 500
`listings[].commission`	object \| null	No	—	Unknown fields are rejected.
`listings[].commission.buyer_pct`	number \| null	sale only	≥ 0 · ≤ 100
`listings[].commission.seller_pct`	number \| null	sale only	≥ 0 · ≤ 100
`listings[].commission.landlord_pct`	number \| null	rent only	≥ 0 · ≤ 100
`listings[].commission.agency_fee_pct`	number \| null	rent only	≥ 0 · ≤ 100
`listings[].rent`	object	rent only	—	Unknown fields are rejected.
`listings[].rent.amount`	number	rent only	≥ 1 · ≤ 10000000
`listings[].rent.currency`	string (enum)`EURRSD`	rent only	—
`listings[].rent.type`	string (enum)`long_termmid_termshort_termroom`	rent only	—
`listings[].rent.deposit_months`	number \| null	rent only	≥ 0 · ≤ 12
`listings[].rent.min_lease_months`	integer \| null	rent only	≥ 0 · ≤ 120
`listings[].rent.max_lease_months`	integer \| null	rent only	≥ 0 · ≤ 120
`listings[].rent.available_from`	string (date) \| null	rent only	—
`listings[].rent.utilities_included`	map of boolean \| null	rent only	—
`listings[].rent.utilities_estimate_rsd`	integer \| null	rent only	≥ 0 · ≤ 100000000
`listings[].rent.owner_lives_nearby`	boolean \| null	rent only	—
`listings[].rent.owner_proximity`	string (enum) \| null`same_apartmentsame_floorupstairsdownstairssame_buildingsame_streetwalking_distance`	rent only	—
`listings[].rent.max_occupants`	integer \| null	rent only	≥ 1 · ≤ 20
`listings[].house_rules`	object	rent only	—	Unknown fields are rejected.
`listings[].house_rules.pets`	object	rent only	—	Unknown fields are rejected.
`listings[].house_rules.pets.policy`	string (enum)`allowedon_requestnot_allowed`	rent only	—
`listings[].house_rules.pets.kinds`	array of string (enum)`dogscatssmall_cagedbirdsaquarium`	rent only	max items 5
`listings[].house_rules.pets.dog_size`	string (enum)`smallmediumany`	rent only	—
`listings[].house_rules.pets.max_count`	integer	rent only	≥ 1 · ≤ 5
`listings[].house_rules.pets.deposit_eur`	integer	rent only	≥ 0 · ≤ 100000
`listings[].house_rules.pets.note`	string	rent only	max length 200
`listings[].house_rules.smoking`	string (enum)`not_allowedbalcony_onlyallowed`	rent only	—
`listings[].house_rules.guests`	string (enum)`allowedask_firstnot_allowed`	rent only	—
`listings[].house_rules.parties`	string (enum)`not_allowedallowed`	rent only	—
`listings[].house_rules.quiet_hours`	string	rent only	max length 200
`listings[].house_rules.subletting`	string (enum)`not_allowedwith_consent`	rent only	—
`listings[].house_rules.students`	string (enum)`yesno`	rent only	—
`listings[].house_rules.families`	string (enum)`yesno`	rent only	—
`listings[].house_rules.foreign_tenants`	string (enum)`welcomeask_first`	rent only	—
`listings[].house_rules.registers_residence`	boolean	rent only	—
`listings[].house_rules.other`	string	rent only	max length 500
`connection_id`	string (uuid)	No	—

scrolls →

Responses

200 OK.

Unknown fields are rejected.

Response 200 of validate
Field	Type	Required	Constraints
`results`	array of object	Yes	—
`results[].position`	integer	Yes	≥ 0 · ≤ 9007199254740991
`results[].external_id`	string \| null	Yes	—
`results[].valid`	boolean	Yes	—
`results[].errors`	array of object	Yes	—
`results[].errors[].pointer`	string	Yes	—
`results[].errors[].code`	string (enum)`unknown_fieldrequiredinvalid_typetoo_smalltoo_biginvalid_enuminvalid_formatunknown_place`	Yes	—
`results[].errors[].message`	string	Yes	—
`results[].warnings`	array of object	Yes	—
`results[].warnings[].code`	string (enum)`agent_not_membervirtual_tour_droppedcommission_droppedfield_not_applicablecoordinates_outside_placephoto_cap_applied`	Yes	—
`results[].warnings[].pointer`	string	No	—
`results[].warnings[].message`	string	Yes	—
`results[].mapped_preview`	map of any \| null	Yes	—

scrolls →

400 body_invalid: The body is not a JSON object. The body is the error envelope.
404 connection_not_found: Unknown id, or another app's connection. The body is the error envelope.
409 connection_not_active: details.status is pending, paused or revoked. The body is the error envelope.
422 batch_too_large: More than max_batch_items, more than 50 to validate, or more than 5,000 reconcile ids. validation_failed: The payload is invalid (details array). The body is the error envelope.

Examples

Request · validate

POST /api/partners/v1/validate
NK-Key-Id: nkp_sandbox_7f3k9q2m4x8c1v6b
NK-Timestamp: 1791792000
NK-Nonce: <16–64 random bytes, base64url>
Content-Digest: sha-256=:<base64 SHA-256 of the exact body bytes>:
NK-Signature: v1=<86 base64url characters, no padding>
Content-Type: application/json

{
  "listing": {
    "external_id": "REAA-12345",
    "transaction": "sale",
    "category": "apartment",
    "state": "active",
    "title": {
      "sr": "Trosoban stan, Vračar",
      "en": "Three-room flat, Vračar"
    },
    "description": {
      "sr": "Svetao trosoban stan na Vračaru, renoviran 2024, na pet minuta od Hrama Svetog Save.",
      "en": "A bright three-room flat in Vračar, renovated in 2024, five minutes from the Temple of Saint Sava."
    },
    "price": {
      "amount": 245000,
      "currency": "EUR",
      "negotiable": false
    },
    "location": {
      "place_id": "b2c0d6a4-3f1e-4d2a-9c8b-7e6f5a4b3c2d",
      "address_line": "Njegoševa 10",
      "neighbourhood": "Crveni krst",
      "lat": 44.8012,
      "lng": 20.4722
    },
    "structure": {
      "area_sqm": 78.5,
      "rooms": 3,
      "bedrooms": 2,
      "bathrooms": 1,
      "floor": 3,
      "total_floors": 5,
      "levels": 1,
      "year_built": 1968,
      "building_group": "old",
      "condition": "renovated",
      "furnished": "semi_furnished",
      "heating": "district",
      "elevator": true,
      "parking": false,
      "garage": false,
      "balcony": true,
      "terrace": false,
      "air_conditioning": true,
      "basement": false
    },
    "legal": {
      "ownership_status": "uknjizen",
      "legalization_status": "legalizovan",
      "mortgage_eligible": true,
      "mandate_attested": true,
      "exclusive": false,
      "broker_license_no": null,
      "tapija_note": null
    },
    "commission": {
      "buyer_pct": 2,
      "seller_pct": 2
    },
    "amenities": [
      "built_in_wardrobes",
      "intercom"
    ],
    "attributes": {},
    "photos": [
      {
        "url": "https://cdn.reaa.rs/listings/12345/1.jpg",
        "caption": null,
        "room_type": "living_room",
        "digest": null
      },
      {
        "url": "https://cdn.reaa.rs/listings/12345/2.jpg",
        "caption": null,
        "room_type": "kitchen",
        "digest": null
      },
      {
        "url": "https://cdn.reaa.rs/listings/12345/3.jpg",
        "caption": null,
        "room_type": "bedroom",
        "digest": null
      }
    ],
    "video_url": null,
    "virtual_tour_url": null,
    "agent": {
      "email": "milan@agencija.rs",
      "name": "Milan Petrović",
      "phone": "+381601234567"
    },
    "source": {
      "updated_at": "2026-10-12T08:00:00Z",
      "url": "https://agencija.rs/nekretnine/12345"
    },
    "digest": null
  },
  "connection_id": "9b1d6c2e-4f3a-4c8e-9a71-2d5e8f0b3c44"
}

Errors

Errors of validate
Code	HTTP	When it happens	What to do
`body_invalid`	400	The body is not a JSON object.	Send valid JSON.
`connection_not_found`	404	Unknown id, or another app's connection.	Check the id and the key environment.
`connection_not_active`	409	details.status is pending, paused or revoked.	Wait for the agency, or stop pushing.
`validation_failed`	422	The payload is invalid (details array).	Fix the fields at the pointers.
`batch_too_large`	422	More than max_batch_items, more than 50 to validate, or more than 5,000 reconcile ids.	Split.

scrolls →

Errors on every endpoint (14)

Errors on every endpoint, validate
Code	HTTP	When it happens	What to do
`ingest_disabled`	503	Novi Kvadrat switched ingestion off.	Retry later with backoff.
`body_too_large`	413	The body is over 4 MiB (checked first).	Split the batch.
`signature_missing`	401	A signing header is absent or malformed.	Send all five headers.
`key_invalid`	401	Unknown or revoked key.	Register a new key.
`key_expired`	401	The key is past its 365 days.	Register a new key.
`app_suspended`	403	Staff suspended the app.	Write to partners@novikvadrat.rs.
`account_blocked`	403	Staff suspended or archived the organization.	Write to partners@novikvadrat.rs.
`ip_allowlist_empty`	403	A live app without addresses.	Edit the allowlist.
`ip_not_allowed`	403	The caller is not listed, or its address can't be determined.	Edit the allowlist.
`digest_mismatch`	400	The body changed after hashing.	Hash the exact bytes you send.
`timestamp_out_of_window`	401	The clock is off by more than 300 s.	Sync the clock (NTP).
`signature_invalid`	401	The base string or the key does not match.	Compare with the test vector.
`nonce_reused`	401	A nonce sent twice within 15 minutes.	A fresh random nonce per request.
`rate_limited`	429	Over the per-minute budget (replays count too).	Wait Retry-After.

scrolls →

Detail codes

Detail codes of validate
Detail code	Meaning	Example pointer
`unknown_field`	A key the schema doesn't know.	`/structure/balcon`
`required`	A required field is missing.	`/title/sr`
`invalid_type`	The wrong JSON type.	`/structure/rooms`
`too_small`	Below a minimum (length or value).	`/description/sr`
`too_big`	Above a maximum (length or value).	`/price/amount`
`invalid_enum`	A value outside the vocabulary.	`/structure/heating`
`invalid_format`	A malformed id, URL, date or pattern.	`/photos/0/url`
`unknown_place`	place_id is not a city or municipality we know.	`/location/place_id`
`duplicate_external_id`	One external_id twice in one batch.	`/listings/3/external_id`
`duplicate_photo_url`	One photo URL listed twice.	`/photos/2/url`

scrolls →

Warnings of validate
Warning	Meaning	Example pointer
`agent_not_member`	agent.email is not an active member of the agency; the listing has no agent.	`/agent/email`
`virtual_tour_dropped`	The agency's plan has no virtual tours; the URL was not stored.	`/virtual_tour_url`
`commission_dropped`	The agency is a bank; commission was not stored.	`/commission`
`field_not_applicable`	A field that does not apply to the category was not stored.	`/structure/floor`
`coordinates_outside_place`	The coordinates fall outside the place's boundary (kept).	`/location`
`photo_cap_applied`	More photos than the agency's plan allows; the extra ones were dropped.	`/photos`

scrolls →

Vocabularies

GET`/vocabularies`

Every enumeration, with labels and per-category attributes.

Signed request; five headers

Parameters

Parameters of vocabularies
Name	In	Type	Required	Description
`If-None-Match`	header	string	No	The ETag of a previous answer; when it is still current the answer is 304 with no body.

scrolls →

Responses

200 OK.

Unknown fields are rejected.

Response 200 of vocabularies
Field	Type	Required	Constraints	Description
`version`	string	Yes	—
`categories`	array of object	Yes	—
`categories[].code`	string	Yes	—
`categories[].group`	string	Yes	—
`categories[].labels`	object	Yes	—	Unknown fields are rejected.
`categories[].labels.en`	string	Yes	—
`categories[].labels.sr`	string	Yes	—
`transaction`	array of string	Yes	—
`heating`	array of string	Yes	—
`condition`	array of string	Yes	—
`furnished`	array of string	Yes	—
`building_group`	array of string	Yes	—
`ownership_status`	array of string	Yes	—
`legalization_status`	array of string	Yes	—
`rental_type`	array of string	Yes	—
`room_types`	array of string	Yes	—
`amenities`	array of object	Yes	—
`amenities[].code`	string	Yes	—
`amenities[].labels`	object	Yes	—	Unknown fields are rejected.
`amenities[].labels.en`	string	Yes	—
`amenities[].labels.sr`	string	Yes	—
`remove_reasons`	array of string	Yes	—
`attributes_by_category`	map of any	Yes	—

scrolls →

304 Not modified: If-None-Match matched the current ETag. The body is the error envelope.

Examples

Request · vocabularies

GET /api/partners/v1/vocabularies
NK-Key-Id: nkp_sandbox_7f3k9q2m4x8c1v6b
NK-Timestamp: 1791792000
NK-Nonce: <16–64 random bytes, base64url>
Content-Digest: sha-256=:47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=:
NK-Signature: v1=<86 base64url characters, no padding>

Errors

No errors beyond the signed-request checks.

Errors on every endpoint (14)

Errors on every endpoint, vocabularies
Code	HTTP	When it happens	What to do
`ingest_disabled`	503	Novi Kvadrat switched ingestion off.	Retry later with backoff.
`body_too_large`	413	The body is over 4 MiB (checked first).	Split the batch.
`signature_missing`	401	A signing header is absent or malformed.	Send all five headers.
`key_invalid`	401	Unknown or revoked key.	Register a new key.
`key_expired`	401	The key is past its 365 days.	Register a new key.
`app_suspended`	403	Staff suspended the app.	Write to partners@novikvadrat.rs.
`account_blocked`	403	Staff suspended or archived the organization.	Write to partners@novikvadrat.rs.
`ip_allowlist_empty`	403	A live app without addresses.	Edit the allowlist.
`ip_not_allowed`	403	The caller is not listed, or its address can't be determined.	Edit the allowlist.
`digest_mismatch`	400	The body changed after hashing.	Hash the exact bytes you send.
`timestamp_out_of_window`	401	The clock is off by more than 300 s.	Sync the clock (NTP).
`signature_invalid`	401	The base string or the key does not match.	Compare with the test vector.
`nonce_reused`	401	A nonce sent twice within 15 minutes.	A fresh random nonce per request.
`rate_limited`	429	Over the per-minute budget (replays count too).	Wait Retry-After.

scrolls →

Places

GET`/places`

Search cities and municipalities.

Signed request; five headers

Parameters

Parameters of places.search
Name	In	Type	Required
`q`	query	string	No
`type`	query	enum: city, municipality	No
`cursor`	query	string	No
`limit`	query	string, pattern ^\d{1,3}$	No

scrolls →

Responses

200 OK.

Unknown fields are rejected.

Response 200 of places.search
Field	Type	Required	Constraints
`places`	array of object	Yes	—
`places[].id`	string (uuid)	Yes	—
`places[].type`	string (enum)`citymunicipality`	Yes	—
`places[].name_sr`	string	Yes	—
`places[].name_en`	string	Yes	—
`places[].official_code`	string \| null	Yes	—
`places[].city_id`	string (uuid) \| null	Yes	—
`places[].city_name_sr`	string \| null	Yes	—
`places[].lat`	number \| null	Yes	—
`places[].lng`	number \| null	Yes	—
`next_cursor`	string \| null	Yes	—

scrolls →

422 validation_failed: The payload is invalid (details array). The body is the error envelope.

Examples

Request · places.search

GET /api/partners/v1/places
NK-Key-Id: nkp_sandbox_7f3k9q2m4x8c1v6b
NK-Timestamp: 1791792000
NK-Nonce: <16–64 random bytes, base64url>
Content-Digest: sha-256=:47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=:
NK-Signature: v1=<86 base64url characters, no padding>

Errors

Errors of places.search
Code	HTTP	When it happens	What to do
`validation_failed`	422	The payload is invalid (details array).	Fix the fields at the pointers.

scrolls →

Errors on every endpoint (14)

Errors on every endpoint, places.search
Code	HTTP	When it happens	What to do
`ingest_disabled`	503	Novi Kvadrat switched ingestion off.	Retry later with backoff.
`body_too_large`	413	The body is over 4 MiB (checked first).	Split the batch.
`signature_missing`	401	A signing header is absent or malformed.	Send all five headers.
`key_invalid`	401	Unknown or revoked key.	Register a new key.
`key_expired`	401	The key is past its 365 days.	Register a new key.
`app_suspended`	403	Staff suspended the app.	Write to partners@novikvadrat.rs.
`account_blocked`	403	Staff suspended or archived the organization.	Write to partners@novikvadrat.rs.
`ip_allowlist_empty`	403	A live app without addresses.	Edit the allowlist.
`ip_not_allowed`	403	The caller is not listed, or its address can't be determined.	Edit the allowlist.
`digest_mismatch`	400	The body changed after hashing.	Hash the exact bytes you send.
`timestamp_out_of_window`	401	The clock is off by more than 300 s.	Sync the clock (NTP).
`signature_invalid`	401	The base string or the key does not match.	Compare with the test vector.
`nonce_reused`	401	A nonce sent twice within 15 minutes.	A fresh random nonce per request.
`rate_limited`	429	Over the per-minute budget (replays count too).	Wait Retry-After.

scrolls →

Detail codes

Detail codes of places.search
Detail code	Meaning	Example pointer
`unknown_field`	A key the schema doesn't know.	`/structure/balcon`
`required`	A required field is missing.	`/title/sr`
`invalid_type`	The wrong JSON type.	`/structure/rooms`
`too_small`	Below a minimum (length or value).	`/description/sr`
`too_big`	Above a maximum (length or value).	`/price/amount`
`invalid_enum`	A value outside the vocabulary.	`/structure/heating`
`invalid_format`	A malformed id, URL, date or pattern.	`/photos/0/url`

scrolls →

GET`/places/{id}`

One place.

Signed request; five headers

Parameters

Parameters of places.get
Name	In	Type	Required	Description
`id`	path	string (uuid)	Yes	The place id.

scrolls →

Responses

200 OK.

Unknown fields are rejected.

Response 200 of places.get
Field	Type	Required	Constraints	Description
`place`	object	Yes	—	Unknown fields are rejected.
`place.id`	string (uuid)	Yes	—
`place.type`	string (enum)`citymunicipality`	Yes	—
`place.name_sr`	string	Yes	—
`place.name_en`	string	Yes	—
`place.official_code`	string \| null	Yes	—
`place.city_id`	string (uuid) \| null	Yes	—
`place.city_name_sr`	string \| null	Yes	—
`place.lat`	number \| null	Yes	—
`place.lng`	number \| null	Yes	—

scrolls →

404 place_not_found: Unknown place id. The body is the error envelope.

Examples

Request · places.get

GET /api/partners/v1/places/{id}
NK-Key-Id: nkp_sandbox_7f3k9q2m4x8c1v6b
NK-Timestamp: 1791792000
NK-Nonce: <16–64 random bytes, base64url>
Content-Digest: sha-256=:47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=:
NK-Signature: v1=<86 base64url characters, no padding>

Errors

Errors of places.get
Code	HTTP	When it happens	What to do
`place_not_found`	404	Unknown place id.	—

scrolls →

Errors on every endpoint (14)

Errors on every endpoint, places.get
Code	HTTP	When it happens	What to do
`ingest_disabled`	503	Novi Kvadrat switched ingestion off.	Retry later with backoff.
`body_too_large`	413	The body is over 4 MiB (checked first).	Split the batch.
`signature_missing`	401	A signing header is absent or malformed.	Send all five headers.
`key_invalid`	401	Unknown or revoked key.	Register a new key.
`key_expired`	401	The key is past its 365 days.	Register a new key.
`app_suspended`	403	Staff suspended the app.	Write to partners@novikvadrat.rs.
`account_blocked`	403	Staff suspended or archived the organization.	Write to partners@novikvadrat.rs.
`ip_allowlist_empty`	403	A live app without addresses.	Edit the allowlist.
`ip_not_allowed`	403	The caller is not listed, or its address can't be determined.	Edit the allowlist.
`digest_mismatch`	400	The body changed after hashing.	Hash the exact bytes you send.
`timestamp_out_of_window`	401	The clock is off by more than 300 s.	Sync the clock (NTP).
`signature_invalid`	401	The base string or the key does not match.	Compare with the test vector.
`nonce_reused`	401	A nonce sent twice within 15 minutes.	A fresh random nonce per request.
`rate_limited`	429	Over the per-minute budget (replays count too).	Wait Retry-After.

scrolls →