Changelog
Back to All
Added

Full property model and list endpoints for properties and users

about 2 hours ago by ReadMe API

The real estate property endpoints now accept and return the full BKBN property model, so you can sync everything your CRM holds about a listing, not just its address and basics.

New property fields

POST /v1/real-estate-properties and PATCH /v1/real-estate-properties/{propertyId} (or /by-reference/{objectReferenceId}) accept them, and both GET variants return them:

  • References: displayReferenceId, projectReferenceId, houseReferenceId, is24Id, parentRealtyReferenceId and the Swiss identifiers in swissReferences (EGID, EWID, EGRID, Minergie).
  • Availability: availabilityState, availabilityStartAt, availabilityExpiresAt.
  • Classification: propertyCategories, developmentState, buildingZones, conditions, constructionMethod.
  • Areas and counts: usable, rentable, cellar, balcony, terrace, loggia and garden areas, building volume, ceiling and hall height, floor and elevator loads, utilization ratios, and bedroom, bathroom, shower, toilet and balcony counts.
  • Heating and energy: heatingType, heatingDistribution, the extended energyCertificate.
  • Prices: the prices object (buy and rent, gross, net and extra costs, deposit, interval), commissions, heating costs and rental income.
  • Amenities: characteristics, one field per feature (elevator, balcony, garden, parking, views and more), each APPLIES, DOES_NOT_APPLY or UNKNOWN.
  • Listing: localized texts in localizations, publishers, parkingLots, virtualTourLinks, videoLinks, the owner and seller contacts, and your own customFields.

Every new field is optional. The API Reference lists each field with its allowed values.

List your properties and users

Two new endpoints page through everything in your workspace:

  • GET /v1/real-estate-properties: id, title, property type, address and your objectReferenceId per property.
  • GET /v1/users: BKBN id, your userReferenceId, email, name, language, phone and country per user.

Both take a zero-based page and a size (default 50, at most 100) and return the page with totalElements, totalPages, first and last. Filtering and sorting are not supported; fetch a single entry for its full detail.

How updates treat what you send

  • A field you leave out, or send as null, keeps its stored value.
  • Lists and maps are replaced as a whole, so [] or {} empties them.
  • characteristics, energyCertificate, prices and swissReferences are merged field by field.

Good to know

  • An enum field can return UNKNOWN when the property holds a value newer than the API. Never send UNKNOWN back: it is rejected with a 400 naming the field (except in characteristics, where it is a regular answer).
  • The newer text fields have length limits (255 characters for references and short texts); a violation is a 400 naming the field.
  • rooms (the per-room breakdown) is returned on read but cannot be set through the API; numberOfRooms can.
  • Boolean fields are documented under the names the API has always sent and accepted, with their is prefix. Earlier versions of the API Reference showed some of them without it, for example isHydraulicBalancingDone, isMultiStoryPlan and isFurnished.